ANX SDK Communication APIs: UART, I2C, and SPI

The ANX SDK provides separate APIs for each serial communication protocol: UART for point-to-point serial communication with a host or another microcontroller, I2C for connecting multiple low-speed sensors and peripherals on a shared two-wire bus, and SPI for high-speed full-duplex data exchange with flash memory, displays, and other peripherals. Each protocol has its own header, configuration struct, and set of read/write functions — all returning anx_err_t for consistent error handling.

UART
I2C
SPI

UART — `anx/uart.h`

UART is a point-to-point asynchronous serial protocol. Include the header to access the UART API:

#include "anx/uart.h"

Initialization

Configure a UART port by populating an anx_uart_config_t struct and passing it to anx_uart_init(). Call anx_uart_init() once per port during application startup before any read or write operations.

`anx_uart_config_t` members

port

anx_uart_port_t

required

The UART port to configure. Use ANX_UART0 for the primary serial port or ANX_UART1 for the secondary port.

baud

uint32_t

required

Baud rate in bits per second. Common values: 9600, 19200, 57600, 115200, 230400, 921600. Both ends of the connection must use the same baud rate.

data_bits

uint8_t

required

Number of data bits per frame. Typically 8; 7 is supported for legacy protocols.

stop_bits

uint8_t

required

Number of stop bits. Use 1 for standard operation; 2 for compatibility with older hardware.

parity

anx_parity_t

required

Parity mode. Use ANX_PARITY_NONE for no parity, ANX_PARITY_EVEN for even parity, or ANX_PARITY_ODD for odd parity.

anx_uart_init return

anx_err_t

ANX_OK on success. ANX_ERR_INVALID_ARG if any config member is out of range. ANX_ERR_FAIL if the hardware port is already in use.

`anx_uart_write()`

Writes len bytes from data to the specified UART port. The function blocks until all bytes have been placed in the hardware transmit buffer or the operation times out.

port

anx_uart_port_t

required

The initialized UART port to write to (ANX_UART0 or ANX_UART1).

data

const uint8_t *

required

Pointer to the byte array to transmit. Must not be NULL.

len

size_t

required

Number of bytes to transmit from data.

return

anx_err_t

ANX_OK when all bytes are sent. ANX_ERR_TIMEOUT if the transmit buffer does not drain within the hardware timeout. ANX_ERR_INVALID_ARG if data is NULL or len is zero.

`anx_uart_read()`

Reads up to len bytes from the specified UART port into buf, waiting up to timeout_ms milliseconds for data to arrive.

port

anx_uart_port_t

required

The initialized UART port to read from (ANX_UART0 or ANX_UART1).

buf

uint8_t *

required

Pointer to the buffer that receives the incoming data. Must be at least len bytes long.

len

size_t

required

Maximum number of bytes to read into buf.

timeout_ms

uint32_t

required

Maximum number of milliseconds to wait for data. Pass 0 to return immediately with whatever bytes are currently available in the receive buffer.

return

int

The number of bytes actually read (0 to len). Returns -1 on error (for example, if the port is not initialized).

Example: UART loopback test

uart_loopback.c

#include "anx/anx.h"
#include "anx/uart.h"

void app_main(void) {
    anx_uart_config_t cfg = {
        .port      = ANX_UART0,
        .baud      = 115200,
        .data_bits = 8,
        .stop_bits = 1,
        .parity    = ANX_PARITY_NONE,
    };
    anx_uart_init(&cfg);

    const char *msg = "Hello UART";
    anx_uart_write(ANX_UART0, (const uint8_t *)msg, strlen(msg));

    uint8_t buf[32];
    int n = anx_uart_read(ANX_UART0, buf, sizeof(buf), 1000);
    ANX_LOGI("UART", "Received %d bytes", n);
}

Connect the TX and RX pins together on your dev module to run a loopback test without needing a second device. It is a fast way to verify your baud rate and framing settings before integrating a real peripheral.

I2C — `anx/i2c.h`

I2C is a two-wire, multi-device bus protocol. Include the header to access the I2C API:

#include "anx/i2c.h"

Initialization

Configure an I2C bus by populating an anx_i2c_config_t struct and passing it to anx_i2c_init(). The ANX dev module exposes two independent I2C buses.

`anx_i2c_config_t` members

bus

anx_i2c_bus_t

required

The I2C bus to configure. Use ANX_I2C0 for the primary bus or ANX_I2C1 for the secondary bus.

speed

anx_i2c_speed_t

required

Bus clock speed. Use ANX_I2C_STANDARD for 100 kHz (compatible with all I2C devices) or ANX_I2C_FAST for 400 kHz (requires all devices on the bus to support fast mode).

anx_i2c_init return

anx_err_t

ANX_OK on success. ANX_ERR_INVALID_ARG if speed is not a valid value. ANX_ERR_FAIL if the bus is already initialized.

`anx_i2c_write()`

Sends len bytes from data to the device at 7-bit address addr on the specified bus.

bus

anx_i2c_bus_t

required

The initialized I2C bus (ANX_I2C0 or ANX_I2C1).

addr

uint8_t

required

The 7-bit I2C address of the target device (0x00–0x7F).

data

const uint8_t *

required

Pointer to the byte array to send. Must not be NULL.

len

size_t

required

Number of bytes to send.

return

anx_err_t

ANX_OK on success. ANX_ERR_NOT_FOUND if no device acknowledges the address. ANX_ERR_TIMEOUT if the bus does not become idle within the timeout window.

`anx_i2c_read()`

Reads len bytes from the device at 7-bit address addr on the specified bus into buf.

bus

anx_i2c_bus_t

required

The initialized I2C bus (ANX_I2C0 or ANX_I2C1).

addr

uint8_t

required

The 7-bit I2C address of the target device.

buf

uint8_t *

required

Pointer to the buffer that receives the read data. Must be at least len bytes long.

len

size_t

required

Number of bytes to read from the device.

return

anx_err_t

ANX_OK on success. ANX_ERR_NOT_FOUND if the device does not acknowledge. ANX_ERR_TIMEOUT if the read does not complete in time.

`anx_i2c_scan()`

Scans the bus and logs the 7-bit address of every device that sends an acknowledgement. Use this during development to verify that all sensors are wired correctly and that their addresses match your expectations.

bus

anx_i2c_bus_t

required

The initialized I2C bus to scan (ANX_I2C0 or ANX_I2C1).

return

anx_err_t

ANX_OK after the scan completes, regardless of how many devices responded.

Example: register read pattern

Most I2C sensors use a register-based interface: write the register address you want to read, then read back the value in a separate transaction.

i2c_register_read.c

#include "anx/anx.h"
#include "anx/i2c.h"

// Read WHO_AM_I register (0x0F) from a device at address 0x19
void read_who_am_i(void) {
    uint8_t reg = 0x0F;
    uint8_t id;
    anx_i2c_write(ANX_I2C0, 0x19, &reg, 1);
    anx_i2c_read(ANX_I2C0, 0x19, &id, 1);
    ANX_LOGI("I2C", "WHO_AM_I = 0x%02X", id);
}

Some I2C devices require a repeated-start condition between the write and read phases. If anx_i2c_read() returns ANX_ERR_NOT_FOUND immediately after a successful write, check the device datasheet to see whether it supports repeated-start or requires a full stop/start sequence.

SPI — `anx/spi.h`

SPI is a synchronous, full-duplex serial protocol well suited for high-speed peripherals. Include the header to access the SPI API:

#include "anx/spi.h"

Initialization

Configure an SPI bus by populating an anx_spi_config_t struct and passing it to anx_spi_init().

`anx_spi_config_t` members

bus

anx_spi_bus_t

required

The SPI bus to configure. Use ANX_SPI0 for the primary SPI bus.

speed

uint32_t

required

Clock frequency in Hz. The maximum supported speed is 40000000 (40 MHz). Start at a lower speed (4–8 MHz) when debugging and raise it once the connection is verified stable.

mode

anx_spi_mode_t

required

SPI clock polarity and phase. Choose from:

ANX_SPI_MODE0 — CPOL=0, CPHA=0 (clock idles low, data sampled on rising edge)
ANX_SPI_MODE1 — CPOL=0, CPHA=1 (clock idles low, data sampled on falling edge)
ANX_SPI_MODE2 — CPOL=1, CPHA=0 (clock idles high, data sampled on falling edge)
ANX_SPI_MODE3 — CPOL=1, CPHA=1 (clock idles high, data sampled on rising edge)

anx_spi_init return

anx_err_t

ANX_OK on success. ANX_ERR_INVALID_ARG if speed exceeds 40 MHz or mode is not valid. ANX_ERR_FAIL if the bus is already initialized.

`anx_spi_transfer()`

Performs a full-duplex SPI transfer, simultaneously clocking out len bytes from tx and clocking in len bytes into rx. Pass NULL for tx to receive only (MOSI held low), or NULL for rx to transmit only (MISO ignored).

bus

anx_spi_bus_t

required

The initialized SPI bus (ANX_SPI0).

const uint8_t *

Pointer to the transmit buffer. Pass NULL to send zeroed bytes (receive-only operation).

uint8_t *

Pointer to the receive buffer. Must be at least len bytes long if non-NULL. Pass NULL to discard incoming data (transmit-only operation).

len

size_t

required

Number of bytes to transfer. Both tx and rx (when non-NULL) must be at least this long.

return

anx_err_t

ANX_OK on success. ANX_ERR_INVALID_ARG if both tx and rx are NULL, or if len is zero. ANX_ERR_TIMEOUT if the transfer does not complete within the hardware timeout.

Chip-Select Control

The ANX SPI API gives you manual control over the chip-select (CS) line so you can compose multi-transfer transactions without deselecting the device between calls.

`anx_spi_cs_active()`

Asserts the chip-select line (drives it low) to begin a transaction.

bus

anx_spi_bus_t

required

The initialized SPI bus whose CS line you want to assert.

return

anx_err_t

ANX_OK on success.

`anx_spi_cs_idle()`

Deasserts the chip-select line (drives it high) to end a transaction.

bus

anx_spi_bus_t

required

The initialized SPI bus whose CS line you want to release.

return

anx_err_t

ANX_OK on success.

Example: SPI flash read

spi_flash_read.c

#include "anx/anx.h"
#include "anx/spi.h"

// Read 4 bytes from SPI flash at address 0x001000
void read_spi_flash(void) {
    anx_spi_config_t cfg = {
        .bus   = ANX_SPI0,
        .speed = 4000000, // 4 MHz
        .mode  = ANX_SPI_MODE0,
    };
    anx_spi_init(&cfg);

    uint8_t cmd[] = {0x03, 0x00, 0x10, 0x00}; // READ cmd + 24-bit addr
    uint8_t data[4];

    anx_spi_cs_active(ANX_SPI0);
    anx_spi_transfer(ANX_SPI0, cmd, NULL, 4);   // send command
    anx_spi_transfer(ANX_SPI0, NULL, data, 4);  // receive data
    anx_spi_cs_idle(ANX_SPI0);

    ANX_LOGI("SPI", "Data: %02X %02X %02X %02X",
             data[0], data[1], data[2], data[3]);
}

Always call anx_spi_cs_idle() after every transaction — even if anx_spi_transfer() returns an error. Leaving the CS line asserted prevents other devices that share the same SPI bus from communicating and may lock up the bus until the next reboot.

Choosing the correct SPI mode

Consult your peripheral’s datasheet and look for the CPOL and CPHA timing diagrams in the electrical characteristics section. Most SPI flash and display controllers use ANX_SPI_MODE0. If you see corrupted data at higher clock speeds, try lowering the frequency first before switching the mode — a marginal PCB trace is more commonly the culprit than a mode mismatch.

​UART — anx/uart.h

​Initialization

​anx_uart_config_t members

​anx_uart_write()

​anx_uart_read()

​Example: UART loopback test

​I2C — anx/i2c.h

​Initialization

​anx_i2c_config_t members

​anx_i2c_write()

​anx_i2c_read()

​anx_i2c_scan()

​Example: register read pattern

​SPI — anx/spi.h

​Initialization

​anx_spi_config_t members

​anx_spi_transfer()

​Chip-Select Control

​anx_spi_cs_active()

​anx_spi_cs_idle()

​Example: SPI flash read

UART — `anx/uart.h`

Initialization

`anx_uart_config_t` members

`anx_uart_write()`

`anx_uart_read()`

Example: UART loopback test

I2C — `anx/i2c.h`

Initialization

`anx_i2c_config_t` members

`anx_i2c_write()`

`anx_i2c_read()`

`anx_i2c_scan()`

Example: register read pattern

SPI — `anx/spi.h`

Initialization

`anx_spi_config_t` members

`anx_spi_transfer()`

Chip-Select Control

`anx_spi_cs_active()`

`anx_spi_cs_idle()`

Example: SPI flash read