Welcome

BTrain is my¹ attempt at automating a model railway layout. It is open-source and free to use but still experimental: use it at your own risk!

This is a slightly modified version of Jean Bovet's BTrain repository to allow BTrain to be used without an attached Marklin CS2 or CS3 controller. For the original version, see here. To use BTrain without a CS2 / CS3 controller, tick on "Gleisbox" in the Preferences panel.

This YouTube video shows BTrain in action with my still-in-progress layout.

BTrain allows the layout to be created quickly with just a few clicks. Each block is connected to another block using curves that can be dragged and dropped.

BTrain renders many details of the train in the layout, including the position and direction of travel of the locomotive and its wagons and the name of the block. Individual feedbacks located in the block are displayed and expected feedbacks - when BTrain is in charge of monitoring the position of each train.

Each train's direction, speed, and position is controlled via a dedicated section. A train can follow a predefined route or a random route created on the fly as the train moves through the layout.

BTrain allows routes to be defined manually or automatically without any effort. Automatic route allows a train to be moved on the layout without the need to define a route ahead of time. The integrated CS 3 simulator simulates the entire layout before connecting to the real CS 3.

BTrain allows each locomotive's speed to be measured using 3 feedbacks. This measurement enables the locomotive speed to represent its prototype accurately and ensures all locomotives move at the same speed regardless of their decoder type.

An embedded Marklin Central 3 station simulator allows BTrain to simulate a layout entirely offline, allowing the development of the layout without connecting to a real Central Station 3 until it is ready.

BTrain offers several editors to define the various elements of the layout, such as blocks, turnouts, feedback, trains, locomotive, and much more. Here is the locomotive editor, which automatically retrieves the locomotive defined in the Central Station:

BTrain allows the user to write powerful scripts without a single line of code. A script is a series of commands that runs a train along a specific user-defined route:

BTrain defines several routes:

• Automatic routes that are created automatically when BTrain moves a train from one block to another or when the user asks BTrain to move the train in the layout without any particular destination in mind.
• User-defined routes that the user creates. A powerful editor allows for the user-defined routes to be created in a few minutes:

Requirements

Either

• Marklin Central Station 3 (CS3); or
• Marklin 60116 Gleisbox (optionally with a Mobile Station 2 (MS2)) with a TCP-CAN hub

Features

• Easy to use layout editor where blocks and turnouts can be added in one click and linked together by dragging and dropping links between them.
• Locomotive speed, acceleration and direction control.
• Locomotive speed measurements.
• Turnouts state control.
• Automatic or manual routing management of one or more trains simultaneously with collision avoidance and shortest path detection.
• Take into account the length of the train, block, turnout, and feedback position to accurately understand the location of each train to reserve the necessary block to avoid a collision.
• Visual feedback of the exact location of the train, including the locomotive and its wagons, within blocks.
• Unexpected feedback detection.
• Automatic discovery of locomotives (with a CS3 only).
• Offline layout simulator to simulate the movement of the trains, including feedbacks and turnouts, without having to connect to a real Central Station 3.

Known Issues

• The document does not get marked as "Edited" for some changes.
• Gleisbox support does not provide full access to all locomotive functions.

Glossary

• Block: a logical grouping of rails where one and only one train can be present at a time; has a physical length to reckon a train position in it
• Station: a special type of block that optionally lets a train wait in it a while before proceeding
• Turnout: an element that guides a train from one rail to another
• Feedback: an element that indicates when a train is present or not
• Transition: any stretch of track between a block and turnout (and any combination of); has no physical length by definition
• Route: a series of blocks that a train follows
• Train: a locomotive and collection of wagons (each of which has a length)

Build from Source

To compile BTrain from source, the following versions are required:

• macOS 13.x (or higher)
• Xcode 14.x (or higher)

Clone this repository and open the BTrain.xcodeproj in Xcode. Hit Command-R and enjoy!

References

• MFX (German)
• Marklin CS2 CAN Protocol version 1.0 (German)
• Marklin CS2 CAN Protocol version 2.0 (German)
• Thanks to Frans Jacobs for his open-source project that inspired me to create the initial command interface to the Central Station.

Copyrights

• Application icon (c) Manaqib S from NounProject.com
• Undo Provider (c) 2020 by Matthaus Woolard
• Custom Slider (c) 2020 Aubree Quiroz
• GraphicsRenderer (c) 2016 by Shaps Benkau
• Unit tests use ViewInspector by Alexey Naumov

Copyright 2021-22 Jean Bovet

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Footnotes

1. Me, my and I in this document refer to Jean Bovet ↩