`runtime.messaging`¶

Smart Device messaging.

This library provides low-level bindings for building Message objects and encoding them to or decoding them from a binary format. This module’s API adheres closely to that of the underlying native C++ code and manipulates parameters using bitmaps and memory. To generate or digest messages at a higher level (for example, using parameter names), use runtime.buffer.DeviceBuffer.

exception runtime.messaging.MessageError(message, /, **context)¶

Bases: runtime.exception.RuntimeBaseException

General message error.

class runtime.messaging.ErrorCode(value)¶

Bases: enum.IntEnum

Error codes produced by the Smart Device or during message encoding/decoding.

OK¶: No error occurred.

BACKOFF¶: The receiver is overwhelmed. The peer should transmit less data.

INVALID_TYPE¶: The receiver received a message type it does not handle.

BUFFER_OVERFLOW¶: Message was too large to encode/decode.

UNEXPECTED_DELIMETER¶: Message was incomplete or otherwise unable to be decoded.

BAD_CHECKSUM¶: Checksum computed by the receiver did not match the sender’s claim.

GENERIC_ERROR¶: General error.

class runtime.messaging.Message¶

Bases: object

A Smart Device message.

The len() of a message is the length of its payload in bytes.

static decode(buf)¶

Decode a raw binary buffer, as it is transported on the wire.

Parameters: buf – An object that implements Python’s writeable buffer protocol.
Returns: A message containing the parsed data.
Return type: Message
Raises: MessageError – If the message was not able to be decoded.

encode()¶

Encode this message into a newly allocated buffer.

Returns: The encoded message, ready to be put on the wire.
Return type: bytearray
Raises: MessageError – If the message was not able to be encoded.

encode_into_buf(buf)¶

Encode this message into an existing buffer.

Parameters: buf – A object that implements Python’s writeable buffer protocol.
Returns: The number of bytes used, which may be less than the length of buf.
Return type: int
Raises: MessageError – If the message was not able to be encoded.

static make_dev_data(msg, params, param_map)¶

Make a MessageType.DEV_DATA message.

Parameters

params (int) – A bitmap of parameters to write.
param_map (ParameterMap) – A parameter map specifying where in memory the parameter values should be read from.

Returns

A Smart Device message.

Return type

Message

static make_dev_disable(msg)¶

Make a MessageType.DEV_DISABLE message.

Returns: A Smart Device message.
Return type: Message

static make_dev_read(msg, params)¶

Make a MessageType.DEV_READ message.

Parameters: params (int) – A bitmap of parameters to read.
Returns: A Smart Device message.
Return type: Message

static make_dev_write(msg, params, param_map)¶

Make a MessageType.DEV_WRITE message.

Parameters

params (int) – A bitmap of parameters to write.
param_map (ParameterMap) – A parameter map specifying where in memory the parameter values should be read from.

Returns

A Smart Device message.

Return type

Message

static make_error(msg, error)¶

Make a MessageType.ERROR message.

Parameters: error (ErrorCode) – An error code.
Returns: A Smart Device message.
Return type: Message

static make_hb_req(msg, hb_id)¶

Make a MessageType.HB_REQ message.

Parameters: hb_id (int) – A heartbeat identifier.
Returns: A Smart Device message.
Return type: Message

static make_hb_res(msg, hb_id)¶

Make a MessageType.HB_RES message.

Parameters: hb_id (int) – A heartbeat identifier matching that of its corresponding heartbeat request.
Returns: A Smart Device message.
Return type: Message

static make_ping(msg)¶

Make a MessageType.PING message.

Returns: A Smart Device message.
Return type: Message

static make_sub_req(msg, params, interval)¶

Make a MessageType.SUB_REQ message.

Parameters

params (int) – A bitmap of parameters to subscribe to.
interval (int) – The delay between updates in milliseconds.

Returns

A Smart Device message.

Return type

Message

static make_sub_res(msg, params, interval, device_id, year, random)¶

Make a MessageType.SUB_RES message.

Parameters

params (int) – A bitmap of parameters subscribed to.
interval (int) – The delay between updates in milliseconds.
device_id (int) – The device type identifier.
year (int) – A number identifier the year the device was manufactured.
random (int) – Random bits for uniqueness.

Returns

A Smart Device message.

Return type

Message

classmethod make_unsubscribe()¶

Make a message to unsubscribe from all parameters.

Returns: A MessageType.SUB_REQ message.
Return type: Message

read_dev_data(param_map)¶

Read the parameter values of a MessageType.DEV_DATA message.

Parameters: param_map (ParameterMap) – A parameter map specifying the addresses to write the values to.
Returns: A bitmap of the parameters read.
Return type: int

read_dev_read()¶

Read the parameter values of a MessageType.DEV_READ message.

Returns: A bitmap of the parameters contained.
Return type: int

read_dev_write(param_map)¶

Read the parameter values of a MessageType.DEV_WRITE message.

Parameters: param_map (ParameterMap) – A parameter map specifying the addresses to write the values to.
Returns: A bitmap of the parameters read.
Return type: int

read_error()¶

Read the error code of a MessageType.ERROR message.

Returns: The error code.
Return type: ErrorCode

read_hb_req()¶

Read the heartbeat identifier of a MessageType.HB_REQ message.

Returns: The heartbeat ID.
Return type: int

read_hb_res()¶

Read the heartbeat identifier of a MessageType.HB_RES message.

Returns: The heartbeat ID.
Return type: int

read_sub_req()¶

Read the fields of a MessageType.SUB_REQ message.

Returns: The parameters to subscribe to (as a bitmap) and the requested delay in milliseconds.
Return type: tuple[int, int]

read_sub_res()¶

Read the fields of a MessageType.SUB_RES message.

Returns: The parameters subscribed to as a bitmap, the delay in milliseconds, and the device’s UID components (device ID, year, random bits).
Return type: tuple[int, int, tuple[int, int, int]]

verify_checksum()¶

Determine whether the claimed checksum of the payload is valid.

Returns: True if the checksum is valid, False otherwise.
Return type: bool

type¶

The type of this message.

Type: MessageType

class runtime.messaging.MessageType(value)¶

Bases: enum.IntEnum

The Smart Device message’s type identifies what kind of payload it contains.

PING¶: Ping request from Runtime to the Smart Device.

SUB_REQ¶: Subscription request.

SUB_RES¶: Subscription response.

DEV_READ¶: Device read.

DEV_WRITE¶: Device write.

DEV_DATA¶: Device data.

DEV_DISABLE¶: Device disable.

HB_REQ¶: Heartbeat request.

HB_RES¶: Heartbeat response.

ERROR¶: Error.

class runtime.messaging.ParameterMap¶

Bases: object

A map of parameters in memory.

This object is used by Message to determine where and how many bytes should be written to or read from for each parameter.

clear_param(index)¶: Clear an existing parameter.

set_param(index, base, size)¶

Set the address and size of a parameter.

Parameters

index (int) – The parameter ID between 0 (inclusive) and Message.MAX_PARAMS (exclusive).
base (int) – The address of the parameter in memory.
size (int) – The size of the parameter in bytes.

Raises

MessageError – If the index is out of bounds.

Warning

Since this method accepts addresses that a Message will eventually dereference, a bad address may cause a segfault. Use with caution.

runtime.messaging¶

`runtime.messaging`¶