Loco Sound API

Architecture

The architecture of loco sound is wrapped primary around a main loop of a pygame application.

Startup

During startup we will try

Sound Packet

Speed Curve

_images/speed_curve.png

Measured time between cylinder sound time delta and Z21 speed steps.

Z21

Z21 is a digital platform to control miniature train by the manufacture Roco/Fleischmann.

The LAN specification of the Z21 can be found here.

Sources

loco_sound.loco

The loco package stores the state of each registered locomotive. For registration of a locomotive, see loco_sound.loco.LocoCollector.add_locos()

class loco_sound.loco.Loco(loco_number)

This class has all the loco logic

Parameters

  • loco_number (int) – The number of the locomotive you want to control.

  • scheduled_function_calls – Scheduled function calls.

change_f_0(new_value, old_value, all_functions, *args, **kwargs)

Foo

Parameters

new_value (bool) – Foo

class loco_sound.loco.SteamLoco(loco_number)
class loco_sound.loco.LocoCollector

This class maps a Loco to a SoundPackage, passes updates in form of LocoInfo to a within a LocoCollector registered Loco and also checks if some scheduled functions needs to be called. This is necessary on a SteamLoco.

add_locos(*locos)

Registers a Loco for information monitoring.

execute_due_functions()

Each registered Loco can store a set of functions in the attribute scheduled_function_calls which should be executed in the future at a given timestamp.

We check if these functions are due and if so we will execute them.

update_locos(*loco_infos)

Passes the received LocoInfo update to a registered Loco in our collector. If the loco_address of LocoInfo is not registered we will ignore the info.

Parameters

loco_infos (LocoInfo) – Received updates

loco_sound.z21

The z21 package contains the network communication to the Z21.

class loco_sound.z21.Message(header, x_header=None, db_data=None, xor=None, length=None)

Serializes and builds messages for Z21. For serializing see from_z21_message().

See Z21 LAN reference sheet for more information.

Parameters

  • header (bytearray) – Header

  • x_header (Optional[int]) – X_header

  • db_data (Optional[bytearray]) – db_data

  • xor (Optional[int]) – xor byte

  • length (Optional[bytearray]) – 2 length bytes.

property data

Builds a byte representation of the message which can be send to Z21.

Return type

bytearray

Returns

Message as raw bytes.

classmethod from_z21_message(message)

Parses a received Z21 message.

Parameters

message (bytearray) – Raw byte UDP package received from Z21.

class loco_sound.z21.Client(host='192.168.0.111', port=21105)

Handles the communication to the Z21 in both ways via send_message() and listen().

Parameters

  • host (str) – Hostname of the z21 in your network.

  • port (int) – Port number of the z21

listen()

Collects UDP messages which were send to us.

Todo

Maybe marry this properly into the main loop by providing callback

Return type

Optional[Message]

Returns

If a message is available we will return this as a parsed Message. If no message is available we will return None.

send_message(message)

Sends a Message to the connected z21.

Parameters

message (Message) – Message which you want to send.

Return type

None

send_welcome()

Sends welcome message to z21 so we are a registered client. We do this by asking for the serial number of the z21.

We will call this periodically so we still receive messages from z21 after some time because otherwise we will get logged out as a client.

Return type

None

subscribe_to_all_locos()

Sends message so we are subscribed to changes of all locomotives. You need to collect the messages from z21 via listen().

Return type

None

subscribe_to_loco(loco)

Subscribes to a single loco for changes. You need to collect the messages from z21 via listen().

Warning

Using this is not recommended because we will receive stacked messages which are not yet supported. This also this limits our application to 15 locos. Use subscribe_to_all_locos() instead.

Parameters

loco – Loco on which you want to receive changes from.

Return type

None

class loco_sound.z21.LocoInfo(loco_address, dcc_speed_steps, direction, speed, functions)

Serializes locomotive status updates from a received loco_sound.z21.Message, see from_z21_response().

Parameters

  • loco_address (int) – Address which caused the information

  • dcc_speed_steps (int) – Speed steps of the loco

  • direction (int) – Driving direction of the loco. 0 for backwards, 1 for forwards.

  • speed (int) – speed step which was send - will be absolute so please compare with dcc_speed_steps for relative speed.

  • functions (Dict[int, bool]) – Stores a dict of which informations are selected and which are currently not selected.

classmethod from_z21_response(message)

Serializes a loco_sound.z21.Message

Parameters

message (Message) – Message which you want to serialize.