Other Classes & Methods

Knowledge of the following classes, methods, constants, and functions is only of benefit to those who wish to better understand the internals of the metlinkpid module.

Message Class

class metlinkpid.Message

The Message class is an abstract base class of the DisplayMessage, PingMessage, and ResponseMessage classes. Its existence allows for simplified implementation & return typing of the inspect() function.

abstract classmethod marker() → bytes

The bytes that a raw byte representation must start with in order to possibly be an instance of this Message subclass.

abstract classmethod from_bytes(bytes_in: bytes) → metlinkpid.Message

Construct an instance of this Message subclass from a raw byte representation (not including the CRC-checksumming and packet-framing required for transmission).

abstract to_bytes() → bytes

Construct a raw byte representation of this Message subclass (not including the CRC-checksumming and packet-framing required for transmission).

PingMessage Class

class metlinkpid.PingMessage(unspecified_byte: int = 111)

A PingMessage exists as Message to send to the display with no visual effect, but which impedes the automatic clearing of the display (which otherwise occurs after approximately one minute of inactivity).

PingMessage objects are exclusively constructed and sent by the PID.ping() method, but they exist as a class in case their raw byte representations are passed to the inspect() function.

Parameters

unspecified_byte – a byte that seems to have no effect if changed, but in deployment is typically 0x6F.

classmethod from_bytes(bytes_in: bytes) → metlinkpid.PingMessage

Construct an instance of this Message subclass from a raw byte representation (not including the CRC-checksumming and packet-framing required for transmission).

to_bytes() → bytes

Construct a raw byte representation of this Message subclass (not including the CRC-checksumming and packet-framing required for transmission).

ResponseMessage Class

class metlinkpid.ResponseMessage(unspecified_byte: int)

A ResponseMessage represents a response received from the display after a transmission to it.

ResponseMessage objects are not intended to be sent to the display. They exist as a class in order to be recognised by the inspect() function, which is used internally by PID.send() to verify acknowledgement from the display following the sending of a message.

Parameters

unspecified_byte – a variable byte that usually somewhat seems to be related to the unspecified_byte value of the previously-sent PingMessage, but not always, so it is captured but otherwise ignored.

classmethod from_bytes(bytes_in: bytes) → metlinkpid.ResponseMessage

Construct an instance of this Message subclass from a raw byte representation (not including the CRC-checksumming and packet-framing required for transmission).

to_bytes() → bytes

Construct a raw byte representation of this Message subclass (not including the CRC-checksumming and packet-framing required for transmission).

Private Page Methods & Constants

_encode_text() Method

classmethod Page._encode_text(text: str) → bytes

Convert a string of characters into a string of display-level bytes. Called from the to_bytes() method.

Parameters

text – the string for display.

Raises

ValueError – if any of the characters in the input are unable to be displayed.

_TEXT_ENCODING Constant

Page._TEXT_ENCODING = {' ': b' ', '!': b'!', '#': b'#', '$': b'$', '&': b'&', "'": b"'", '(': b'(', ')': b')', '*': b'*', '+': b'+', ',': b',', '-': b'-', '.': b'.', '/': b'/', '0': b'0', '1': b'1', '2': b'2', '3': b'3', '4': b'4', '5': b'5', '6': b'6', '7': b'7', '8': b'8', '9': b'9', ':': b':', ';': b';', '<': b'<', '=': b'=', '>': b'>', '?': b'?', 'A': b'A', 'B': b'B', 'C': b'C', 'D': b'D', 'E': b'E', 'F': b'F', 'G': b'G', 'H': b'H', 'I': b'I', 'J': b'J', 'K': b'K', 'L': b'L', 'M': b'M', 'N': b'N', 'O': b'O', 'P': b'P', 'Q': b'Q', 'R': b'R', 'S': b'S', 'T': b'T', 'U': b'U', 'V': b'V', 'W': b'W', 'X': b'X', 'Y': b'Y', 'Z': b'Z', '\\': b'\\', 'a': b'a', 'b': b'b', 'c': b'c', 'd': b'd', 'e': b'e', 'f': b'f', 'g': b'g', 'h': b'h', 'i': b'i', 'j': b'j', 'k': b'k', 'l': b'l', 'm': b'm', 'n': b'n', 'o': b'o', 'p': b'p', 'q': b'q', 'r': b'r', 's': b's', 't': b't', 'u': b'u', 'v': b'v', 'w': b'w', 'x': b'x', 'y': b'y', 'z': b'z', '·': b'\x8f', '•': b'\xd3', '─': b'\x97', '━': b'\xd2', '█': b'_', '▔': b'\xa3'}

A mapping from permissible ASCII/Unicode characters to the equivalent display-level byte.

_decode_text() Method

classmethod Page._decode_text(bytes_in: bytes) → str

Convert a string of display-level bytes into a string of characters. Any byte without a corresponding character is converted to the Unicode “Replacement Character” (�). Called from the Page.from_bytes() method.

Parameters

bytes_in – the display-level bytes.

_TEXT_DECODING Constant

Page._TEXT_DECODING = {b' ': ' ', b'!': '!', b'"': "'", b'#': '#', b'$': '$', b'&': '&', b"'": "'", b'(': '(', b')': ')', b'*': '*', b'+': '+', b',': ',', b'-': '-', b'.': '.', b'/': '/', b'0': '0', b'1': '1', b'2': '2', b'3': '3', b'4': '4', b'5': '5', b'6': '6', b'7': '7', b'8': '8', b'9': '9', b':': ':', b';': ';', b'<': '<', b'=': '=', b'>': '>', b'?': '?', b'A': 'A', b'B': 'B', b'C': 'C', b'D': 'D', b'E': 'E', b'F': 'F', b'G': 'G', b'H': 'H', b'I': 'I', b'J': 'J', b'K': 'K', b'L': 'L', b'M': 'M', b'N': 'N', b'O': 'O', b'P': 'P', b'Q': 'Q', b'R': 'R', b'S': 'S', b'T': 'T', b'U': 'U', b'V': 'V', b'W': 'W', b'X': 'X', b'Y': 'Y', b'Z': 'Z', b'\\': '\\', b'_': '█', b'a': 'a', b'b': 'b', b'c': 'c', b'd': 'd', b'e': 'e', b'f': 'f', b'g': 'g', b'h': 'h', b'i': 'i', b'j': 'j', b'k': 'k', b'l': 'l', b'm': 'm', b'n': 'n', b'o': 'o', b'p': 'p', b'q': 'q', b'r': 'r', b's': 's', b't': 't', b'u': 'u', b'v': 'v', b'w': 'w', b'x': 'x', b'y': 'y', b'z': 'z', b'\x8f': '·', b'\x97': '─', b'\x98': '─', b'\xa3': '▔', b'\xa4': '▔', b'\xa5': '▔', b'\xd2': '━', b'\xd3': '•'}

A mapping from display-level bytes to the equivalent ASCII/Unicode character.

In some cases, multiple display-level bytes map to a common ASCII/Unicode character:

• Bytes " and ' map to character ' (which means " can’t be permitted as an input character).

• Bytes \xA3, \xA4, and \xA5 map to character ▔.

Although not problematic, this makes perfect round-tripping between characters and display bytes impossible, so it should never be assumed to be possible.

Private _crc() Function

metlinkpid._crc(bytes_in: bytes) → bytes

Generate an X.25 checksum for the specified byte sequence.

Parameters

bytes_in – the bytes to generate the checksum for.

Returns

a two-byte bytes sequence in the order expected by the display.

Private _uncrc() Function

metlinkpid._uncrc(bytes_in: bytes) → bytes

Verify the validity of the specified byte sequence, which ends with a two-byte CRC checksum as generated by _crc(), and discard the checksum.

Parameters

bytes_in – the bytes with checksum to verify.

Returns

the verified byte sequence without the checksum.

Raises

ValueError – if the checksum verification fails.