Aller au contenu

Installation Guide

Complete setup instructions for Espilon firmware development and C2 server deployment.

Prerequisites

System Requirements

  • Ubuntu 20.04+ / Debian 11+
  • 4GB RAM minimum
  • 5GB free disk space
  • USB port for ESP32
  • macOS 10.15+
  • 4GB RAM minimum
  • 5GB free disk space
  • USB port for ESP32
  • Windows 10/11
  • WSL2 (Ubuntu recommended)
  • 4GB RAM minimum
  • 5GB free disk space

Required Software

  • Git
  • Python 3.11 or later
  • USB-to-UART drivers (CH340, CP2102, or CH9102)

Part 1: ESP-IDF Installation

ESP-IDF (Espressif IoT Development Framework) is required to build Espilon firmware.

Step 1: Install Dependencies

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

brew install cmake ninja dfu-util python3

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

Step 2: Download ESP-IDF v5.3.2

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

Step 3: Install ESP-IDF

cd ~/esp/esp-idf
./install.sh esp32

This will download the ESP32 toolchain (~1GB).

Step 4: Set Up Environment

Add to your ~/.bashrc or ~/.zshrc:

alias get_idf='. $HOME/esp/esp-idf/export.sh'

Then reload:

source ~/.bashrc  # or source ~/.zshrc

Step 5: Verify Installation

get_idf
idf.py --version

Expected output: 

ESP-IDF v5.3.2

Part 2: Clone the Repositories

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

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

# C3PO control server
git clone https://github.com/Espilon-Net/Espilon-C3PO.git

Part 3: Build Espilon Firmware

Step 1: Configure Project

cd Espilon-Firmware/espilon_bot
get_idf
idf.py menuconfig

Step 2: Configure Basic Settings

Navigate through the menu:

Espilon Bot Configuration
  ├─ Device ID: "ce4f626b" (change to unique ID)
  ├─ Network
  │   ├─ Connection Mode: [X] WiFi (or GPRS for T-Call)
  │   ├─ WiFi SSID: "YourWiFiName"
  │   └─ WiFi Password: "YourPassword"
  ├─ Server
  │   ├─ Server IP: "192.168.1.100" (your C2 server IP)
  │   └─ Server Port: 2626
  └─ Modules
      ├─ [X] Network Commands
      ├─ [ ] Recon Commands
      └─ [ ] Fake Access Point Commands

Press S to save, then Q to quit.

Step 3: Build Firmware

idf.py build

First build takes 5-10 minutes. Subsequent builds are faster.

Step 4: Flash to ESP32

Connect your ESP32 via USB, then:

# Auto-detect port and flash
idf.py flash

# Or specify port manually
idf.py -p /dev/ttyUSB0 flash

Step 5: Monitor Output

idf.py monitor

Press Ctrl+] to exit monitor.

Expected output: 

I (123) boot: ESP-IDF v5.3.2
I (456) epsilon: Device ce4f626b starting...
I (789) WiFi: Connecting to YourWiFiName
I (1234) WiFi: Connected, IP: 192.168.1.50
I (1567) epsilon: Connecting to C2: 192.168.1.100:2626
I (2345) epsilon: Connected to C2
I (2456) epsilon: Device ready

Part 4: C3PO Server Setup

Step 1: Install Dependencies

cd Espilon-C3PO
pip install -r requirements.txt

Step 2: Configure .env

cp .env.example .env
# Edit .env — change all default secrets

Mandatory changes:

FLASK_SECRET_KEY=<random_64_chars>
WEB_USERNAME=<your_username>
WEB_PASSWORD=<strong_password>
CAMERA_SECRET_TOKEN=<random_token>
MULTILAT_AUTH_TOKEN=<random_token>

Cryptographic keys are not configured here. They are generated per-device by deploy.py and stored in keys.json.

Step 3: Provision a Device

Run deploy.py to flash the master key into the device's factory NVS partition and register it in keys.json:

python deploy.py --port /dev/ttyUSB0 --device-id ce4f626b \
    --wifi MySSID MyPassword --srv 192.168.1.100

Step 4: Start C3PO

# TUI mode (interactive terminal)
python c3po.py

# Headless mode (web dashboard + REST API, no TUI)
python c3po.py --headless

Expected output: 

[C3PO] C2 listening on 0.0.0.0:2626
[C3PO] SOCKS5 proxy on 127.0.0.1:1080, tunnel listener on 0.0.0.0:2627

Step 5: Verify Connection

When an ESP32 connects, you'll see in the TUI:

[+] ce4f626b connected from 192.168.1.50

Type help in the C2 CLI to see available commands.

Part 5: Multi-Device Flasher (Optional)

For flashing multiple devices with different configs:

cd ~/epsilon/tools/flasher

Edit devices.json with your device configurations, then:

python3 flash.py --config devices.json

See Flasher Documentation for details.

Troubleshooting

ESP-IDF Installation Failed

Error: fatal error: Python.h: No such file or directory

Solution: 

sudo apt-get install python3-dev

Cannot Flash ESP32

Error: A serial exception error occurred: could not open port

Solution: Add user to dialout group: 

sudo usermod -a -G dialout $USER
# Log out and log back in

Build Failed

Error: fatal error: sdkconfig.h: No such file or directory

Solution: Run menuconfig first: 

idf.py menuconfig
# Save and quit
idf.py build

Agent Won't Connect to C2

Checks: 1. Is C2 server running? 2. Correct server IP in menuconfig? 3. Firewall blocking port 2626? 4. Agent and C2 on same network (WiFi mode)?

Solution: 

# Check C2 is listening
netstat -tln | grep 2626

# Check firewall (Linux)
sudo ufw allow 2626/tcp

Next Steps

Now that Espilon is installed:

  1. Hardware Guide - Choose the right ESP32 board
  2. Configuration Guide - Advanced settings
  3. Module Reference - Available commands

Previous: Overview | Next: Hardware