Firmware Validation Tools

This guide details the internal tools used to validate the ELRS Mobile application’s firmware assembly logic against official “Golden” binaries.

Ground Truth vs. Configurator Binaries

When running validation audits, 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 ExpressLRS Configurator (Python).

This is expected behavior. The ESP32's internal C++ JSON parser ignores whitespace, meaning both binaries execute identically on hardware despite failing a strict byte-for-byte SHA256 comparison due to minification differences.

---

1. ExpressLRS Logic Validator (Dart)

Location: firmware_testing/scripts/dart/logic_validator.dart

The Logic Validator is a high-performance bit-level comparison tool. It is designed to verify that ELRS Mobile’s internal patching and assembly logic mirrors the official ExpressLRS logic.

Key Features

• Bit-Level Analysis: Pinpoints exact bit-offset failures within discrepant bytes.
• Interactive Selection: Lists all binaries found in firmware_testing/binaries/.
• Zero-Copy Memory Management: Optimized for high-speed analysis of large firmware files.

How to Use

1. Prepare Binaries: Place the generated .bin or .gz files in firmware_testing/binaries/.
2. Setup & Run:

   cd firmware_testing/scripts/dart/
   dart pub get
   dart run logic_validator.dart

---

2. Ground Truth Auditor (Python)

Location: firmware_testing/scripts/python/audit_tool.py

The Auditor is a standalone, zero-dependency script intended for “Ground Truth” verification. It parses the 2704-byte configuration block appended to the end of every ExpressLRS firmware image.

Purpose

It verifies that the metadata actually flashed to the device (Product Name, Lua Name, Hardware Layout, and Options) is correct, regardless of any layout differences in the base firmware code.

How to Use

1. Run directly:

   python3 firmware_testing/scripts/python/audit_tool.py [file1] [file2]

---

3. Binary Cross-Validation Workflow

To ensure ELRS Mobile is assembling firmware correctly, developers should periodically perform a cross-validation audit against a “Ground Truth” binary compiled on a PC.

1

Export Binary from ELRS Mobile

Enable Expert Mode in Settings, then use the DOWNLOAD BINARY button in the Flasher tab after configuring your target and options.

2

Generate PC Ground Truth

Build the exact same target and version with identical options using the official ExpressLRS Configurator on your PC.

3

Run the Audit

Place both binaries in firmware_testing/binaries/ and run the audit_tool.py script to verify perfect hardware and options parity.