OXRecorder Firmware

Developer documentation & API reference

This is the central reference for every class in the OXRecorder namespace. Each class has an API reference page (what every method and parameter does, with copy-paste examples) and a How It Works page (the design and internals). Use the sidebar — or the search box in it — to navigate.

Want to reuse this code in your own project? The SDK & download page shows how to download the managers as a ready-to-use PlatformIO SDK and wire it up.

Download the OXRecorder app to set up your OX Device

Use the OXRecorder mobile app to initialize and configure your OX Device. Connect to your device over Bluetooth, set up its Wi-Fi connection, and manage its device settings from your phone.

Android

APK download

Version 1.0 · September 14, 2026 · approximately 17 MB

Requires Android 7.0 or later. This download is a debug build.

Download for Android (APK)

iOS

TestFlight beta

Install OXRecorder on your iPhone with TestFlight.

Open the invitation, install Apple's TestFlight app if prompted, then accept the invitation and install OXRecorder.

Get the iOS app via TestFlight

Android installation: Open the downloaded APK on your Android device. If prompted, allow your browser or file manager to install apps from this source, then complete the installation.

Set up your device

  1. Power on your OX Device and keep it near your phone.
  2. Open OXRecorder and sign in or create an account.
  3. Enable Bluetooth and grant the permissions requested by the app to discover nearby devices.
  4. Add your OX Device, select it from the scan results, and follow the app's instructions to configure Wi-Fi and device settings.

PSSP connects the OXRecorder system

PSSP provides communication between end devices and servers throughout the OXRecorder system. Learn how to install the broker, connect and authenticate clients, exchange application data and handle delivery and reconnection.

Download the PSSP service and client · developer guide →

Set up the broker · Test with the desktop client · Connect an end device and server · Protocol reference

Upload firmware to your recorder

Download the USB firmware uploader for Windows x64, macOS Apple Silicon or Linux x64, then open an .oxfw package to update your recorder. Python and the upload tools are included.

Firmware uploader downloads & step-by-step instructions →

Developer guide: build, export, validate and upload your own firmware

Current downloads are development previews for the ESP32-S3 Super Mini N4R2. See the guide for platform requirements and validation status.

Hardware blueprint

The OXRecorder hardware is an ESP32-S3 Super Mini with three peripherals: an INMP441 microphone (I2S), a microSD adapter (SPI), and a WS2812 status LED, powered by a 3.7 V LiPo battery through a TP4056, plus a battery-sense divider on GPIO7 and a reset button on GPIO8. The full pin map is below — anyone with this page can build the board. Each peripheral's detailed wiring is on its How It Works page (mic, SD, LED, battery sense).

Battery 3.7 V LiPo + − TP4056 charge + boost 3.7 V → 5 V out 5V GND 5 V rail Battery sense GPIO7 ADC raw cell VCC 1k 1k midpoint ESP32-S3 Super Mini 5V GND GPIO7 ADC GPIO3 GPIO5 GPIO4 3V3 out GPIO13 GPIO12 GPIO10 GPIO11 GPIO9 GPIO8 INMP441 I2S mic SCK WS SD VDD 3V3 L/R → GND microSD SPI adapter CS SCK MISO MOSI VCC 3V3 GND 10uF WS2812 status LED DIN 5V 330 Ω 3V3→5V Reset button hold 10 s → reset GPIO8 GND
data clock / resistors power (5V / 3V3) ground

OXRecorder hardware blueprint — power: Battery → TP4056 (5 V) → ESP32-S3, microSD & INMP441 on the ESP32's 3V3 output; GPIO7 senses the raw battery VCC/GND terminals through a 1k/1k divider, not the TP4056 output rail; 10uF across microSD VCC/GND; 330 Ω and a level shifter on the WS2812 data line if the LED runs at 5 V.

PeripheralPeripheral pinESP32-S3 Super MiniManaged by
INMP441 mic (I2S)SCKGPIO3OXAudioManager
WSGPIO5
SDGPIO4
L/RGND
microSD (SPI)CSGPIO13OXFileManager
SCKGPIO12
MISOGPIO10
MOSIGPIO11
VCC3V3 with 10uF to GND at adapter
GNDGND
Battery sense dividertop resistor 1kraw battery VCC / cell +, before TP4056 outputOXBatteryManager
midpointGPIO7 (ADC)
bottom resistor 1kraw battery GND / cell −
WS2812 LEDDINGPIO9 via 330 Ω; level shift if LED VDD is 5 VOXLEDManager
Reset buttonterminal AGPIO8OXConfigManager — hold 10 s to reset
terminal BGND

Signal pins are the firmware defaults and can be overridden in each manager's begin(). Internal flash storage (LittleFS) needs no wiring.

Power topology

The 3.7 V LiPo feeds a TP4056 module, which charges the cell and boosts its output to 5 V. That 5 V rail powers the ESP32-S3 Super Mini (5V pin). The INMP441 and a 3.3 V-compatible microSD adapter run from the ESP32-S3's regulated 3V3 output, not the 5 V rail.

FromToRailNotes
Battery 3.7 V (+/−)TP4056 B+ / B−3.7 VCharge + protect the cell.
TP4056 OUT 5 VESP32-S3 Super Mini 5V5 VBoosted output powers the MCU board.
ESP32-S3 3V3 outmicroSD VCC3.3 VUse an adapter with 3.3 V MISO; place 10uF from VCC to GND near the adapter.
TP4056 OUT 5 VWS2812 5V5 VUse a 3.3 V-to-5 V level shifter between GPIO9 and DIN.
Battery cell + / −GPIO7 through 1k/1k dividerADC senseTop resistor goes to raw battery VCC; bottom resistor goes to raw battery GND. Do not connect this divider to TP4056 OUT 5 V.
ESP32-S3 3V3 outINMP441 VDD3.3 VMic runs on the MCU's regulated 3.3 V only.
Common GNDall devices—TP4056, MCU, mic, SD, and LED share ground.

The ESP32-S3 GPIOs are not 5 V tolerant. Keep the SD bus at 3.3 V, and add a 3.3 V-to-5 V level shifter after the 330 Ω series resistor when the WS2812 runs at 5 V. The SD adapter should have a local 10uF capacitor from VCC to GND to absorb card current spikes. The INMP441 is kept on 3.3 V because it is a 1.8–3.6 V part.

Classes