How the open EarthSpark / SparkMeter stack should work in an ideal village install: meters and CIUs (Customer Interface Units) in the field on a 2.4 GHz mesh, a USB Gateway as the RF bridge (works on a laptop), GroundBolt as the on-site brain talking to meters via that Gateway, optional ThunderCloud (= GroundBolt in the cloud). Diagrams below share the same layers — toggle site-only vs site+cloud once for both views.
Meeting notes (11 Aug 2026): SparkNet-HTTP and Firefly are software plugins — not standalone RF radios.
Physical RF interface = USB Gateway. Meters = 2.4 GHz (encrypted / hidden SSID). Village SVGs may still show older “Firefly coverage discs”; treat those as provisional pending redraw.
Public check: sparknet-http is a software repo; marketing still says meters have built-in RF mesh.
SparkMeter built prepaid LV (low-voltage) metering for mini-grids and distribution utilities — meters with built-in RF mesh, a site basestation, and cloud software (ThunderCloud / GroundBolt lineage) for billing and control. That stack served a large installed base, but the operator software was historically hard to run outside the vendor’s managed environment: proprietary internals, Chef-era bootstrap, and a soft lock where leaving the SaaS (software-as-a-service) path meant losing a workable head-end system (HES) — the utility software that talks to meters for billing, disconnect, and config.
In September 2025, EarthSpark took over SparkMeter energy-metering operations (on the order of ~1 M people served on the meters). The mandate was continuity for live fleets and an exit from single-vendor software lock where operators could carry the risk. In July 2026 EarthSpark published ThunderCloud 2.0 (also called TC2.0) under Apache-2.0 as an open foundation — same product family as GroundBolt (on-site) and ThunderCloud (cloud), modernized so it can actually be bootstrapped and self-hosted. Hub: sparkmeter.io/open-source · code: github.com/EarthSpark/thundercloud.
Open-sourcing did not cut over the field. Production basestations still run ThunderCloud 1.x (TC1.x)
managed SaaS; TC2.0 is explicitly a pre-production foundation, not a drop-in flash for every live site.
Community near-term goal (OSEA Discord / GitHub — Open Source Energy Access community around EnAccess): a stable releasable main (Ansible from-scratch converge,
SymmetricDS container CI / continuous integration) before years of deferred product features.
Operators could own meters in the field but not realistically run the head-end system themselves. TC2.0 opens GroundBolt / ThunderCloud so self-host (or mix-and-match with managed cloud) is a real path.
meter-driver-spec publishes an HTTP / SSE (Server-Sent Events; optional gRPC) driver contract — energy, power, voltage, enable/disable, tamper, balance flags — so other OEMs (original equipment manufacturers) can aim at the same basestation later.
SparkNet-HTTP is the direct meter/gateway path. TC2.0 uses it natively; operators can also use it outside ThunderCloud as a vendor-exit / alternate HES edge.
SymmetricDS makes continuous ground↔cloud database sync explicit. Basestation and cloud are not one process — the WAN (wide-area network / internet uplink) can fail while GroundBolt keeps local prepaid and control alive.
Chef-era installs blocked outsiders. Ansible converge is the TC2.0 bootstrap path so a GroundBolt box can be rebuilt from public tooling.
Meter crypto keys can stay with EarthSpark, escrow at A2EI (Access to Energy Institute / Access to Energy gGmbH), or move to the operator. That unlocks sovereign ownership — and creates real brick risk if mishandled.
What TC2.0 does not claim to solve alone: CRM (customer relationship management) depth of a mature SaaS, every deferred product feature from a decade of backlog, or Phase 2 ISV (IEEE Smart Village) work (Street-EMS / OpenAMI MQTT telemetry / feeder intelligence). ISV maps TC2.0 under Phase 1 — open operator software for the installed SparkMeter base — complementary to MPM (metering / prepaid management class systems) and to later OpenAMI tracks. See roadmap · ThunderCloud update.
A village mini-grid powers homes and civic loads over LV feeders. Each prepaid customer has an SM (SparkMeter) meter and a CIU (Customer Interface Unit — keypad / balance display) on a short local link — no cloud required for that UI. Meters join a 2.4 GHz mesh (encrypted / hidden SSID). A USB Gateway bridges that RF to the site computer; GroundBolt speaks to meters through the Gateway. SparkNet-HTTP and Firefly are software plugins on that path (not separate radio boxes).
When the operator wants remote ops, CRM, or multi-site portfolio tools, SymmetricDS syncs the site database to ThunderCloud in the sky (managed EarthSpark SaaS or self-hosted) — same app family as GroundBolt, cloud deploy. Cloud is optional. Commission the field ↔ Gateway ↔ GroundBolt loop first; attach cloud only after that loop is proven.
EarthSpark hosts ThunderCloud / supports basestations. Current TC1.x customers stay here. Lowest ops burden; production improvements land here first.
Run GroundBolt on-site and/or ThunderCloud yourself. Mix-and-match (your site + their cloud, or both). Uses the same TC2.0 codebase. Self-host terms still evolving.
set_balance is display). Do not redo STS vending for other meter families here.Left = software / protocol stack. Right = simplified village with the same horizontal bands. Gray = LV power. Amber discs on current SVG still labeled “Firefly coverage” — provisional; RF bridge is the USB Gateway per 11 Aug notes. Green = site backhaul. Blue dashed = optional WAN to ThunderCloud.
Teaching map for ~100 homes plus market, medical center, cultural center, and ops building. Multiple Fireflies with translucent coverage; GroundBolt inside ops; power feeders in gray/black (no roads). Same hosting toggle as above.
ThunderCloud — remote ops / CRM. SymmetricDS — site↔cloud database sync. Optional after site loop works.
GroundBolt — site UI + Postgres at the ops building. Installer hub. Survives WAN outages for local control.
SparkNet-HTTP + Firefly (software plugins) + meter-driver-spec — open contract for commands / SSE / meter capabilities (energy, power, voltage, enable/disable, tamper, …).
USB Gateway = RF bridge to meter 2.4 GHz mesh; SM meter / CIU at each prepaid home. Gray LV feeders carry power, not data.
ThunderCloud and GroundBolt are the same sparkmeter app.
On-site: HEROKU unset → GroundBolt. In the cloud: ThunderCloud.
Radio is a sibling process. GroundBolt talks HTTP commands out and SSE events in; it never sees SparkNet RF frames inside the USB Gateway.
thundercloud
tree (Aug 2026 pass). README: do not bill real customers. Live fleets still TC1.x managed SaaS.
SparkNet RF inside the Gateway is not specified in this repo.
cash and bonus only. No mobile-money plugin in-repo.set_balance updates the CIU display. The HES wallet in Postgres is the system of record.meter_config.state = AUTO → relay on iff credit (and plan) > 0.reconcile_all() rebuilds the provider roster from Postgres. Hard request→job-ID correlation still under community discussion.Meter, Customer, Address, MeterConfig, SparkmacNode, Wallet, Transaction, Tariff, Reading, Event, User. Readings sync ground→cloud only. SymmetricDS is optional after the site loop works.
meter_reading / meter_reading_phased → add_reading. heartbeat_summary → watchdog log. log → Python logging. Neighbor / network-health / command-lifecycle events exist on the wire; GroundBolt does not persist them.
configure_provider (heartbeat 900 s), register_meter, configure_meter (enable/disable, limits), set_balance, unregister_meter. Fire-and-forget via SparkNet-HTTP POST /v1/commands.
sparkmac_node stores forwarding mode (default flooding), optional static_routes, TTL. Site UI “Routing Algorithm” is still an empty TODO. That is desired-state pushed to meters — not a hop list per heartbeat.
Not from stored readings. NAN is proprietary SparkMAC on 2.4 GHz — not Z-Wave.
A legacy emulator can attach hops[] (last_hop, RSSI, retry) to SparkMAC replies;
MeterReadingEvent / the reading table drop that. Energy, volts, watts, credit, state only.
On-demand: query_meter_neighbors → SSE meter_neighbors (who this meter hears now: neighbor_id, RSSI, link quality).
CLI: meter get-neighborlists. query_network_health is packet counts + latency, not a path.
GroundBolt does not write those replies to Postgres. You can poll a neighbor graph if the USB Gateway translator implements the command (contract in this tree; live firmware not in-tree). You cannot replay “this heartbeat went hut A → hut B → USB.”
Hypothetical prepaid day using these rules (not live telemetry): Village Simulator.
ISV Phase 1 parks TC2.0 as the open HES for the installed SparkMeter base.
MPM (MicroPowerManager) owns CRM + other prepaid families (STS tokens, OpenPAYGO SHS).
Posting /api/v0/transaction/ from MPM into GroundBolt can share a wallet; running both as system of record without a split will double-count.
Phase 2 OpenAMI MQTT / Street-EMS is a different track.
SparkMAC — SparkMeter NAN protocol on the 2.4 GHz mesh (not Z-Wave).
AUTO — meter state: relay on iff HES credit (and plan) > 0.
HES — head-end system: utility software that commands and reads meters.
CIU — Customer Interface Unit: prepaid keypad / balance display at the home.
USB Gateway — hardware RF interface (laptop/site) to the meter mesh.
NAN — neighborhood area network: local 2.4 GHz mesh among meters (bridged by USB Gateway).
WAN — wide-area network: usually the site’s internet uplink to cloud.
LV — low voltage: customer / village distribution voltages.
OMS — A2EI Open Meter Stack (CRM / operator platform; ThunderCloud and Nimbus both sit here).
SSE — Server-Sent Events: one-way live stream from server to client (readings / events).
OEM — original equipment manufacturer (e.g. another meter vendor).
SaaS — software-as-a-service (vendor-hosted cloud).
CRM — customer relationship management (accounts, tickets, portfolio ops).
SGC — Security Group Code (Nimbus universal key used for token generation).
TC1.x / TC2.0 — ThunderCloud software generations (field vs open foundation).
thundercloud — GroundBolt / ThunderCloud appsparknet-http — meter/gateway HTTP pathmeter-driver-spec — OpenAPI driver contractsymmetricds — syncansible — basestation convergegroundbolt-dev — local metarepo
Diagrams: tc20-stack-village.svg · village-meter-topology.svg
· last review pass for ISV Phase 1 open-operator path + GroundBolt HES notes from the public TC2.0 tree (Aug 2026).