OTA Firmware Update Server

Project Overview

Key Features

Project Structure

Root Directory Structure

/var/www/ota-server/ Directory

Main project directory containing the Python FastAPI server and ESP32 client code.

/var/www/ota-server/storage/ Directory

Centralized storage directory for all firmware-related files. Organized into subdirectories for different file types.

/var/www/server/ Directory

Additional server directory containing reference code for cryptographic operations.

System Architecture

High-Level Architecture

Update Flow Diagram

Component Details

Server Components

server.py - FastAPI Application

patch_utils.py - Binary Patching

crypto_utils.py - Cryptography

Client Components (ESP32)

src/main.cpp - ESP32 Main Application

lib/bspatch_stub/ - Patch Application Library

API Endpoints

Server Endpoints

{
  "status": "ok",
  "stored": "storage/firmware/firmware_1.0.1.bin"
}

{
  "status": "ok",
  "patch": "storage/patches/patch_1.0.0_to_1.0.1.bsdiff.enc",
  "signature": "storage/signatures/patch_1.0.0_to_1.0.1.sig"
}

{
  "status": "update_queued"
}

{
  "update_available": true,
  "old_version": "1.0.0",
  "new_version": "1.0.1",
  "patch_url": "/get_patch/1.0.0/1.0.1/esp32_01",
  "signature_url": "/get_signature/1.0.0/1.0.1"
}

{
  "update_available": false
}

Security Features

Cryptographic Protection

Security Best Practices

Attack Mitigation

Setup & Usage Guide

Server Setup

1. Install Dependencies

cd /var/www/ota-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Install System Dependencies

# Install bsdiff/bspatch tools
sudo apt-get update
sudo apt-get install bsdiff

# Or compile from source if not available in package manager
# https://github.com/mendsley/bsdiff

3. Generate Cryptographic Keys

# Generate ECC key pair for signing
openssl ecparam -genkey -name secp256r1 -noout -out ecc_private.pem
openssl ec -in ecc_private.pem -pubout -out ecc_public.pem

# Set secure permissions
chmod 600 ecc_private.pem

4. Configure Server

• Update DEVICE_AES_KEY in server.py (or use key management)
• Ensure ecc_private.pem is in the project directory
• Create storage directories if they don't exist

5. Run Server

source venv/bin/activate
uvicorn server:app --host 0.0.0.0 --port 8000

Method 1: Using PlatformIO (Recommended)

Step 1: Install PlatformIO

# Install PlatformIO Core
pip install platformio

# Or install PlatformIO IDE (VS Code extension)
# https://platformio.org/install/ide?install=vscode

Step 2: Create platformio.ini Configuration

Create a platformio.ini file in /var/www/ota-server/:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino

lib_deps = 
    adafruit/Adafruit SSD1306@^2.5.7
    adafruit/Adafruit GFX Library@^1.11.9

upload_speed = 921600
monitor_speed = 115200

board_build.filesystem = littlefs

Step 3: Configure WiFi and Server Settings

Open src/main.cpp and update these configuration values (lines 17-32):

// ---------- CONFIG: set these ----------
const char* WIFI_SSID = "YourWiFiNetwork";        // Your WiFi network name
const char* WIFI_PASS = "YourWiFiPassword";        // Your WiFi password

const char* SERVER_HOST = "84.46.255.218";        // Your server IP or domain
const uint16_t SERVER_PORT = 8000;                 // Server port (usually 8000)
const char* DEVICE_ID = "esp32_01";                // Unique device identifier

// AES-256 per-device key (32 bytes) - MUST MATCH SERVER KEY
// This key must be the same in server.py DEVICE_AES_KEY
const uint8_t DEVICE_AES_KEY[32] = {
  0x00,0x11,0x22,0x33,0x44,0x55,0x66,0x77,0x88,0x99,0xAA,0xBB,0xCC,0xDD,0xEE,0xFF,
  0x00,0x11,0x22,0x33,0x44,0x55,0x66,0x77,0x88,0x99,0xAA,0xBB,0xCC,0xDD,0xEE,0xFF
};

Step 4: Generate and Prepare Server Public Key

On your server, generate the public key file if you haven't already:

# Generate ECC key pair (if not done already)
cd /var/www/ota-server
openssl ecparam -genkey -name secp256r1 -noout -out ecc_private.pem
openssl ec -in ecc_private.pem -pubout -out ecc_public.pem

# Copy public key to data directory for ESP32
mkdir -p data
cp ecc_public.pem data/server_pub.pem

Step 5: Upload Files to ESP32 LittleFS

Upload the public key file to ESP32's LittleFS filesystem:

cd /var/www/ota-server
platformio run --target uploadfs

This uploads all files from the data/ directory to ESP32's LittleFS.

Step 6: Compile and Upload Firmware

cd /var/www/ota-server
platformio run --target upload

This will compile the code and upload it to your ESP32.

Step 7: Monitor Serial Output

platformio device monitor

Or use Arduino Serial Monitor at 115200 baud to see connection status and debug messages.

Method 2: Using Arduino IDE

Step 1: Install ESP32 Board Support

1. Open Arduino IDE
2. Go to File → Preferences
3. Add this URL to "Additional Board Manager URLs":
   https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
4. Go to Tools → Board → Boards Manager
5. Search for "ESP32" and install "esp32 by Espressif Systems"

Step 2: Install Required Libraries

1. Go to Sketch → Include Library → Manage Libraries
2. Install these libraries:
   • Adafruit SSD1306 by Adafruit
   • Adafruit GFX Library by Adafruit

Step 3: Configure Board Settings

Go to Tools → Board and select your ESP32 board (e.g., "ESP32 Dev Module")

Configure these settings:

• Upload Speed: 921600
• CPU Frequency: 240MHz
• Flash Frequency: 80MHz
• Flash Mode: QIO
• Flash Size: 4MB (or your board's size)
• Partition Scheme: Default 4MB with spiffs (or OTA if available)
• Port: Select your ESP32's COM port

Step 4: Configure WiFi and Server

Same as PlatformIO Method - edit src/main.cpp lines 17-32 with your settings.

Step 5: Upload Server Public Key

For Arduino IDE, you'll need a SPIFFS/LittleFS uploader plugin:

1. Install "ESP32 Filesystem Uploader" plugin from Arduino Library Manager
2. Create data/server_pub.pem with your server's public key
3. Use Tools → ESP32 Sketch Data Upload to upload the data folder

Or manually copy the public key content and paste it into a file in the data directory.

Step 6: Compile and Upload

Click the Upload button (→) in Arduino IDE to compile and upload to ESP32.

Connection Testing

WiFi connecting...
WiFi connected
PUBKEY found
Starting update flow demo...

# On server, monitor logs
tail -f /var/log/your-server.log
# Or if using uvicorn directly, you'll see HTTP requests in terminal

Matching Server and Device Configuration

Network Requirements

Optional: Disable OLED Displays

If you don't have OLED displays, you can comment out OLED-related code or the code will handle missing displays gracefully. The Serial Monitor will still show all status information.

Quick Reference: Configuration Values

# 1. Generate keys
openssl ecparam -genkey -name secp256r1 -noout -out ecc_private.pem
openssl ec -in ecc_private.pem -pubout -out ecc_public.pem
cp ecc_public.pem data/server_pub.pem

# 2. Edit src/main.cpp with your WiFi and server settings

# 3. Upload public key to ESP32
platformio run --target uploadfs

# 4. Upload firmware
platformio run --target upload

# 5. Monitor connection
platformio device monitor

Setup & Usage Guide

Usage Workflow

curl -X POST "http://your-server:8000/upload_firmware/" \
  -F "version=1.0.1" \
  -F "file=@firmware_1.0.1.bin"

curl -X POST "http://your-server:8000/make_patch/" \
  -F "old_version=1.0.0" \
  -F "new_version=1.0.1"

curl -X POST "http://your-server:8000/instruct_update/" \
  -F "device_id=esp32_01" \
  -F "old_version=1.0.0" \
  -F "new_version=1.0.1"

Testing