PID Class

class metlinkpid.PID(serial: serial.serialposix.Serial, ignore_responses: bool = False)

A PID object represents a serial connection to a physical display.

PID objects are typically constructed using the PID.for_device() class method, and can send messages in the form of Message objects, strings, or raw bytes using the send() method. It is possible to ping() the display at regular intervals to persist the currently-displayed message.

PID objects also manage the CRC checksumming & DLE/STX/ETX packet framing used by the display in what it receives & transmits, and ensure that every instruction sent to the display is acknowledged.

PID objects are context managers, enabling automatic closing of the underlying Serial connection when used in a with block:

with PID.for_device(...) as pid:
    pid.send(...)

# serial connection will never be open at this point
Parameters

  • serial – a serial.Serial object. In normal use a correctly configured one is set by PID.for_device().

  • ignore_responses – whether to ignore the response from the PID whenever PID.send() is called. Defaults to False.

PID.for_device() Class Method

classmethod PID.for_device(port: str, ignore_responses: bool = False) → metlinkpid.PID

Construct a PID object connected to the specified serial device with a correctly configured serial.Serial object.

The Serial object is configured to time out after 500ms during read operations, which is ample time for the display to send acknowledgement after being written to.

Parameters

  • port – the serial device name, such as /dev/ttyUSB0 on Linux or COM1 on Windows. The correct device name can be found on Linux by unplugging and re-plugging the display connection, running dmesg, and inspecting the output for the device name.

  • ignore_responses – whether to ignore the response from the PID whenever PID.send() is called. Defaults to False.

Raises

serial.SerialException – if the serial device can’t be found or can’t be configured.

send() Method

PID.send(data: Union[str, metlinkpid.Message, bytes]) → None

Send data to the display—most typically message data, although any bytes data can be sent.

  • If a string is provided, it is converted to a DisplayMessage object using DisplayMessage.from_str(), then to_bytes(), then CRC-checksummed and packet-framed before sending.

  • If a Message object is provided (usually a DisplayMessage but sometimes a PingMessage), it is converted to_bytes(), then CRC-checksummed and packet-framed before sending.

  • If a bytes object is provided that is not a valid DLE/STX/ETX packet (\x10\x02 ··· \x10\x03), the bytes are CRC-checksummed and packet-framed before sending.

  • If a bytes object is provided that is a valid DLE/STX/ETX packet, the packet is assumed to already contain a correct CRC checksum and sent without change.

Parameters

data – a string, Message object, or bytes object.

Raises

ping() Method

PID.ping() → None

“Ping” the display, which has no direct visual effect but impedes the automatic clearing of the display (which otherwise occurs after approximately one minute of inactivity).

In deployment, Metlink displays are typically pinged every ten seconds in addition to all other traffic sent to them.

This method is simply a convenience wrapper for send()-ing a PingMessage:

pid.send(PingMessage())
Raises

close() Method

PID.close() → None

Close the underlying Serial connection.

Called automatically when the PID object is used in a with block:

with PID.for_device(...) as pid:
    pid.send(...)

# serial connection will never be open at this point