.. module:: zerynthzdm .. _lib.zerynth.zdm: =============== Getting started =============== The Zerynth Device Manager (ZDM) Library contains classes and methods allowing the devices to connect to the ZDM. The ZDM library can be used to send data from a device and to let it receive remote commands called *jobs* in the ZDM lingo. To learn how to use it and call ZDM methods, see the `ZDM getting started doc `_. ===================== The Credentials class ===================== .. class:: Credentials() Creates a Credentials instance that loads the provisioning information from the appropriate location. Provisioning information is saved in the :samp:`zdevice.json` file contained in the Zerynth project folder. Based on its content, the Credentials class is capable of loading or creating all the necessary pieces of information: * :samp:`device_id` the unique identifier of the device in the ZDM * :samp:`credential_type` the type of credentials to use (i.e. cloud token, device token, certificates, etc...) * :samp:`device_secret`, secret key. If empty, the secure element is used as key storage * :samp:`endpoint`, the mqtt broker address * :samp:`ca`, the ZDM root certificate ================ The Config class ================ .. class:: Config(keepalive=60,cycle_timeout=500,command_timeout=60000,clean_session=True,qos_publish=0,qos_subscribe=1) Creates a Config instance that set parameters for the connection to the MQTT broker. In particular, the following parameters are available: * :samp:`keepalive` the MQTT keep alive timeout, in seconds * :samp:`cycle_timeout` how long to block on the socket waiting for broker input, in milliseconds * :samp:`command_timeout`, how long to wait for a connect/disconnect command to finish, in milliseconds * :samp:`clean_session`, use MQTT clean session flag * :samp:`qos_publish`, the quality of service when publishing to the MQTT broker * :samp:`qos_subscribe`, the quality of service when subscribing to the MQTT broker ================ The Device class ================ .. class:: Device(cred=None, cfg=None, jobs_dict=None, condition_tags=[], on_timestamp=None, on_open_conditions=None, fota_callback=None, time_function=default_time_func) Creates a Device instance with uid :samp:`device_id`. All other parameters are optional and have default values. * :samp:`jobs_dict` is the dictionary that defines the device's available jobs * :samp:`condition_tags` is a list of strings defining the conditions tags used by the device (default []). * :samp:`on_timestamp`, is a callback function called when timestamp is received after requesting current time to the ZDM (default None). * :samp:`on_open_conditions`, is a callback function that is called when the list of open conditions is received (default None). * :samp:`fota_callback`, is a function accepting one ore more arguments that will be called at different steps of the FOTA process. * :samp:`time_function`, is a synchronous function that returns the time. Default is retrieving the time through a ntp server. .. method:: connect() Connect to the ZDM with the parameters and credentials specified in the constructor. Upon successful connection, subscribe to the required ZDM topics for jobs. Upon successful subscription, request current device status from the ZDM. Return the result code of MQTT connection (0 for ok). .. method:: connected() Returns ``True`` if the device is connected to the ZDM, ``False`` otherwise. .. method:: publish(data, tag=None) Publish a message to the ZDM. * :samp:`data`, is the message payload, represented by a dictionary. * :samp:`tag`, is a label for the data. .. method:: new_condition(condition_tag) Create and return a new condition. * :samp:`condition_tag`, the tag of the new condition. For the condition to be created correctly, the condition tag must be presend in the :samp:`condition_tags` parameter of the class constructor. .. method:: request_timestamp() Request the current timestamp. When successfully received, the :samp:`on_timestamp` callback is called .. method:: request_open_conditions() Request all the device conditions not yet closed. When the open conditions are received, the :samp:`on_open_conditions` callback is called =================== The Condition class =================== .. class:: Condition(device, uuid, tag) Creates a Condition for device instance :samp:`device` with unique identifier :samp:`uuid` and tag :samp:`tag`. A Condition is an event described by :samp:`tag` (i.e. temperature_high) with an associated opening and closing time. Conditions are useful to represent alarms or in general events with a duration in time. .. method:: is_open() Return True if the condition is open. False otherwise. .. method:: open(payload={}, start=None) Open a condition. * :samp:`tag`, the label associated to the condition * :samp:`start`, the opening time of the condition (RFC3339 format) (if not given, uses current timestamp) .. method:: close(payload={}, finish=None) Close a condition * :samp:`payload`, an optional dict associated with the close operation. * :samp:`finish`, the closing time of the condition (RFC3339 format) (if not given, uses current timestamp) .. method:: reset() Reset a condition in order to reuse it without creating a new one. The method generates a new id for the condition, and reset all the others fields except the tag. .. method:: get_payload_open() Return the payload of the condition when it was opened. .. method:: get_payload_close() Return the payload of the condition when it was closed. .. method:: get_id() Return the condition unique identifier .. method:: get_tag() Return the condition tag .. method:: get_start() Return the opening time .. method:: get_finish() Return the closing time