pyrocrail 1.0.0

Python library for interfacing with Rocrail model railway control software

PyRocrail

Python library for controlling Rocrail model railway systems.

PyRocrail provides a Pythonic interface to the Rocrail server, allowing you to control locomotives, switches, signals, routes, and other layout objects programmatically. Replace XML scripting with Python for better automation and control.

Features

• 17 Object Types: Full support for locomotives, blocks, switches, signals, routes, and more
• Real-time Control: Direct TCP/IP communication with Rocrail server
• Event-Driven: Action system for time-based and event-based automation
• Type-Safe: Complete type annotations for IDE support and error detection
• Verified Commands: All commands verified against official Rocrail documentation

Documentation

• Object Reference - Complete documentation for all object types with links to official Rocrail docs
• Testing Strategy - Testing approach and guidelines
• Examples - Tutorial examples and usage patterns

Quick Start

from pyrocrail import PyRocrail, Action, Trigger
import time

# Connect to Rocrail using context manager (automatic cleanup)
with PyRocrail("localhost", 8051) as pr:
    # Control a locomotive
    loco = pr.model.get_lc("BR01")
    loco.set_speed(50)
    loco.set_direction(True)
    loco.go()

    # Set a switch
    switch = pr.model.get_sw("SW01")
    switch.turnout()

    # Activate a route
    route = pr.model.get_st("RT01")
    route.set()

    # Time-based action (run at 12:30)
    def morning_announcement(model):
        print("Morning operations starting")

    pr.add(Action(
        script=morning_announcement,
        trigger_type=Trigger.TIME,
        trigger="12:30"
    ))

    # Event-based action (when sensor activates)
    def on_train_detected(model):
        loco = model.get_lc("BR01")
        loco.set_speed(25)  # Slow down

    pr.add(Action(
        script=on_train_detected,
        trigger_type=Trigger.EVENT,
        trigger="FB01",
        condition="obj.state == True"
    ))

    # Keep running
    try:
        while True:
            time.sleep(1)
    except KeyboardInterrupt:
        pass
# Automatically cleaned up when exiting 'with' block

Installation

# Clone the repository
git clone https://github.com/thetrainroom/py-rocrail.git
cd py-rocrail

# Install with Poetry
poetry install

# Or install with pip
pip install -e .

Supported Objects

See OBJECTS.md for complete documentation.

Object	Description	Rocrail Docs
Locomotive	Train engine control	lc-gen-en
Block	Track section management	block-gen-en
Switch	Turnout/point control	switch-gen-en
Signal	Signal aspect control	signal-gen-en
Route	Path routing	route-gen-en
Feedback	Sensor detection	sensor-gen-en
Output	Accessory control	output-gen-en
Car	Rolling stock	car-gen-en
Operator	Train compositions ("Trains" in GUI)	operator-gen-en
Schedule	Timetables	schedule-gen-en
Stage	Staging yards	stage-details-en
Text	Information displays	text-gen-en
Booster	Power districts	booster-gen-en
Variable	Global variables	variable-gen-en
Weather	Atmospheric effects	weather-gen-en

Plus: Tour, Location, and more...

Development

# Run linter
ruff check $(git ls-files '*.py')

# Run type checker
pyright src/pyrocrail

# Format code
black --line-length 180 src/

References

• Rocrail Wiki
• XMLScript Documentation
• Rocrail Protocol

License

See LICENSE file for details