Firmware download URL & API

How the release API and S3 download URL are constructed — on the phone app, and on the device.

The firmware image analysed here is publicly downloadable. Two different URL constructions reach the same bytes: the phone app’s direct S3 download, recovered by decompiling the Android app’s Hermes bytecode, and the device’s own OTA fetch, recovered from the frozen MicroPython bytecode in re/v5.0.3/mpy/*.dis. They do not share a single string.

App-side facts below come from decompiled Hermes bytecode and from observing the live API — they cannot be verified against the firmware image. Device-side facts carry file.dis:line citations into the disassembly.

Device-side: how the firmware builds its own URLs

Everything the device fetches hangs off cfg.ota_url and cfg.version.

Where cfg.ota_url comes from

1. project_main.perform_ota() sets it from the branch named in perform.ota (project_main.dis:446):

   branch = d.get('ota_branch', 'totem_compass/totem') or 'totem_compass/totem'
   url = 'http://datapeak-developer.s3.us-east-1.amazonaws.com/{}'.format(branch)
   

2. Failing that, f_ota.main.start_ota assembles the same default by concatenation (f_ota_main.dis:1221):

   if not cfg.ota_url:
       cfg.ota_url = ('http://datapeak-developer.s3.us-east-1.amazonaws.com'
                      + '/' + 'totem_compass' + '/' + 'totem')
   

3. If the release poll succeeds, the API overwrites it with its body.endpoint string and cfg.version with body.release_code (get_release_from_api, f_ota_install_ota.dis:672). The server therefore chooses the download host; the on-device S3 URL is only the fallback.

All three host literals are in the image at re/v5.0.3/rodata_strings.txt:1816, :1837 and :2123 — http://datapeak-developer.s3.us-east-1.amazonaws.com, the …/{} template of it, and http://api.totemportal.com. No https:// Totem host appears anywhere; the only https:// literals in the image are upstream MicroPython defaults (micropython.org, raw.githubusercontent.com, gitlab.com).

The fetches

_get_endpoints(file_path, s3_dir_url, dest_dir) is the whole of the URL builder (f_ota_install_ota.dis:1214):

return [s3_dir_url + '/' + file_path, dest_dir + '/' + file_path]

with s3_dir_url = cfg.ota_url + '/' + cfg.version and dest_dir = cfg.save_to (default 'next'). So:

{cfg.ota_url}/{cfg.version}/contents.json[?uid=XXXXXXXX]   # index, is_cached==False adds the uid
{cfg.ota_url}/{cfg.version}/{name picked from contents.json}

The ?uid= cache-buster is rand_key(length=8), 8 characters from A–Za–z0–9 seeded by os.urandom (f_lib_helpers.dis).

The name is not a template — it is whichever entry of the contents.json array satisfies entry[-4:] == '.bin' (or '.tgz'). The device then reverse-engineers the version from the resulting URL (f_ota_install_ota.dis:1017):

version = firmware_url.split('_v')[-1].lower()
ota_status.version = '.'.join(version.split('.')[:-1])

which is the only place the firmware ever assumes a …_v<code>.<ext> naming convention — and it assumes it about a string the server supplied, with no validation.

The literal firmware_v appears nowhere in the image: zero matches across all seven segments seg0–seg6 and zero across the 94 frozen modules. The filename is a server-side/app-side convention that the device only parses, never constructs.

App-side: the releases API

The phone app fetches release metadata from an endpoint the firmware never mentions:

https://api.totemportal.com/releases

No releases literal exists in the firmware (grep -l releases *.dis → no matches). The device’s only API endpoints are {API_ENDPOINT}/devices/{mac}/ota and …/devices/{mac}/ota?updated, plus {API_ENDPOINT}/events/{mac} and {API_ENDPOINT}/debug/{mac} for log upload after an update (ota_callback.dis:497).

Response (abridged) at time of analysis. The API lists one current release per branch; after the 5.0.3 rollout, release 335 (v5.0.2) was no longer listed:

{
  "body": {
    "releases": {
      "339": {
        "release_id": "339",
        "release_date": null,
        "endpoint_id": "2",
        "s3_bucket": "datapeak-developer",
        "s3_product_dir": "totem_compass",
        "s3_branch_dir": "totem",
        "release_name": "Totem",
        "release_code": "5.0.3",
        "size_bytes": "1699872",
        "sha256_hash": "bfe1f5a4c39790d068ab4f041a6a56766f4b21f48289518d83d831b323450dc4",
        "release_badge": null
      },
      "240": {
        "release_code": "3.2.12",
        "s3_branch_dir": "pre_alpha",
        "...": "..."
      }
    }
  }
}

URL construction (app)

filename = "firmware_v" + release_code + ".bin"

url = "https://" + s3_bucket + ".s3.us-east-1.amazonaws.com/"
      + s3_product_dir + "/"
      + s3_branch_dir + "/"
      + release_code + "/"
      + filename

For release 339 (v5.0.3):

https://datapeak-developer.s3.us-east-1.amazonaws.com/totem_compass/totem/5.0.3/firmware_v5.0.3.bin

Release 335 (v5.0.2) followed the same pattern (…/totem/5.0.2/firmware_v5.0.2.bin). The construction order was confirmed from the raw Hermes opcodes (a HermesInternal.concat call of exactly ten operands ending in the filename), not only from decompiler output.

The https:// scheme above is the app’s. The firmware embeds only the plaintext http:// variants of both hosts. Whether the app rewrites http:// to https:// before use is not verifiable from the firmware.

Which release fields the firmware actually knows about

Earlier revisions of this page listed s3_dir_url and package_json_url among the “release fields referenced by the firmware.” Both were wrong:

Name	Where it really comes from
s3_dir_url	a parameter name of _get_endpoints in f_ota/install_ota.py — a local variable holding cfg.ota_url + '/' + cfg.version, never a JSON key
package_json_url, {base}/package/{}/{}/{}.json	upstream mip, MicroPython’s own package installer (mip___init__.dis). Nothing in f_ota/ touches it, and no Totem code path calls mip
sha256_hash	appears only in f_ble_chunking.dis and f_ble_file_upload.dis — the BLE transfer’s per-file digest. The WiFi release path never reads a hash
endpoint, release_code, release_id, product_name, branch_name, device_id	the six keys the firmware really does read, out of resp['body'] (f_ota_install_ota.dis:672)
ota_branch	not an API field at all — a perform.ota key, produced by ble_manager.handle_ota (ble_manager.dis:5727), espnow_conn_v2 and project_main.force_ota
s3_bucket, s3_product_dir, s3_branch_dir, size_bytes	app-side only; none of these names appear in the firmware

The product/branch directory names are on-device, as plain strings: totem_compass and totem in f_ota/main.py and f_ota/system.py, totem_compass/totem as perform_ota()’s ota_branch default, and totem_compass/pre_alpha as the default first argument of the REPL helper project_main.force_ota() (project_main.dis:386).

On-device OTA vs app download

Aspect	Phone app	On-device firmware
Release lookup	GET /releases	POST {API}/devices/{mac}/ota, else fall back to the built-in S3 URL
Artifact naming	builds firmware_v<code>.bin itself	reads contents.json and picks the first entry whose last 4 characters are .bin / .tgz
Index	(none)	contents.json — a bare JSON array of filenames
Where it lands	a file on the phone	.bin streams straight from the socket into the inactive OTA slot and is never written to the filesystem; only the .tgz preview is saved, under next/, then unpacked over the filesystem root
Integrity	sha256_hash from the releases API	none on the WiFi path beyond bytes written == Content-Length

Firmware: {} found in repo is a log line about the remote contents.json listing, not a local repository. Earlier revisions of this page read it as an on-device artifact store; there is no such store for firmware images.

Verification

The object at the app-constructed URL matched the API’s own integrity fields exactly:

Field	API value	Downloaded file
Size	1,699,872 B	1,699,872 B
SHA-256	bfe1f5a4…23450dc4	bfe1f5a4…23450dc4

The v5.0.2 download (release 335) matched its record the same way (1,692,352 B, a6d05597…c7bf8896). The image begins with 0xE9 and carries the ESP-IDF app-descriptor magic 0xABCD5432, confirming a genuine ESP32 application image.

Since the device never sees sha256_hash, this check confirms that the app’s download is intact — it says nothing about what the device flashes. See OTA integrity.

The path is scoped by release_code (the /5.0.3/ segment), but the object is a plain static S3 key with no content hash or immutable prefix — that fixed per-version URL keeps serving whatever bytes currently sit at the key until the object is replaced. Release metadata, including the pre_alpha branch, is served openly by the app’s releases API.