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.
- 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.
- 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.
- 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.
- 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:
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_file_management_message(message: Message) bool [source]¶
Check if message is any kind of file management related message.
- is_file_url_initiate(message: Message) bool [source]¶
Check if message is file URL download command.
- is_firmware_install(message: Message) bool [source]¶
Check if message is firmware update install command.
- is_firmware_message(message: Message) bool [source]¶
Check if message is any kind of firmware related message.
- parse_feed_values(message: Message) List[Dict[str, Union[bool, int, float, str]]] [source]¶
Parse the incoming feed values message.
- 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:
- parse_file_delete_command(message: Message) List[str] [source]¶
Parse the message into a list of file names.
- parse_file_initiate(message: Message) Tuple[str, int, str] [source]¶
Return file name, file size and file hash from message.
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.
- 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.
- make_feed_removal(reference: str) Message [source]¶
Serialize request to remove a feed from the device on the Platform.
- 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:
- make_from_feed_values_collected(collected_readings: Dict[int, Dict[str, Union[bool, int, float, str]]]) Message [source]¶
Serialize feed values collected over time.
- make_from_file_list(file_list: List[Dict[str, Union[str, int]]]) Message [source]¶
Serialize list of files present on device.
- 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:
- 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:
- make_from_package_request(file_name: str, chunk_index: int) Message [source]¶
Request a package of the file from WolkAbout IoT Platform.
- make_from_parameters(parameters: Dict[str, Union[bool, int, float, str]]) Message [source]¶
Serialize device parameters to be sent to the Platform.
- make_pull_feed_values() Message [source]¶
Serialize message requesting any pending inbound feed values.
- Returns:
message
- Return type:
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:
logger (logging.Logger) – Logger instance issued by wolk.LoggerFactory
queue (collections.deque) – Double ended queue used to store messages
- get() Optional[Message] [source]¶
Take the first message from the queue.
- Returns:
message
- Return type:
Optional[Message]
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.
- 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.
- get_preffered_package_size() int [source]¶
Return preffered package size for file transfer.
- Returns:
preferred_package_size
- Return type:
- 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_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.
- 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.
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:
Utility¶
Logger factory¶
LoggerFactory Module.