Development Guide

Development Guide

& Firmware Auditing

Note on Firmware Auditing and Byte-Perfect Matches

When running Ground Truth audit tools, you may notice that binaries generated by ELRS Mobile perfectly match the official ExpressLRS Web Flasher, but diverge slightly from binaries built using the local Python ExpressLRS Configurator.

This is expected behavior and does not affect hardware compatibility. The local Configurator uses Python’s json.dumps() to assemble configuration metadata, which injects whitespace after colons and commas (e.g., {"uid":, "domain": 1}). ELRS Mobile and the official Web Flasher use dense, minified JSON (e.g., {"uid":,"domain":1}). The ESP32’s internal C++ JSON parser ignores whitespace, meaning both binaries execute identically on the hardware despite failing a strict byte-for-byte SHA256 comparison.

Firmware Testing Suite

The primary testing suite used to validate the app’s internal firmware assembly logic is located in the firmware_testing/ directory. It houses firmware binaries in firmware_testing/binaries/ and contains two main scripts used to compare generated binaries against official ExpressLRS (“Golden”) binaries.

1. ExpressLRS Logic Validator (Dart)

Location: firmware_testing/scripts/dart/logic_validator.dart Purpose: A low-level, high-performance tool that performs a bit-by-bit comparison between two firmware binaries (.bin or .gz), highlighting exactly where they diverge. It is built to verify the internal logic mirroring of the core package:binary logic.

How to Use:

1. Navigate to the firmware_testing/scripts/dart/ directory.
2. Run dart pub get to install dependencies.
3. Run dart run logic_validator.dart to start the interactive CLI.
4. The tool will list all binaries found in firmware_testing/binaries/. Select the two binaries you want to compare by index.

Interpreting Results: The tool checks for identical sizes and then compares the files bit by bit. It creates a detailed, timestamped log file in the firmware_testing/logs/ folder. For any mismatch, the log will output the exact offset address, the hex value of both files at that byte, and pinpoint exactly which bit differs.

2. Ground Truth Auditor (Python)

Location: firmware_testing/scripts/python/audit_tool.py Purpose: An independent, zero-dependency Python script designed for “Ground Truth” verification. It acts as an external auditor to parse and validate the configuration block packed at the very end of an ESP8285/ESP32 firmware image.

How to Use:

1. From any directory, run python firmware_testing/scripts/python/audit_tool.py [file1] [file2].
2. If you don’t supply file paths, the script will launch in interactive mode, listing the binaries in firmware_testing/binaries/ for selection.

Interpreting Results: First, the auditor calculates the SHA-256 hash. If they match identically, it reports success. If they differ, it performs a deep inspection of the configuration chunk (the final 2704 bytes), dissecting the Product Name, Lua Name, Hardware JSON, and Options JSON. It compares the inner contents (ignoring the randomized flash-discriminator within the JSON). Any divergences discovered during this block inspection are printed to the console and detailed in a log file generated in firmware_testing/logs/. If everything matches except the hash, the auditor will note that the config blocks match perfectly, but differences remain in the base firmware segments (often due to padding or JSON minification differences).