Application architecture

The MicroPython application: 94 frozen modules (v5.0.3) and how they are layered.

Layered view

Totem’s firmware is a MicroPython application organized into a small number of packages plus a set of top-level modules — 94 frozen modules in v5.0.3 (v5.0.2: 96; the unused imu_fusion.py and io_mgr.py were removed). From the bottom up:

┌─────────────────────────────────────────────────────────────┐
│  Application    compass.py · compassing.py · main.py          │
│                 project_main.py · new_vibe.py · chat_msg.py    │
├─────────────────────────────────────────────────────────────┤
│  Comms          f_ble/ (BLE)   espnow*/peer* (ESP-NOW mesh)    │
│                 data_upload_v2 · svc_ble_transfer · ota_ble    │
├─────────────────────────────────────────────────────────────┤
│  Sense & act    ubx_gnss · imu_fusion_auto · mag_wmm_data      │
│                 leds · animations · apa106 · touch_button_v2    │
│                 button · device_power · ds18x20                 │
├─────────────────────────────────────────────────────────────┤
│  Platform lib   f_lib/ (wifi, requests, task_mgr, rtc, gzip,   │
│                 tarfile, logger, file_mgr, firmware_ota…)       │
├─────────────────────────────────────────────────────────────┤
│  Runtime        MicroPython v1.25.0 · asyncio · espnow · ble    │
│                 (native, on ESP-IDF v5.4)                       │
└─────────────────────────────────────────────────────────────┘

Packages

f_lib/ — platform library

Reusable infrastructure used by everything above it.

Module	Role
wifi.py, wifi_v2.py	station/AP control, connect, scan
requests.py	HTTP client (used by OTA and cloud sync)
task_mgr.py, async_helpers.py, generators.py	asyncio task orchestration
event_manager.py (top-level)	pub/sub event bus (evt_* events)
rtc_mem.py, rtc_v2.py	data retained across deep sleep in RTC memory
file_mgr.py, gzip.py, tarfile.py, unpack.py	file + archive handling for .tgz OTA packages
firmware_ota.py, firmware_rollback.py, firmware_helpers.py	OTA slot write + rollback
neopixel_v2.py	addressable-LED driver
bitwise.py, helpers.py, logger.py	utilities and structured logging

f_ble/ — Bluetooth LE

Module	Role
peripheral.py	builds the BLE advertising payload (gen_advertise_payload)
ble_lite.py	BleLite GATT peripheral: advertise/advertise_burst, enable/disable, register_services, add_characteristic, connection lifecycle (irq_cb, disconnect)
ble_data.py	GATT data types: Characteristic (flag bits), Service, Conn (connection status), BleErr
chunking.py	fragmenting large payloads into chunks (FileTransfer, gen_transfer_buff, download_ota/download_vfs)
file_upload.py	chunked file transfer with resume/ACK (FileUploader: request, _send_header, _stream, pause gates)

f_ota/ — update engine

Module	Role
main.py	OTA orchestration
hotspot.py	phone-hotspot update flow (totemupdate SSID) — now sunset; WiFi OTA (Performing Firmware update via WiFi) is the active update path
install_ota.py	write + activate the new slot
config.py, system.py, f_assets.py	update config, system helpers, asset fetch

Top-level modules by subsystem

Compass & nav

compass.py, compassing.py, ubx_gnss.py, nav_helpers.py, nav_logger.py, imu_fusion_auto.py, mag_wmm_data.py, task_mag_declination.py

LEDs

leds.py, animations.py, neopixel.py, apa106.py, f_lib/neopixel_v2.py

Input & sensors

button.py, touch_button_v2.py, peripherals.py, ds18x20.py, onewire.py, new_vibe.py

Mesh & peers

espnow.py, espnow_conn_v2.py, espnow_msg.py, aioespnow.py, peer_auto_bond.py, peer_helpers.py, peer_management.py

Comms & upload

ble_controller.py, ble_core.py, ble_manager.py, svc_ble_transfer.py, data_upload_v2.py, ota_ble.py, ota_block_writer.py, ota_callback.py, ota_daemon.py, chat_msg.py

Power & system

device_power.py, wdt_manager.py, stats.py, debugger.py, demi_god.py, flashbdev.py, inisetup.py, webrepl.py, mip/

The full list with one-line descriptions is on the module reference.

Concurrency model

The application is asyncio-based. f_lib/task_mgr.py and the frozen asyncio package schedule long-running coroutines (BLE service loop, mesh outbox drain, GNSS polling, LED animation ticks, background checks). Many tasks wait on evt_* events from the event_manager bus before doing work, so subsystems can be paused and resumed — for example, evt_ble_active and evt_battery_usable gate BLE and battery-dependent tasks, and Vibe Mode (new_vibe) waits on events such as evt_non_eco_mode and evt_led_override_off. (The v5.0.2 log lines task started, waiting on enable events / task cancelled came from Vibe Mode’s _DBG telemetry and no longer exist in v5.0.3.)

In v5.0.3 compass.start launches the ESP-NOW comms task through enow_v2.communicate_supervised, which restarts it if it crashes (v5.0.2 launched communicate_v2 directly).

A separate async watchdog-feed loop (wdt_manager.py / WdtManager) runs alongside task_mgr and asyncio: it feeds the hardware WDT via wdt_feed_loop / feed_now, but is disabled while any WdtConditions condition or WdtBlockers blocker is active (_should_enable returns False). v5.0.3’s blockers are log rotate, vfs write, and the new wlan kick (WLAN_KICK = 2, set by ble_manager around its WiFi-driver kick). When the loop is running, a stalled event loop stops the feed and lets the watchdog fire.