wolk package

Module that provides connection to WolkAbout IoT Platform.

To start publishing data to the platform create an instance of Device class with credentials obtained from the platform and pass it to an instance of WolkConnect class.

For more information about module features visit: https://github.com/Wolkabout/WolkConnect-Python/tree/master/examples/full_feature_set

WolkConnect

Core of this package. Wraps in all functionality.

class wolk.wolk_connect.WolkConnect(device: Device, host: Optional[str] = None, port: Optional[int] = None, ca_cert: Optional[str] = None)[source]

Bases: object

Exchange data with WolkAbout IoT Platform.

Variables:
  • connectivity_service (ConnectivityService) – Means of sending/receiving data

  • device (Device) – Contains device key and password

  • file_management (FileManagement or None) – File management module

  • firmware_update (FirmwareUpdate or None) – Firmware update handler

  • logger (logging.Logger) – Logger instance issued by wolk.LoggerFactory

  • message_deserializer (MessageDeserializer) – Deserializer of inbound messages

  • message_factory (MessageFactory) – Create messages to send

  • message_queue (MessageQueue) – Store data before sending

  • readings_persistence (ReadingsPersistence) – Store readings before sending

  • readings_limit (int) – Limit of readings stored in persistence

add_feed_value(reading: Union[Tuple[str, Union[bool, int, float, str]], List[Tuple[str, Union[bool, int, float, str]]]], timestamp: Optional[int] = None) None[source]

Place a feed value reading into storage.

A reading is identified by a unique feed reference string and the current value of the feed.

This reading can either be passed as a tuple of (reference, value) for a single feed or as a list of previously mentioned tuples to pass multiple feed readings at once.

A Unix epoch timestamp in milliseconds as int can be provided to denote when the reading occurred. By default, the current system provided time will be assigned to a reading.

Parameters:
  • reading (Union[Reading, List[Reading]]) – Feed value reading

  • timestamp (Optional[int]) – Unix timestamp. Defaults to system time.

add_feed_value_separated(reading: Union[Tuple[str, Union[bool, int, float, str]], List[Tuple[str, Union[bool, int, float, str]]]], timestamp: Optional[int] = None) None[source]

Place a feed value reading into storage.

A reading is identified by a unique feed reference string and the current value of the feed.

This reading can either be passed as a tuple of (reference, value) for a single feed or as a list of previously mentioned tuples to pass multiple feed readings at once.

A Unix epoch timestamp in milliseconds as int can be provided to denote when the reading occurred. By default, the current system provided time will be assigned to a reading.

The separated variant will ensure that these reading values get sent as a separate message, independent of any other feed values that have been added to the object.

Parameters:
  • reading (Union[Reading, List[Reading]]) – Feed value reading

  • timestamp (Optional[int]) – Unix timestamp. Defaults to system time.

connect() None[source]

Connect the device to the WolkAbout IoT Platform.

If the connection is made, then it also sends information about list of files present on device, current firmware version and the result of the firmware update process.

disconnect() None[source]

Disconnect the device from WolkAbout IoT Platform.

publish() None[source]

Publish all currently stored messages to WolkAbout IoT Platform.

pull_feed_values() None[source]

Issue a message to pull commanded feed values.

pull_parameters() None[source]

Issue a message to pull commanded feed values.

register_attribute(name: str, data_type: DataType, value: str) None[source]

Register an attribute for the device.

The attribute name must be unique per device. All attributes created by a device are always required and read-only. If an attribute with the given name already exists, the value will be updated.

Parameters:
  • name (str) – Unique attribute name

  • data_type (DataType) – Data type this attribute will hold

  • value (str) – Value of the attribute

register_feed(name: str, reference: str, feed_type: FeedType, unit: Union[Unit, str]) None[source]

Register a new feed for the device.

Feed is identified by name, unique reference, type (in or in/out) and unit; Where unit is either a default available unit listed in Unit enumeration, or a custom user defined unit that should be passed as a string value.

Parameters:
  • name (str) – Feed name

  • reference (str) – Unique identifier

  • feed_type (FeedType) – Is the feed one or two-way communication

  • unit (Union[Unit, str]) – Unit used to measure this feed

remove_feed(reference: str) None[source]

Remove a feed from the device.

Parameters:

reference (str) – Unique identifier

request_timestamp() Optional[int][source]

Return last received timestamp from Platform.

If the device didn’t connect at least once, then this will return None.

Returns:

UTC timestamp in milliseconds

Return type:

int or None

set_custom_readings_persistence_limit(limit: int)[source]

Change the limit for readings persistence.

Parameters:

limit (int) – New limit for readings persistence

with_custom_connectivity(connectivity_service: ConnectivityService)[source]

Provide a custom way to communicate with the Platform.

Parameters:

connectivity_service (ConnectivityService) – Custom connectivity service

with_custom_message_queue(message_queue: MessageQueue)[source]

Use custom means of storing serialized messages.

Parameters:

message_queue (MessageQueue) – Custom message queue

with_custom_protocol(message_factory: MessageFactory, message_deserializer: MessageDeserializer)[source]

Provide a custom protocol to use for communication with the Platform.

Parameters:
  • message_factory (MessageFactory) – Creator of messages to be sent to the Platform

  • message_deserializer (MessageDeserializer) – Deserializer of messages from the Platform

with_custom_readings_persistence(readings_persistence: ReadingsPersistence)[source]

Use custom means of storing readings.

Parameters:

readings_persistence (ReadingsPersistence) – Custom readings persistence

with_file_management(file_directory: str, preferred_package_size: int = 0, url_downloader: Optional[Callable[[str, str], bool]] = None)[source]

Enable file management on the device.

Parameters:
  • file_directory (str) – Directory where files are stored

  • preferred_package_size (int) – Size in kilobytes, 0 means no limit

  • url_downloader (Optional[Callable[[str, str], bool]]) – Function for downloading file from URL

with_firmware_update(firmware_handler: FirmwareHandler)[source]

Enable firmware update for device.

Requires that file management is previously enabled on device.

Parameters:

firmware_handler (FirmwareHandler) – Provide firmware version & handle installation

with_incoming_feed_value_handler(incoming_feed_value_handler: Callable[[List[Dict[str, Union[bool, int, float, str]]]], None])[source]

Enable device to respond to incoming feed value change commands.

Commands will be delivered as a list of dictionaries that contain a feed_reference:value pair, and a “timestamp” field that specifies when this command was issued from the platform. The timestamp is an int representing Unix milliseconds.

Parameters:

incoming_feed_value_handler (Callable[[IncomingData], None]) – Handler of feed value commands

Connection Management

MQTT connectivity service

Connectivity service based on MQTT protocol.

class wolk.mqtt_connectivity_service.MQTTConnectivityService(device: Device, topics: List[str], qos: int = 2, host: str = 'insert_host', port: int = 80, max_retries: int = 3, ca_cert: Optional[str] = None)[source]

Bases: ConnectivityService

Handle sending and receiving MQTT messages.

connect() bool[source]

Establish the connection to the WolkAbout IoT platform.

Subscribes to all topics defined by device communication protocol. Starts a loop to handle inbound messages.

Returns:

Connection state, True if connected, False otherwise

Return type:

bool

disconnect() None[source]

Disconnects the device from the WolkAbout IoT Platform.

is_connected() bool[source]

Return current connection state.

Returns:

connected

Return type:

bool

publish(message: Message) bool[source]

Publish serialized data to WolkAbout IoT Platform.

Parameters:

message (Message) – Message to be published

Returns:

result

Return type:

bool

set_inbound_message_listener(listener: Callable[[Message], None]) None[source]

Set the callback function to handle inbound messages.

Parameters:

listener (Callable[[Message], None]) – Function that handles inbound messages

Data Handling

WolkAbout Protocol message deserializer

Deserialize messages received in WolkAbout Protocol format.

class wolk.wolkabout_protocol_message_deserializer.WolkAboutProtocolMessageDeserializer(device: Device)[source]

Bases: MessageDeserializer

Deserialize messages received from the WolkAbout IoT Platform.

Variables:

logger (logging.Logger) – Logger instance issued by wolk.LoggerFactory

CHANNEL_DELIMITER = '/'
FEED_VALUES = 'feed_values'
FILE_BINARY = 'file_binary_response'
FILE_DELETE = 'file_delete'
FILE_LIST = 'file_list'
FILE_PURGE = 'file_purge'
FILE_UPLOAD_ABORT = 'file_upload_abort'
FILE_UPLOAD_INITIATE = 'file_upload_initiate'
FILE_URL_ABORT = 'file_url_download_abort'
FILE_URL_INITIATE = 'file_url_download_initiate'
FIRMWARE_ABORT = 'firmware_update_abort'
FIRMWARE_INSTALL = 'firmware_update_install'
PARAMETERS = 'parameters'
PLATFORM_TO_DEVICE = 'p2d/'
TIME = 'time'
get_inbound_topics() List[str][source]

Return list of inbound topics for device.

Returns:

List of topics to subscribe to

Return type:

List[str]

is_feed_values(message: Message) bool[source]

Check if message is for incoming feed values.

Parameters:

message (Message) – The message received

Returns:

is_feed_values

Return type:

bool

is_file_binary_response(message: Message) bool[source]

Check if message is file binary message.

Parameters:

message (Message) – The message received

Returns:

file_binary

Return type:

bool

is_file_delete_command(message: Message) bool[source]

Check if message if file delete command.

Parameters:

message (Message) – The message received

Returns:

file_delete_command

Return type:

bool

is_file_list(message: Message) bool[source]

Check if message is file list request message.

Parameters:

message (Message) – The message received

Returns:

file_list

Return type:

bool

is_file_management_message(message: Message) bool[source]

Check if message is any kind of file management related message.

Parameters:

message (Message) – The message received

Returns:

is_file_management_message

Return type:

bool

is_file_purge_command(message: Message) bool[source]

Check if message if file purge command.

Parameters:

message (Message) – The message received

Returns:

file_purge_command

Return type:

bool

is_file_upload_abort(message: Message) bool[source]

Check if message is file upload command.

Parameters:

message (Message) – The message received

Returns:

file_upload_abort_command

Return type:

bool

is_file_upload_initiate(message: Message) bool[source]

Check if message is file upload command.

Parameters:

message (Message) – The message received

Returns:

file_upload_initiate

Return type:

bool

is_file_url_abort(message: Message) bool[source]

Check if message is file URL download command.

Parameters:

message (Message) – The message received

Returns:

file_url_download_abort

Return type:

bool

is_file_url_initiate(message: Message) bool[source]

Check if message is file URL download command.

Parameters:

message (Message) – The message received

Returns:

file_url_download_init

Return type:

bool

is_firmware_abort(message: Message) bool[source]

Check if message is firmware update command.

Parameters:

message (Message) – The message received

Returns:

firmware_update_abort

Return type:

bool

is_firmware_install(message: Message) bool[source]

Check if message is firmware update install command.

Parameters:

message (Message) – The message received

Returns:

firmware_update_install

Return type:

bool

is_firmware_message(message: Message) bool[source]

Check if message is any kind of firmware related message.

Parameters:

message (Message) – The message received

Returns:

is_firmware_message

Return type:

bool

is_parameters(message: Message) bool[source]

Check if message is for updating device parameters.

Parameters:

message (Message) – The message received

Returns:

is_parameters

Return type:

bool

is_time_response(message: Message) bool[source]

Check if message is response to time request.

Parameters:

message (Message) – The message received

Returns:

is_time_response

Return type:

bool

parse_feed_values(message: Message) List[Dict[str, Union[bool, int, float, str]]][source]

Parse the incoming feed values message.

Parameters:

message (Message) – The message received

Returns:

feed_values

Return type:

List[Dict[str, Union[bool, int, float, str]]]

parse_file_binary(message: Message) FileTransferPackage[source]

Parse the message into a file transfer package.

Parameters:

message (Message) – The message received

Returns:

file_transfer_package

Return type:

FileTransferPackage

parse_file_delete_command(message: Message) List[str][source]

Parse the message into a list of file names.

Parameters:

message (Message) – The message received

Returns:

file_name

Return type:

List[str]

parse_file_initiate(message: Message) Tuple[str, int, str][source]

Return file name, file size and file hash from message.

Parameters:

message (Message) – The message received

Returns:

(name, size, hash)

Return type:

Tuple[str, int, str]

parse_file_url(message: Message) str[source]

Parse the message into a URL string.

Parameters:

message (Message) – The message received

Returns:

file_url

Return type:

str

parse_firmware_install(message: Message) str[source]

Return file name from message.

Parameters:

message (Message) – The message received

Returns:

file_name

Return type:

str

parse_parameters(message: Message) Dict[str, Union[bool, int, float, str]][source]

Parse the incoming parameters message.

Parameters:

message (Message) – The message received

Returns:

parameters

Return type:

Dict[str, Union[bool, int, float, str]]

parse_time_response(message: Message) int[source]

Parse the message into an UTC timestamp.

Parameters:

message (Message) – The message received

Returns:

timestamp

Return type:

int

WolkAbout protocol message factory

Factory for serializing messages according to WolkAbout Protocol.

class wolk.wolkabout_protocol_message_factory.WolkAboutProtocolMessageFactory(device_key: str)[source]

Bases: MessageFactory

Serialize messages to be sent to WolkAbout IoT Platform.

ATTRIBUTE_REGISTRATION = 'attribute_registration'
CHANNEL_DELIMITER = '/'
DEVICE_TO_PLATFORM = 'd2p/'
FEED_REGISTRATION = 'feed_registration'
FEED_REMOVAL = 'feed_removal'
FEED_VALUES = 'feed_values'
FILE_BINARY_REQUEST = 'file_binary_request'
FILE_LIST = 'file_list'
FILE_UPLOAD_STATUS = 'file_upload_status'
FILE_URL_DOWNLOAD_STATUS = 'file_url_download_status'
FIRMWARE_UPDATE_STATUS = 'firmware_update_status'
FIRMWARE_VERSION_UPDATE = 'firmware_version_update'
PARAMETERS = 'parameters'
PULL_FEED_VALUES = 'pull_feed_values'
PULL_PARAMETERS = 'pull_parameters'
TIME = 'time'
make_attribute_registration(name: str, data_type: DataType, value: str) Message[source]

Serialize request to register an attribute for the device.

Parameters:
  • name (str) – Unique identifier

  • data_type (DataType) – Type of data this attribute holds

  • value (str) – Value of the attribute

Returns:

message

Return type:

Message

make_feed_registration(name: str, reference: str, feed_type: FeedType, unit: Union[Unit, str]) Message[source]

Serialize request to register a feed on the Platform.

Parameters:
  • name (str) – Feed name

  • reference (str) – Unique identifier

  • feed_type (FeedType) – Is the feed one or two-way communication

  • unit (Union[Unit, str]) – Unit used to measure this feed

Returns:

message

Return type:

Message

make_feed_removal(reference: str) Message[source]

Serialize request to remove a feed from the device on the Platform.

Parameters:

reference (str) – Unique identifier

Returns:

message

Return type:

Message

make_from_feed_value(reading: Union[Tuple[str, Union[bool, int, float, str]], List[Tuple[str, Union[bool, int, float, str]]]], timestamp: Optional[int]) Message[source]

Serialize feed value data.

Parameters:
  • reading (Union[Reading, List[Reading]]) – Feed value data as (reference, value) or list of tuple

  • timestamp – Unix timestamp in ms. Default to current time if None

Raises:

ValueError – Reading is invalid data type

Returns:

message

Return type:

Message

make_from_feed_values_collected(collected_readings: Dict[int, Dict[str, Union[bool, int, float, str]]]) Message[source]

Serialize feed values collected over time.

Parameters:

collected_readings (Dict[int, Dict[str, OutgoingDataTypes]]) – The map of collected readings.

Returns:

The message containing all data.

Return type:

Message

make_from_file_list(file_list: List[Dict[str, Union[str, int]]]) Message[source]

Serialize list of files present on device.

Parameters:

file_list (List[Dict[str, Union[str, int]]]) – Files present on device

Returns:

message

Return type:

Message

make_from_file_management_status(status: FileManagementStatus, file_name: str) Message[source]

Serialize device’s current file management status.

Parameters:
  • status (FileManagementStatus) – Current file management status

  • file_name (str) – Name of file being transferred

Returns:

message

Return type:

Message

make_from_file_url_status(file_url: str, status: FileManagementStatus, file_name: Optional[str] = None) Message[source]

Serialize device’s current file URL download status.

Parameters:
  • file_url (str) – URL from where the file is to be downloaded

  • status (FileManagementStatus) – Current file management status

  • file_name (Optional[str]) – Only present when download of file is completed

make_from_firmware_update_status(firmware_update_status: FirmwareUpdateStatus) Message[source]

Serialize firmware update status to be sent to WolkAbout IoT Platform.

Parameters:

firmware_update_status – Firmware update status to be serialized

Returns:

message

Return type:

Message

make_from_package_request(file_name: str, chunk_index: int) Message[source]

Request a package of the file from WolkAbout IoT Platform.

Parameters:
  • file_name (str) – Name of the file that contains the requested package

  • chunk_index (int) – Index of the requested package

Returns:

message

Return type:

Message

make_from_parameters(parameters: Dict[str, Union[bool, int, float, str]]) Message[source]

Serialize device parameters to be sent to the Platform.

Parameters:

parameters (Dict[str, Union[bool, int, float, str]]) – Device parameters

Returns:

message

Return type:

Message

make_pull_feed_values() Message[source]

Serialize message requesting any pending inbound feed values.

Returns:

message

Return type:

Message

make_pull_parameters() Message[source]

Serialize request to pull device parameters from the Platform.

Returns:

message

Return type:

Message

make_time_request() Message[source]

Serialize message requesting platform timestamp.

Returns:

message

Return type:

Message

Message deque

Message storage implemented via double ended queue.

class wolk.message_deque.MessageDeque[source]

Bases: MessageQueue

Store messages before they are sent to the WolkAbout IoT Platform.

Variables:
get() Optional[Message][source]

Take the first message from the queue.

Returns:

message

Return type:

Optional[Message]

peek() Optional[Message][source]

Return the first message from the queue without removing it.

Returns:

message

Return type:

Optional[Message]

put(message: Message) bool[source]

Add the message to the queue.

Parameters:

message (Message) – Message to place in the queue

Returns:

success

Return type:

bool

File management

OS File Management module.

class wolk.os_file_management.OSFileManagement(status_callback: Callable[[str, FileManagementStatus], None], packet_request_callback: Callable[[str, int], None], url_status_callback: Callable[[str, FileManagementStatus, Optional[str]], None])[source]

Bases: FileManagement

File transfer manager.

Enables device to transfer files from WolkAbout IoT Platform package by package or/and URL download as well as report list of files currently on device and delete them on request.

configure(file_directory: str, preferred_package_size: int = 0) None[source]

Configure options for file management module.

Parameters:
  • file_directory (str) – Path to where files are stored

  • preferred_package_size (int) – Size in kilobytes, 0 means no limit

get_file_list() List[Dict[str, Union[str, int]]][source]

Return list of files present on device.

Each list item is a dictionary that contains the name of the file, its size in bytes, and a MD5 checksum of the file.

Returns:

file_list

Return type:

List[Dict[str, Union[str, int]]]

get_file_path(file_name: str) Optional[str][source]

Return path to file if it exists.

Parameters:

file_name (str) – File for which to get path

Returns:

file_path

Return type:

Optional[str]

get_preffered_package_size() int[source]

Return preffered package size for file transfer.

Returns:

preferred_package_size

Return type:

int

handle_file_binary_response(package: FileTransferPackage) None[source]

Validate received package and store or use callback to request again.

Parameters:

package (FileTransferPackage) – Package of file being transfered.

handle_file_delete(file_names: List[str]) None[source]

Delete files from device.

Parameters:

file_names (List[str]) – Files to be deleted

handle_file_purge() None[source]

Delete all files from device.

handle_file_upload_abort() None[source]

Abort file upload and revert to idle status.

handle_file_url_download_abort() None[source]

Abort file URL download.

handle_file_url_download_initiation(file_url: str) None[source]

Start file transfer from specified URL.

Parameters:

file_url (str) – URL from where to download file

handle_upload_initiation(file_name: str, file_size: int, file_hash: str) None[source]

Start making package requests and set status to file transfer.

Parameters:
  • file_name (str) – File name

  • file_size (int) – Size in bytes

  • file_hash (str) – MD5 hash of file

set_custom_url_downloader(downloader: Callable[[str, str], bool]) None[source]

Set the URL file downloader to a custom implementation.

Default implementation uses requests and is available as a static method within this class.

Parameters:

downloader (Callable[[[Arg(str, 'file_url'), Arg(str, 'file_path')], bool]) – Function that will download the file from the URL

supports_url_download() bool[source]

Return if the file management module supports URL download.

Returns:

supports_url_download

Return type:

bool

static url_download(file_url: str, file_path: str) bool[source]

Attempt to download file from specified URL.

Parameters:
  • file_url (str) – URL from which to download file

  • file_path – Path where to store file

Type:

file_path: str

Returns:

Successful download

Return type:

bool

Firmware update

Enables firmware update for device.

class wolk.os_firmware_update.OSFirmwareUpdate(firmware_handler: FirmwareHandler, status_callback: Callable[[FirmwareUpdateStatus], None])[source]

Bases: FirmwareUpdate

Responsible for everything related to the firmware update process.

get_current_version() str[source]

Return device’s current firmware version.

Returns:

Firmware version

Return type:

str

handle_abort() None[source]

Handle the abort command received from the platform.

handle_install(file_path: str) None[source]

Handle received firmware installation command.

Parameters:

file_path (str) – Firmware file to install

report_result() None[source]

Report the result of the firmware installation process.

Utility

Logger factory

LoggerFactory Module.

class wolk.logger_factory.LoggerFactory(level=20, console=True, log_file=None)[source]

Bases: object

Factory for issuing ready to use loggers in other modules.

get_logger(name: str, level: Optional[int] = None) Logger[source]

Return a ready to use logger instance.

Parameters:
  • name (str) – Name of the logger

  • level (int or None) – Override the log level

Returns:

Logger instance

Return type:

logger

set_device_key(device_key: str) None[source]

Set device key.

Parameters:

device_key (str) – Device key

wolk.logger_factory.logging_config(level: str, log_file: Optional[str] = None) None[source]

Set desired log level and designate a log file.

Parameters:
  • level (str) – Available levels : debug, info, notset

  • log_file (str or None) – path to log file