Skip to content

A Hardware Hacking Tool with Web-Based CLI That Speaks Every Protocol

8.8 KB
Raw Blame
/**
 * @AUTHOR Ákos Szabó (Whitehawk Tailor) - [email protected]
 * 
 * This is an I2C sniffer that logs traffic on I2C BUS.
 * 
 * It is not part of the I2C BUS. It is neither a Master, nor a Slave and puts no data to the lines.
 * It just listens and logs the communication.
 * 
 * Two pins as imput are attached to SDC and SDA lines.
 * Since the I2C communications runs on 400kHz so,
 * the tool that runs this program should be fast.
 * This was tested on an ESP32 bord Heltec WiFi Lora32 v2
 * ESP32 core runs on 240MHz.
 * It means there are 600 ESP32 cycles during one I2C clock tick.
 *
 * 
 * The program uses interrupts to detect
 * the raise edge of the SCL - bit transfer 
 * the falling edge of SDA if SCL is HIGH- START
 * the raise edge of SDA if SCL id HIGH - STOP 
 * 
 * In the interrupt routines there is just a few line of code
 * that mainly sets the status and stores the incoming bits.
 * Otherwise the program gets timeout panic in interrupt handler and
 * restart the CPU.
 * 
 * 
 * REWORKED for ESP32 Bus Pirate
 * 
 *                   https://github.com/WhitehawkTailor/I2C-sniffer/
 */

#include "i2c_sniffer.h"
#include <Arduino.h>
#include "driver/gpio.h"

// --- Minimal internal notes (added): ISR pushes compact events into an event ring.
// The main context converts events into ASCII and exposes them via read()/available().

static uint8_t sniffer_scl_pin = 1; // override by i2c_sniffer_begin()
static uint8_t sniffer_sda_pin = 2;

#define I2C_IDLE 0
#define I2C_TRX  2

// ---- Event tags (4 bits) ----
#define TAG_START 0x1
#define TAG_STOP  0x2
#define TAG_DATA  0x3
#define TAG_ADDR  0x4
#define TAG_ACK   0x5

static inline uint16_t PACK_EVENT(uint16_t tag, uint16_t value) {
    return (uint16_t)((tag << 12) | (value & 0x0FFF));
}
static inline uint8_t  EVENT_TAG(uint16_t ev) { return (uint8_t)((ev >> 12) & 0x0F); }
static inline uint16_t EVENT_VAL(uint16_t ev) { return (uint16_t)(ev & 0x0FFF); }

// ---- Event ring (ISR -> main) ----
#define EVENT_RING_ORDER 11
#define EVENT_RING_SIZE  (1u << EVENT_RING_ORDER)   // 2048 events
#define EVENT_RING_MASK  (EVENT_RING_SIZE - 1u)
static volatile uint16_t eventRing[EVENT_RING_SIZE];
static volatile uint16_t eventW = 0;
static volatile uint16_t eventR = 0;

// ---- Output char ring (main -> user read()) ----
#define CHAR_RING_ORDER 13
#define CHAR_RING_SIZE  (1u << CHAR_RING_ORDER)     // 8192 chars
#define CHAR_RING_MASK  (CHAR_RING_SIZE - 1u)
static volatile char charRing[CHAR_RING_SIZE];
static volatile uint16_t charW = 0;
static volatile uint16_t charR = 0;

// ---- I2C state (ISR) ----
static volatile uint8_t i2cStatus = I2C_IDLE;
static volatile uint8_t bitCount = 0;
static volatile uint8_t currentByte = 0;
static volatile uint16_t byteCountInFrame = 0;
static volatile uint8_t expectingAck = 0;

// Optional counters (kept, cheap)
static volatile uint16_t falseStart = 0;
static volatile uint16_t sclUpCnt = 0;
static volatile uint16_t sdaUpCnt = 0;
static volatile uint16_t sdaDownCnt = 0;

// ---- Helpers (ISR-safe) ----
static inline void IRAM_ATTR push_event(uint16_t ev) {
    uint16_t next = (uint16_t)((eventW + 1u) & EVENT_RING_MASK);
    if (next == eventR) { // full -> drop oldest
        eventR = (uint16_t)((eventR + 1u) & EVENT_RING_MASK);
    }
    eventRing[eventW] = ev;
    eventW = next;
}

static inline uint8_t IRAM_ATTR fast_gpio_read(uint8_t pin) {
    return (uint8_t)gpio_get_level((gpio_num_t)pin);
}

// ---- ISR handlers ----
void IRAM_ATTR i2cTriggerOnRaisingSCL() {
    sclUpCnt++;

    if (i2cStatus == I2C_IDLE) {
        falseStart++;
    }

    if (expectingAck) {
        uint8_t ackBit = fast_gpio_read(sniffer_sda_pin); // 0 = ACK, 1 = NACK
        push_event(PACK_EVENT(TAG_ACK, (uint16_t)ackBit));
        expectingAck = 0;
        bitCount = 0;
        currentByte = 0;
        return;
    }

    uint8_t bit = fast_gpio_read(sniffer_sda_pin);
    currentByte = (uint8_t)((currentByte << 1) | (bit & 0x01));
    bitCount++;

    if (bitCount >= 8) {
        uint16_t tag = (byteCountInFrame == 0) ? TAG_ADDR : TAG_DATA;
        push_event(PACK_EVENT(tag, currentByte));
        byteCountInFrame++;
        expectingAck = 1;
    }
}

void IRAM_ATTR i2cTriggerOnChangeSDA() {
    uint8_t s1 = fast_gpio_read(sniffer_sda_pin);
    uint8_t s2 = fast_gpio_read(sniffer_sda_pin);
    if (s1 != s2) s1 = s2;

    if (s1) {
        sdaUpCnt++;
        uint8_t scl = fast_gpio_read(sniffer_scl_pin);
        if (i2cStatus != I2C_IDLE && scl == 1) {
            push_event(PACK_EVENT(TAG_STOP, 0));
            i2cStatus = I2C_IDLE;
            bitCount = 0;
            currentByte = 0;
            expectingAck = 0;
            byteCountInFrame = 0;
        }
    } else {
        sdaDownCnt++;
        uint8_t scl = fast_gpio_read(sniffer_scl_pin);
        if (i2cStatus == I2C_IDLE && scl == 1) {
            push_event(PACK_EVENT(TAG_START, 0));
            i2cStatus = I2C_TRX;
            bitCount = 0;
            currentByte = 0;
            expectingAck = 0;
            byteCountInFrame = 0;
        }
    }
}

// ---- API ----
void i2c_sniffer_begin(uint8_t scl, uint8_t sda) {
    sniffer_scl_pin = scl;
    sniffer_sda_pin = sda;
}

static void reset_state_and_buffers() {
    noInterrupts();
    // I2C state
    i2cStatus = I2C_IDLE;
    bitCount = 0;
    currentByte = 0;
    byteCountInFrame = 0;
    expectingAck = 0;
    // rings
    eventW = eventR = 0;
    charW  = charR  = 0;
    interrupts();
}

void i2c_sniffer_setup() {
    pinMode(sniffer_scl_pin, INPUT_PULLUP);
    pinMode(sniffer_sda_pin, INPUT_PULLUP);
    reset_state_and_buffers();
    attachInterrupt(digitalPinToInterrupt(sniffer_scl_pin), i2cTriggerOnRaisingSCL, RISING);
    attachInterrupt(digitalPinToInterrupt(sniffer_sda_pin), i2cTriggerOnChangeSDA, CHANGE);
}

void i2c_sniffer_stop() {
    detachInterrupt(digitalPinToInterrupt(sniffer_scl_pin));
    detachInterrupt(digitalPinToInterrupt(sniffer_sda_pin));
    noInterrupts();
    i2cStatus = I2C_IDLE;
    interrupts();
}

// ---- Output char ring helpers (main context) ----
static inline void char_push(char c) {
    uint16_t next = (uint16_t)((charW + 1u) & CHAR_RING_MASK);
    if (next == charR) { // full -> drop oldest
        charR = (uint16_t)((charR + 1u) & CHAR_RING_MASK);
    }
    charRing[charW] = c;
    charW = next;
}

static void text_push_str(const char* s) {
    while (*s) { char_push(*s++); }
}

static void text_push_hex8(uint8_t v) {
    const char* hex = "0123456789ABCDEF";
    char_push('0'); char_push('x');
    char_push(hex[(v >> 4) & 0x0F]);
    char_push(hex[(v     ) & 0x0F]);
}

// ---- Convert pending events into ASCII (called on demand) ----
// Format example:
//   [S]                      (START)
//   ADDR 0x3C W <ACK>
//   0x00 <ACK> 0xAB <ACK>  (DATA ...)
//   [P]\n                    (STOP + newline)
static void pump_events_to_text() {
    // Process a bounded number of events per call to avoid long critical sections
    // (added) keeps latency low while ensuring steady drain.
    const uint16_t MAX_EVENTS_PER_PUMP = 128;
    uint16_t processed = 0;

    while (processed < MAX_EVENTS_PER_PUMP) {
        uint16_t ev;
        noInterrupts();
        if (eventR == eventW) { interrupts(); break; }
        ev = eventRing[eventR];
        eventR = (uint16_t)((eventR + 1u) & EVENT_RING_MASK);
        interrupts();

        uint8_t tag = EVENT_TAG(ev);
        uint16_t val = EVENT_VAL(ev);

        switch (tag) {
            case TAG_START:
                text_push_str("[S] ");
                break;

            case TAG_STOP:
                text_push_str("[P]");
                char_push('\r\n'); // newline to separate frames
                break;

            case TAG_ADDR: {
                uint8_t b = (uint8_t)val;
                uint8_t addr = (uint8_t)((b >> 1) & 0x7F);
                uint8_t rw   = (uint8_t)(b & 0x01);
                text_push_str("ADDR ");
                text_push_hex8(addr);
                char_push(' ');
                char_push(rw ? 'R' : 'W');
                char_push(' ');
                break;
            }

            case TAG_DATA: {
                uint8_t b = (uint8_t)val;
                text_push_hex8(b);
                char_push(' ');
                break;
            }

            case TAG_ACK:
                text_push_str((val == 0) ? "<ACK> " : "<NACK> ");
                break;

            default:
                // ignore
                break;
        }
        processed++;
    }
}

bool i2c_sniffer_available() {
    // If no chars ready, try pumping events into ASCII
    if (charR == charW) {
        pump_events_to_text();
    }
    return (charR != charW);
}

char i2c_sniffer_read() {
    // Ensure at least one char is present
    if (charR == charW) {
        pump_events_to_text();
    }
    char out = '\0';
    if (charR != charW) {
        out = charRing[charR];
        charR = (uint16_t)((charR + 1u) & CHAR_RING_MASK);
    }
    return out;
}

void i2c_sniffer_reset_buffer() {
    reset_state_and_buffers();
}