ormus-solutions/libreembed-claude-code/communication-buses

Communication buses pattern library

Reference patterns for I2C, SPI, UART, CAN, and USB driver development. Use as a lookup when designing or reviewing drivers.

I2C reference

Address resolution

Format on the wire (7-bit):

S | 7-bit addr | R/W | A | ... | P

The R/W bit is bit 0. Many HALs accept the address pre-shifted (address << 1); some accept it raw. Confirm against the HAL docs — common bug source.

Pull-up sizing

For VCC = 3.3V:

Bus capacitance matters. Wire capacitance ~ 1 pF/cm. Total bus capacitance (wire + slaves + master) should be < 400 pF for standard, < 200 pF for fast modes.

Clock stretching

Slave holds SCL low to gain processing time. Master must wait. STM32 hardware I2C handles this. Some software bit-bang implementations don't. If using bit-bang, sample SCL before assuming the master controls it.

Bus recovery

When SDA is stuck low (slave hung mid-transfer):

1. Configure SDA + SCL as GPIO (out of AF)
2. Pulse SCL low → high, 9-16 times
3. Check if SDA released (high)
4. If yes: generate STOP (SCL high, SDA low → high)
5. Restore SDA + SCL to AF
6. Re-init the I2C peripheral

SPI reference

Mode card

Most sensors: mode 0 or 3. Always verify against datasheet — wrong mode silently corrupts every byte.

CS line patterns

Hardware NSS (single slave):

• Peripheral toggles NSS automatically
• Faster setup/hold timing
• Limited to one slave

GPIO CS (multi-slave):

• Software writes GPIO before/after transfer
• More flexible
• Setup time: typically need a few microseconds CS-low before SCK starts
• Hold time: keep CS low until last bit clocked + a few extra cycles

DMA buffer alignment

For Cortex-M7 cache maintenance:

// Before DMA write (CPU → peripheral):
SCB_CleanDCache_by_Addr((uint32_t*)tx_buf, len);
 
// Before DMA read (peripheral → CPU):
SCB_InvalidateDCache_by_Addr((uint32_t*)rx_buf, len);

Daisy chain

For multiple SPI slaves on one CS:

Master MOSI → Slave 1 MOSI
Slave 1 MISO → Slave 2 MOSI
Slave 2 MISO → Master MISO
 
Common CS to all slaves
Common SCK to all slaves

Transfer N×M bytes for N slaves with M-byte registers. Each slave shifts out its previous-cycle data while shifting in new data. Useful for sensor arrays.

UART reference

Frame format

Start bit | Data bits (5-9) | Parity (optional) | Stop bits (1 / 1.5 / 2)

Common configurations:

• 8N1: 8 data, no parity, 1 stop — default for most modern UART
• 7E1: 7 data, even parity, 1 stop — legacy serial
• 8E2: 8 data, even parity, 2 stop — older industrial

Baud rate selection

Common rates: 9600, 19200, 38400, 57600, 115200, 230400, 460800, 921600, 1500000, 2000000, 3000000

Above 921600, accuracy of the MCU's UART clock matters. STM32 USART_BRR can hit any baud rate; calculate the actual rate and verify it's within ±2% of nominal.

RX patterns

Ring buffer pattern

typedef struct {
    uint8_t buf[256];
    volatile uint16_t head;
    uint16_t tail;
} ringbuf_t;
 
// ISR
void USART2_IRQHandler(void) {
    if (USART2->SR & USART_SR_RXNE) {
        uint8_t byte = USART2->DR;
        uint16_t next = (rb.head + 1) & 0xFF;
        if (next != rb.tail) {           // Not full
            rb.buf[rb.head] = byte;
            rb.head = next;
        }
        // else: overflow — log it
    }
}
 
// Task
ssize_t ringbuf_read(uint8_t *out, size_t maxlen) {
    size_t count = 0;
    while (rb.tail != rb.head && count < maxlen) {
        out[count++] = rb.buf[rb.tail];
        rb.tail = (rb.tail + 1) & 0xFF;
    }
    return count;
}

Hardware flow control (RTS/CTS)

When the host can stall:

• MCU asserts RTS = "I have buffer space, send me data"
• MCU deasserts RTS = "stop, my buffer is full"
• MCU checks CTS = "host has buffer space, I can transmit"

For STM32 USART:

• USART_CR3_CTSE enables CTS
• USART_CR3_RTSE enables RTS
• Hardware handles both — no software signaling needed

CAN reference

Bit timing

Bit time = sync + propagation + phase1 + phase2
Sample point = (sync + propagation + phase1) / bit time

Recommended sample point: 75–87.5% of bit time. Higher sample point gives more margin for bus propagation delay but less margin for resync.

For 500 kbps on 42 MHz APB clock:

• 42 MHz / 0.5 MHz = 84 time quanta — too many, use prescaler
• Prescaler = 6 → 14 time quanta per bit
• 1 sync + 6 prop + 5 phase1 + 2 phase2 → sample point at (1+6+5)/14 = 86% ✓
• SJW = 2

Filter banks

For STM32 bxCAN:

• 14 filter banks per CAN peripheral
• Each bank: 16-bit list mode (4 IDs) OR 16-bit mask mode (2 ID/mask pairs) OR 32-bit list (2 IDs) OR 32-bit mask (1 ID/mask)

Configure for the IDs you actually consume. Other IDs dropped at the controller (no CPU work).

Error states

Active → Passive (TX error count > 127): sends recessive error frames only
Active → Bus-off (TX error count > 255): controller stops
Bus-off → Active (after 128 × 11 recessive bits): automatic recovery

Driver must detect bus-off and either wait for auto-recovery OR explicitly re-init. Auto-recovery is safer for production.

USB reference

Descriptor tree

Device descriptor
├─ Configuration descriptor (1+)
│  ├─ Interface descriptor (1+)
│  │  └─ Endpoint descriptor (0+)
│  └─ String descriptors (indexed)
└─ Vendor extensions (rare)

Total length in configuration descriptor must equal sum of all subordinate descriptor lengths. Off-by-one here causes enumeration to fail at the configuration-read step.

Endpoint types

• Control (EP0) — required, bidirectional, 8/16/32/64 byte packets
• Bulk — high throughput, no latency guarantee, packet size 8-512
• Interrupt — low latency, periodic polling, packet size 8-1024
• Isochronous — guaranteed bandwidth, no error recovery, packet size up to 1024

Common enumeration failures

Common mistakes catalog

"I2C bus is stuck"

A slave is holding SDA low. Use bus recovery (pulse SCL 9-16 times, then STOP). Common causes:

• Power glitch on slave during transfer
• Master reset mid-transfer
• Slave with buggy firmware

"SPI reads all 0xFFs"

Slave isn't driving MISO. Check:

• Slave VCC (at the chip, not the regulator)
• Slave reset state
• CS line actually going low during transfer
• Correct SPI mode
• Slave power-up time elapsed

"UART loses bytes under load"

RX overrun. Either:

• Increase RX FIFO threshold to give software more time
• Switch from interrupt to DMA RX
• Add hardware flow control

"CAN bus shows messages but receiver doesn't see them"

Filter bank misconfigured. Check the filter bank's ID + mask vs. the actual message ID being broadcast.

"USB device works on one host, fails on another"

Descriptor issue. Some hosts are stricter than others. Run USB-IF compliance tool on the descriptors.

Code patterns (STM32 HAL)

Production communication bus patterns for embedded C. STM32 HAL and LL examples.

I2C Register Read/Write for MEMS Sensors

Generic register-addressed I2C sensor driver (BME280, MPU-6050, etc.):

#define I2C_TIMEOUT_MS  5U
 
HAL_StatusTypeDef sensor_write_reg(I2C_HandleTypeDef *hi2c,
                                    uint8_t dev_addr, uint8_t reg, uint8_t val)
{
    uint8_t buf[2] = { reg, val };
    return HAL_I2C_Master_Transmit(hi2c, dev_addr << 1, buf, 2, I2C_TIMEOUT_MS);
}
 
HAL_StatusTypeDef sensor_read_reg(I2C_HandleTypeDef *hi2c,
                                   uint8_t dev_addr, uint8_t reg,
                                   uint8_t *out, uint16_t len)
{
    HAL_StatusTypeDef s;
    s = HAL_I2C_Master_Transmit(hi2c, dev_addr << 1, &reg, 1, I2C_TIMEOUT_MS);
    if (s != HAL_OK) { return s; }
    return HAL_I2C_Master_Receive(hi2c, (dev_addr << 1) | 1,
                                   out, len, I2C_TIMEOUT_MS);
}
 
/* I2C bus recovery: toggle SCL 9 times to release stuck SDA */
void i2c_bus_recover(GPIO_TypeDef *scl_port, uint16_t scl_pin,
                     GPIO_TypeDef *sda_port, uint16_t sda_pin)
{
    for (int i = 0; i < 9; i++) {
        HAL_GPIO_WritePin(scl_port, scl_pin, GPIO_PIN_SET);
        HAL_Delay(1);
        HAL_GPIO_WritePin(scl_port, scl_pin, GPIO_PIN_RESET);
        HAL_Delay(1);
    }
    /* Generate STOP: SDA low→high while SCL high */
    HAL_GPIO_WritePin(sda_port, sda_pin, GPIO_PIN_RESET);
    HAL_GPIO_WritePin(scl_port, scl_pin, GPIO_PIN_SET);
    HAL_Delay(1);
    HAL_GPIO_WritePin(sda_port, sda_pin, GPIO_PIN_SET);
}

SPI DMA Transfer with Semaphore

Non-blocking SPI using DMA and FreeRTOS binary semaphore for completion notification:

static SemaphoreHandle_t s_spi_done;
 
void HAL_SPI_TxRxCpltCallback(SPI_HandleTypeDef *hspi)
{
    if (hspi == &hspi1) {
        BaseType_t woken = pdFALSE;
        xSemaphoreGiveFromISR(s_spi_done, &woken);
        portYIELD_FROM_ISR(woken);
    }
}
 
void spi_dma_init(void)
{
    s_spi_done = xSemaphoreCreateBinary();
}
 
bool spi_transfer(const uint8_t *tx, uint8_t *rx, uint16_t len)
{
    spi_cs_assert();
    HAL_SPI_TransmitReceive_DMA(&hspi1, (uint8_t *)tx, rx, len);
    /* Block task until DMA complete (max 10ms) */
    bool ok = xSemaphoreTake(s_spi_done, pdMS_TO_TICKS(10)) == pdTRUE;
    spi_cs_deassert();
    return ok;
}

UART DMA Circular Buffer with IDLE Detection

Most reliable pattern for variable-length UART frames at high baud:

#define DMA_RX_BUF  256U
static uint8_t  s_dma_rx[DMA_RX_BUF];
static uint32_t s_rx_wr = 0U;  /* Written by IDLE ISR */
static uint32_t s_rx_rd = 0U;  /* Read by application  */
 
void uart_dma_init(UART_HandleTypeDef *hu)
{
    /* Start DMA receive in circular mode — never needs restart */
    HAL_UARTEx_ReceiveToIdle_DMA(hu, s_dma_rx, DMA_RX_BUF);
    __HAL_DMA_DISABLE_IT(hu->hdmarx, DMA_IT_HT);  /* Disable half-transfer */
}
 
void HAL_UARTEx_RxEventCallback(UART_HandleTypeDef *hu, uint16_t size)
{
    /* size = write position in s_dma_rx (bytes from buffer start), not a  */
    /* count since the last callback. size == DMA_RX_BUF means it wrapped.  */
    s_rx_wr = size % DMA_RX_BUF;
}
 
uint16_t uart_available(void) {
    return (s_rx_wr - s_rx_rd + DMA_RX_BUF) % DMA_RX_BUF;
}
 
uint8_t uart_read_byte(void) {
    uint8_t c = s_dma_rx[s_rx_rd];
    s_rx_rd = (s_rx_rd + 1U) % DMA_RX_BUF;
    return c;
}

CAN Transmit and Receive