SFP Tool is a field device for reading and programming transceiver modules. It combines custom hardware, ESP32-S3 firmware, a React and Tauri user interface, and a small firmware recovery web app.
The hardware is built around an ESP32-S3, chosen
for:
The hardware design includes:
128x64 OLED.The firmware supports two OLED controller families:
SSD1306SH1106The firmware currently distinguishes two hardware revisions:
1.01.1Revision 1.1 is the default current revision and
includes battery support. Revision 1.0 does not have a
battery gauge.
Current firmware configuration defines:
GPIO_I2C_SDA = 21GPIO_I2C_SCL = 47GPIO_PWR_SW = 45GPIO_SFP_PRESENT = 39GPIO_QSFP_PRESENT = 40GPIO_QSFP_LPMODE = 35GPIO_SFP_TX_FAULT = 38GPIO_SFP_TX = 37GPIO_BTN_UP = 5GPIO_BTN_OK = 6GPIO_BTN_DOWN = 7Battery-aware firmware builds use an RT9426 battery
gauge and enforce low-voltage protection. The configured battery
safeguards include:
60 mA3000 mV3000 msIf the battery remains below the configured threshold long enough, the tool powers off to protect the cell.
The PCB export in pcb/info contains a machine-generated
bill of materials with components such as:
That file should be treated as the source for manufacturing detail. This reference intentionally stays at the architectural level.
The firmware is implemented with Arduino on top of PlatformIO for the ESP32-S3 target.
Primary firmware areas visible in the source tree include:
The firmware is designed to execute as much device functionality as possible locally so the tool remains useful without a permanently attached app host.
The main firmware includes several recovery-oriented behaviors:
These mechanisms reduce the chance that a bad build leaves the tool permanently inaccessible.
The firmware stores tool-specific configuration in ESP preferences, including:
The app communicates with the tool over a custom BLE service:
e33cfd9a-883f-4627-b483-76cb710147f0The application uses dedicated characteristics for settings, EEPROM access, password workflows, scripting, telemetry, and firmware updates.
Desktop service workflows can also use USB HID transport. This avoids BLE throughput limits and is preferred for large transfers such as firmware upload.
The main app is built with:
192Desktop builds use Tauri, while Android builds use the generated mobile wrapper. The feature set is intended to stay aligned across supported platforms.
The app routes between these major pages:
The scripts feature provides a small domain-specific workflow for deterministic EEPROM programming. Supported command families include:
name, vendor,
model, part, revision,
serialbytespasswordchecksumwriteThe UI validates syntax before execution and requires
write to be present.
The app and firmware support:
Password change currently requires both old and new passwords as exactly 4-byte values expressed as 8 hexadecimal characters.
There are two main update paths:
The app detects whether an image is app-only or a merged ESP image and skips the bootloader region when needed.
The software/Firmwareupdater project is a small web
frontend based on esp-web-tools. It publishes a
browser-based installer that can flash the firmware from a manifest
hosted alongside release artifacts.
The repository includes external/TransceiverTool, a C++
parser and assembler for transceiver standards data. It contains support
code for:
The app builds a WebAssembly variant so parsing and pretty-printing logic can be reused in the frontend.
The CI pipeline currently covers:
Documentation is generated from Markdown during CI and exported as both HTML and PDF.
Important repository locations:
software/MCU/SFP Tool/: ESP32 firmwaresoftware/App/SFP-Tool/: React and Tauri appsoftware/Firmwareupdater/: browser recovery
updatersoftware/buildenvironment/: shared CI build imageexternal/TransceiverTool/: transceiver parsing and
formatting librarypcb/: hardware manufacturing and BOM exportsdocs/: published documentation sources