Protocol & connectivity¶

The Wolk class is modular, in the sense that it relies on implementation of certain abstract base classes that each handle a certain aspect of the package:

Data protocol - Parses messages related to device data (actuators, alarms, sensors & configurations)
Firmware update protocol - Parses messages related to firmware update (sending current firmware version, handling installation commands, reporting current firmware installation status)
Registration protocol - Parses messages related to device registration (sending registration requests, handling registration responses)
Status protocol - Parses messages related to device status(send current device status, respond to device status requests)
Outbound message queue - Store serialized messages before publishing them to the gateway/platform
Connectivity service - Means of establishing connection to WolkGateway and exchanging messages

All listed items have already been implemented to work over MQTT using WolkAbout’s JSON_PROTOCOL for serializing messages and they will be listed in the remainder of this page.

If you are interested in implementing a different means of storing messages, or want to use a different MQTT client, or even implement a custom message formatting protocol you can do so by implementing these Abstract base classes.

JSON Data Protocol¶

class wolk_gateway_module.json_data_protocol.JsonDataProtocol[source]¶

Parse inbound messages and serialize outbound messages.

extract_key_from_message(message: wolk_gateway_module.model.message.Message) → str[source]¶

Extract device key from message.

Parameters:	message (Message) – Message received
Returns:	device_key
Return type:	str

get_inbound_topics_for_device(device_key: str) → list[source]¶

Return list of inbound topics for given device key.

Parameters:	device_key (str) – Device key for which to create topics
Returns:	inbound_topics
Return type:	list

is_actuator_get_message(message: wolk_gateway_module.model.message.Message) → bool[source]¶

Check if message is actuator get command.

Parameters:	message (Message) – Message received
Returns:	is_actuator_get_message
Return type:	bool

is_actuator_set_message(message: wolk_gateway_module.model.message.Message) → bool[source]¶

Check if message is actuator set command.

Parameters:	message (Message) – Message received
Returns:	is_actuator_set_message
Return type:	bool

is_configuration_get_message(message: wolk_gateway_module.model.message.Message) → bool[source]¶

Check if message is configuration get command.

Parameters:	message (Message) – Message received
Returns:	is_configuration_get_message
Return type:	bool

is_configuration_set_message(message: wolk_gateway_module.model.message.Message) → bool[source]¶

Check if message is configuration set command.

Parameters:	message (Message) – Message received
Returns:	is_configuration_set_message
Return type:	bool

make_actuator_command(message: wolk_gateway_module.model.message.Message) → wolk_gateway_module.model.actuator_command.ActuatorCommand[source]¶

Make actuator command from message.

Parameters:	message (Message) – Message received
Returns:	actuator_command
Return type:	ActuatorCommand

make_actuator_status_message(device_key: str, actuator_status: wolk_gateway_module.model.actuator_status.ActuatorStatus) → wolk_gateway_module.model.message.Message[source]¶

Make message from actuator status for device key.

Parameters:	device_key (str) – Device on which the actuator status occurred actuator_status (ActuatorStatus) – Actuator status data
Returns:	message
Return type:	Message

make_alarm_message(device_key: str, alarm: wolk_gateway_module.model.alarm.Alarm) → wolk_gateway_module.model.message.Message[source]¶

Make message from alarm for device key.

Parameters:	device_key (str) – Device on which the alarm occurred alarm (Alarm) – Alarm data
Returns:	message
Return type:	Message

make_configuration_command(message: wolk_gateway_module.model.message.Message) → wolk_gateway_module.model.configuration_command.ConfigurationCommand[source]¶

Make configuration command from message.

Parameters:	message (Message) – Message received
Returns:	configuration_command
Return type:	ConfigurationCommand

make_configuration_message(device_key: str, configuration: dict) → wolk_gateway_module.model.message.Message[source]¶

Make message from configuration for device key.

Parameters:	device_key (str) – Device to which the configuration belongs to. configuration (dict) – Current configuration data
Returns:	message
Return type:	Message

make_sensor_reading_message(device_key: str, sensor_reading: wolk_gateway_module.model.sensor_reading.SensorReading) → wolk_gateway_module.model.message.Message[source]¶

Make message from sensor reading for device key.

Parameters:	device_key (str) – Device on which the sensor reading occurred sensor_reading (SensorReading) – Sensor reading data
Returns:	message
Return type:	Message

make_sensor_readings_message(device_key: str, sensor_readings: List[wolk_gateway_module.model.sensor_reading.SensorReading], timestamp: int = None) → wolk_gateway_module.model.message.Message[source]¶

Make message from multiple sensor readings for device key.

Parameters:	device_key (str) – Device on which the sensor reading occurred sensor_reading (List[SensorReading]) – Sensor readings data timestamp (Optional[int]) – Timestamp
Returns:	message
Return type:	Message

JSON Firmware Update Protocol¶

class wolk_gateway_module.json_firmware_update_protocol.JsonFirmwareUpdateProtocol[source]¶

Parse inbound messages and serialize outbound firmware messages.

extract_key_from_message(message: wolk_gateway_module.model.message.Message) → str[source]¶

Return device key from message.

Parameters:	message (Message) – Message received
Returns:	device_key
Return type:	str

get_inbound_topics_for_device(device_key: str) → list[source]¶

Return list of inbound topics for given device key.

Parameters:	device_key (str) – Device key for which to create topics
Returns:	inbound_topics
Return type:	list

is_firmware_abort_command(message: wolk_gateway_module.model.message.Message) → bool[source]¶

Check if received message is firmware abort command.

Parameters:	message (Message) – Message received
Returns:	is_firmware_abort_command
Return type:	bool

is_firmware_install_command(message: wolk_gateway_module.model.message.Message) → bool[source]¶

Check if received message is firmware install command.

Parameters:	message (Message) – Message received
Returns:	is_firmware_install_command
Return type:	bool

make_firmware_file_path(message: wolk_gateway_module.model.message.Message) → str[source]¶

Extract file path from firmware install message.

Parameters:	message (Message) – Message received
Returns:	firmware_file_path
Return type:	str

make_update_message(device_key: str, status: wolk_gateway_module.model.firmware_update_status.FirmwareUpdateStatus) → wolk_gateway_module.model.message.Message[source]¶

Make message from device firmware update status.

Parameters:	device_key (str) – Device key to which the firmware update status belongs to status (FirmwareUpdateStatus) – Device firmware update status
Returns:	message
Return type:	Message

make_version_message(device_key: str, firmware_verison: str) → wolk_gateway_module.model.message.Message[source]¶

Make message from device firmware update version.

Parameters:	device_key (str) – Device key to which the firmware update belongs to firmware_verison (str) – Current firmware version
Returns:	message
Return type:	Message

JSON Registration Protocol¶

class wolk_gateway_module.json_registration_protocol.JsonRegistrationProtocol[source]¶

Send device registration requests and handle their responses.

extract_key_from_message(message: wolk_gateway_module.model.message.Message) → str[source]¶

Return device key from message.

Parameters:	message (Message) – Message received
Returns:	device_key
Return type:	str

get_inbound_topics_for_device(device_key: str) → list[source]¶

Return list of inbound topics for given device key.

Parameters:	device_key (str) – Device key for which to create topics
Returns:	inbound_topics
Return type:	list

is_registration_response_message(message: wolk_gateway_module.model.message.Message) → bool[source]¶

Check if message is device registration response.

Parameters:	message (Message) – Message received
Returns:	is_device_registration_response
Return type:	bool

make_registration_message(request: wolk_gateway_module.model.device_registration_request.DeviceRegistrationRequest) → wolk_gateway_module.model.message.Message[source]¶

Make message from device registration request.

Parameters:	request (DeviceRegistrationRequest) – Device registration request
Returns:	message
Return type:	Message

make_registration_response(message: wolk_gateway_module.model.message.Message) → wolk_gateway_module.model.device_registration_response.DeviceRegistrationResponse[source]¶

Make device registration response from message.

Parameters:	message – Message received
Rtype message:	Message
Returns:	device_registration_response
Return type:	DeviceRegistrationResponse

JSON Status Protocol¶

class wolk_gateway_module.json_status_protocol.JsonStatusProtocol[source]¶

Parse inbound messages and serialize device status messages.

extract_key_from_message(message: wolk_gateway_module.model.message.Message) → str[source]¶

Extract device key from message.

Parameters:	message (Message) – Message received
Returns:	device_key
Return type:	str

get_inbound_topics_for_device(device_key: str) → list[source]¶

Return list of inbound topics for given device key.

Parameters:	device_key (str) – Device key for which to create topics
Returns:	inbound_topics
Return type:	list

is_device_status_request_message(message: wolk_gateway_module.model.message.Message) → bool[source]¶

Check if message is device status request.

Parameters:	message (Message) – Message received
Returns:	is_device_status_request
Return type:	bool

make_device_status_response_message(device_status: wolk_gateway_module.model.device_status.DeviceStatus, device_key: str) → wolk_gateway_module.model.message.Message[source]¶

Make message from device status response.

Parameters:	device_key (str) – Device to which the status belongs to device_status (DeviceStatus) – Device’s current status
Returns:	message
Return type:	Message

make_device_status_update_message(device_status: wolk_gateway_module.model.device_status.DeviceStatus, device_key: str) → wolk_gateway_module.model.message.Message[source]¶

Make message from device status update.

Parameters:	device_key (str) – Device to which the status belongs to device_status (DeviceStatus) – Device’s current status
Returns:	message
Return type:	Message

make_last_will_message(device_keys: list) → wolk_gateway_module.model.message.Message[source]¶

Make last will message from list of device keys.

Parameters:	device_keys (list(str)) – List of device keys
Returns:	message
Return type:	Message

Outbound Message Deque¶

class wolk_gateway_module.outbound_message_deque.OutboundMessageDeque[source]¶

Responsible for storing messages before being sent to WolkGateway.

Messages are sent in the order they were added to the queue.

Storing readings and alarms without Unix timestamp will result in all sent messages being treated as live readings and will be assigned a timestamp upon reception, so for a valid history add timestamps to readings via int(round(time.time() * 1000))

get() → Optional[wolk_gateway_module.model.message.Message][source]¶

Get the first message from storage without removing it.

Returns:	message
Return type:	Message, None

get_messages_for_device(device_key: str) → List[wolk_gateway_module.model.message.Message][source]¶

Return a list of messages that belong to a certain device.

Does not remove from storage.

Parameters:	device_key (str) – Device identifier
Returns:	messages
Return type:	List[Message]

put(message: wolk_gateway_module.model.message.Message) → bool[source]¶

Place a message in storage.

Parameters:	message (Message) – Message to be stored
Returns:	result
Return type:	bool

queue_size() → int[source]¶

Return current number of messages in storage.

Returns:	size
Return type:	int

remove(message: wolk_gateway_module.model.message.Message) → bool[source]¶

Remove specific message from storage.

Returns:	result
Return type:	bool

MQTT Connectivity Service¶

class wolk_gateway_module.mqtt_connectivity_service.MQTTConnectivityService(host: str, port: int, client_id: str, qos: int, lastwill_message: wolk_gateway_module.model.message.Message, topics: list)[source]¶

Responsible for exchanging data with WolkGateway through MQTT.

add_subscription_topics(topics: List[str]) → None[source]¶

Add subscription topics.

Adding these topics will not subscribe to them immediately, a new connection needs to happen to subscribe to them.

Parameters:	topics (List[str]) – List of topics

connect() → bool[source]¶

Establish connection with WolkGateway.

Returns:	result
Return type:	bool

connected() → bool[source]¶

Return if currently connected.

Returns:	connected
Return type:	bool

disconnect() → None[source]¶: Terminate connection with WolkGateway.

publish(message: wolk_gateway_module.model.message.Message) → bool[source]¶

Publish serialized data to WolkGateway.

Parameters:	message (Message) – Message to be published
Returns:	result
Return type:	bool

reconnect() → bool[source]¶

Terminate existing and create new connection with WolkGateway.

Returns:	result
Return type:	bool
Raises:	RuntimeError – Reason for connection being refused

remove_topics_for_device(device_key: str) → None[source]¶

Remove topics for device from subscription topics.

Parameters:	device_key (str) – Device identifier

set_inbound_message_listener(on_inbound_message: Callable[[wolk_gateway_module.model.message.Message], None]) → None[source]¶

Set the callback function ot handle inbound messages.

Parameters:	on_inbound_message (Callable[[Message], None]) – Callable that handles inbound messages

set_lastwill_message(message: wolk_gateway_module.model.message.Message) → None[source]¶: Send offline state for module devices on disconnect.