Start on your host.
Then choose the hardware.

01 / Standalone package

Install the source checkout.

Use Python 3.11 or later. The package depends on cryptography and PyNaCl; the development extra includes pytest. The commands below install the current source, rather than an alpha release artifact.

git clone https://github.com/l33tdawg/meshticulum.git
cd meshticulum
python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
python -m pytest
python tools/verify_frozen_flow.py
meshticulum-seed --help

The final command displays the public-resource CLI. Imports and CLI help do not open a radio, enroll a peer or start a device service.

Verified against package metadata, installation instructions and the CLI entry point.

02 / Python SDK

An exchange with one deadline.

BlockServer reads a caller-owned public allowlist. BlockReader is callable: reader(path, limit, deadline). Its exchange receives the request bytes, maximum response size and the same absolute monotonic deadline.

This small example runs entirely in one process. It demonstrates the codec with synthetic public bytes; it supplies no authentication or publisher-verification evidence.

import hashlib
import time
from meshticulum.resources.resource import BlockReader, BlockServer

payload = b"Public codec fixture: hello Meshticulum."
manifest_id = hashlib.sha256(b"local fixture manifest").hexdigest()
chunk_id = hashlib.sha256(payload).hexdigest()
path = f"/packs/{manifest_id}/chunks/{chunk_id}.json"
server = BlockServer({path: payload}.__getitem__)

def exchange(request, response_limit, deadline):
    if time.monotonic() >= deadline:
        raise TimeoutError("Original deadline expired")
    reply = server.handle(request)
    if len(reply) > response_limit:
        raise ValueError("Response exceeded bound")
    return reply

reader = BlockReader(exchange, max_block=16)
assert reader(path, 1024, time.monotonic() + 2) == payload

For a real public pack, use an independently pinned publisher key and signed manifest. VerifiedCache and the chunk verifier check the content before it enters a reusable cache. A radio or TCP exchange must enforce its own authentication, authority and original deadline.

03 / Experimental firmware

Build from pinned inputs.

The public raw-radio recipe has separate fetch, prepare and build actions. Its recorded build host is macOS arm64 with Python 3.12.8 and PlatformIO Core 6.1.19. The two reviewed targets are Heltec V4 and Xiao S3 WIO.

Run from the Meshticulum checkout. Use a fresh build/firmware-work directory; preparation refuses an existing output. Fetch downloads the 14 checksum-pinned inputs, while build invokes no upload or erase action.

python3 -m venv build/firmware-cli
build/firmware-cli/bin/python -m pip install \
  -r firmware/meshticulum-bench/requirements-firmware.txt

python3 firmware/meshticulum-bench/prepare_firmware.py fetch \
  --archive-dir build/firmware-archives

python3 firmware/meshticulum-bench/prepare_firmware.py prepare \
  --archive-dir build/firmware-archives \
  --output-dir build/firmware-work

python3 firmware/meshticulum-bench/prepare_firmware.py build \
  --output-dir build/firmware-work \
  --pio-python build/firmware-cli/bin/python

Both targets compile by default. Select one explicitly with --target mtbench_heltec_v4 or --target mtbench_xiao_s3_wio. The outputs include application, ELF, map, bootloader and partition hashes. Compilation does not qualify those images for RF operation or production deployment.

Exact firmware recipe and recorded scope · Pinned inputs

04 / Flashing and native setup

Use the application that owns the device.

The experimental bench firmware is not a ready-to-use production device release. Lantern owns its native port/HAT selection, protected admission, provisioning, flashing and rollback. Another application must supply equivalent ownership and lifecycle controls.

1. Match the target and existing device state.

   Verify the actual board, source/build hashes, partition layout, active image and rollback correspondence. A target label alone is insufficient.

2. Establish exclusive device ownership.

   Coordinate existing radio clients and services before an application-owned transition. Keep original process and device identities through setup and cleanup.

3. Prepare the reviewed flash transaction.

   The generic app-only flash library plans its 0x10000 application range only after partition, OTA-selector and current-image checks. Preserve the exact backup and rollback receipt; a generic upload command does not perform those checks.

4. Provision a fresh finite run.

   The host supplies peers, keys, profile, regional/antenna confirmation, budgets and original deadlines. Verify disarm and terminal ownership before handback. A successful install supplies no radio permission.