> ## Documentation Index
> Fetch the complete documentation index at: https://launchpad.anxlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ANX SDK Reference: Modules and Architecture

> The ANX SDK provides C APIs for GPIO, UART, I2C, SPI, ADC, PWM, Wi-Fi, BLE, MQTT, OTA, and system utilities on ANX dev modules.

The ANX SDK is a C library that runs on top of ANX OS and gives your application direct access to all hardware peripherals and networking capabilities on ANX dev modules. Every module in the SDK maps to a dedicated header file and exposes a consistent, error-code-driven API so you can build reliable embedded applications without wrestling with low-level register access or OS internals.

## SDK Modules

The SDK is organized into focused modules. Include only the headers you need to keep your binary lean.

<CardGroup cols={2}>
  <Card title="Initialization" icon="power-off" href="/api/initialization">
    Core system setup, logging, delays, and device info via `anx/anx.h`.
  </Card>

  <Card title="GPIO" icon="microchip" href="/api/gpio">
    Digital I/O, pull resistors, and interrupt handlers via `anx/gpio.h`.
  </Card>

  <Card title="Communication" icon="arrows-left-right" href="/api/communication">
    Serial protocols — UART, I2C, and SPI — via `anx/uart.h`, `anx/i2c.h`, and `anx/spi.h`.
  </Card>

  <Card title="ADC" icon="wave-sine">
    Analog-to-digital conversion and channel sampling via `anx/adc.h`.
  </Card>

  <Card title="PWM" icon="signal">
    Pulse-width modulation output and duty-cycle control via `anx/pwm.h`.
  </Card>

  <Card title="Wi-Fi" icon="wifi">
    Station and access-point mode, network scanning, and connection management via `anx/wifi.h`.
  </Card>

  <Card title="MQTT" icon="tower-broadcast">
    Publish, subscribe, and broker connection management via `anx/mqtt.h`.
  </Card>

  <Card title="OTA" icon="cloud-arrow-down">
    Over-the-air firmware updates and rollback support via `anx/ota.h`.
  </Card>
</CardGroup>

## Including the SDK

Always include `anx/anx.h` as the first header in your application. It initializes the ANX OS integration layer and pulls in the common types — including `anx_err_t` — that every other module depends on.

```c main.c theme={null}
#include "anx/anx.h"  // Always include this first

void app_main(void) {
    // Your application entry point
}
```

<Note>
  ANX OS calls `app_main()` automatically after the hardware and `config.json` finish loading. You do not need to write a `main()` function yourself.
</Note>

## SDK Versioning

Call `anx_sdk_version()` at runtime to retrieve the SDK version string (for example, `"1.2.0"`). The SDK version must be compatible with the firmware version running on the device — compatibility requires that the **MAJOR** and **MINOR** components match exactly. A mismatch will cause `anx_sdk_version()` to log a warning on boot and may result in undefined behavior from certain API calls.

```c version_check.c theme={null}
#include "anx/anx.h"

void app_main(void) {
    ANX_LOGI("APP", "Firmware: %s", anx_firmware_version());
    ANX_LOGI("APP", "SDK:      %s", anx_sdk_version());
}
```

<Tip>
  Print both versions on startup so that your serial logs always capture the exact firmware and SDK combination used during a test run.
</Tip>

## Error Handling

Every ANX SDK function returns an `anx_err_t` value. Check the return value after every call — silent failures in embedded systems are difficult to diagnose in the field. Use `anx_err_to_str()` to convert an error code into a human-readable string for logging.

| Code                  | Value | Meaning                                                |
| --------------------- | ----- | ------------------------------------------------------ |
| `ANX_OK`              | `0`   | Operation succeeded                                    |
| `ANX_ERR_INVALID_ARG` | —     | An invalid argument was passed to the function         |
| `ANX_ERR_TIMEOUT`     | —     | The operation did not complete within the allowed time |
| `ANX_ERR_NO_MEM`      | —     | The system ran out of heap memory                      |
| `ANX_ERR_NOT_FOUND`   | —     | A requested resource or peripheral was not found       |
| `ANX_ERR_FAIL`        | —     | A generic, unclassified failure occurred               |

Use the pattern below as a template for every SDK call in your application:

```c error_handling.c theme={null}
anx_err_t err = anx_gpio_set_direction(5, ANX_GPIO_OUTPUT);
if (err != ANX_OK) {
    ANX_LOGE("APP", "GPIO init failed: %s", anx_err_to_str(err));
    // handle error
}
```

<Warning>
  Never ignore a non-`ANX_OK` return value in production code. Proceeding after a failed initialization call typically produces unpredictable hardware behavior that is hard to reproduce.
</Warning>