WolkAbout IoT Platform Library¶
WolkAbout Python Connector library for connecting Zerynth devices to WolkAbout IoT Platform. The Wolk class depends upon interfaces, making it possible to provide different implementations. The section Dependencies contains the documentation of the default implementations, followed by the Wolk section that contains everything necessary to connect and publish data to the WolkAbout IoT Platform.
Dependencies¶
The following classes are implementations of interfaces on which the Wolk class depends.
MQTT Connectivity Service¶
class ZerynthMQTTConnectivityService¶
class ZerynthMQTTConnectivityService(ConnectivityService.ConnectivityService)
This class provides the connection to the WolkAbout IoT Platform by implementing the ConnectivityService
interface.
device
: Contains device key, device password and actuator referenceshost
: Address of the WolkAbout IoT Platform instanceport
: Port of WolkAbout IoT Platform instanceqos
: Quality of Service for MQTT connection (0,1,2), defaults to 0
ZerynthMQTTConnectivityService.set_inbound_message_listener¶
set_inbound_message_listener(on_inbound_message)
Sets the callback method to handle inbound messages.
on_inbound_message
: The method that handles inbound messages
ZerynthMQTTConnectivityService.on_mqtt_message¶
on_mqtt_message(client, data)
Method that serializes inbound messages and passes them to the inbound message listener.
client
: The client that received the messagedata
: The message received
ZerynthMQTTConnectivityService.connect¶
connect()
This method establishes the connection to the WolkAbout IoT platform. If there are actuators it will subscribe to topics that will contain actuator commands and also starts a loop to handle inbound messages. Raises an exception if the connection failed.
ZerynthMQTTConnectivityService.disconnect¶
disconnect()
Disconnects the device from the WolkAbout IoT Platform.
ZerynthMQTTConnectivityService.connected¶
connected()
Returns the current status of the connection.
ZerynthMQTTConnectivityService.publish¶
publish(outbound_message)
Publishes the outbound_message
to the WolkAbout IoT Platform.
Outbound Message Queue¶
class ZerynthOutboundMessageQueue¶
class ZerynthOutboundMessageQueue(OutboundMessageQueue.OutboundMessageQueue)
This class provides the means of storing messages before they are sent to the WolkAbout IoT Platform.
maxsize
: Int - The maximum size of the queue, effectively limiting the number of messages to persist in memory.
ZerynthOutboundMessageQueue.put¶
put(message)
Adds the message
to self.queue
.
ZerynthOutboundMessageQueue.get¶
get()
Takes the first message
from self.queue
.
ZerynthOutboundMessageQueue.peek¶
peek()
Returns the first message
from self.queue
without removing it from the queue.
Outbound Message Factory¶
class ZerynthOutboundMessageFactory¶
class ZerynthOutboundMessageFactory(OutboundMessageFactory.OutboundMessageFactory)
This class serializes sensor readings, alarms and actuator statuses so that they can be properly sent to the WolkAbout IoT Platform.
device_key
- The key used to serialize messages.
ZerynthOutboundMessageFactory.make_from_sensor_reading¶
make_from_sensor_reading(reading)
Serializes the reading
to be sent to the WolkAbout IoT Platform.
reading
: Sensor reading to be serialized.
ZerynthOutboundMessageFactory.make_from_alarm¶
make_from_alarm(alarm)
Serializes the alarm
to be sent to the WolkAbout IoT Platform.
alarm
: Alarm event to be serialized.
ZerynthOutboundMessageFactory.make_from_actuator_status¶
make_from_actuator_status(actuator)
Serializes the actuator
to be sent to the WolkAbout IoT .
actuator
: Actuator status to be serialized.
ZerynthOutboundMessageFactory.make_from_configuration¶
make_from_configuration(self, configuration)
Serializes the device’s configuration to be sent to the platform.
configuration
: Configuration to be serialized.
Inbound Message Factory¶
class ZerynthInboundMessageDeserializer¶
class ZerynthInboundMessageDeserializer(InboundMessageDeserializer.InboundMessageDeserializer)
This class deserializes messages that the device receives from the WolkAbout IoT Platform from the topics it is subscribed to.
ZerynthInboundMessageDeserializer.deserialize_actuator_command¶
deserialize_actuator_command(message)
Deserializes the message
that was received from the WolkAbout IoT Platform.
message
: The message to be deserialized.
ZerynthInboundMessageDeserializer.deserialize_configuration_command¶
deserialize_configuration_command(message)
Deserializes the message
that was received from the WolkAbout IoT Platform.
message
The message to be deserialized.
Wolk class¶
class Wolk¶
class Wolk()
This class is a wrapper for the WolkCore class that passes the Zerynth compatible implementation of interfaces to the constructor
device
: Contains device key and password, and actuator referenceshost
: The address of the WolkAbout IoT Platform, defaults to the Demo instanceport
: The port to which to send messages, defaults to 1883actuation_handler
: Implementation of theActuationHandler
interfaceactuator_status_provider
: Implementation of theActuatorStatusProvider
interfaceoutbound_message_queue
: Implementation of theOutboundMessageQueue
interfaceconfiguration_handler
: Implementation of theConfigurationHandler
interfaceconfiguration_provider
: Implementation of theConfigurationProvider
interface
Wolk.connect¶
connect()
Connects the device to the WolkAbout IoT Platform by calling the provided connectivity_service’s connect
method.
Wolk.disconnect¶
disconnect()
Disconnects the device from the WolkAbout IoT Platform by calling the provided connectivity_service’s disconnect
method.
Wolk.add_sensor_reading¶
add_sensor_reading(reference, value, timestamp=None)
Publish a sensor reading to the platform.
reference
: String - The reference of the sensorvalue
: Int, Float - The value of the sensor readingtimestamp
: (optional) Unix timestamp - if not provided, platform will assign one upon reception
Wolk.add_alarm¶
add_alarm(reference, active, timestamp=None)
Publish an alarm to the platform
reference
: String - The reference of the alarmactive
: Bool - Current state of the alarmtimestamp
: (optional) Unix timestamp - if not provided, platform will assign one upon reception
Wolk.publish¶
publish()
Publishes all currently stored messages and current actuator statuses to the platform.
Wolk.publish_actuator_status¶
publish_actuator_status(reference)
Publish the current actuator status to the platform.
reference
: String - The reference of the actuator.
Wolk._on_inbound_message¶
_on_inbound_message(message)
Callback method to handle inbound messages.
Note
Pass this method to the implementation of ConnectivityService
interface.
message
: The message received from the platform.
Wolk.publish_configuration¶
publish_configuration()
Publishes the current device configuration to the platform.
Device¶
class Device¶
class Device()
The Device
class contains all the required information for connecting to the WolkAbout IoT Platform.
key
- The device key obtained when creating the device on WolkAbout IoT platformpassword
- The device password obtained when creating the device on WolkAbout IoT platformactuator_references
- A list of actuator references defined in the device template on WolkAbout IoT Platform
Actuation Handler¶
class .ActuationHandler¶
class ActuationHandler()
This interface must be implemented in order to execute actuation commands issued from WolkAbout IoT Platform.
ActuationHandler.handle_actuation¶
handle_actuation(reference, value)
This method will try to set the actuator, identified by reference
, to the value
specified by WolkAbout IoT Platform.
Actuator Status Provider¶
class ActuatorStatusProvider¶
class ActuatorStatusProvider()
This interface must be implemented in order to provide information about the current status of the actuator to the WolkAbout IoT Platform.
ActuatorStatusProvider.get_actuator_status¶
get_actuator_status(reference)
This method will return the current actuator state
and value
, identified by reference
, to the WolkAbout IoT Platform.
The possible states are:
iot.ACTUATOR_STATE_READY
iot.ACTUATOR_STATE_BUSY
iot.ACTUATOR_STATE_ERROR
The method should return something like this:
return (iot.ACTUATOR_STATE_READY, value)
Configuration Handler¶
class ConfigurationHandler¶
class ConfigurationHandler()
This interface must be implemented in order to handle configuration commands issued from WolkAbout IoT Platform.
ConfigurationHandler.handle_configuration¶
handle_configuration(configuration)
This method should update device configuration with received configuration values.
configuration
- Dictionary that containes reference:value pairs.
Configuration Provider¶
class ConfigurationProvider¶
class ConfigurationProvider()
This interface must be implemented to provide information about the current configuration settings to the WolkAbout IoT Platform.
ConfigurationProvider.get_configuration¶
get_configuration()
Reads current device configuration and returns it as a dictionary with device configuration reference as the key, and device configuration value as the value.