.. module:: iot

WolkAbout IoT Platform Library
******************************

WolkAbout IoT Platform is an IoT application enablement platform that
allows users to easily and securely connect, manage, monitor and control
disparate devices, transform real-time readings into meaningful data and
combine different devices and services into
a complete IoT solution: `WolkAbout IoT Platform <https://wolkabout.com/>`_
  
Device
------

The :samp:`Device` class contains all the required information for connecting
to the WolkAbout IoT Platform.

.. method:: Device(key, password, actuator_references=None)

* :samp:`key` - The device key obtained when creating the device on WolkAbout IoT platform
* :samp:`password` - The device password obtained when creating the device on WolkAbout IoT platform
* :samp:`actuator_references` - A list of actuator references defined in the device type on WolkAbout IoT Platform
        
Wolk
----

The :samp:`Wolk` class wraps all the functionality of the library.

.. method:: Wolk(device, host="api-demo.wolkabout.com", port=2883, actuation_handler=None, actuator_status_provider=None, configuration_handler=None, configuration_provider=None, message_queue_size=100, keep_alive_enabled=True)

* :samp:`device`: Device containing key, password and actuator references
* :samp:`host`: Address of the MQTT broker of the Platform - defaults to demo instance
* :samp:`port`: Port of the MQTT broker - defaults to demo instance's port
* :samp:`actuation_handler`: Actuation handler function, optional

    .. method:: actuation_handler(reference, value)

    Implement this function in order to execute actuation commands issued from the Platform.

    This function will try to set the actuator, identified by :samp:`reference`, to the :samp:`value` specified by the Platform.

* :samp:`actuator_status_provider`: Actuator status provider function, optional

    .. method:: actuator_status_provider(reference)

    Implement this function in order to provide information about the current status of the actuator to the Platform.

    This function will return the current actuator :samp:`state` and :samp:`value`, identified by :samp:`reference`, to the Platform.

    The possible `states` are::

        iot.ACTUATOR_STATE_READY
        iot.ACTUATOR_STATE_BUSY
        iot.ACTUATOR_STATE_ERROR

    The method should return something like this::

        return (iot.ACTUATOR_STATE_READY, value)

* :samp:`configuration_handler`: Configuration handler function, optional

    .. method:: configuration_handler(configuration)

    Implement this function in order to handle configuration commands issued from the Platform.

    This function should update device configuration with received configuration values.

        * :samp:`configuration` - Dictionary that contains reference:value pairs

* :samp:`configuration_provider`: Configuration provider function, optional

    .. method:: configuration_provider()

    Implement this function to provide information about the current configuration settings to the Platform.

    Reads current device configuration and returns it as a dictionary with device configuration reference as the key, and device configuration value as the value.

* :samp:`message_queue_size`: Number of reading to store in memory, defaults to 100
* :samp:`keep_alive_enabled`: Periodically publish keep alive message, default True

  
        
.. method:: Wolk.connect()
Connect to the Platform.


        
.. method:: Wolk.disconnect()
Disconnect from the Platform.


        
.. method:: Wolk.add_sensor_reading(reference, value, timestamp=None)
Add a sensor reading into storage.

* :samp:`reference`: The reference of the sensor
* :samp:`value`: The value of the sensor reading
* :samp:`timestamp`: (optional) Unix timestamp - if not provided, Platform will assign one


        
.. method:: Wolk.add_alarm(reference, active, timestamp=None)
Add an alarm event into storage.

* :samp:`reference`: The reference of the alarm
* :samp:`active`: Current state of the alarm
* :samp:`timestamp`: (optional) Unix timestamp - if not provided, Platform will assign one


        
.. method:: Wolk.publish()
Publish all currently stored messages to the Platform.


        
.. method:: Wolk.publish_actuator_status(reference)
Publish the current actuator status to the Platform.

* :samp:`reference` The reference of the actuator


        
.. method:: Wolk.publish_configuration()
Publish the current device configuration to the Platform.


        
.. method:: Wolk.request_timestamp()
Return last received Platform timestamp.

If keep alive service is not enabled, this will always be None.

:return: UTC timestamp in milliseconds or None
:rtype: int, None