MegaPoints Route Processor User Guide

Your MegaPoints Route Processor is the brain of an automated System2 layout. It watches inputs — block detectors, panel buttons, RFID readers, the clock — and fires routes: short, timed sequences of point throws, signal aspects, brake releases and any other vPort writes you want.

The Route Processor brings four ideas together on one board:

The Route Processor is built on the System2 platform — the same proven infrastructure that powers the Panel Controller, Servo-8, Solenoid Driver and the rest of the family. That means you get:

• Wi-Fi connectivity — configure everything from any web browser
• No software to install — just open a browser and go
• CAN bus networking — connect to every other System2 board with two wires
• Over-the-air firmware updates with a separate recovery image
• Browser-direct cloud backup — reliable even for full 100-route layouts
• Native MQTT and JMRI support alongside CAN

Whether you are running a fully-automatic exhibition layout or letting an operator pull the strings on a busy through station, the Route Processor sits quietly on the bus, listens, decides, and fires the right sequence at the right time.

The System2 Family

The Route Processor is one of several System2 boards that share the same infrastructure. Each board does one thing well, then they cooperate over the CAN bus to drive a whole layout:

Shared Infrastructure

Every System2 board shares the same Wi-Fi setup, CAN ID, cloud backup, OTA update path, status log and dashboard. Once you have learned one board's pages, you know all of them — only the per-product editor in the middle differs.

Power Supply

The Route Processor accepts 12 V DC on its barrel jack or screw terminals. Current draw is modest (under 200 mA) — any clean 12 V supply that powers your other System2 boards will do. The board has reverse-polarity protection but please make sure positive and ground are the right way around the first time.

CAN Bus

The board has two CAN screw terminals (H and L) wired in parallel so you can daisy-chain through the board without a Y-splitter. Add a 120 Ω termination resistor at each end of the bus (see §26 Connecting Multiple Boards).

LED Indicators

One yellow LED indicates power and one green LED indicates Wi-Fi association. After Wi-Fi association the green LED flashes briefly each time a CAN frame is received.

On first power-up — or any time the board has no saved Wi-Fi credentials — the Route Processor starts as a Wi-Fi access point so you can configure it from your phone or laptop.

Step-by-step Wi-Fi Setup

1. Power the board. After a few seconds it advertises an SSID called MegaPoints-XXXXXX, where XXXXXX is the last 6 digits of its MAC address.
2. From your phone or laptop, join that network. A captive portal should open automatically; if it doesn't, browse to http://192.168.4.1.
3. Pick your home Wi-Fi from the scan list and enter the password. Press Save & Connect.
4. The board reboots, joins your network, and the green LED settles to a slow heartbeat.
5. Look on your router's client list (or the System2 Dashboard) for the device's new IP. Browse to http://<ip>/ — or to http://<hostname>.local/ on networks with mDNS.

The Main page is the everyday view: one route on screen, with its slot table, trigger gating panel, the network row underneath, and a status log at the foot.

Header strip

Across the top sit three blocks: the System2 logo / hostname on the left, the product photo in the centre (it doubles as a link straight to this guide), and a System2 Air / Location label box on the right. The chart panel toggles below the header strip.

Route Editor

The big blue number on the left is the route you are currently editing. Click the up/down arrows to step one at a time or the double arrows to step ten at a time. To the right of the number sit the route header fields: default delay, enable vPort, feedback vPort, RFID vPort and a 24-character name.

Slot table

Below the header is the slot table. Each row is one timed write: a vPort, an On/Off value, an action delay before the next slot fires, plus Move and Delete icons. The default layout is Wide (2×8) with two columns of eight slots side-by-side, or you can switch to Long (1×16) with all sixteen slots running down the page — whichever reads better for the sequence you are building. The choice sticks across reloads and reboots.

Action bar

Underneath the slots: Trigger Route (fires this route once, on-demand), Duplicate (copies to another route number), Clear, Invert (flips every On/Off), Save Routes (persists every route to flash), Load Routes (re-reads from flash), Backup/Restore (local file), and Del All (zeros every route).

Trigger Gating

Click the Trigger gating heading to expand the gating panel: conditions, schedule, chain, trigger edge, defer TTL, timer, and the fast-clock panel. This is where the smart automation lives — see §9 Trigger Gating for the full tour.

Block Groups

Click Block Groups to expand the block-group editor. Define named ranges of detector vPorts here, then reference them from any condition. See §10.

Network strip

Protocol picker (CAN / JMRI / MQTT), CAN auto-ID toggle and manual ID, Wi-Fi boot delay, roaming toggle, and the Share/Revoke/Erase credentials buttons. See §14–§15.

Bottom bar

Save Changes (writes settings to NVS), Reload Values (discards unsaved edits), Reset to Defaults. The Backup/Restore/Cloud Backup/Reboot links sit just below.

Here is the shortest practical example: "When detector 101 goes SET, throw point 201 reverse and clear signal 301."

1. Open the Main page. The route number defaults to 1; leave it there.
2. Set Enable vPort to 101 (your detector).
3. Optionally set Name to something memorable, e.g. Up arrival.
4. In the slot table, type 201 into Slot 1's vPort cell and click the On/Off toggle so it shows green (SET = REVERSE for points).
5. Set Slot 1's Delay to 300 — that's the pause after writing 201 before the next slot fires.
6. In Slot 2, type 301, leave On (CLEAR / OFF DANGER, depending on your signal driver's convention).
7. Click Save Routes. The button glow indicates an unsaved state; once you click it the glow disappears.
8. Click Trigger Route to test the sequence on the bench without waiting for the detector to fire.

Roaming

Roaming is on by default. The board keeps an eye on all access points broadcasting your configured SSID and switches to the strongest one whenever the current signal drops below threshold. On a single-AP household this never kicks in; on layouts that span a garden room and a workshop with two APs sharing the same SSID/passphrase, roaming keeps the board on the better signal automatically.

Boot Delay

If multiple System2 boards on the same power supply all boot together they can momentarily overload your router with simultaneous Wi-Fi associations. The Boot delay toggle adds a random 0–15 second hold before the Route Processor attempts to associate — spread across all your boards, that's enough to stagger the requests. Tick the box and set a maximum delay in seconds.

Sharing Wi-Fi Credentials

Once one board on the CAN bus has working Wi-Fi credentials, click Share on its Main page and every System2 board on the bus will receive those credentials on its next boot. The data is encrypted with a board-pair handshake; nothing leaks onto the bus in clear text. Revoke tells the bus to forget any shared credentials; Erase wipes credentials from this board only.

V10 (15 May 2026)

Initial public release of the Route Processor firmware. 100 routes, 16 slots per route, CAN and RFID triggers, JMRI and Native MQTT protocols, OTA updates, dashboard, Wi-Fi sharing.

Between a route's trigger (the thing that decides it should fire) and the slot sequence (what actually happens) sits the gating panel. Five features live here:

Conditions

Up to four conditions per route. Each one tests a vPort or a block group against SET, CLEAR or UNKNOWN. Combined with AND (all must pass) or OR (any one passes). Click + condition to add a row, pick the type, type the vPort or pick the group, choose the test.

On Fail: Defer or Drop

If the conditions don't pass at trigger time, you get a choice:

• Drop — throw the trigger away immediately. Use when "fire iff right now" matters more than "fire eventually".
• Defer — keep the trigger and re-check every second for up to TTL seconds (default 5, range 1–60). Use when conditions are likely to become true shortly — e.g. a block clearing as the loco rolls forward.

Trigger Edge

The enable vPort can fire on rising, falling, or both edges:

• Enable vPort SET (default) — classic "block just became occupied" trigger.
• Enable vPort CLEAR — falling-edge: "block just emptied". Useful for cleanup routes after a train passes.
• Either edge — fires on every state change.

Schedule Window

Tick Schedule enable, set Start and End (HH:MM, local time). The route only fires when the current time is inside the window. If End is less than Start the window wraps midnight (e.g. 22:00 – 06:00 is overnight). Schedules apply to every trigger source: CAN, RFID, exact-time, interval and chain.

Chain

On completion, fire route N. The chained target goes through its own conditions / schedule / trigger gating, so the cascade is safe — if the chained route's own conditions don't pass, the chain is dropped or deferred according to its own on-fail setting, not the originating route's.

Dry-run preview

At the bottom of the gating panel sits a Dry-run preview: a client-side "what would happen now?" check against the live block-group state. Use it while authoring — it will catch off-by-one vPort numbers and condition typos without your having to send a real train.

A block group is a named range of vPorts that condition tests can refer to as a whole. The group is OCCUPIED if any vPort in the range is SET, CLEAR if every vPort is known to be CLEAR, and UNKNOWN if no vPort in the range has been observed since boot.

Block groups solve "is the yard occupied?" without listing the 22 detector vPorts that make up the yard. Up to 32 groups, configured on the Block Groups section of the Main page.

Defining a group

1. Click the Block Groups heading to expand the section.
2. Click Add Block Group. A prompt asks for a name — up to 23 characters, case-sensitive, no colons.
3. Enter the start and end vPorts for the range (inclusive). Ranges may not overlap each other.
4. The Status column shows OCCUPIED / CLEAR / UNKNOWN live as the bus updates.

Using a group from a condition

In the Trigger Gating panel, when you click + condition, set the type to Block group instead of vPort and pick the group name from the drop-down. The condition then evaluates against the group state.

In addition to the enable, feedback and RFID triggers, a route can fire itself on the clock with no input change at all. Two flavours, both in the Trigger Gating panel:

Exact time

Fire once per layout day at HHMM. Useful for the morning station opening sequence, the lights-on-at-dusk routine, or the scheduled 09:42 to Banchory.

Interval

Fire every N minutes (1 minimum, 1092 maximum). Useful for animated scenics that should cycle on a heartbeat — a level crossing demo every 3 minutes, a factory whistle every 15 minutes, a yard cycle every half hour.

Interaction with the schedule window

Both timed triggers respect the route's schedule window:

• Exact time outside its window: the fire is silently dropped, and the daily-fired flag is still set — no repeated retries for the rest of that minute.
• Interval outside its window: the interval timer is frozen, so the first fire after the window reopens is exactly one full interval later, not an accumulated burst.

Fast Clock

The Fast Clock panel sits inside the gating section. Set the multiplier (1–60), click Start Session, and exact-time triggers compare against layout time, not wall time:

The multiplier is saved to flash on Save Changes and persists across reboots. The session epoch resets on each Start Session click — by design, so power-cycling between operators starts clean.

An S2-RFIDr or S2-RFIDd reader can fire a route when a specific tag passes its antenna. RFID triggers run independently of CAN-vPort triggers — one route can have both, either, or none.

Setting up an RFID route

1. Open the route you want to fire.
2. Set RFID vPort in the route header to the vPort the reader publishes (typically configured on the reader itself).
3. In the RFID Tags row, type up to ten 4-digit hex tag IDs. The route fires only when one of those tags is read on that reader.
4. Save Routes.

If the route also has an enable vPort and conditions, those still apply — the tag-read triggers the route, and the conditions / schedule then decide whether it actually fires.

What the examples cover

The examples document also includes a Common patterns reference card at the back — one-liners for the recurring building blocks (fire on arrival, fire on departure, always-RED-by-default signal, panel-button override, schedule-bound route).

The Route Processor talks to three external worlds:

• CAN bus — the layout's nervous system. Other System2 boards live here. Always on.
• Wi-Fi (HTTP / WebSocket) — the web UI you are looking at, plus dashboard sync, OTA updates and cloud backup.
• An off-layout protocol — one of: CAN-only (no off-layout traffic), JMRI (System2's native JMRI bridge), or Native MQTT (publish/subscribe to your own broker).

CAN Bus

The Route Processor's CAN ID can be picked automatically (Auto ID on) or set manually (1000–1999 range). Auto ID looks at the existing bus and picks the lowest unused address. Use manual ID when you want a predictable address for diagnostics.

JMRI

Select JMRI as the protocol, save, and reboot. The Route Processor pretends to be a JMRI signal-and-sensor server — vPort SET/CLEAR frames map to JMRI sensors, slot writes correspond to JMRI turnouts and signal masts.

Native MQTT

Select Native MQTT, point the broker hostname and port at your MQTT server, save, and reboot. The board publishes to system2/<hostname>/vport/<n> on changes and subscribes for inbound writes. QoS is picked with the Async / Sync toggle — Async (QoS 0) is fastest and recommended; Sync (QoS 1) gives broker-acknowledged delivery at the cost of speed and broker load.

The Route Processor keeps two separate kinds of persistent storage:

• NVS settings — protocol, CAN ID, Wi-Fi, fast-clock multiplier, etc. Saved by Save Changes at the bottom of the Main page.
• Route store — every route header, slot table, conditions, schedule, chains, timers, plus block groups. Saved by Save Routes in the Route Editor.

Save Routes / Load Routes

Save Routes writes every route to SPIFFS (a fixed-size binary file). The save button glows orange while there are unsaved edits; the glow clears on save. Load Routes re-reads from SPIFFS, discarding any unsaved edits in the browser.

Local Backup — Download

The Backup button in the Route Editor downloads every route as a JSON file. The filename is <hostname>-routes-YYYY-MM-DD.json. The file is a complete, lossless snapshot — trigger gating, schedules, chains, timers, the lot. Save it somewhere safe or check it into a layout-config git repo.

Local Restore — Upload

The Restore button reads a previously downloaded file back. Both the new JSON format and older colon-text .txt backups are accepted — the browser converts legacy files on the fly. Routes are sent to the device in small batches so even a full 100-route restore is reliable and incremental: you can see "Sending 25 / 100 routes…" in the progress overlay rather than staring at a frozen page.

Reset to Defaults

The bottom Reset to Defaults button wipes settings (NVS), but leaves the route store alone. Use it when settings are corrupted but you want to keep your routes.

Cloud backup keeps a server-side copy of your settings and routes. The first time you click Cloud Backup the board prompts for a name and email; that one-time handshake registers the board to your account. After that the Cloud Backup link opens straight onto a panel listing every backup that has ever been uploaded for this board.

Register Your Board

The registration banner appears on the Main page on first boot. Enter your name and email and click Register. Cloud Backup is then available; the Cloud Backup link in the bottom bar goes from grey to blue. You can dismiss the banner with Not now — it will reappear on later boots until you register or click Don't ask me again.

Automatic Backups

The router auto-backs-up:

• After every Save Changes (settings change).
• After every Save Routes (route change).
• After every successful OTA firmware upgrade.

The backup runs through the browser's TLS stack (not the device's), so big route sets ship reliably without making the board appear to freeze.

Viewing and Restoring Backups

Open Cloud Backup. The panel lists every backup with its timestamp and a Lock toggle. Click any backup to expand it, then Restore to push it back to the device.

Locking Important Backups

Unlocked backups rotate — once you exceed five, the oldest is deleted to keep storage costs sane. Lock the ones that matter (a particularly good operating state, a snapshot before a major rework, the night before an exhibition) and they're preserved indefinitely.

Re-registration for New Owners

If a board changes hands, the new owner clicks Change registered owner (the small grey link below the bottom action bar). The board returns to the registration banner state on the next boot.

Click Show Charts at the top of the Main page to expand four rolling 60-second strip charts:

• Wi-Fi RSSI — signal strength in dBm. -50 is rock-solid; -70 is borderline; -80 is rough.
• Wi-Fi Traffic — packets per 5-second window, Tx and Rx separately.
• CAN Activity — frames per second on the bus, with the current rate and the rolling peak.
• MQTT Activity — Tx, Rx, errors, reconnections (only meaningful in Native MQTT mode).

Click any chart to enlarge it. Click outside the enlarged chart to dismiss.

The Route Processor pulls firmware over Wi-Fi. Updates are signed and version-checked — a corrupted or rolled-back image is rejected before being committed.

What you see on the Update page

Browse to /update. The page shows:

• Currently installed version and build date.
• Latest stable version available on S3 (with a link to its release notes).
• A Pre-release toggle that switches the update channel from stable to beta.
• An Update History panel listing every previously installed version and the option to roll back.

How to install an update

1. Open /update in your browser.
2. Confirm the "available" version is newer than what's installed. If not, click Check now.
3. Click Install. The page tracks the download (~1.2 MB) then the flash write.
4. The board reboots into the new image. Watch for the green LED returning to slow-blink.
5. The board auto-backs-up post-OTA, then verifies the new image works. If it crashes, the bootloader rolls back to the previous image on the next boot.

Firmware Validation — Your Safety Net

The new image is committed to flash but kept on probation for the first 30 seconds after boot. If the board crashes or the firmware sets an explicit "validation failed" flag during that probationary window, the bootloader rolls back to the previous image on the next boot. After 30 seconds of clean operation the validation flag is set and the image becomes permanent.

Manual Rollback

If you install an update and decide you preferred the previous version, the Update History panel has a Rollback button next to the previous version. Click it, confirm, and the board reboots into the old image. The skipped version is added to a do-not-auto-install list so the next "Check now" doesn't keep offering the version you just rolled back from.

Recovery Mode

If something goes catastrophically wrong — a corrupt SPIFFS, a wedged main image, an OTA that bricked Wi-Fi setup — the board falls back into Recovery Mode: a minimal firmware that brings up Wi-Fi, hosts a static page, and lets you OTA a known-good image. The Recovery image is also published to S3 and updates whenever the main image does.

Pre-release Channel

Flip the Pre-release toggle to switch to the beta channel. Beta firmware is the next release candidate — new features are visible there first. Beta builds carry both stable and beta entries in the manifest, so you can roll back to the latest stable from any beta build.

The CAN Monitor page (/monitor) is a live trace of every CAN frame the Route Processor sees on the bus — the diagnostic equivalent of a packet sniffer. Open it when something on the bus isn't doing what you expect.

Accessing the monitor

From any System2 page bottom-bar, click CAN Monitor. The view opens with the trace running — new frames appear at the top of the table as they arrive.

The Filter Bar

At the top of the page sits the filter bar. Type a vPort number to show only frames touching that vPort. Tick a command (SET / CLEAR / TOGGLE / PUBLISH…) to limit the display to that command type. Pause the live feed to take screenshots or share captures.

Packet Log Columns

The Dashboard (/dashboard) is a read-only at-a-glance health summary. Open it before starting an operating session and again when something doesn't smell right.

System

Uptime, free heap, free PSRAM (if present), flash usage, total reboots since first boot, and the active firmware version with build date.

Wi-Fi

SSID, RSSI, IP address, gateway, association uptime, and total reconnects since boot.

CAN Bus

Configured CAN ID (auto or manual), frames received and transmitted since boot, bus errors, and the rolling-window frame rate.

MQTT

Only meaningful in Native MQTT mode. Broker hostname, connection state, Tx / Rx / error counters, reconnections.

Route Engine

Total routes configured (1–100), routes fired since boot, conditions deferred since boot, conditions dropped since boot, timed-route fires since boot, fast-clock state and current layout time.

Diagnostics

Collapsible section: partition layout, version history, last 32 boot-cause records (clean reboot / brown-out / WDT reset / etc.), and a link to the raw status log JSON.

The status log at the foot of the Main page is the Route Processor's running narrative. Every significant event is emitted as a single-line entry with a timestamp:

What appears in the log

• Boot summary (version, build, free heap, Wi-Fi association time).
• CAN frames that fire a route ("Route 12 fired (CAN vP 101 SET)").
• Timed route fires ("Route 10 fired (interval 720s)").
• Condition failures and deferrals ("Route 15 deferred 4s — cond block-yard-clear failed").
• Save/Load events, registration handshakes, OTA progress.
• Error frames, dropped frames, bus errors, network disconnections.

Reading the log

The log is reverse-chronological: newest at the top. Background colour indicates severity — green for normal operation, yellow for warnings, red for errors. Hover over any line to see the full timestamp and source.

Using the log for troubleshooting

The status log is the single best place to start when something isn't working. A common diagnostic flow:

1. Note the time you observed the bad behaviour on the layout.
2. Open the status log and scroll to that timestamp.
3. Look for the route fire you expected. If it's not there, the trigger never reached the Route Processor — check the CAN Monitor.
4. If the route fire is there but tagged "deferred" or "dropped", check the conditions in the route's Trigger Gating section.
5. If the route fired but the layout didn't respond, the problem is on the receiving board — check that board's status log.

The Contact page (/contact) lets you send feedback, bug reports, or feature requests straight from the board to MegaPoints. The page is purpose-built — no email account or copy-paste needed.

Feedback Categories

• Bug report — something the firmware does wrong.
• Feature request — something you wish it did.
• Question — "how do I…".
• Other — everything else.

What Gets Sent

The text you type, plus a small device fingerprint: firmware version, free heap, uptime, configured protocol, total reboots. No route data is sent. No Wi-Fi credentials are sent.

Internet Connectivity

The Contact page needs the board to be on a Wi-Fi network with internet access — the message goes out over the same HTTPS endpoint used for cloud backup. If the board is on an isolated Wi-Fi network, the form will say so before you waste effort typing.

Every Route Processor exposes a small REST API for scripting and integration. Use it from JMRI Jython, Home Assistant, Node-RED, a phone-side app, or any tool that can speak HTTP.

Quick Examples

# Fire route 10 immediately
curl -X POST http://route-bench.local/api/route/trigger/10

# Read current state of vPort 201
curl http://route-bench.local/api/vport/201

# Write vPort 311 to CLEAR
curl -X PUT http://route-bench.local/api/vport/311 -d 'value=0'

# Read live diagnostics
curl http://route-bench.local/api/debug/stats

# Start a fast-clock session at 12x
curl -X POST http://route-bench.local/api/fc/start?mult=12

Full API Endpoints

Built for reliability

The Route Processor runs on an ESP32 module with 4 MB of flash, partitioned for redundant OTA images plus SPIFFS storage. The CAN controller is a hardware MCP-class peripheral — not bit-banged — so frame timing is rock-solid.

What makes it robust

• Rollover-safe timers — every millis() comparison uses the subtraction pattern, so the 49-day rollover doesn't disturb timed routes, intervals, or schedules.
• Cross-core route cache — the route store is protected by a mutex that holds across pin-set-mark, so timed-route scanning on the other core can't evict a slot mid-restore.
• Streaming manifest fetch — the OTA manifest is streamed, not buffered, so release notes can grow beyond 2 KB without breaking the version check.
• Browser-direct cloud backup — the ESP32 doesn't attempt to be a TLS client for the large backup payload. The desktop browser does that, which lets full 100-route layouts back up reliably.
• Boot-cause tracking — the last 32 boot causes are kept in RTC memory and surfaced on the Dashboard, so a flaky power supply or marginal supply rail leaves a trail.
• Recovery image — even a catastrophic main-firmware failure leaves a fallback that can OTA itself back to health.

Specifications

The CAN bus is the layout's nervous system: every System2 board listens on it and any board can publish to it. Wiring is two screw terminals (H and L) plus a common ground reference between any two adjacent boards.

Wiring rules

• Two wires, twisted pair recommended (cheap CAT5 / CAT6 is ideal).
• Daisy-chain only — no star, no Y-splitters in the middle of a run.
• 120 Ω termination at each end of the bus. Not in the middle.
• Total bus length up to 100 m at 125 kbit/s. Most layouts will be well under this.
• Common DC ground between all boards on the bus. The CAN screw terminals do not carry ground — share the 12 V supply rail across all System2 boards if possible, or wire a dedicated ground link if not.

Termination Jumpers

Each System2 board (including the Route Processor) has an on-board 120 Ω termination resistor with a slide-switch or jumper to enable/disable it. Look for the silkscreened TERM label near the CAN terminals.

• Both bus endpoints terminate. Whichever two boards are at the physical ends of the daisy-chain have TERM enabled.
• Every intermediate board does not. All middle boards have TERM disabled.