Skip to content

Quick Start Guide

Get Espilon up and running in minutes with this quick start guide.

Prerequisites

Before you begin, ensure you have:

  • ESP32 development board (DevKit, LilyGO T-Call, or ESP32-CAM)
  • USB cable (data-capable)
  • Computer running Linux, macOS, or Windows (WSL2)
  • Python 3.11 or newer
  • Git

Installation Steps

1. Install ESP-IDF

# Install dependencies
sudo apt-get update
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

# Clone ESP-IDF
mkdir -p ~/esp
cd ~/esp
git clone --recursive -b v5.3.2 \
    https://github.com/espressif/esp-idf.git

# Install toolchain
cd esp-idf
./install.sh esp32

# Set up environment
. ./export.sh

# Install Homebrew
/bin/bash -c "$(curl -fsSL \
    https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install cmake ninja ccache dfu-util python3

# Clone and install ESP-IDF
mkdir -p ~/esp
cd ~/esp
git clone --recursive -b v5.3.2 \
    https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32
. ./export.sh

# Open WSL2 terminal, then follow Linux instructions
# Ensure WSL2 is installed:
wsl --install

# Then follow the Linux tab instructions above

2. Clone the Repositories

Espilon is split into two repositories: the firmware and the C3PO control server.

# Firmware
git clone https://github.com/Espilon-Net/Espilon-Firmware.git
cd Espilon-Firmware

# In another terminal — C3PO control server
git clone https://github.com/Espilon-Net/Espilon-C3PO.git

3. Configure Firmware

cd Espilon-Firmware/espilon_bot
idf.py menuconfig

Configure the following settings:

Espilon Configuration
  ├─ Network Backend → [X] WiFi
  ├─ WiFi SSID: "YourNetwork"
  ├─ WiFi Password: "YourPassword"
  ├─ C2 Server IP: "192.168.1.100"
  └─ C2 Server Port: 2626

Espilon Configuration
  ├─ Network Backend → [X] GPRS
  ├─ GPRS APN: "your-apn"
  ├─ C2 Server IP: "your.server.ip"
  └─ C2 Server Port: 2626

Keys are managed by deploy.py

Cryptographic keys (master keys) are not configured in menuconfig. They are generated automatically by deploy.py and written to the device's NVS factory partition during provisioning. See Step 5 below.

4. Build and Flash

# Build firmware
idf.py build

# Flash to device (replace port if needed)
idf.py -p /dev/ttyUSB0 flash

Find Your Port

ls /dev/ttyUSB* /dev/ttyACM*

ls /dev/cu.*

Use Device Manager to find the COM port.

5. Provision the Device

After flashing, use deploy.py to write the master key into the device's NVS factory partition and register it with C3PO. This step binds the device to your C3PO instance.

cd Espilon-C3PO

# Install dependencies
pip install -r requirements.txt

# Provision a connected device (generates key, writes NVS, registers in keys.json)
python deploy.py --port /dev/ttyUSB0 --device-id my-device-01

# Or provide an existing 32-byte hex key
python deploy.py --port /dev/ttyUSB0 --device-id my-device-01 --key <64_hex_chars>

deploy.py will:

  1. Generate a random 32-byte master key (or use the one you provide)
  2. Flash the factory NVS partition to the device at address 0x10000
  3. Store my-device-01 → hex_key in keys.json

Backup keys.json

keys.json is the only copy of your device keys. If lost, devices must be re-provisioned. Keep an encrypted backup after every provisioning run.

6. Start C3PO

Configure the server first:

cd Espilon-C3PO
cp .env.example .env
# Edit .env — at minimum, change the default credentials

# TUI mode (default — interactive terminal)
python c3po.py

# Headless mode (web dashboard only, no TUI — ideal for servers)
python c3po.py --headless

Security Check

C3PO refuses to start if default credentials are detected in .env. Set ESPILON_ALLOW_DEFAULTS=1 to bypass (development only).

7. Verify Connection

Once the ESP32 boots, you should see in the TUI:

[+] Device ce4f626b connected from 192.168.1.42
[i] ce4f626b: INFO: heap:   187K free  (min 142K)  internal 98K
[i] ce4f626b: INFO: chip:   esp32 rev3  cores=2  tasks=14

The device appears in the device panel and its status changes to Connected.

First Commands

Commands are sent from the TUI or the web dashboard. In the TUI, select a device and type:

status                      # Full status (heap, chip, modules, uptime)
ping 8.8.8.8 5              # ICMP ping (5 packets)
arp_scan 192.168.1.0/24     # ARP scan the local subnet
system_reboot               # Reboot the device

To send commands via the web dashboard, open http://localhost:8000, log in, and use the Terminal page.

Common Issues

Device Won't Flash

Permission denied on /dev/ttyUSB0 
# Add user to dialout group
sudo usermod -a -G dialout $USER
# Log out and log back in
Failed to connect to ESP32

Put device in download mode:

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

WiFi Won't Connect

Wrong credentials
  • Verify SSID and password in menuconfig
  • Ensure the network is 2.4 GHz (ESP32 does not support 5 GHz)
Hidden SSID

Hidden SSIDs require additional configuration not enabled by default.

C3PO Won't Receive the Device

Can't reach C2 server
  • Check that port 2626 is open in your firewall
  • Verify the C2 IP address is reachable from the ESP32's network
  • Confirm C3PO is running (python c3po.py)
Decryption errors in C3PO log
  • The device ID in keys.json must match the one written during provisioning
  • Re-run deploy.py to re-provision the device if keys are out of sync

Next Steps

  • Explore Modules

    Learn about available commands and modules

    Module Reference

  • Hardware Setup

    Configure additional hardware (GPRS, Camera)

    Hardware Guide

  • C3PO Setup

    Full C3PO installation, Docker, and .env reference

    C3PO Installation

  • Security Review

    Understand the security model and best practices

    Security

Getting Help

You now have a working Espilon installation.