Abstract base classes and function stubs¶

Connectivity service¶

Service for exchanging data with WolkAbout IoT Platform.

class wolk.interface.connectivity_service.ConnectivityService[source]¶

Bases: ABC

Responsible for exchanging data with WolkAbout IoT Platform.

abstract connect() → bool[source]¶: Connect to WolkAbout IoT Platform.

abstract disconnect() → None[source]¶: Disconnect from WolkAbout IoT Platform.

abstract is_connected() → bool[source]¶

Return current connection state.

Returns:: connected
Return type:: bool

abstract publish(message: Message) → bool[source]¶

Publish a message to WolkAbout IoT Platform.

Parameters:: outbound_message (Message) – Message to send
Returns:: success
Return type:: bool

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

Set a callback method to handle inbound messages.

Parameters:: listener (Callable[[Message], None]) – Method hat handles inbound messages

File management¶

Module responsible for handling files and file transfer.

class wolk.interface.file_management.FileManagement(status_callback: Callable[[str, FileManagementStatus], None], packet_request_callback: Callable[[str, int, int], None], url_status_callback: Callable[[str, FileManagementStatus, Optional[str]], None])[source]¶

Bases: ABC

File transfer manager.

Enables device to transfer files from WolkAbout IoT Platform: package by package or/and URL download.

abstract 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

abstract 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]]]

abstract 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]

abstract get_preffered_package_size() → int[source]¶

Return preffered package size for file transfer.

Returns:: preferred_package_size
Return type:: int

abstract 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.

abstract handle_file_delete(file_names: List[str]) → None[source]¶

Delete files from device.

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

abstract handle_file_purge() → None[source]¶: Delete all files from device.

abstract handle_file_upload_abort() → None[source]¶: Abort file upload and revert to idle status.

abstract handle_file_url_download_abort() → None[source]¶: Abort file URL download.

abstract 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

abstract 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) – base64 encoded sha256 hash of file

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

Set the URL file downloader to a custom implementation.

Parameters:: downloader (Callable[[str, str], bool]) – Function that will download the file from the URL

abstract supports_url_download() → bool[source]¶

Return if the file management module supports URL download.

Returns:: supports_url_download
Return type:: bool

Firmware handler¶

Firmware handler for file installation and version reporting.

class wolk.interface.firmware_handler.FirmwareHandler[source]¶

Bases: ABC

Handle firmware installation and get current firmware version.

abstract get_current_version() → str[source]¶

Obtain device’s current firmware version.

Returns:: version
Rtpe:: str

abstract install_firmware(firmware_file_path: str) → None[source]¶

Handle the installation of the firmware file.

Parameters:: firmware_file_path (str) – Path where the firmware file is located

Firmware update¶

Enables firmware update for device.

class wolk.interface.firmware_update.FirmwareUpdate(firmware_handler: FirmwareHandler, status_callback: Callable[[FirmwareUpdateStatus], None])[source]¶

Bases: ABC

Firmware Update enabler.

Responsible for supervising firmware installation and reporting current firmware installation status and version.

abstract get_current_version() → str[source]¶

Return device’s current firmware version.

Returns:: Firmware version
Return type:: str

abstract handle_abort() → None[source]¶: Handle received firmware installation abort command.

abstract handle_install(file_path: str) → None[source]¶

Handle received firmware installation command.

Parameters:: file_path (str) – Firmware file to install

abstract report_result() → None[source]¶: Report the results of the firmware update process.

Message deserializer¶

Process messages received from WolkAbout IoT Platform.

class wolk.interface.message_deserializer.MessageDeserializer[source]¶

Bases: ABC

Deserialize messages received from the platform.

abstract get_inbound_topics() → List[str][source]¶

Return list of inbound topics for device.

Returns:: List of topics to subscribe to
Return type:: List[str]

abstract 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

abstract is_file_binary_response(message: Message) → bool[source]¶

Check if message is file binary message.

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

abstract 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

abstract 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

abstract 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

abstract 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

abstract 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

abstract 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_command
Return type:: bool

abstract 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

abstract 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_initiate
Return type:: bool

abstract is_firmware_abort(message: Message) → bool[source]¶

Check if message is firmware update command.

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

abstract 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_command
Return type:: bool

abstract 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

abstract 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

abstract 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

abstract 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]]]

abstract 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

abstract 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]

abstract 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:: (file_name, file_size, file_hash)
Return type:: Tuple[str, int, str]

abstract 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

abstract parse_firmware_install(message: Message) → str[source]¶

Return file name from message.

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

abstract 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]]

abstract 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

Message factory¶

Create messages from data that conform to device’s specified protocol.

class wolk.interface.message_factory.MessageFactory[source]¶

Bases: ABC

Serialize messages to be sent to WolkAbout IoT Platform.

abstract 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

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

Serialize request to register a feed for the device 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

abstract 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

abstract 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

Returns:

message

Return type:

Message

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

Serialize feed values collected and organized by timestamp.

Parameters:: collected_readings (Dict[int, Dict[str, OutgoingDataTypes]]) – Feed values, organized by timestamp, and then by reference.
Returns:: The message containing all the data
Return type:: Message

abstract 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

abstract 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

abstract 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

abstract make_from_firmware_update_status(firmware_update_status: FirmwareUpdateStatus) → Message[source]¶

Report the current status of the firmware update process.

Parameters:: firmware_update_status (FirmwareUpdateStatus) – Status of the firmware update process
Returns:: message
Return type:: Message

abstract 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

abstract 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

abstract make_pull_feed_values() → Message[source]¶

Serialize message requesting any pending inbound feed values.

Returns:: message
Return type:: Message

abstract make_pull_parameters() → Message[source]¶

Serialize request to pull device parameters from the Platform.

Returns:: message
Return type:: Message

abstract make_time_request() → Message[source]¶

Serialize message requesting platform timestamp.

Returns:: message
Return type:: Message

Message queue¶

Store messages before sending them to WolkAbout IoT Platform.

class wolk.interface.message_queue.MessageQueue[source]¶

Bases: ABC

Store messages on device before publishing to WolkAbout IoT Platform.

abstract get() → Optional[Message][source]¶

Get a message from storage.

Returns:: message
Return type:: Optional[Message]

abstract peek() → Optional[Message][source]¶

Get a message without removing from storage.

Returns:: message
Return type:: Optional[Message]

abstract put(message: Message) → bool[source]¶

Place a message in storage.

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