tslumd.messages

class tslumd.messages.Display(index: int, rh_tally: TallyColor = <TallyColor.OFF: 0>, txt_tally: TallyColor = <TallyColor.OFF: 0>, lh_tally: TallyColor = <TallyColor.OFF: 0>, brightness: int = 3, text: str = '', control: bytes = b'', type: MessageType = MessageType.display, text_length: int | None = None)

Bases: object

A single tally “display”

index: int

The display index from 0 to 65534 (0xFFFE)

rh_tally: TallyColor = 0

Right hand tally indicator

txt_tally: TallyColor = 0

Text tally indicator

lh_tally: TallyColor = 0

Left hand tally indicator

brightness: int = 3

Display brightness (from 0 to 3)

text: str = ''

Text to display

control: bytes = b''

Control data (if type is control)

Added in version 0.0.2.

type: MessageType = 1

The message type. One of display or control.

• For display (the default), the message contains text information and the control field must be empty.

• For control, the message contains control data and the text field must be empty

Added in version 0.0.2.

is_broadcast: bool

True if the display is to a “broadcast”, meaning sent to all display indices.

(if the index is 0xffff)

Added in version 0.0.2.

text_length: int | None = None

Length of the text field

If provided, the text output will be zero-padded or truncated to this length. If None (the default), the text length is variable.

Note

This is mainly for internal use during test runs to match the fixed-length text field in actual message bytes.

Added in version 0.0.8.

class SerializeTD

Bases: TypedDict

Dictionary representation of a Display instance

classmethod broadcast(**kwargs) → Display

Create a broadcast display

(with index set to 0xffff)

Added in version 0.0.2.

classmethod from_dmsg(flags: Flags, dmsg: bytes, retain_text_length: bool = False) → Tuple[Display, bytes]

Construct an instance from a DMSG portion of received message.

Any remaining message data after the relevant DMSG is returned along with the instance.

Parameters:

• flags – The message Flags field

• dmsg – The portion of the message containing the DMSG data

• retain_text_length – If True, the text_length attribute will be set to the length of the text field as found in the message bytes. Otherwise (the default), it will be set to None and the text length will be variable.

Changed in version 0.0.8: The retain_text_length argument was added.

static _unpack_control_data(data: bytes) → Tuple[bytes, bytes]

Unpack control data (if control bit 15 is set)

Parameters:

data – The portion of the dmsg at the start of the “Control Data” field

Returns:

remaining

The remaining message data after the control data field

Return type:

bytes

Note

This is undefined as of UMDv5.0 and its implementation is the author’s “best guess” based off of other areas of the protocol

Added in version 0.0.2.

static _pack_control_data(data: bytes) → bytes

Pack control data (if control bit 15 is set)

Parameters:

data – The control data to pack

Returns:

packed

The packed control data

Return type:

bytes

Note

This is undefined as of UMDv5.0 and its implementation is the author’s “best guess” based off of other areas of the protocol

Added in version 0.0.2.

to_dmsg() → bytes

Build dmsg bytes to be included in a message (called from Message.build_message())

to_common_dict() → DisplayTallyCommonDict

Return a dict of the common fields between Display and Tally objects

Added in version 0.0.8.

classmethod from_tally(tally: Tally, msg_type: MessageType = MessageType.display) → Display

Create a Display from the given Tally

Added in version 0.0.2: The msg_type argument

class tslumd.messages.Message(version: int = 0, flags: Flags = <Flags.NO_FLAGS: 0>, screen: int = 0, displays: list[Display] = <factory>, scontrol: bytes = b'', type: MessageType = MessageType.display)

Bases: object

A single UMDv5 message packet

version: int = 0

Protocol minor version

flags: Flags = 0

The message Flags field

screen: int = 0

Screen index from 0 to 65534 (0xFFFE)

displays: list[Display]

A list of Display instances

scontrol: bytes = b''

SCONTROL data (if type is control)

type: MessageType = 1

The message type. One of display or control.

• For display (the default), the contents of displays are used and the scontrol field must be empty.

• For control, the scontrol field is used and displays must be empty.

Added in version 0.0.2.

is_broadcast: bool

True if the message is to be “broadcast” to all screens.

(if screen is 0xffff)

Added in version 0.0.2.

classmethod broadcast(**kwargs) → Message

Create a broadcast message

(with screen set to 0xffff)

Added in version 0.0.2.

classmethod parse(msg: bytes, retain_text_length: bool = False) → Tuple[Message, bytes]

Parse incoming message data to create a Message instance.

Any remaining message data after parsing is returned along with the instance.

Parameters:

• msg – The incoming message bytes to parse

• retain_text_length – Value to pass to Display.from_dmsg()

Changed in version 0.0.8: The retain_text_length argument was added.

build_message(ignore_packet_length: bool = False) → bytes

Build a message packet from data in this instance

Parameters:

ignore_packet_length (bool, optional) – If False, the message limit of 2048 bytes is respected, and if exceeded, an exception is raised. Otherwise, the limit is ignored. (default is False)

Raises:

MessageLengthError – If the message packet is larger than 2048 bytes (and ignore_packet_length is False)

Note

This method is retained for backwards compatability. To properly handle the message limit, use build_messages()

Changed in version 0.0.4:

• The ignore_packet_length parameter was added

• Message length is limited to 2048 bytes

build_messages(ignore_packet_length: bool = False) → Iterator[bytes]

Build message packet(s) from data in this instance as an iterator

The specified maximum packet length of 2048 is respected and if necessary, the data will be split into separate messages.

This method will always function as a generator, regardless of the number of message packets produced.

Added in version 0.0.4.

exception tslumd.messages.ParseError(msg: str, value: bytes)

Bases: Exception

Raised on errors during message parsing

Added in version 0.0.2.

msg: str

Error message

value: bytes

The relevant message bytes containing the error

exception tslumd.messages.MessageParseError(msg: str, value: bytes)

Bases: ParseError

Raised on errors while parsing Message objects

Added in version 0.0.2.

exception tslumd.messages.DmsgParseError(msg: str, value: bytes)

Bases: ParseError

Raised on errors while parsing Display objects

Added in version 0.0.2.

exception tslumd.messages.DmsgControlParseError(msg: str, value: bytes)

Bases: ParseError

Raised on errors when parsing Display.control data

Added in version 0.0.2.

exception tslumd.messages.MessageLengthError

Bases: ValueError

Raised when message length is larger than 2048 bytes

Added in version 0.0.4.