PaSD bus Modbus API

This module provides a Modbus API to the PaSD bus.

class PasdBusModbusApi(simulators, logger)

A Modbus API for a PaSD bus simulator.

__init__(simulators, logger)

Initialise a new instance.

Parameters:

simulators (dict) – dictionary of simulators (FNDH, FNCC and smartbox) that this API fronts.
logger (Logger) – the logger to use

class PasdBusModbusApiClient(host, port, logger_object, timeout, enable_logging=False, log_file_dir=None)

A client class for a PaSD (simulator or h/w) with a Modbus API.

__init__(host, port, logger_object, timeout, enable_logging=False, log_file_dir=None)

Initialise a new instance.

Parameters:

host (str) – the host IP address for the PaSD
port (int) – the PaSD port
logger_object (Logger) – the logger to use
timeout (float) – the timeout period in seconds
enable_logging (Optional[bool]) – True if pymodbus logging is to be enabled
log_file_dir (Optional[str]) – the directory to create the log file if required

close()

Close the connection to the remote API.

Return type:: None

connect()

Establish a connection to the remote API.

Return type:: None

execute_command(device_id, name, *args)

Execute a command and return the results.

Parameters:

device_id (int) – ID of the device to be commanded.
name (str) – name of the command.
args (Any) – positional arguments to the command.

Return type:

dict[str, Any]

Returns:

the results of the command execution.

read_attributes(device_id, *names)

Read attribute values from the server.

Note these must be stored in contiguous Modbus registers in the h/w.

Parameters:

device_id (int) – id of the device to be read from.
names (str) – names of the attributes to be read.

Raises:

ModbusIOException if the h/w failed to respond

Return type:

dict[str, Any]

Returns:

dictionary of attribute values keyed by name

reset_connection()

Reset the connection to the device.

Re-create the Modbus client to ensure the transaction manager is properly reset.

Return type:: None

write_attribute(device_id, name, *values)

Write a new attribute value.

Parameters:: device_id (int) – id of the device to write to.
Param:: name: attribute name to write.
Param:: values: new value(s).
Return type:: dict[str, Any]
Returns:: dictionary mapping attribute name to new value.
Raises:: ModbusIOException if the h/w failed to respond.

PaSD bus register map

This module provides a register mapping utility for the PaSD bus.

class DesiredPowerEnum(value)

Enum type for the DSON and DSOFF attributes.

Note that DevEnum types must start at 0 and increment by 1.

class PasdBusAttribute(address, count, conversion_function=<bound method PasdConversionUtility.default_conversion of <class 'ska_low_pasd_driver.pasd_bus_conversions.PasdConversionUtility'>>, writable=False)

Class representing a Modbus attribute stored on a Smartbox or FNDH.

This stores the starting register address and count (number of registers) containing this attribute, and a conversion function used to convert the raw register value into engineering units / status strings for read operations.

It is also used to store the value to be written to the register for command operations.

__init__(address, count, conversion_function=<bound method PasdConversionUtility.default_conversion of <class 'ska_low_pasd_driver.pasd_bus_conversions.PasdConversionUtility'>>, writable=False)

Initialise a new instance.

Parameters:

address (int) – starting register address
count (int) – number of registers containing the attribute
conversion_function (Callable) – callable function to scale the value
writable (bool) – True if the attribute is read/write

property address: int

Return the starting register address.

Returns:: the starting register address

convert_value(values)

Execute the attribute’s conversion function on the supplied value.

Convert the raw register value(s) into a meaningful value

Parameters:: values (list[Any]) – a list of the raw value(s) to convert
Return type:: Any
Returns:: the converted value

convert_write_value(values)

Execute the attribute’s conversion function on the supplied value.

Convert the desired user value into a raw register value

Parameters:: values (list[Any]) – a list of the user values to convert
Return type:: Any
Returns:: the raw converted values

property count: int

Return the number of registers containing this attribute.

Returns:: the register count for this attribute

property value: int | list[int]

Return the value to be set for this attribute.

Returns:: the desired value as a raw integer or list of ints.

class PasdBusPortAttribute(address, count, desired_info=<PortStatusBits.NONE: 0>)

Class representing the power status for one or more ports.

__init__(address, count, desired_info=<PortStatusBits.NONE: 0>)

Initialise a new instance.

Parameters:

address (int) – starting register address
count (int) – number of registers containing the port data
desired_info (PortStatusBits) – port status attribute of interest if reading status (must match member of PortStatusBits)

class PasdBusRegisterInfo(register_map, number_of_sensors=0, first_sensor_register=0, number_of_extra_sensors=0, first_extra_sensor_register=0, number_of_ports=0, starting_port_register=0)

Hold register information for a PaSD device.

__init__(register_map, number_of_sensors=0, first_sensor_register=0, number_of_extra_sensors=0, first_extra_sensor_register=0, number_of_ports=0, starting_port_register=0)

class PasdBusRegisterMap(revision_number=1)

A register mapping utility for the PaSD.

__init__(revision_number=1)

Initialize a new instance.

Parameters:: revision_number (int) – Modbus register map revision number, if known (this will be set later after interrogating the h/w)

get_attribute_names(device_id, addresses)

Map a list of register numbers to attribute names.

Parameters:

device_id (int) – The ID of the smartbox / FNDH device
addresses (list[int]) – Starting address(es) of the desired Modbus registers

Return type:

list[str]

Returns:

A list of the corresponding string attribute names

get_attributes(device_id, attribute_names)

Map a list of attribute names to PasdAttribute objects.

Raises:

PasdBusRequestError – If attributes do not match register map or non-contiguous set of registers requested

Parameters:

device_id (int) – the ID (address) of the smartbox / FNDH device
attribute_names (list[str]) – name of the attribute(s)

Return type:

dict[str, PasdBusAttribute]

Returns:

A dictionary mapping attribute names to PasdAttributes, inserted in Modbus address order

get_attributes_from_address_and_count(device_id, first_address, count)

Map initial register address and count to attributes.

Parameters:

device_id (int) – The ID of the smartbox / FNDH device
first_address (int) – Starting address of the desired Modbus registers
count (int) – number of registers

Return type:

dict[str, PasdBusAttribute]

Returns:

A dictionary of the corresponding string attribute names and attribute instances

get_command(device_id, command_string, arguments)

Get a PasdBusAttribute object for the specified command.

Parameters:

device_id (int) – Device (responder) id
command_string (str) – String command
arguments (Sequence[Any]) – arguments (if any)

Return type:

PasdBusAttribute

Returns:

PasdBusAttribute object populated with converted value ready to send over Modbus

Raises:

PasdBusRequestError – if the given string does not match any command or the arguments are invalid

get_writable_attribute(device_id, attribute_name, write_values)

Return a PasdAttribute object for a writable object.

Raises:

PasdBusRequestError – If a non-existing or non-writable register is requested

Parameters:

device_id (int) – The ID (address) of the smartbox / FNDH device
attribute_name (str) – name of the attribute
write_values (list[Any]) – the requested user values to write

Return type:

PasdBusAttribute

Returns:

A PasdAttribute object for this attribute

property revision_number: int

Return the Modbus register map revision number.

Returns:: The integer revision number

exception PasdBusRequestError(error, *args)

Exception to be raised for invalid PaSD bus requests.

__init__(error, *args)

Initialize new instance.

Parameters:

error (RequestErrors) – type of PaSD bus request error.
args (Any) – attributes, command or other arguments in the request.

class PasdCommandStrings(value): Enum type for PaSD command strings.

class PortDesiredStateOffline(value): Port desired state when device is offline.

class PortDesiredStateOnline(value): Port desired state when device is online.

class PortOverride(value): Port override for field maintenance.

class PortStatusBits(value)

Enum type for PDOC/FEM port status bits.

Corresponds to register bit names in PaSD firmware description document.

class RequestErrors(value): Type of PaSD bus request errors.

PaSD bus conversions

This module provides scaling and other conversion functions for the PaSD.

class FnccStatusMap(value): Enum type for FNCC health status strings.

class FndhAlarmFlags(value): Enum type for the FNDH alarm/warning flags.

class FndhStatusMap(value): Enum type for FNDH health status strings.

class LedServiceMap(value): Enum type for the service LED (MSB in SYS_LIGHTS register).

class LedStatusMap(value): Enum type for the status LED (LSB in SYS_LIGHTS_REGISTER).

class PasdConversionUtility

Conversion utility to provide scaling functions for PaSD registers.

The following methods each accept and return a list of values to simplify the calling code.

classmethod convert_chip_id(value_list, inverse=False)

Convert the raw register values to a string chip id.

Parameters:

value_list (list) – list of raw register contents
inverse (bool) – Boolean, True to perform physical->raw conversion instead of raw->physical

Return type:

list

Returns:

string chip identification

classmethod convert_cpu_id(value_list, inverse=False)

Convert a number of raw register values to a CPU ID.

Parameters:

value_list (list) – list of raw register contents
inverse (bool) – Boolean, True to perform physical->raw conversion instead of raw->physical

Return type:

list

Returns:

string ID

classmethod convert_firmware_version(value_list, inverse=False)

Convert the raw register values to a string firmware version.

Parameters:

value_list (list) – list of raw register contents
inverse (bool) – Boolean, True to perform physical->raw conversion instead of raw->physical

Return type:

list

Returns:

string firmware version

classmethod convert_fncc_status(value_list, inverse=False)

Convert the raw register value to a string status.

Parameters:

value_list (list) – raw register contents
inverse (bool) – Boolean, True to perform physical->raw conversion instead of raw->physical

Return type:

list

Returns:

string status representation

classmethod convert_fndh_alarm_status(value_list, inverse=False)

Convert the alarm and warning flag registers to strings.

Parameters:

value_list (list) – raw register contents (each of the 16 bits represents a potential alarm cause)
inverse (bool) – Boolean, True to perform physical->raw conversion instead of raw->physical

Return type:

str | list[int]

Returns:

string describing the parameters that have triggered the alarm or warning.

classmethod convert_fndh_status(value_list, inverse=False)

Convert the raw register value to a string status.

Parameters:

value_list (list) – raw register contents
inverse (bool) – Boolean, True to perform physical->raw conversion instead of raw->physical

Return type:

list

Returns:

string status representation

classmethod convert_led_status(value_list, inverse=False)

Convert the raw register value to LED status strings.

Parameters:

value_list (list) – raw register contents (MSB represents service LED and LSB represents status LED)
inverse (bool) – Boolean, True to perform physical->raw conversion instead of raw->physical

Return type:

str | list[int]

Returns:

string describing LED patterns

classmethod convert_smartbox_alarm_status(value_list, inverse=False)

Convert the alarm and warning flag registers to strings.

Parameters:

value_list (list) – raw register contents (each of the 16 bits represents a potential alarm cause)
inverse (bool) – Boolean, True to perform physical->raw conversion instead of raw->physical

Return type:

str | list[int]

Returns:

string describing the parameters that have triggered the alarm or warning.

classmethod convert_smartbox_status(value_list, inverse=False)

Convert the raw register value to a string status.

Parameters:

value_list (list) – raw register contents
inverse (bool) – Boolean, True to perform physical->raw conversion instead of raw->physical

Return type:

list

Returns:

string status representation

classmethod convert_uptime(value_list, inverse=False)

Convert the raw register values to an uptime in seconds.

Parameters:

value_list (list[int]) – list of raw register contents
inverse (bool) – Boolean, True to perform physical->raw conversion instead of raw->physical

Return type:

list[int]

Returns:

integer number of seconds

classmethod default_conversion(values, inverse=False)

Return the supplied raw value(s) with no conversion.

Parameters:

values (list[Any]) – raw value(s)
inverse (bool) – whether to invert the conversion

Return type:

list[Any]

Returns:

the value(s) unchanged

classmethod scale_48vcurrents(value_list, inverse=False)

Convert raw register value(s) to Amps.

For now, raw values are hundredths of an Amp, positive only.

Parameters:

value_list (UnionType[int, list[int], list[float], None]) – raw register contents as a list of values from 0-65535 or list of currents in amps
inverse (bool) – Boolean, True to perform physical->raw conversion instead of raw->physical

Raises:

ValueError – if value_list is None

Return type:

list[int] | list[float]

Returns:

list of output_values

classmethod scale_signed_16bit(value_list, inverse=False)

Convert raw register value(s) to deg C.

For now, raw values are hundredths of a deg C, as a signed 16-bit integer value

Parameters:

value_list (UnionType[int, list[int], list[float], None]) – raw register contents as a list of values from 0-65535, or floating point temperatures in degrees
inverse (bool) – Boolean, True to perform physical->raw conversion instead of raw->physical

Raises:

ValueError – if value_list is None

Return type:

list[int] | list[float]

Returns:

value in deg C (if inverse=False), or raw value as an unsigned 16 bit integer

classmethod scale_volts(value_list, inverse=False)

Convert raw register value(s) to Volts.

For now, raw values are hundredths of a volt, positive only.

Parameters:

value_list (UnionType[int, list[int], list[float], None]) – raw register contents as a list of values from 0-65535, or a list of voltages
inverse (bool) – Boolean, True to perform physical->raw conversion instead of raw->physical

Raises:

ValueError – if value_list is None

Return type:

list[int] | list[float]

Returns:

output_values in Volts

class SmartboxAlarmFlags(value): Enum type for the Smartbox alarm/warning flags.

class SmartboxStatusMap(value): Enum type for SmartBox health status strings.