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)[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_key: str, device_status: wolk_gateway_module.model.device_status.DeviceStatus) → wolk_gateway_module.model.message.Message[source]

Make message from device status response.

Parameters:
  • device_status (DeviceStatus) – Device’s current status
  • device_key (str) – Device to which the status belongs to
Returns:

message

Return type:

Message

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

Make message from device status update.

Parameters:
  • device_status (DeviceStatus) – Device’s current status
  • device_key (str) – Device to which the status belongs to
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.

Parameters:topics (List[str]) – List of topics
connect() → bool[source]

Establish connection with WolkGateway.

Returns:result
Return type:bool
Raises:RuntimeError – Reason for connection being refused
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]) – 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.