# Totem Compass Firmware

> Reverse-engineering documentation for the Totem Compass ESP32 firmware (v5.0.3).

- [Totem Compass Firmware](https://totem-cb8b3887.mintlify.app/index.md): Reverse-engineering documentation for the Totem Compass ESP32 firmware, version 5.0.3.
- [Firmware image](https://totem-cb8b3887.mintlify.app/firmware/overview.md): The ESP32 application image: header, segments, footer, and build metadata.
- [What changed in 5.0.3](https://totem-cb8b3887.mintlify.app/firmware/changes-5.0.3.md): Function-level differences between firmware v5.0.2 (release 335) and v5.0.3 (release 339).
- [Application architecture](https://totem-cb8b3887.mintlify.app/firmware/architecture.md): The MicroPython application: 94 frozen modules (v5.0.3) and how they are layered.
- [Memory map](https://totem-cb8b3887.mintlify.app/firmware/memory-map.md): The seven segments of the ESP32 application image and their load addresses.
- [Boot & power states](https://totem-cb8b3887.mintlify.app/firmware/boot-flow.md): From reset to the application main loop, and the device power modes.
- [Hotspot server](https://totem-cb8b3887.mintlify.app/firmware/hotspot-server.md): f_ota/hotspot.py is not an updater — it is an HTTP/1.0 and WebSocket server on a soft-AP the device raises itself. Nothing in v5.0.3 imports it.
- [2.4 GHz protocols overview](https://totem-cb8b3887.mintlify.app/protocols/overview.md): The three radios that share the 2.4 GHz band and how completely each is captured.
- [Message format](https://totem-cb8b3887.mintlify.app/protocols/message-format.md): The (cat_id, cmd_id) model, the two format registries (BLE gen_* vs ESP-NOW TOTEM_MSG_MAP), chunking, and file transfer.
- [Bluetooth LE](https://totem-cb8b3887.mintlify.app/protocols/ble.md): The GATT peripheral the phone app talks to: UUIDs, advertising, connection handshake, transfer, and the reconnect schedule.
- [ESP-NOW mesh (Unity Mesh)](https://totem-cb8b3887.mintlify.app/protocols/espnow-mesh.md): The Totem-to-Totem 2.4 GHz protocol: framing, bonding, peer sync, and relay.
- [Demi-god broadcast commands](https://totem-cb8b3887.mintlify.app/protocols/demigod.md): A privileged one-to-many command channel over ESP-NOW broadcast.
- [WiFi (OTA updates)](https://totem-cb8b3887.mintlify.app/protocols/wifi-ota.md): The third 2.4 GHz role: station-mode WiFi used to pull firmware/preview updates over HTTP.
- [Navigation & compass](https://totem-cb8b3887.mintlify.app/subsystems/navigation.md): u-blox GNSS, AssistNow, IMU fusion, and World Magnetic Model declination.
- [LEDs & animations](https://totem-cb8b3887.mintlify.app/subsystems/leds.md): The halo ring and Touch Crystal: the NeoPixel driver, the animation set, and status colors.
- [Power, input & sensors](https://totem-cb8b3887.mintlify.app/subsystems/power.md): Battery measurement and health, power modes, shutdown paths, the watchdog, the Touch Crystal, the power and SOS buttons, Vibe Mode, and the temperature sensor.
- [OTA & rollback](https://totem-cb8b3887.mintlify.app/subsystems/ota.md): How firmware updates are triggered, packaged, delivered, written, verified, and rolled back.
- [Telemetry: the debug recorder](https://totem-cb8b3887.mintlify.app/subsystems/telemetry.md): debugger.py decoded from the v5.0.3 bytecode — a binary flight recorder that packs battery, sleep, GNSS and orientation counters into debug.bin and ships them to the cloud, the arming flag that nothing on a shipped device ever sets, the NameError that caps the file at one batch, and a second unused…
- [Module reference](https://totem-cb8b3887.mintlify.app/reference/modules.md): All 94 frozen MicroPython modules in the v5.0.3 image, with a per-module decode-coverage rating.
- [f_lib: the support library](https://totem-cb8b3887.mintlify.app/reference/f-lib.md): Twelve f_lib modules decoded from the v5.0.3 bytecode — the task manager every coroutine on this device is launched through, the file manager, the RTC calendar and the RTC-memory allocator, the pack/unpack primitives underneath every wire format, and the logger that produced every log line quoted on…
- [Networking: HTTP and WiFi](https://totem-cb8b3887.mintlify.app/reference/networking.md): f_lib/requests.py and f_lib/wifi.py decoded from the v5.0.3 bytecode — the async HTTP client that carries every cloud request this device makes, whether any of it is ever protected by TLS, and the station-mode WiFi join underneath it.
- [Building a custom client](https://totem-cb8b3887.mintlify.app/reference/building-a-client.md): A practical reference for implementing your own client that talks to your own Totems over BLE, the ESP-NOW mesh, and a custom OTA server — no keys required.
- [ESP32 emulator](https://totem-cb8b3887.mintlify.app/reference/esp32-emulator.md): An ESP32 running TinyGo that joins the ESP-NOW mesh as another Totem.
- [Firmware download URL & API](https://totem-cb8b3887.mintlify.app/reference/download-url.md): How the release API and S3 download URL are constructed — on the phone app, and on the device.
- [Methodology & next steps](https://totem-cb8b3887.mintlify.app/reference/methodology.md): How this firmware was analyzed, the tools used, and how to close the remaining gaps.