Upload OXRecorder firmware

1. Download the uploader and firmware

You need one uploader for your operating system and one .oxfw firmware package. The firmware package is the same on all three platforms. Uploading works offline after downloading.

Alternative formats: macOS DMG · Linux tar.gz

Download development firmware (.oxfw · 972 KiB)

Keep the .oxfw file intact: open it from the uploader without extracting or renaming it. This package is labeled development and records local source changes; it is not a stable firmware release.

SHA-256 checksums · Build verification details · Uploader source ZIP

# macOS
shasum -a 256 OXFirmwareLoader-macos-arm64.zip
# Linux
sha256sum OXFirmwareLoader-linux-x86_64.zip
# Windows PowerShell
Get-FileHash .\OXFirmwareLoader-windows-amd64.zip -Algorithm SHA256

2. Install and open the application

Windows

1. Download the ZIP, right-click it and choose Extract All.
2. Open the extracted OXFirmwareLoader folder and double-click OXFirmwareLoader.exe. Keep its _internal folder alongside the executable; do not run it from inside the ZIP.
3. The preview is unsigned and Windows may ask you to review it. Confirm that you downloaded the intended file before allowing it through your organization's normal application approval process.

macOS (Apple Silicon)

1. Extract the ZIP and copy OXFirmwareLoader.app into Applications.
2. Open the app from Applications. Keep the complete app bundle together.
3. If macOS blocks the development app, review the blocked-app entry in System Settings → Privacy & Security. Use the per-app Open Anyway option only if it is offered and you trust this download. Managed Macs may require administrator approval.

Linux (x64)

1. Extract the archive from your Downloads folder, then launch the executable:

cd ~/Downloads
unzip OXFirmwareLoader-linux-x86_64.zip
./OXFirmwareLoader/OXFirmwareLoader

Keep the whole extracted folder together. On Ubuntu, install unzip if needed with sudo apt install unzip. The archive preserves executable permission; if your extraction tool removes it, run chmod +x OXFirmwareLoader/OXFirmwareLoader.

A desktop session with normal graphics libraries is required. On a minimal Ubuntu desktop, missing EGL/GL libraries can be installed with sudo apt install libegl1 libgl1. If the serial port reports permission denied, add your account to Ubuntu's serial group and then log out and log back in:

sudo usermod -aG dialout "$USER"

Other distributions may use a different serial-access group. Run the uploader as your normal user.

3. Upload firmware, step by step

1. Prepare the recorder. Confirm that it is the supported N4R2 board. Save any recordings and recovery information you need before a development update. Connect with a USB data cable and close PlatformIO, serial monitors and other programs using this device.
2. Open the package. In the app select Open .oxfw firmware package and choose the downloaded file. Wait for Package validated. Review the version, hardware, Git revision and any dirty-build indication.
3. Select the recorder's serial port. The list refreshes automatically about every two seconds. Select the matching COM port on Windows, /dev/cu.* on macOS or /dev/ttyACM* / /dev/ttyUSB* on Linux. If uncertain, disconnect and reconnect the recorder to identify which port appears; then select it explicitly.
4. Choose the operation. For an existing compatible recorder choose Normal update — preserve configuration and recovery key. Choose Initial installation — blank board only only for a fully erased board. Initial installation cannot replace an incompatible existing installation.
5. Inspect before writing. Select Inspect recorder and review upload. The app checks the device and flash compatibility. Inspection may take time while reading flash. An incompatible chip, protected flash, bootloader or partition layout stops the operation.
6. Review and confirm. The Review upload dialog shows the chip, MAC address, firmware version and operation. Select Yes to start writing, or No to cancel. Cancel before writing is available during inspection.
7. Wait through verification. Keep USB connected and the computer awake. Cancellation and window closing are disabled after confirmation. Progress describes the current stage and may restart for another stage. The app verifies the written data and preserved regions before restarting the recorder.
8. Check the running recorder. Confirm normal startup, recording and playback, configuration and recovery-key access. Developers should also check PSRAM initialization in the firmware's boot logs. Successful flash verification does not itself confirm firmware boot.

The loader provides no whole-chip erase, layout migration or automatic rollback. A failed compatibility check needs diagnosis before another upload attempt.

Connection and recovery help

• No serial port: try another USB data cable and direct USB port. On Windows check Device Manager; if your board uses a USB bridge, use its manufacturer's driver. On Linux check serial permissions. Port names can change after entering download mode.
• Port busy: close any serial monitor or other uploader, reconnect the recorder and select its current port.
• Cannot enter download mode: on boards with BOOT and RESET buttons, hold BOOT, press and release RESET, then release BOOT. Wait for the port list to refresh and retry inspection. This common ESP32-S3 sequence still needs validation for your board revision.
• Package validation fails: re-download the complete .oxfw file and check its checksum. A raw .bin file or SDK archive is not an uploader package.
• Bootloader or layout mismatch: use a compatible package or ask the firmware maintainer to review recovery. Switching to initial installation will not bypass the check on an occupied board.
• Interrupted update: reconnect in download mode and retry the same normal update if the bootloader and partition table remain intact. A partially completed initial installation is no longer blank and requires a separately reviewed recovery procedure.
• Cancelled inspection: reset or reconnect the recorder if it remains in download mode.
• Need diagnostic details: select Show / hide diagnostics, then Save diagnostics. Include your OS, board revision, firmware version, port and the failed stage when reporting a problem. Review the saved log before sharing device identifiers.

Developer guide: build, export and upload your firmware

The firmware compiler project and the desktop uploader are separate projects. You need the actual oxrecorder-firmware project, Git, PlatformIO and Python 3.10 for the tested uploader development environment. The SDK download alone is not the full recorder firmware project.

Step 1 — Prepare the uploader source

Extract the uploader source ZIP, or use your uploader checkout. Open a terminal in its root (the folder containing pyproject.toml). Install its development dependencies:

python3.10 -m venv .venv
.venv/bin/python -m pip install -c requirements-lock.txt '.[test,build]'
.venv/bin/python -m pytest -q
.venv/bin/python -m oxfirmwareloader

py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -c requirements-lock.txt '.[test,build]'
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m oxfirmwareloader

Close the development app before continuing. Building firmware needs PlatformIO separately; confirm pio --version works in your terminal, or use the PlatformIO terminal in your IDE.

Step 2 — Connect the firmware project's export hook

From the uploader source root, run the following with the real path to your firmware project:

# macOS / Linux
.venv/bin/python scripts/install_firmware_hook.py /path/to/oxrecorder-firmware
# Windows PowerShell
.\.venv\Scripts\python.exe scripts/install_firmware_hook.py C:/Projects/oxrecorder-firmware

The helper adds these settings to the existing [env:esp32-s3-super-mini] section in the firmware project's platformio.ini. If that section already has extra_scripts, merge the hook into its list manually instead of replacing existing scripts. If the hook is already configured, check that its path points to your current uploader source folder.

[env:esp32-s3-super-mini]
; Keep all the project's existing board, build and library options.
custom_oxloader_dir = /absolute/path/to/oxrecorder-firmwareloader
extra_scripts = post:${env:esp32-s3-super-mini.custom_oxloader_dir}/scripts/platformio_export_hook.py

Use a Windows path such as C:/Projects/oxrecorder-firmwareloader when appropriate. Keep the firmware project's N4R2 QSPI PSRAM configuration and supported 4 MB partition layout; arbitrary SDK examples and other board layouts will not export as compatible packages.

Step 3 — Build and export an .oxfw package

Run from the firmware project root. Replace the Python path with the absolute path to the uploader environment created in step 1. The output directory is created by the exporter.

cd /path/to/oxrecorder-firmware
export PLATFORMIO_CORE_DIR=.pio-core
export OXLOADER_PYTHON=/absolute/path/to/oxrecorder-firmwareloader/.venv/bin/python
export OXFW_VERSION=development
export OXFW_OUTPUT="$PWD/dist/OXRecorder-development.oxfw"
pio run -e esp32-s3-super-mini

Set-Location C:/Projects/oxrecorder-firmware
$env:PLATFORMIO_CORE_DIR = '.pio-core'
$env:OXLOADER_PYTHON = 'C:/Projects/oxrecorder-firmwareloader/.venv/Scripts/python.exe'
$env:OXFW_VERSION = 'development'
$env:OXFW_OUTPUT = "$PWD/dist/OXRecorder-development.oxfw"
pio run -e esp32-s3-super-mini

Wait for a successful build and export. Without OXFW_OUTPUT, the default output is dist/esp32-s3-super-mini.oxfw in the firmware project. Use an intentional version label for each release. Git revision and dirty status are recorded automatically. Do not edit source during compilation: the hook rejects changed inputs and stale image hashes. A failed export leaves the previous package intact, so do not mistake an older output file for a successful new build.

Step 4 — Validate the package without writing to a board

From the uploader source root, run the appropriate command with your exported package path. It emits JSON Lines and returns a nonzero exit status on validation failure. This checks the archive and images; live hardware compatibility is checked later during inspection.

# macOS / Linux
.venv/bin/python -m oxfirmwareloader --worker validate --package /path/to/oxrecorder-firmware/dist/OXRecorder-development.oxfw
# Windows PowerShell
.\.venv\Scripts\python.exe -m oxfirmwareloader --worker validate --package C:/Projects/oxrecorder-firmware/dist/OXRecorder-development.oxfw

The downloaded standalone executables support the same read-only validation command, with no separate Python installation:

# macOS
/Applications/OXFirmwareLoader.app/Contents/MacOS/OXFirmwareLoader --worker validate --package ~/Downloads/OXRecorder-development.oxfw
# Linux, from the extracted archive's parent folder
./OXFirmwareLoader/OXFirmwareLoader --worker validate --package ~/Downloads/OXRecorder-development.oxfw
# Windows PowerShell, from the extracted archive's parent folder
.\OXFirmwareLoader\OXFirmwareLoader.exe --worker validate --package "$HOME/Downloads/OXRecorder-development.oxfw"

Step 5 — Upload and check the hardware

Open the newly exported .oxfw in the desktop uploader and follow the upload steps above. Check the displayed revision and version before confirming. For normal updates, confirm that configuration and recovery-key access still work afterward. Check startup, PSRAM initialization, microphone recording and playback on the actual board. Save the upload diagnostics and record the host OS and board revision with your test result.

Step 6 — Build your own uploader applications (optional)

From the uploader source root on each target OS, run the native build and smoke checks using that OS's virtual-environment Python:

# macOS / Linux
.venv/bin/python scripts/build_app.py
.venv/bin/python scripts/smoke_bundle.py
.venv/bin/python scripts/smoke_gui.py
# Windows PowerShell
.\.venv\Scripts\python.exe scripts/build_app.py
.\.venv\Scripts\python.exe scripts/smoke_bundle.py
.\.venv\Scripts\python.exe scripts/smoke_gui.py

Outputs go to dist/. Build each Mac architecture separately; the available DMG is Apple Silicon only. With Docker Desktop and x64 emulation on a development Mac, python3 scripts/build_other_platforms.py builds both Windows and Linux x64 archives. It retains build containers and writes logs to build/cross-platform. The source README and packaging directories describe signing and release preparation.

What is inside .oxfw?

An .oxfw is a ZIP containing manifest.json, bootloader.bin, partitions.bin, boot_app0.bin and firmware.bin. The manifest contains the hardware target, version, source revision, build tools, image addresses, sizes and SHA-256 hashes. The uploader validates the package before using it. Export through the build hook so the metadata describes the exact compiled images.