Skip to main content
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

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 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:
If the node appears but anx device list still fails, the issue is likely a permissions problem — see the accordion below.
On macOS, the device appears as /dev/cu.usbserial-* rather than /dev/ttyUSB*. Run ls /dev/cu.* to find it.
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:
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.
After logging back in, verify your membership:
You should see dialout listed in the output.

​
Flashing

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:
1

Hold the BOOT button

Press and hold the BOOT button on the module. Do not release it yet.
2

Press and release RESET

While still holding BOOT, press and release the RESET button.
3

Release BOOT

Release the BOOT button. The module is now in bootloader mode and waiting for a flash command.
4

Run the flash command

Flash the firmware immediately — the bootloader does not wait indefinitely.
If the flash still fails, try reducing the baud rate. Some USB-to-serial adapters are unstable at high speeds:
On Windows, substitute /dev/ttyUSB0 with the appropriate COM port, e.g. --port COM3.
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:
If retrying fails, use recovery mode. Recovery mode performs a slower, more reliable write with additional error correction:
While the recovery flash runs, avoid moving the cable or the module. A stable, direct USB connection is essential.
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.

​
Wi-Fi

Work through these checks before diving deeper into logs:
1

Verify credentials in config.json

Open config.json and confirm the ssid and password fields are correct. Wi-Fi passwords are case-sensitive.
2

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

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

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:
Check the serial monitor output for specific error messages by running anx monitor.
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.
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.

​
Peripheral Communication

A missing ACK on the I2C bus means the module sent an address and nothing responded. Check the following:

Wiring

Confirm SDA connects to SDA and SCL to SCL. A swapped pair is the most common cause.

Voltage

Verify the sensor or peripheral is powered from the 3.3 V rail. The module’s GPIO is not 5 V tolerant.

I2C Address

Scan the bus to find what addresses respond, then compare against your sensor’s datasheet.
Run a bus scan to discover active I2C addresses:
The output lists every address that acknowledged. If your device does not appear, recheck power and wiring before assuming the device is faulty.
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.
Applying a voltage above 3.3 V to an ADC pin can permanently damage the module. Always verify your signal levels before connecting.
Corrupted UART data almost always has one of two causes: a baud rate mismatch or swapped TX/RX lines.
1

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

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

​
OTA Updates

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