z21aio - Z21 DCC Command Station API

z21aio is an async Python library for controlling Roco/Fleischmann Z21 DCC command stations over UDP.

Features

• Pure Python asyncio implementation - No external dependencies, stdlib only

• Control locomotives - Speed, direction, and functions (F0-F31)

• Track power management - Turn track power on/off

• System state monitoring - Monitor voltage, current, and temperature

• Multiple simultaneous connections - Control multiple Z21 stations in parallel

• RailCom support - Read back locomotive data (firmware 1.29+)

Requirements

• Python 3.10 or higher

• Roco/Fleischmann Z21 command station

Installation

Install via pip:

pip install z21aio

Or install from source:

git clone https://github.com/botmonster/z21aio.git
cd z21-dcc
pip install -e .

Quick Start

Here’s a minimal example to connect to a Z21 station and control a locomotive:

import asyncio
from z21aio import Z21Station, Loco

async def main():
    # Connect to Z21 station
    async with await Z21Station.connect("192.168.0.111") as station:
        # Get serial number
        serial = await station.get_serial_number()
        print(f"Connected to Z21, serial: {serial}")

        # Turn on track power
        await station.voltage_on()

        # Control locomotive at address 3
        loco = await Loco.control(station, address=3)
        await loco.set_headlights(True)
        await loco.drive(50.0)  # 50% forward

        await asyncio.sleep(5)

        await loco.stop()
        await station.voltage_off()

asyncio.run(main())

Contents

• Quick Start
  • Basic Connection
  • Key Points
  • Multi-Station Control
  • Speed Control
  • Function Control
  • Throttle Modes
  • Getting Station Information
  • System State Monitoring
  • Locomotive State
  • RailCom Support
  • Error Handling
  • Next Steps
• API Reference
  • Core Classes
  • Message Handling
  • Data Types
  • Low-Level Details
• Examples
  • Basic Example
  • Speed Control Example
  • Function Control Example
  • Multi-Station Example
  • System State Monitoring Example
  • Locomotive State Example
  • Custom Example
  • Tips

Key Concepts

Z21Station

The main entry point for communicating with a Z21 command station. Use the async context manager for proper resource management.

Example:

async with await Z21Station.connect("192.168.0.111") as station:
    await station.voltage_on()

Loco

Control a locomotive on the track. Use the control() class method to take control of a locomotive by its address.

Example:

loco = await Loco.control(station, address=3)
await loco.drive(75.0)  # 75% forward

DccThrottleSteps

Specify the throttle resolution for a locomotive. Supported modes:

• DccThrottleSteps.STEPS_14 - 14-step mode (legacy)

• DccThrottleSteps.STEPS_28 - 28-step mode (common)

• DccThrottleSteps.STEPS_128 - 128-step mode (default, smoothest)

Example:

loco = await Loco.control(
    station,
    address=3,
    steps=DccThrottleSteps.STEPS_128
)

Architecture

z21aio implements a layered protocol stack:

1. Packet - UDP frame serialization/deserialization

2. XBusMessage - X-Bus tunneling layer (encapsulated in UDP)

3. Z21Station - Connection management and packet routing

4. Loco - High-level locomotive control

All communication uses the official Z21 LAN Protocol specification.

Protocol Reference

For detailed protocol documentation, see the Z21 LAN Protocol Specification included in the repository.

License

MIT License - See LICENSE file for details.

Indices and tables

• Index

• Module Index

• Search Page