telegram
¶
This module defines classes for creating, representing and reading telegrams which are used to communicate with the pump.
- class turboctl.telegram.telegram.Telegram(parameter_code: Bin, parameter_number: Uint, parameter_index: Uint, parameter_value: Data, flag_bits: Bin, frequency: Uint, temperature: Sint, current: Uint, voltage: Uint)¶
A simple dataclass that represents a telegram sent to or from the pump.
This class is cumbersome to initialize directly, since the values of all attributes must be given as arguments. Instances should instead be created with the
TelegramBuilder
class.The Leybold TURBOVAC i/iX vacuum pump communicates with a computer via its RS 232 or RS 485 serial port or a USB port using telegrams of 24 bytes. The general structure of the telegrams follows the USS protocol.
Each byte consists of a start bit (0), 8 data bits, an even parity bit (1 if there are an even number of 1s in the data bits, 0 otherwise) and an ending bit (1). However, only the data bits are included in the bytes objects that represent telegrams; the serial module automatically adds the other bits.
In the TURBOVAC manual, the data bits in a byte are indexed as [7,6,5,4,3,2,1,0] (i.e. according to the power of 2 they represent), but this class uses the convention [0,1,2,3,4,5,6,7], because it corresponds to the indices of a Python list.
The functions and values of the different bytes in a telegram are detailed below. Each list entry contains the name of the
Telegram
object attribute (if any) that represents the value associated with the entry.Unless otherwise noted, all bytes have a default value of 0.
Byte 0: STX (start of text). Always 2.
Byte 1: LGE (telegram length). Excludes bytes 0 and 1, and thus always has a value of 22.
Byte 2: ADR (address). With a RS485 port this denotes the slave node number (0-31). Reading or changing this byte is not currently supported by this class.
Bytes 3-4: PKE (parameter number and type of access). A 16 bit block:
- Bits 0-3:
Type of parameter access or response. This is a 4 bit code indicating e.g. whether a parameter should be read from or written to. Valid codes are detailed in the
codes
module.Attribute:
parameter_code
.
- Bit 4:
Always 0.
- Bits 5-15:
The number of the parameter to be accessed.
Attribute:
parameter_number
.
Byte 5: - (reserved). Always 0.
Byte 6: IND (parameter index). If the requested parameter is indexed, this specifies the number of the requested index.
Attribute:
parameter_index
.Bytes 7-10: PWE (parameter value). This block contains a parameter value that is written to or read from the pump. If the pump tries to access a parameter but fails, the reply will contain an error code in this block.
Attribute:
parameter_value
.Bytes 11-12: PZD1 (status and control bits). 16 bits each corresponding to a single setting or command which can be turned on by setting the bit to 1. In a reply from the pump these correspond to status conditions affecting the pump instead of commands.
Attribute:
flag_bits
.Bytes 13-14: PZD2 (current rotor frequency). Rotor frequency in Hz; the same as parameter 3. Included in all replies, and can be included in queries to define a setpoint for the frequency. (This only works if the setpoint is enabled through the control bits, and overrides the setpoint defined in parameter 24).
Attribute:
frequency
.Bytes 15-16: PZD3 (current frequency converter temperature). Frequency converter temperature in °C, included in all replies. Same as parameter 11.
Attribute:
temperature
.Bytes 17-18: PZD4 (current motor current). Motor current in 0.1 A, included in all replies. Same as parameter 5.
Attribute:
current
.Bytes 19-20: - (reserved). Always 0.
Bytes 21-22: PZD6 (current intermediate circuit voltage). Intermediate circuit voltage in V, included in all replies. Same as parameter 4.
Attribute:
voltage
Byte 23: BCC (byte block check): A checksum computed using the following algorithm:
checksum = bytes_[0] for byte in bytes_[1:23]: checksum = checksum ^ byte_
where
^
is the exclusive or (XOR) operator.- parameter_value: Data¶
The parameter value. This attribute is always a 32-bit instance of a subclass of
Data
, but the exact type depends on the parameter.
- LENGTH = 24¶
The length of a telegram in bytes.
- __bytes__()¶
Return the telegram as a
bytes
object.The checksum is computed automatically and added to the end.
- __eq__(other)¶
Return self==value.
- __hash__ = None¶
- __init__(parameter_code: Bin, parameter_number: Uint, parameter_index: Uint, parameter_value: Data, flag_bits: Bin, frequency: Uint, temperature: Sint, current: Uint, voltage: Uint) None ¶
- __repr__()¶
Return repr(self).
- class turboctl.telegram.telegram.TelegramBuilder(parameters=PARAMETERS)¶
This class can be used to easily construct instances of the
Telegram
class.Here is an example of how to use this class:
telegram = (TelegramBuilder().set_parameter_mode('write') .set_paramerer_number(1) .set_parameter_index(2) .set_parameter_value(3) .build())
The above creates a telegram which writes the value 3 to parameter 1, index 2. Note that this is just an example of the syntax; parameter 1 isn’t actually indexed.
Attributes which aren’t explicitly set to a value with a setter method are set to zero when the telegram is created. Trying to set an attribute to an invalid value results in a
ValueError
or aTypeError
.A telegram can also be created from a
bytes
object:telegram = TelegramBuilder().from_bytes(bytes_).build()
- parameters¶
A
dict
ofParameter
objects, with parameter numbers as keys. The default value isPARAMETERS
, but non-default parameter sets can be used for testing purposes.
- __init__(parameters=PARAMETERS)¶
Initialize a new
TelegramBuilder
.- Parameters:
parameters – The object to be assigned to
parameters
.
- from_bytes(bytes_)¶
Read the contents of the telegram from a
bytes
object.The type of
parameter_value
depends onparameter_number
, and is assigned automatically. If bytes_ contains a parameter number that doesn’t exist, aValueError
is raised.If the parameter isn’t accessed (i.e. the parameter mode is set to
'none'
or code to'0000'
), invalid parameter numbers, such as the default value of 0, are permitted. In that case, the parameter type is set toUint
.Note that this isn’t a class method; a
TelegramBuilder
must first be initialized normally with__init__()
, after which this method may be called.- Raises:
ValueError – If bytes_ doesn’t represent a valid telegram.
- set_parameter_mode(value: str)¶
Set the parameter access or response mode to one of the following:
- Access modes:
'none'
'read'
'write'
- Response modes:
'none'
'response'
'error'
'no write'
The parameter access or response code is determined automatically based on the parameter mode and the parameter number.
- set_parameter_number(value: int)¶
Set the parameter number.
- Raises:
ValueError – If there isn’t a parameter with the specified number.
- set_parameter_value(value)¶
Set the parameter value.
The type of value depends on the type of the parameter. This method can also be used to set the error code; if
set_parameter_mode()
is called to set the parameter mode to'error'
, the parameter value is always interpreted as anUint
error code regardless of parameter number or type.
- set_flag_bits(bits)¶
Set the control or status bits.
bits should be an iterable of those
ControlBits
orStatusBits
members that should be included in the telegram.
- set_current(value)¶
Set the current.
- set_voltage(value)¶
Set the voltage.
- build(type_='query')¶
Build and return a
Telegram
object.- Parameters:
type –
query
if the telegram represents a message to the pump,reply
if it represents a message from the pump.- Raises:
ValueError – If a telegram cannot be created with the specified attributes.
- class turboctl.telegram.telegram.TelegramReader(telegram, type_='reply')¶
This class can be used to read the data of a telegram in a more user-friendly way. This means the returned values are Python built-ins instead of the custom datatypes used by the
Telegram
class, and parameter_code is automatically converted to a human-readable value.- type¶
'query'
for telegrams to the pump,'reply'
for telegrams from the pump.
- __init__(telegram, type_='reply')¶
Initialize a new
TelegramReader
.- Parameters:
telegram – The
Telegram
to be read.type –
query
if the telegram represents a message to the pump,reply
if it represents a message from the pump.
- Raises:
ValueError – If type_ has an invalid value.
- __repr__()¶
Return an exact string respresentation of this object.
The returned string can be evaluated to create a copy of this object. The format is
ClassName(telegram=<telegram>, type=<type>)
.
- __str__()¶
Return an easily readable string representation of this object.
The returned string shows the values of both the attributes and the read-only properties of this object, and cannot thus be passed to
eval()
without an raising error.The format is
ClassName( telegram=<telegram>, type=<type>, parameter_mode=<parameter_mode>, ... )
- property parameter_mode¶
Return the parameter mode.
This method is the reverse of
TelegramBuilder.set_parameter_mode()
: it automatically converts a parameter access or response code to a human-readable string.- Raises:
ValueError – If the parameter code of the telegram is invalid.
- property parameter_number¶
Return the parameter number.
- property parameter_index¶
Return the parameter index.
- property parameter_value¶
Return the parameter value.
- property parameter_error¶
Return the parameter error.
- Returns:
A member of the
ParameterError
enum, orNone
, ifparameter_mode
isn’t'error'
.- Raises:
ValueError – If the error number isn’t valid.
- property flag_bits¶
Return the control or status bits as a list of those
StatusBits
orControlBits
members that are set to 1 in the telegram.
- property frequency¶
Return the frequency.
- property temperature¶
Return the temperature.
- property current¶
Return the current.
- property voltage¶
Return the voltage.