Monitoring and Troubleshooting

Use evidence, not guesses

First make the railway safe. Note the exact time and the last action that succeeded, then inspect the relevant monitor before changing addresses, routes or geometry. Change one thing at a time and repeat the same test. Randomly editing several objects can hide the original cause and create new inconsistencies. RailKernel’s refusal dialogs, state tooltips and logs are designed to tell you why an operation stopped; read those messages before rebuilding anything.

Identify which layer is wrong

Project model

Tracks, connectors, blocks, feedback membership, accessories, routes, train placement and configuration. Project Statistics and previews primarily test this layer.

RailKernel runtime

Live occupancy, accessory state, reservations, queued and paused movements, dwell sessions and calculated routes. The Feedback, Accessory and Train monitors expose this layer.

Command station

The messages RailKernel sends and the events it receives. Command-station overview, connection state and protocol logging expose this layer.

Physical railway

Actual turnout position, detector wiring, rolling stock, power, derailments and mechanical failures. Only direct observation can confirm this layer.

Start with Project Statistics

Open Project Statistics from the View menu before testing automatic driving. Open connectors indicate incomplete geometry; unreachable elements indicate that part of the graph cannot be traversed. Automatic driving deliberately refuses an inconsistent project because no monitor can compensate for a broken railway model. After changing tracks, blocks or feedbacks, also inspect saved routes: a formerly valid route may no longer describe the modified graph.

Feedback Monitor: what is occupied?

Feedback Monitor shows the live contacts known to the project and command stations. Use it to verify address, bus and module assignment and to watch FREE/OCCUPIED transitions while operating one detector at a time. The configured colours distinguish normal, occupied and special/action-related contacts. If a detector works at the command station but not in RailKernel, compare its complete identity—not only its final contact number—and check the bus lengths and selected command station. A contact that changes unexpectedly is evidence; do not merely invert it until you understand the wiring and configured polarity.

Accessory Monitor: compare project and station

Accessory Monitor overlays the layout accessories with devices imported from a capable command station. Its states distinguish project-only, matching, command-station-only and conflicting definitions. Accessories without an address are intentionally irrelevant to live comparison. Double-click a conflict for its explanation. If a turnout does not move, verify command station, protocol, address, port half or multi-address definition, current versus default state and the physical decoder. A command in a protocol log with no physical movement points away from routing and toward station, decoder, wiring or mechanism.

Train Monitor: why is a train waiting?

Train Monitor shows every queued, running, dwelling, paused or reserved operation. Read the State tooltip, destination and reserved blocks before pressing Release or Abort. PAUSED commonly means RailKernel is safely waiting for a corridor; it can resume automatically when infrastructure becomes available. Start launches queued work, Stop Cycle ends an operation gracefully, Abort abandons one operation and Emergency Stop is railway-wide. The dedicated Train Monitor page describes the consequences of each action.

Driving Log: reconstruct the decision

Driving Log records the sequence behind automatic operation: route selection, corridor reservation, accessory requirements, locomotive commands, feedback transitions, braking, dwell, continuation, pause, release and alarms. Search around the exact timestamp of the symptom and follow one train name. The useful question is not only “what failed?” but “what was the last safety condition RailKernel could still prove?” Copy the relevant section before restarting, because a fresh run may replace the context you need.

Command-station protocol logs

The Command Station dialog provides bounded live logging for supported CS3, ECoS and Z21 connections. Each log shows timestamp, a readable mnemonic and the underlying protocol frame or message, with Clear, Copy and Close controls. Use it to answer two separate questions: did RailKernel send the expected command, and did the station send the expected reply or event? A missing outgoing command suggests application state or configuration; a correct outgoing command without a station reply suggests connection or protocol; a correct exchange without physical action suggests hardware. Clear immediately before a short reproduction so the evidence remains readable.

When a command station does not connect

• Confirm that the station is enabled in Connections and that its type, display name, host and port are correct.
• Read the startup progress message to see whether loading configuration, connecting, downloading station data or reading initial state is the slow step.
• Use Scan Network where supported, but verify that the discovered device is the station you intend to control.
• Check that the computer and station are on reachable networks and that another application is not exclusively occupying the interface.
• Open the station’s protocol log and perform one small action. No traffic and rejected traffic are different failures.
• Disable unrelated command stations temporarily when isolating startup or timeout behaviour.

Common symptoms and the best first check

Cannot Place Train

Click the disabled explanation and verify occupied exit feedback, unique block membership, block reservation and availability of an unplaced Simple Train.

Cannot Move Train

Use RailKernel’s reason dialog. Check project consistency, source-block speed, command-station GO state, train/locomotive identity, next-block occupancy and missing accessory protection.

Train remains paused

Read its Train Monitor tooltip and reserved corridor. Wait for the blocking train first; use Release only when this train’s own retained reservations are known to be stale.

Turnout moves on screen only

Compare Accessory Monitor and the outgoing protocol command, then verify decoder address, port, power and mechanism.

Turnout moves physically only

Look for the returned accessory event and verify that it is mapped to the same command station, protocol and address as the project accessory.

Feedback is correct after a change but wrong at startup

Inspect initial-state traffic and full bus/module/contact identity. A live transition working later does not prove that startup discovery and initial synchronization are correct.

Repeated Emergency Stop

Use the reported feedback and timestamp. Check unexpected rolling stock, detector bounce or polarity, wrong block membership, action rules and a mismatch between physical and placed train positions.

Route preview omits infrastructure

Inspect the saved route and calculated accessory legs. Preview displays what the route actually contains; missing orange infrastructure is usually missing route data, not merely a paint problem.

Prepare a useful problem report

Include RailKernel version, operating system, command-station type and software version, the exact local time of the event, the smallest repeatable sequence, expected and observed result, the relevant monitor screenshot, and copied Driving Log or protocol-log lines. Export or privately upload the project when geometry or routing is involved. State whether the problem survives a restart and whether it occurs with one command station enabled. Never publish license files, passwords, private keys or unrelated personal data.

Preserve a known-good point

Commit source changes and keep dated project backups before a structural edit or routing experiment. When a regression appears, reproduce it once, preserve the evidence and compare against the last known-good state. Reverting one isolated change is far safer than repairing a growing chain of speculative fixes. Monitoring is not an afterthought: it is what makes a complex physical/digital system maintainable.