> ## 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.

# Diagnose Common ANX Dev Module Issues

> Troubleshoot the most frequent problems with ANX dev modules: connection failures, flashing errors, Wi-Fi issues, and peripheral communication faults.

This page covers the most common issues developers encounter when working with ANX dev modules, along with step-by-step solutions. Use the accordions below to scan for your issue and expand the relevant section — each entry includes the symptoms, likely causes, and the exact commands or steps needed to resolve it.

## Connection & Detection

<Accordion title="Module not detected by `anx device list`">
  If `anx device list` returns an empty list or no ANX device is shown, work through the following checks in order.

  **Check your USB cable first.** Many USB-C cables are charge-only and carry no data. Swap in a known-good data cable and retry.

  **Install the required driver on Windows.** The ANX dev module uses a CP210x USB-to-serial bridge. Download and install the [Silicon Labs CP210x driver](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers) if you haven't already, then reconnect the module.

  **Try a different USB port.** Some ports — particularly those on USB hubs — can be unreliable. Plug directly into a port on your machine.

  **Verify the device node exists on Linux.** Run the following to confirm the OS has registered the module:

  ```bash theme={null}
  ls -la /dev/ttyUSB*
  ```

  If the node appears but `anx device list` still fails, the issue is likely a permissions problem — see the accordion below.

  <Note>
    On macOS, the device appears as `/dev/cu.usbserial-*` rather than `/dev/ttyUSB*`. Run `ls /dev/cu.*` to find it.
  </Note>
</Accordion>

<Accordion title="Permission denied on /dev/ttyUSB0 (Linux)">
  On Linux, serial ports are owned by the `dialout` group. If your user account is not in that group, any attempt to open the port returns `Permission denied`.

  Add your user to the `dialout` group and activate the change in your current session:

  ```bash theme={null}
  sudo usermod -aG dialout $USER
  newgrp dialout
  ```

  <Warning>
    The `usermod` change only takes full effect after you log out and back in. Using `newgrp dialout` applies it to your current terminal session immediately, but other open terminals still use the old group membership.
  </Warning>

  After logging back in, verify your membership:

  ```bash theme={null}
  groups $USER
  ```

  You should see `dialout` listed in the output.
</Accordion>

***

## Flashing

<Accordion title="Flashing fails with &#x22;Could not enter bootloader mode&#x22;">
  The ANX CLI must reboot the module into its ROM bootloader before it can write firmware. If the automatic reset fails, enter bootloader mode manually:

  <Steps>
    <Step title="Hold the BOOT button">
      Press and hold the **BOOT** button on the module. Do not release it yet.
    </Step>

    <Step title="Press and release RESET">
      While still holding BOOT, press and release the **RESET** button.
    </Step>

    <Step title="Release BOOT">
      Release the **BOOT** button. The module is now in bootloader mode and waiting for a flash command.
    </Step>

    <Step title="Run the flash command">
      Flash the firmware immediately — the bootloader does not wait indefinitely.

      ```bash theme={null}
      anx flash --port /dev/ttyUSB0 --latest
      ```
    </Step>
  </Steps>

  If the flash still fails, try reducing the baud rate. Some USB-to-serial adapters are unstable at high speeds:

  ```bash theme={null}
  anx flash --latest --baud 115200
  ```

  <Tip>
    On Windows, substitute `/dev/ttyUSB0` with the appropriate COM port, e.g. `--port COM3`.
  </Tip>
</Accordion>

<Accordion title="Firmware verification failed after flash">
  A verification failure means the bytes written to flash do not match the source image. This is almost always caused by a brief USB connection drop mid-flash.

  **First, retry the flash command.** A single retry resolves this in most cases:

  ```bash theme={null}
  anx flash --latest
  ```

  **If retrying fails, use recovery mode.** Recovery mode performs a slower, more reliable write with additional error correction:

  ```bash theme={null}
  anx flash --recovery
  ```

  While the recovery flash runs, avoid moving the cable or the module. A stable, direct USB connection is essential.

  <Warning>
    Do not unplug the module while a flash or recovery operation is in progress. Interrupting a write mid-stream can leave the module in an unbootable state requiring a full recovery flash to restore.
  </Warning>
</Accordion>

***

## Wi-Fi

<Accordion title="Wi-Fi won't connect">
  Work through these checks before diving deeper into logs:

  <Steps>
    <Step title="Verify credentials in config.json">
      Open `config.json` and confirm the `ssid` and `password` fields are correct. Wi-Fi passwords are **case-sensitive**.
    </Step>

    <Step title="Confirm 2.4 GHz band">
      The ANX dev module supports **2.4 GHz only** (802.11 b/g/n). It cannot connect to a 5 GHz network. If your router broadcasts both bands under the same SSID, split them or connect to the dedicated 2.4 GHz SSID.
    </Step>

    <Step title="Check the Wi-Fi mode in config">
      Ensure `wifi.mode` is set to `station` in `config.json`. Setting it to `ap` or `off` prevents outbound connections.
    </Step>

    <Step title="Read the error code from the serial monitor">
      Run the serial monitor and watch for the Wi-Fi error code printed during the connection attempt:

      ```bash theme={null}
      anx monitor
      ```

      Check the serial monitor output for specific error messages by running `anx monitor`.
    </Step>
  </Steps>
</Accordion>

<Accordion title="Wi-Fi connects but no internet / MQTT fails">
  If the module associates with your access point but cannot reach the internet or your MQTT broker, the issue is usually at the network layer rather than the module itself.

  **Check DNS resolution.** Confirm that your router assigns a valid DNS server to DHCP clients. Many home routers use themselves (`192.168.x.1`) as the DNS server — verify this is reachable from the module's subnet.

  **Check firewall rules for MQTT.** ANX OS uses MQTT over TLS on **TCP port 8883**. If your router or a corporate firewall blocks outbound connections on this port, MQTT will silently time out. Ensure outbound TCP 8883 is permitted.

  <Note>
    If you are using a custom MQTT broker on a non-standard port, update the `mqtt.port` field in `config.json` to match, and open that port in your firewall instead.
  </Note>
</Accordion>

***

## Peripheral Communication

<Accordion title="I2C device not found (no ACK)">
  A missing ACK on the I2C bus means the module sent an address and nothing responded. Check the following:

  <CardGroup cols={3}>
    <Card title="Wiring" icon="cable">
      Confirm SDA connects to SDA and SCL to SCL. A swapped pair is the most common cause.
    </Card>

    <Card title="Voltage" icon="bolt">
      Verify the sensor or peripheral is powered from the **3.3 V** rail. The module's GPIO is not 5 V tolerant.
    </Card>

    <Card title="I2C Address" icon="magnifying-glass">
      Scan the bus to find what addresses respond, then compare against your sensor's datasheet.
    </Card>
  </CardGroup>

  Run a bus scan to discover active I2C addresses:

  ```bash theme={null}
  anx i2c scan
  ```

  The output lists every address that acknowledged. If your device does not appear, recheck power and wiring before assuming the device is faulty.
</Accordion>

<Accordion title="ADC reads always 0 or 4095">
  A stuck-at-zero or stuck-at-full-scale ADC reading points to one of two root causes:

  **The input voltage exceeds 3.3 V.** The ANX module's ADC input range is **0–3.3 V**. Any signal above 3.3 V saturates the converter at 4095. Use a resistor divider to scale the signal down before connecting it.

  **The pin is not ADC-capable.** Only **GPIO18–GPIO25** are wired to the ADC peripheral. Using any other GPIO for analog input always reads 0. Rewire to a pin in that range.

  <Warning>
    Applying a voltage above 3.3 V to an ADC pin can permanently damage the module. Always verify your signal levels before connecting.
  </Warning>
</Accordion>

<Accordion title="UART data is corrupted or garbled">
  Corrupted UART data almost always has one of two causes: a baud rate mismatch or swapped TX/RX lines.

  <Steps>
    <Step title="Verify baud rate on both sides">
      Both the module and the connected device must use the **identical baud rate**. A mismatch of even 100 baud can corrupt every byte. Check `config.json` and your peripheral's datasheet.
    </Step>

    <Step title="Check TX/RX orientation">
      UART is cross-wired: the module's **TX** connects to the peripheral's **RX**, and vice versa. If both TX lines are connected together (or both RX lines), no data passes correctly.
    </Step>
  </Steps>

  <Tip>
    Use `anx monitor --raw` to see the raw bytes received on the UART port. This helps distinguish a baud mismatch (random-looking bytes) from a wiring swap (complete silence).
  </Tip>
</Accordion>

***

## OTA Updates

<Accordion title="OTA update fails with &#x22;signature verification failed&#x22;">
  ANX OS verifies the cryptographic signature of every OTA image before writing it to flash. A verification failure means the downloaded image is corrupted or incomplete.

  **Retry the update.** A transient network hiccup is the most common cause. The `--retry` flag re-downloads and re-verifies from scratch:

  ```bash theme={null}
  anx ota update --retry
  ```

  **Ensure Wi-Fi stays stable during the download.** Large firmware images take 30–90 seconds to download. If the module's Wi-Fi connection drops mid-transfer, the image is truncated and the signature check fails. Move the module closer to your access point if signal strength is marginal.

  <Note>
    ANX OS uses a dual-partition scheme. Even if verification fails, the currently running firmware is never overwritten — the device continues operating normally and you can retry at any time.
  </Note>
</Accordion>