Skip to content

Troubleshooting

Common issues organized by symptom. Each entry lists the likely cause and the fix.

Device does not connect to C3PO

Symptom: a provisioned device never appears in the Fleet view

  • Wrong server address. The device connects to the CONFIG_SERVER_IP / CONFIG_SERVER_PORT written at provisioning. Re-provision with the correct C2 address.
  • Key mismatch. The device's master_key must match its keys.json entry. If you rebuilt the keystore, re-provision the device.
  • Firewall. Port 2626 must be reachable from the device. Check host firewall rules.
  • WiFi credentials. Verify the SSID/password; the device retries with backoff and will not connect with bad credentials.
  • Port already in use. A previous server may hold 2626: lsof -ti:2626 | xargs -r kill -9.

BLE does not work

Symptom: BLE commands fail or the chip resets

  • ESP32 classic has no BLE in this firmware. Use a C6 or S3 v0.3+.
  • ESP32-S3 v0.2 has a BLE silicon errata. Build with configs/esp32s3-v0.2 (CONFIG_BT_ENABLED=n). There is no workaround on that revision.
  • BLE is on-demand. It initializes the first time a module calls ble_controller_init(), not at boot. The first BLE command has extra latency.
  • Identify the revision with python -m esptool chip-id --port /dev/ttyXXX.

GPRS device gets no IP

Symptom: a cellular device never reaches the Management Protocol server

  • Wrong APN. Set the carrier APN at provisioning (default sl2sfr; e.g. orange.fr, free).
  • SIM PIN. Provide the SIM PIN if the card is locked.
  • Modem pins. Confirm the board profile (t-call, t-sim7070g) matches the hardware; the pins differ between boards (see GPRS boards).
  • Server reachability. A GPRS device is on the internet, not your LAN. The Management Protocol server must be a public address.

Module fails to compile

Symptom: Inject fails during compilation

  • Missing cross-compiler. Install the toolchain for the target chip (xtensa-esp32[-s3]-elf-gcc, or gcc-riscv32-esp-elf for C3/C6/H2). C3PO searches PATH and ~/.espressif/tools/.
  • Xtensa relocation errors at load. Modules must be compiled with -mlongcalls -mtext-section-literals; C3PO does this automatically.

Module fails to load

Symptom: mod_load returns an error

  • Signature mismatch (ESPM_ERR_SIGNATURE). The blob was signed with a different device's key. Inject from C3PO so it signs with the correct key.
  • Chip mismatch. The module's targets must include the device's chip; a Xtensa object will not load on a RISC-V chip and vice versa.
  • Out of memory (ESPM_ERR_ALLOC). The module exceeds available IRAM or the 64 KB code / 32 KB data limits. Reduce the module or use a chip with more IRAM/PSRAM.

See also