.. module:: iot
***************
Ubidots Library
***************
The Zerynth Ubidots Library can be used to ease the connection to the `Ubidots IoT platform `_.
It allows to make your device act as an Ubidots Device which can be created through Ubidots dashboard.
===============
The Device class
===============
.. class:: Device(device_label, user_type, api_token)
Create a Device instance representing an Ubidots Device.
The Device object will contain an mqtt client instance pointing to Ubidots MQTT broker located at :samp:`things.ubidots.com` or :samp:`industrial.api.ubidots.com` depending on :samp:`user_type`, a string which can be :samp:`"educational"` or :samp:`"business"`.
The client is configured with :samp:`device_label` as MQTT id and is able to connect securely through TLS and to authenticate setting :samp:`api_token` as client username.
The client is accessible through :samp:`mqtt` instance attribute and exposes all :ref:`Zerynth MQTT Client methods ` so that it is possible, for example, to setup
custom callback on MQTT commands (though the Device class already exposes high-level methods to setup Ubidots specific callbacks).
The only difference concerns mqtt.connect method which does not require broker url and ssl context, taking them from Device configuration::
my_device = iot.Device('my_label', 'business', 'my_api_token')
my_device.mqtt.connect()
...
my_device.mqtt.loop()
.. method:: publish(data, variable=None)
Publish :samp:`data` dictionary to device or device variable :samp:`variable`.
Data dictionary should follow `valid Ubidots data format `_.
.. method:: on_variable_update(device, variable, callback, json=True)
Set a callback to respond to :samp:`variable` updates from device :samp:`device`.
:samp:`callback` will be called passing a dictionary or a float value, containing variable updates, respectively for a :samp:`True` or :samp:`False` :samp:`json` parameter value::
def noise_callback(data):
noise_level = data['value']
noise_location = data['context']
print(noise_level, noise_location)
device.on_variable_update('noise-listener', 'noise-level', noise_callback)