iot/spore

Fork 0

Files

Patrick Balsiger adde7a3676 docs: add FS and FileService info

2025-09-16 08:27:05 +02:00

11 KiB

Raw Blame History

Development & Deployment Guide

Prerequisites

Required Tools

PlatformIO Core or PlatformIO IDE
ESP8266 development tools
jq for JSON processing in scripts
Git for version control

System Requirements

Operating System: Linux, macOS, or Windows
Python: 3.7+ (for PlatformIO)
Memory: 4GB+ RAM recommended
Storage: 2GB+ free space for development environment

Project Structure

spore/
├── src/                    # Source code
│   ├── main.cpp           # Main application entry point
│   ├── ApiServer.cpp      # HTTP API server implementation
│   ├── ClusterManager.cpp # Cluster management logic
│   ├── NetworkManager.cpp # WiFi and network handling
│   ├── TaskManager.cpp    # Background task management
│   └── NodeContext.cpp    # Central context and events
├── include/                # Header files
├── lib/                    # Library files
├── docs/                   # Documentation
├── api/                    # OpenAPI specification
├── examples/               # Example code
├── test/                   # Test files
├── platformio.ini         # PlatformIO configuration
└── ctl.sh                 # Build and deployment scripts

PlatformIO Configuration

Framework and Board

The project uses PlatformIO with the following configuration:

[env:esp01_1m]
platform = platformio/espressif8266@^4.2.1
board = esp01_1m
framework = arduino
upload_speed = 115200
flash_mode = dout

Key Configuration Details

Framework: Arduino
Board: ESP-01 with 1MB flash
Upload Speed: 115200 baud
Flash Mode: DOUT (required for ESP-01S)
Build Type: Release (optimized for production)

Dependencies

The project requires the following libraries:

lib_deps =
    esp32async/ESPAsyncWebServer@^3.8.0
    bblanchon/ArduinoJson@^7.4.2
    arkhipenko/TaskScheduler@^3.8.5
    ESP8266HTTPClient@1.2
    ESP8266WiFi@1.0

Filesystem, Linker Scripts, and Flash Layout

This project uses LittleFS as the filesystem on ESP8266. Flash layout is controlled by the linker script (ldscript) selected per environment in platformio.ini.

Filesystem: LittleFS (replaces SPIFFS). Although ldscripts reference SPIFFS in their names, the reserved region is used by LittleFS transparently.
Why ldscript matters: It defines maximum sketch size and the size of the filesystem area in flash.

Board / Env	Flash size	ldscript	Filesystem	FS size	Notes
esp01_1m	1MB	`eagle.flash.1m64.ld`	LittleFS	64KB	Prioritizes sketch size on 1MB modules. OTA is constrained on 1MB.
d1_mini	4MB	`eagle.flash.4m1m.ld`	LittleFS	1MB	Standard 4M/1M layout; ample space for firmware and data.

Configured in platformio.ini:

[env:esp01_1m]
board_build.filesystem = littlefs
board_build.ldscript = eagle.flash.1m64.ld

[env:d1_mini]
board_build.filesystem = littlefs
board_build.ldscript = eagle.flash.4m1m.ld

Notes:

The ldscript name indicates total flash and filesystem size (e.g., 4m1m = 4MB flash with 1MB FS; 1m64 = 1MB flash with 64KB FS).
LittleFS works within the filesystem region defined by the ldscript, despite SPIFFS naming.
If you need a different FS size, select an appropriate ldscript variant and keep board_build.filesystem = littlefs.
On ESP8266, custom partition CSVs are not used for layout; the linker script defines the flash map. This project removed prior board_build.partitions usage in favor of explicit board_build.ldscript entries per environment.

Building

Basic Build Commands

Build the firmware for specific chip:

# Build for ESP-01 1MB
./ctl.sh build target esp01_1m

# Build for D1 Mini
./ctl.sh build target d1_mini

# Build with verbose output
pio run -v

Build Targets

Available build targets:

Target	Description	Flash Size
`esp01_1m`	ESP-01 with 1MB flash	1MB
`d1_mini`	D1 Mini with 4MB flash	4MB

Build Artifacts

After successful build:

Firmware: .pio/build/{target}/firmware.bin
ELF File: .pio/build/{target}/firmware.elf
Map File: .pio/build/{target}/firmware.map

Flashing

Direct USB Flashing

Flash firmware to a connected device:

# Flash ESP-01
./ctl.sh flash target esp01_1m

# Flash D1 Mini
./ctl.sh flash target d1_mini

# Manual flash command
pio run --target upload

Flash Settings

Upload Speed: 115200 baud (optimal for ESP-01)
Flash Mode: DOUT (required for ESP-01S)
Reset Method: Hardware reset or manual reset

Troubleshooting Flashing

Common flashing issues:

Connection Failed: Check USB cable and drivers
Wrong Upload Speed: Try lower speeds (9600, 57600)
Flash Mode Error: Ensure DOUT mode for ESP-01S
Permission Denied: Run with sudo or add user to dialout group

Over-The-Air Updates

Single Node Update

Update a specific node:

# Update specific node
./ctl.sh ota update 192.168.1.100 esp01_1m

# Update with custom firmware
./ctl.sh ota update 192.168.1.100 esp01_1m custom_firmware.bin

Cluster-Wide Updates

Update all nodes in the cluster:

# Update all nodes
./ctl.sh ota all esp01_1m

OTA Process

Firmware Upload: Send firmware to target node
Verification: Check firmware integrity
Installation: Install new firmware
Restart: Node restarts with new firmware
Verification: Confirm successful update

OTA Requirements

Flash Space: Minimum 1MB for OTA updates
Network: Stable WiFi connection
Power: Stable power supply during update
Memory: Sufficient RAM for firmware processing

Cluster Management

View Cluster Status

# View all cluster members
./ctl.sh cluster members

# View specific node details
./ctl.sh cluster members --node 192.168.1.100

Cluster Commands

Available cluster management commands:

Command	Description
`members`	List all cluster members
`status`	Show cluster health status
`discover`	Force discovery process
`health`	Check cluster member health

Cluster Monitoring

Monitor cluster health in real-time:

# Watch cluster status
watch -n 5 './ctl.sh cluster members'

# Monitor specific metrics
./ctl.sh cluster members | jq '.members[] | {hostname, status, latency}'

Development Workflow

Local Development

Setup Environment:

git clone <repository>
cd spore
pio run

Make Changes:
- Edit source files in src/
- Modify headers in include/
- Update configuration in platformio.ini
Test Changes:
```
pio run
pio check
```

Testing

Run various tests:

# Code quality check
pio check

# Unit tests (if available)
pio test

# Memory usage analysis
pio run --target size

Debugging

Enable debug output:

# Serial monitoring
pio device monitor

# Build with debug symbols
pio run --environment esp01_1m --build-flags -DDEBUG

Configuration Management

Environment Setup

Create a .env file in your project root:

# API node IP for cluster management
export API_NODE=192.168.1.100

Configuration Files

Key configuration files:

platformio.ini: Build and upload configuration
src/Config.cpp: Application configuration
.env: Environment variables
ctl.sh: Build and deployment scripts

Configuration Options

Available configuration options:

Option	Default	Description
`CLUSTER_PORT`	4210	UDP discovery port
`DISCOVERY_INTERVAL`	1000	Discovery packet interval (ms)
`HEALTH_CHECK_INTERVAL`	1000	Health check interval (ms)
`API_SERVER_PORT`	80	HTTP API server port

Deployment Strategies