dirigera2mqtt

A web service for patching ESP32-C6 firmware with WiFi credentials and DIRIGERA configuration for MQTT bridge functionality. This service allows you to dynamically configure firmware images with network settings and authentication tokens without rebuilding the firmware.

Features

• Dynamic Firmware Patching: Modify ESP32-C6 firmware with custom WiFi and DIRIGERA settings
• Checksum Integrity: Automatically recalculates and updates firmware checksums after patching
• Web API: RESTful API for easy integration with build systems and deployment pipelines
• CORS Support: Cross-origin requests enabled for web-based tools
• Multiple Parameters: Support for WiFi credentials, Liquid addresses, DIRIGERA tokens, and URIs

Installation & Setup

Prerequisites

• Go 1.19 or later
• ESP32-C6 firmware binary file

Building from Source

1. Clone the repository:

git clone https://github.com/rddl-network/dirigera2mqtt.git
cd dirigera2mqtt

2. Install dependencies:

go mod download

3. Build the application:

go build -o dirigera2mqtt ./cmd/dirigera2mqtt

Configuration

Create an app.env file in the same directory as the binary:

FIRMWARE_ESP32C6=/path/to/your/firmware.bin
SERVICE_BIND=localhost
SERVICE_PORT=8080
LOG_LEVEL=info

Running the Service

./dirigera2mqtt

The service will start on the configured port (default: 8080) and load the specified firmware file.

API Documentation

POST /firmware/:mcu

Patches firmware with the provided configuration parameters and returns the modified firmware binary.

Supported MCUs:

• esp32c6 - ESP32-C6 microcontroller

Request Body (JSON):

Required parameters:

• ssid (string): WiFi network name
• pwd (string): WiFi password

Optional parameters:

• liquid_address (string): Liquid network address for blockchain operations
• dir_auth_token (string): DIRIGERA authentication token
• dir_uri (string): DIRIGERA service URI endpoint

{
	"ssid": "MyWiFiNetwork",
	"pwd": "MyWiFiPassword",
	"liquid_address": "lq1qq...",
	"dir_auth_token": "your-dirigera-token",
	"dir_uri": "https://dirigera.local"
}

Response:

• Content-Type: application/octet-stream
• Content-Disposition: attachment; filename=dirigerac2mqtt_esp32c6.bin
• Body: Patched firmware binary

Example curl commands:

Basic usage with WiFi credentials only:

curl -X POST http://localhost:8080/firmware/esp32c6 \
	-H "Content-Type: application/json" \
	-d '{"ssid":"MyWiFiNetwork","pwd":"MyWiFiPassword"}' \
	-o patched_firmware.bin

Full configuration with all parameters:

curl -X POST http://localhost:8080/firmware/esp32c6 \
	-H "Content-Type: application/json" \
	-d '{
		"ssid": "MyWiFiNetwork",
		"pwd": "MyWiFiPassword",
		"liquid_address": "lq1qq...",
		"dir_auth_token": "your-dirigera-token",
		"dir_uri": "https://dirigera.local"
	}' \
	-o patched_firmware.bin

How It Works

1. Firmware Loading: The service loads the base ESP32-C6 firmware on startup and validates its integrity
2. Pattern Matching: When a patch request is received, the service searches for predefined patterns in the firmware
3. Value Replacement: WiFi credentials and DIRIGERA settings replace placeholder values in the firmware
4. Checksum Update: The firmware checksum is recalculated to maintain integrity
5. Binary Response: The patched firmware is returned as a downloadable binary file

Firmware Requirements

The ESP32-C6 firmware must contain the following placeholder patterns for patching:

• WiFi SSID: "WIFI SSID" + padding to 64 bytes
• WiFi Password: "WIFI PASSWORD" + padding to 64 bytes
• Liquid Address: "LIQUID ADDRESS" + padding to 64 bytes
• DIRIGERA Token: "DIRIGERA TOKEN" + padding to appropriate length
• DIRIGERA URI: "DIRIGERA URI" + padding to 64 bytes

Development

Running Tests

go test ./...

Linting

golangci-lint run .

Project Structure

.
├── cmd/dirigera2mqtt/       # Main application entry point
├── config/                  # Configuration management
├── service/                 # Core service logic
│   ├── firmware.go         # Firmware patching functions
│   ├── router.go           # HTTP route handlers
│   └── service.go          # Service initialization
└── types/                  # Type definitions

License

See LICENSE file for details.