Aller au contenu

Troubleshooting Guide

Common issues and solutions for Espilon.

Installation Issues

ESP-IDF Installation

Command not found: idf.py

Cause: ESP-IDF environment not sourced.

Solution: 

# Source ESP-IDF environment
. ~/esp/esp-idf/export.sh

# Or add to .bashrc for permanent setup
echo '. ~/esp/esp-idf/export.sh' >> ~/.bashrc

Python version error

Cause: ESP-IDF requires Python 3.8+

Solution: 

# Check Python version
python3 --version

# Install Python 3.8+ if needed
sudo apt install python3.8 python3.8-venv

Missing dependencies

Cause: Build tools not installed.

Solution: 

# Ubuntu/Debian
sudo apt-get install git wget flex bison gperf python3 \
    python3-pip python3-venv cmake ninja-build ccache \
    libffi-dev libssl-dev dfu-util libusb-1.0-0

# macOS
brew install cmake ninja ccache dfu-util python3

Compilation Errors

Component not found

Cause: Submodules not initialized.

Solution: 

cd espilon
git submodule update --init --recursive

PSRAM not available

Cause: Board doesn't have PSRAM or not enabled.

Solution: 

idf.py menuconfig
# Navigate to: Component config -> ESP32-specific
# Enable: Support for external, SPI-connected RAM

Linker error: region 'iram0_0_seg' overflowed

Cause: Code too large for IRAM.

Solution: 

idf.py menuconfig
# Component config -> ESP32-specific -> Instruction cache
# Try: "32KB instruction cache, 32KB line size"

# Or disable unused modules
# Espilon Configuration -> Module Selection

Flashing Issues

Device Not Detected

Permission denied on /dev/ttyUSB0

Cause: User not in dialout group.

Solution: 

# Add user to dialout group
sudo usermod -a -G dialout $USER

# Logout and login again
# Or use sudo (not recommended)
sudo idf.py -p /dev/ttyUSB0 flash

Device not found

Cause: Wrong port or driver issue.

Solution: 

# List available ports
ls /dev/ttyUSB* /dev/ttyACM*

# Check dmesg for device
dmesg | grep -i usb | tail -20

# Install drivers if needed (CH340)
sudo apt install ch341

No serial data received

Cause: USB cable is charge-only (no data).

Solution:

  • Use a data-capable USB cable
  • Try a different USB port
  • Test with another device

Flash Failed

Failed to connect to ESP32: Timed out

Cause: ESP32 not in download mode.

Solution:

  1. Hold BOOT button
  2. Press and release RESET button
  3. Release BOOT button
  4. Try flashing again

For ESP32-CAM:

  1. Connect GPIO 0 to GND
  2. Power cycle
  3. Flash
  4. Disconnect GPIO 0
  5. Power cycle again
A fatal error occurred: Packet content transfer stopped

Cause: Power issue during flash.

Solution:

  • Use external 5V power supply
  • Reduce baud rate: idf.py -p /dev/ttyUSB0 -b 115200 flash
  • Try shorter USB cable
Flash encryption check failed

Cause: Device has flash encryption enabled.

Solution:

  • Flash encryption cannot be disabled once enabled
  • Use a new ESP32 module
  • Or use encrypted firmware

Network Issues

WiFi Connection

WiFi won't connect

Checks:

  1. SSID and password correct?
  2. 2.4GHz network? (ESP32 doesn't support 5GHz)
  3. Router allows new connections?

Debug: 

idf.py monitor
# Look for WiFi connection logs

WiFi keeps disconnecting

Cause: Weak signal or power issues.

Solution:

  • Move closer to access point
  • Use external antenna (if available)
  • Check power supply stability
  • Reduce TX power in menuconfig
Can't find hidden SSID

Cause: Hidden SSIDs require specific handling.

Solution: 

idf.py menuconfig
# Espilon Configuration -> WiFi Settings
# Enable: Scan for hidden APs

GPRS Connection

SIM800 not responding

Checks:

  1. Antenna connected?
  2. SIM card inserted correctly?
  3. SIM PIN disabled?
  4. Power supply adequate?

Debug: 

idf.py monitor
# Look for "AT -> OK" responses

Network registration failed

Cause: No signal or SIM issue.

Solution:

  1. Check SIM is active (has credit/data)
  2. Verify APN settings
  3. Try better antenna placement
  4. Check signal strength in logs
GPRS activation failed

Cause: Wrong APN settings.

Solution: 

idf.py menuconfig
# Espilon Configuration -> GPRS Settings
# Set correct APN for your carrier

Common APNs:

Carrier APN
SFR (FR) sl2sfr
Orange (FR) orange.fr
AT&T (US) phone
T-Mobile (US) fast.t-mobile.com

C2 Connection

Can't connect to C2 server

Checks:

  1. C2 server running?
  2. Correct IP address in firmware?
  3. Correct port?
  4. Firewall allows connection?

Debug: 

# On C2 server
nc -l 2626

# Check firewall
sudo ufw status
sudo ufw allow 2626

Connection established but no commands work

Cause: Encryption key mismatch.

Solution:

  1. Verify keys are identical in C2 and firmware
  2. Keys must be exact hex strings
  3. Key = 32 bytes (64 hex chars)
  4. Nonce = 12 bytes (24 hex chars)
Connection drops after a few seconds

Cause: Timeout or keepalive issue.

Solution: 

// C2 config.json
{
  "server": {
    "timeout": 60,
    "keepalive_interval": 30
  }
}

Command Issues

Commands Not Working

Command not recognized

Cause: Module not enabled or command misspelled.

Solution: 

# Check enabled modules
c3po> send device_id help

# Verify module is enabled in firmware
idf.py menuconfig
# Espilon Configuration -> Module Selection

Command timeout

Cause: Command takes too long or failed.

Solution:

  • Increase timeout for long operations
  • Check device logs for errors
  • Verify network stability
Permission denied for command

Cause: Command requires elevated privileges.

Solution:

  • Some commands are restricted by design
  • Check command documentation
  • Verify firmware configuration

Specific Commands

ARP scan returns no results

Checks:

  1. Correct network range?
  2. Device on same network?
  3. Network allows ARP?

Debug: 

# Try smaller range first
c3po> send device_id arp_scan 192.168.1.1/28

Ping always fails

Checks:

  1. Target IP reachable from device's network?
  2. Target allows ICMP?
  3. Network firewall blocks ICMP?

Debug: 

# Try pinging gateway first
c3po> send device_id ping 192.168.1.1 3

FakeAP not visible

Checks:

  1. FakeAP module enabled?
  2. Not on same channel as connected AP?
  3. Device supports AP mode?

Solution: 

# Start with default settings
c3po> send device_id fakeap_start "TestAP"

# Check logs for errors
idf.py monitor

Camera Issues (ESP32-CAM)

Camera init failed

Checks:

  1. PSRAM enabled in menuconfig?
  2. Camera ribbon cable secure?
  3. Correct camera model selected?

Solution: 

idf.py menuconfig
# Component config -> ESP32-specific
# [X] Support for external, SPI-connected RAM

# Espilon Configuration -> Recon Module
# Camera Model: AI-Thinker ESP32-CAM

Images are too dark

Solution: 

# Enable flash LED
c3po> send cam_agent capture_settings flash on

# Adjust brightness
c3po> send cam_agent capture_settings brightness 2

Capture causes reboot

Cause: Power supply insufficient.

Solution:

  • Use external 5V 1A+ power supply
  • Add 100uF capacitor across power pins
  • Reduce resolution: capture_settings resolution QVGA

Performance Issues

Device runs slowly

Cause: Memory pressure or CPU overload.

Debug: 

c3po> send device_id system_mem
# Check free heap memory

Solution:

  • Disable unused modules
  • Reduce concurrent operations
  • Use smaller buffers in menuconfig
Frequent disconnects

Cause: WiFi interference or power issues.

Solution:

  • Use stable power supply
  • Reduce WiFi TX power
  • Use external antenna
  • Move away from interference sources
Commands take too long

Cause: Network latency or command complexity.

Solution:

  • Check network latency with ping
  • Break complex commands into smaller ones
  • Increase C2 timeout settings

Recovery

Factory Reset

If device is in unknown state:

# Erase flash completely
idf.py -p /dev/ttyUSB0 erase_flash

# Reflash firmware
idf.py -p /dev/ttyUSB0 flash

Safe Mode

Boot with minimal configuration:

  1. Hold BOOT button during power-up
  2. Device starts with default settings
  3. Reconfigure via serial console

Serial Console Debug

Connect and monitor serial output:

# Start monitor
idf.py monitor

# Or use screen
screen /dev/ttyUSB0 115200

# Or use minicom
minicom -D /dev/ttyUSB0 -b 115200

Getting Help

If you can't resolve the issue:

  1. Check logs: Use idf.py monitor for detailed output
  2. Search issues: GitHub Issues
  3. Ask community: GitHub Discussions
  4. Report bug: Create a new issue with:
  5. ESP-IDF version
  6. Board type
  7. Error messages
  8. Steps to reproduce

See also: FAQ | Quick Start