.. module:: iot

****************
OKdo IoT Library
****************

The Zerynth OKdo IoT Library can be used to ease the connection to the `OKdo IoT Cloud <https://www.okdo.com/us/do-iot/>`_.

It makes your device act as an OKdo IoT Device which can be created and provisioned on the OKdo IoT Cloud dashboard.

The device always send and receive data in the JSON format.

Check out the examples for a jump start.

    
================
The Device class
================

.. class:: Device(device_id, device_token, client)

        Create a Device instance representing an OKdo device.

        The device is provisioned by the :samp:`device_id` and :samp:`device_token`, obtained from the OKdo dashboard upon the creation of a new device.
        the :samp:`client` parameter is a class that provides the implementation of the low level details for the connection. It can be one of :samp:`MqttClient` in the :samp:`mqtt_client` module, or :samp:`HttpClient` in the :samp:`http_client` module.


    
.. method:: connect()
    
        Setup a connection to the OKdo Cloud. It can raise an exception in case of error.

        
.. method:: run()
    
        Starts the device by executing the underlying client. It can start a new thread depending on the type of client (Mqtt vs Http)

        
.. method:: publish_asset(asset_name,value)
        
        Modify a device asset state. After a successful execution, the new state of the device asset :samp:`asset_name` will be set to :samp:`value`.

        Return the message sent to the OKdo Cloud, or :samp:`None` if the message cannot be sent.
        
.. method:: publish_state(state)
        
        Modify a device state. After a successful execution, the new state of the device will be set to the values contained in :samp:`state`. :samp:`state` is
        a dict where each key is the name of an asset and each value the desired state.

        Return the message sent to the OKdo Cloud, or :samp:`None` if the message cannot be sent.
        
.. method:: watch_command(asset_name, callback)
       
        Start listening for asset command on the device asset identified by :samp:`asset_name`. When a new asset command arrives, the function :samp:`callback` is executed receiving as arguments the asset name, the new value and the previous value (or None if it is the first update).
        Incoming values are checked against the last received timestamp in order to avoid triggering the callback for 
        Modify a device state. After a successful execution, the new state of the device will be set to the values contained in :samp:`state`. :samp:`state` is
        a dict where each key is the name of an asset and each value the desired state.

        Return the message sent to the OKdo Cloud, or :samp:`None` if the message cannot be sent.