msl.equipment.connection_message_based module

Base class for equipment that use message-based communication.

class msl.equipment.connection_message_based.ConnectionMessageBased(record)[source]

Bases: Connection

Base class for equipment that use message-based communication.

The backend value must be equal to MSL to use this class for the communication system. This is achieved by setting the value in the Backend field for a connection record in the Connections Database to be MSL.

Do not instantiate this class directly. Use the connect() method to connect to the equipment.

Parameters:

record (EquipmentRecord) – A record from an Equipment-Register Database.

CR = b'\r'

The carriage-return character (hex: 0x0D, decimal: 13).

Type:

bytes

LF = b'\n'

The line-feed character (hex: 0x0A, decimal: 10).

Type:

bytes

property encoding

The encoding that is used for read() and write() operations.

Type:

str

property encoding_errors

The error handling scheme to use when encoding and decoding messages.

For example: strict, ignore, replace, xmlcharrefreplace, backslashreplace

Type:

str

property read_termination

The termination character sequence that is used for the read() method.

Reading stops when the equipment stops sending data or the read_termination character sequence is detected. If you set the read_termination to be equal to a variable of type str it will automatically be encoded.

Type:

bytes or None

property write_termination

The termination character sequence that is appended to write() messages.

If you set the write_termination to be equal to a variable of type str it will automatically be encoded.

Type:

bytes or None

property max_read_size

The maximum number of bytes that can be read().

Type:

int

property timeout

The timeout, in seconds, for read() and write() operations.

A value \(\lt\) 0 will set the timeout to be None (blocking mode).

Type:

float or None

property rstrip

Whether to remove trailing whitespace from read() messages.

Type:

bool

raise_timeout(append_msg='')[source]

Raise a MSLTimeoutError.

Parameters:

append_msg (str, optional) – A message to append to the generic timeout message.

read(size=None, fmt='ascii', dtype=None, decode=True)[source]

Read a message from the equipment.

This method will block until one of the following conditions is fulfilled:

  1. the read_termination byte(s) is(are) received – only if read_termination is not None.

  2. size bytes have been received – only if size is not None.

  3. a timeout occurs – only if timeout is not None. An MSLTimeoutError is raised.

  4. max_read_size bytes have been received. An MSLConnectionError is raised.

Parameters:

  • size (int, optional) – The number of bytes to read. Ignored if it is None.

  • fmt (str or None, optional) – The format that the message data is in. Ignored if dtype is not specified. See from_bytes() for more details.

  • dtype – The data type of the elements in the message data. Can be any object that numpy.dtype supports. See from_bytes() for more details. For messages that are of scalar type (i.e., a single number) it is more efficient to not specify dtype but to pass the message to the int or float class to convert the message to the appropriate numeric type.

  • decode (bool, optional) – Whether to decode the message (i.e., convert the message to a str) or keep the message as bytes. Ignored if dtype is specified.

Returns:

str, bytes or ndarray – The message from the equipment. If dtype is specified, then the message is returned as an ndarray, if decode is True then the message is returned as a str, otherwise the message is returned as bytes.

See also

rstrip

write(message, data=None, fmt='ieee', dtype='<f')[source]

Write a message to the equipment.

Parameters:

  • message (str or bytes) – The message to write to the equipment.

  • data (list, tuple or numpy.ndarray, optional) – The data to append to message. See to_bytes() for more details.

  • fmt (str or None, optional) – The format to use to convert data to bytes. Ignored if data is None. See to_bytes() for more details.

  • dtype – The data type to use to convert each element in data to bytes. Ignored if data is None. See to_bytes() for more details.

Returns:

int – The number of bytes written.

query(message, delay=0.0, **kwargs)[source]

Convenience method for performing a write() followed by a read().

Parameters:

  • message (str or bytes) – The message to write to the equipment.

  • delay (float, optional) – The time delay, in seconds, to wait between write() and read() operations.

  • **kwargs – All additional keyword arguments are passed to read()

Returns:

str, bytes or ndarray – The message from the equipment. If dtype is specified, then the message is returned as an ndarray, if decode is True then the message is returned as a str, otherwise the message is returned as bytes.