Skip to content

Home

Jump to bottom
Timo Sariwating edited this page Nov 2, 2026 · 22 revisions

Welcome to the Hive-Rail wiki!

Hive-Rail lets FREMO participants run their module clusters as independent power districts, each with its own command station and a small Hive-Rail node, and makes them work together as one layout with no central server.

Hive-Rail: distributed train tracking that keeps working until the last mesh node dies. Every node follows the trains of its own district, every node knows where all trains are, and a train takes its identity across each district border. See Architecture §10. The nodes speak RocNet over Zenoh; DCC-EX, LocoNet centrals and Rocrail connect through adapters.

The Hive-Rail board is a full DCC-EX command station with the Hive-Rail extras: LocoNet, multiMAUS and Z21 app support, and the Hive-Rail node. At home it works on its own or with Rocrail or JMRI; or as a booster behind a Z21 or an Intellibox; at a FREMO meeting it is a district's lite node, or the command station of a full node on a Raspberry Pi (Hive-Rail Node Board §2).

flowchart LR
    subgraph A["Cluster A"]
        NA["Hive-Rail node"] --- CA["DCC-EX"]
    end
    subgraph B["Cluster B"]
        NB["Hive-Rail node"] --- CB["Intellibox<br/>LocoNet adapter"]
    end
    subgraph C["Cluster C"]
        NC["Hive-Rail node"] --- CC["DCC-EX"]
        RR["Rocrail"] ---|"LocoNet TCP<br/>(RocNet UDP planned)"| NC
    end
    NA <-->|"RocNet over Zenoh"| NB <-->|"RocNet over Zenoh"| NC
Loading

Code documentation: curioustimo.github.io/Hive-Rail (rustdoc, from main); working on the code: CONTRIBUTING.md.

Design documents

  • Architecture and Design Specification: goals, safety rules, heartbeats, handoff, actors, roadmap, and distributed train tracking (§10), the core idea
  • RocNet on the Mesh: the core protocol design. RocNet frames on Zenoh, routing, district power and short reporting, fast clock, loco commands, adapters, dashboard, test setups
  • Hive-Rail Node Board: concept for the Hive-Rail board: a DCC-EX command station with LocoNet, multiMAUS and the Hive-Rail lite node on a second ESP32; five ways to use it, at home and at meetings
  • Node-Lite on the M5StickC: our lite node test device: buttons, screen, setup and tests
  • DCC-EX Adapter: driving a DCC-EX command station over USB serial or WiFi: power, emergency stop, shorts and the fast clock
  • LocoNet Adapter: connecting LocoNet centrals and module LocoNet devices, with a LocoNet message reference
  • Module and Layout Files: design draft. Module owners describe their modules once; the planning team builds each meeting's layout from them, and Hive-Rail derives districts, borders, named devices and routes
  • Signal Faces: the German light signals Hive-Rail draws (the DB LED signals Viessmann makes for H0), each aspect pictured, as faces and as panel tiles, and how to set one up in the module editor
  • Choosing and Placing Signals: which signal goes where and what it shows: entry, departure, block and distant signals in real situations (animated), Ks, shunting, the common mistakes, which Viessmann models to buy, wiring them with MobaLedLib, and the sources
  • Screenshots: Hive-Rail running: the layout in the web view with trains and station information boards, the module editor, the dispatcher screen and a node dashboard
  • Transition Zone Specification: catch-and-takeover between clusters with a dual-coil latching relay (after the simulator)
  • FRED Throttles and the Distributed Master: started. FRED/Fredi walk-around support: loco register and throttle numbers done, dispatch next
  • RocNet Compatibility Matrix: carrying local RocNet transports across the mesh

Current focus

  1. Done: power on/off per district, a global emergency stop and the global go that ends it, every district's power and short circuits shown on all nodes, and a GLOBAL state line on the dispatcher and the nodes
  2. Done in software: one fast clock commanded by Hive-Rail, shown on every node and written to LocoNet slot 123 and DCC-EX
  3. Done: the DCC-EX driver (power on MAIN, emergency stop, overload as short, fast clock), tested on the 2021 board on USB power
  4. Done (2026-10-31): a lite node on an ESP32 joins the mesh (zenoh-pico): Node-Lite on the M5StickC, our test device with district power on its buttons and the global stop and go both ways; lite servers with failover and its district's layout over the mesh are done too. Next: simulator-driven track on the M5StickC, load balancing across lite servers
  5. In progress: the Hive-Rail Node Board. v1 prototype (one ESP32, stock DCC-EX with a Hive-Rail add-on): board definition, stop and go buttons, WS2812 power LED (to be seen with 12 V), OLED screen and the LocoNet buffer (built, not yet tested on a powered bus). Next: board v2 with two ESP32s (DCC-EX and the lite node)
  6. Done: the loco register for the whole layout, with throttle numbers so a FRED keeps its loco on every module, translation of Rocrail's or a central's own slots, and a dispatcher screen for the Zugleiter showing all districts, the clock and the register. Next: dispatch
  7. In progress: a clear CLI view with decoded RocNet and LocoNet messages
  8. Done, not yet tested with hardware: a serial LocoNet interface (--loconet-serial) for an Intellibox I's RS232 port or a LocoBuffer, and a TOML config file (--config) for a node's or the dispatcher's options
  9. Done (2026-10-30/31): LocoNet over UDP through a GCA101, stage 2 with an Intellibox I and an IB-Switch (LocoNet Adapter §4.2), and turnout answers when the node is the command station, so an IB-Switch lights up
  10. Done (2026-11-01): the module editor (modules drawn from SpDrS60 tiles, Module and Layout Files §11), the web view of the layout on the layout simulator, the German light signals (Signal Faces), and occupancy sensors reported as RocNet sensor reports

Test setup: Hive-Rail on a MacBook and a Windows PC, with Rocrail connected over LocoNet over TCP (port 1234). The 2021 "ESP32 LocoNet Command Station" board runs DCC-EX with the Hive-Rail add-on, connected to the MacBook over USB, without 12 V so far. An Intellibox I (65000) and an IB-Switch on a GCA101 (LocoNet over UDP), tested on 30 October 2026 (stage 2). The M5StickC as a lite node. Next: the Intellibox on its RS232 port, and the board on 12 V (LEDs, RailSync, LocoNet).

Clone this wiki locally