> ## Documentation Index
> Fetch the complete documentation index at: https://totem-cb8b3887.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Module reference

> All 94 frozen MicroPython modules in the v5.0.3 image, with inferred roles.

Every module below is frozen into the firmware. Names are exact (from the frozen module
registry); roles are inferred from symbols, string constants, and log lines.

<Note>
  The v5.0.3 frozen-module registry (`mp_frozen_names`) holds exactly **94** entries — the
  modules listed on this page. Two more `.py` files, `boot.py` and `webrepl_cfg.py`,
  exist only as on-flash VFS filesystem paths (`./boot.py`, `./webrepl_cfg.py`) and are
  **not** frozen, which is why some tallies of the image reach 96.

  v5.0.2 had **96** frozen modules (98 with the two VFS files). v5.0.3 removed two that
  nothing imported: `imu_fusion.py` (an older, unused Madgwick `Fusion`/`Cal`
  implementation) and `io_mgr.py` (only `import io`).
</Note>

## Top-level application

| Module            | Role                                                                                                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `main.py`         | application entry after boot                                                                                                                                             |
| `project_main.py` | project-specific top-level orchestration                                                                                                                                 |
| `project_data.py` | project constants / configuration data; `ActiveModes` flags (v5.0.3 adds `ble_ticks_app_internet`, `is_ble_log_upload`, `is_file_upload_test`, `is_nav_log_fast_rotate`) |
| `compass.py`      | top-level compass state machine                                                                                                                                          |
| `compassing.py`   | compass math (heading, 2D/3D, bias)                                                                                                                                      |
| `new_vibe.py`     | Vibe Mode — microphone-driven sound-reactive ring LED effect (`mic.read_u16` → `ring.buf`; `newvibe-1.10`, v5.0.2: `newvibe-1.9`). Not magnetometer calibration          |
| `chat_msg.py`     | peer-to-peer chat messages                                                                                                                                               |
| `stats.py`        | runtime statistics                                                                                                                                                       |
| `debugger.py`     | on-device debug hooks                                                                                                                                                    |
| `demi_god.py`     | privileged broadcast command system                                                                                                                                      |

## Boot & filesystem

| Module         | Role                                  |
| -------------- | ------------------------------------- |
| `_boot.py`     | first script run at MicroPython start |
| `inisetup.py`  | first-boot filesystem setup           |
| `flashbdev.py` | flash block device for the VFS        |

## Navigation

| Module                    | Role                                                                                                                                          |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubx_gnss.py`             | u-blox UBX GNSS driver                                                                                                                        |
| `nav_helpers.py`          | navigation math helpers                                                                                                                       |
| `nav_logger.py`           | navigation event logging (v5.0.3: fast `events.bin` rotation at ≥1024 B when `is_nav_log_fast_rotate`)                                        |
| `imu_fusion_auto.py`      | accel/gyro sensor fusion and 2D/3D magnetometer calibration; the sole fusion module in v5.0.3 (byte-identical to v5.0.2), defines `_spin_deg` |
| `mag_wmm_data.py`         | World Magnetic Model data                                                                                                                     |
| `task_mag_declination.py` | periodic declination recompute                                                                                                                |

## LEDs

| Module          | Role                          |
| --------------- | ----------------------------- |
| `leds.py`       | LED behavior / status mapping |
| `animations.py` | animation definitions         |
| `apa106.py`     | APA106 addressable-LED driver |
| `neopixel.py`   | NeoPixel-style driver shim    |

## Input & sensors

| Module               | Role                                                                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `button.py`          | both physical buttons, power and SOS (`AsyncButton`); v5.0.3 replaces the 50 ms `debounce` coroutine with a 30 ms `_edge_ms` lockout |
| `touch_button_v2.py` | capacitive Touch Crystal                                                                                                             |
| `peripherals.py`     | peripheral bring-up                                                                                                                  |
| `ds18x20.py`         | DS18B20 temperature sensor                                                                                                           |
| `onewire.py`         | 1-Wire bus                                                                                                                           |

## Bluetooth LE

| Module                | Role                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------ |
| `ble_controller.py`   | high-level BLE control (`BleCtrl`, blockers)                                         |
| `ble_core.py`         | core BLE glue                                                                        |
| `ble_manager.py`      | connection/session manager (`BleManager`, `send_data_v2`, `gen_live_data`)           |
| `svc_ble_transfer.py` | chunked transfer GATT service                                                        |
| `ota_ble.py`          | OTA over BLE (v5.0.3 imports `CHUNK_HDR_FMT` / `CHUNK_HDR_SZ` from `f_ble.chunking`) |

## ESP-NOW mesh & peers

| Module               | Role                                                                                      |
| -------------------- | ----------------------------------------------------------------------------------------- |
| `espnow.py`          | ESP-NOW wrapper/shim (origin uncertain; stock MicroPython ships `espnow` as a C module)   |
| `espnow_conn_v2.py`  | connection/session layer; message schema maps (`TOTEM_MSG_MAP`, `EXTENDED`, `COMM_SPEED`) |
| `espnow_msg.py`      | ESP-NOW message builders (`*_gen_*` payload generators, `pack_flags`, `rot13`)            |
| `aioespnow.py`       | asyncio ESP-NOW (`AIOESPNow`)                                                             |
| `peer_auto_bond.py`  | automatic peer bonding                                                                    |
| `peer_helpers.py`    | peer utilities (`is_peer_stale`: 7200 s in v5.0.3, v5.0.2: 14400 s)                       |
| `peer_management.py` | peer registry / lifecycle                                                                 |

## Upload & OTA

| Module                | Role                                                                         |
| --------------------- | ---------------------------------------------------------------------------- |
| `data_upload_v2.py`   | app data upload over WiFi/HTTP (`UploadData`, `upload_file`, `API_ENDPOINT`) |
| `ota_block_writer.py` | write image chunks to the OTA slot                                           |
| `ota_callback.py`     | OTA progress/state callbacks                                                 |
| `ota_daemon.py`       | background OTA task                                                          |

## Power & system

| Module             | Role                                                                           |
| ------------------ | ------------------------------------------------------------------------------ |
| `device_power.py`  | power state machine, battery health                                            |
| `wdt_manager.py`   | watchdog management (conditions/blockers; v5.0.3 adds the `WLAN_KICK` blocker) |
| `event_manager.py` | pub/sub event bus                                                              |

## `f_ble/` package

| Module                 | Role                                                                   |
| ---------------------- | ---------------------------------------------------------------------- |
| `f_ble/__init__.py`    | package init                                                           |
| `f_ble/peripheral.py`  | GATT peripheral + advertising                                          |
| `f_ble/ble_lite.py`    | lightweight message model                                              |
| `f_ble/ble_data.py`    | message (de)serialization                                              |
| `f_ble/chunking.py`    | payload fragmentation (`CHUNK_HDR_FMT = '<HHiH'`, `CHUNK_HDR_SZ = 12`) |
| `f_ble/file_upload.py` | resumable chunked file transfer                                        |

## `f_ota/` package

| Module                 | Role                                                                   |
| ---------------------- | ---------------------------------------------------------------------- |
| `f_ota/__init__.py`    | package init                                                           |
| `f_ota/main.py`        | OTA orchestration                                                      |
| `f_ota/hotspot.py`     | WiFi hotspot updater                                                   |
| `f_ota/install_ota.py` | write + activate new slot                                              |
| `f_ota/config.py`      | OTA configuration                                                      |
| `f_ota/system.py`      | system helpers; `release_code` `5.0.3`, `release_id` 339 (v5.0.2: 335) |
| `f_ota/f_assets.py`    | asset fetch/apply                                                      |

## `f_lib/` package

| Module                                                 | Role                                                                                                                                                   |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `f_lib/__init__.py`                                    | package init                                                                                                                                           |
| `f_lib/wifi.py`, `f_lib/wifi_v2.py`                    | WiFi station/AP control                                                                                                                                |
| `f_lib/requests.py`                                    | HTTP client                                                                                                                                            |
| `f_lib/task_mgr.py`                                    | asyncio task manager                                                                                                                                   |
| `f_lib/async_helpers.py`                               | async utilities                                                                                                                                        |
| `f_lib/generators.py`                                  | generator helpers                                                                                                                                      |
| `f_lib/rtc_mem.py`, `f_lib/rtc_v2.py`                  | RTC-retained memory                                                                                                                                    |
| `f_lib/file_mgr.py`                                    | file management; v5.0.3 adds async SHA-256 `gen_file_hash(path, buff=None, yield_every=4)` and `get_oldest_file(prefix)` (used by `remove_oldest_log`) |
| `f_lib/gzip.py`, `f_lib/tarfile.py`, `f_lib/unpack.py` | archive handling for `.tgz` OTA                                                                                                                        |
| `f_lib/firmware_ota.py`                                | OTA slot writing                                                                                                                                       |
| `f_lib/firmware_rollback.py`                           | rollback logic                                                                                                                                         |
| `f_lib/firmware_helpers.py`                            | firmware helpers                                                                                                                                       |
| `f_lib/neopixel_v2.py`                                 | LED driver v2                                                                                                                                          |
| `f_lib/bitwise.py`                                     | bit manipulation                                                                                                                                       |
| `f_lib/helpers.py`                                     | misc utilities                                                                                                                                         |
| `f_lib/logger.py`                                      | structured logging                                                                                                                                     |

## Standard / vendored MicroPython

Frozen library modules that ship with or are vendored into MicroPython, not Totem-specific:
`asyncio/` (`__init__`, `core`, `event`, `funcs`, `lock`, `stream`), `uasyncio.py`,
`requests/__init__.py`, `urequests.py`, `mip/__init__.py`, `ssl.py`, `upysh.py`,
`webrepl.py`, `webrepl_setup.py`.