.. module:: iot

********************
Fortebit IoT Library
********************

The Zerynth Fortebit IoT Library can be used to ease the connection to the `Fortebit IoT Cloud <https://fortebit.tech/cloud/>`_.

It makes your device act as a Fortebit IoT Device that can be monitored and controlled on the Fortebit IoT Cloud dashboard.

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

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

.. class:: Device(device_token, client, ctx=None)

        Create a Device instance representing a Fortebit IoT device.

        The device is provisioned by the :samp:`device_token`, obtained from the Fortebit 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.
        The optional :samp:`ctx` parameter is an initialized secure socket context.

    
.. method:: listen_rpc(callback)

        Listen to incoming RPC requests that get reported to the specified :samp:`callback` function,
        called as *callback(id, method, params)*:
        
        * :samp:`id` is the request identifier (number)
        * :samp:`method` is the method identifier of the RPC (Remote Procedure Call)
        * :samp:`params` is a dictionary containing the RPC method arguments (or parameters)
        
        Call :func:`send_rpc_reply` to provide the result of the RPC request.
        
        
.. method:: connect()

        Setup a connection to the Fortebit Cloud. Return *True* if successful.

        
.. method:: is_connected()

        Returns the status of the connection to the Fortebit Cloud (reconnections are automatic).

        
.. method:: run()

        Starts the device by executing the underlying client loop.

        
.. method:: publish_telemetry(values, ts)

        Publish :samp:`values` (dictionary) to the device telemetry, with optional timestamp :samp:`ts` (epoch in milliseconds).

        Return a boolean, *False* if the message cannot be sent.
        
.. method:: publish_attributes(attributes)

        Publish :samp:`attributes` (dictionary) to the device *client* attributes.

        Return a boolean, *False* if the message cannot be sent.
        
.. method:: get_attributes(client, shared, timeout)

        Obtain the specified :samp:`client` and/or :samp:`shared` attributes from the device.

        Return a dictionary, *None* if the data could not be received.
        
.. method:: send_rpc_reply(id, result)

        Publish :samp:`result` (dictionary) as a reply to the RPC request with identifier :samp:`id`.

        Return a boolean, *False* if the message cannot be sent.
        
.. method:: do_rpc_request(method, params, timeout)

        Perform an RPC request with name :samp:`method` and arguments :samp:`params`, waiting for
        a reply maximum :samp:`timeout` milliseconds (only with MqttClient).

        Return the result of the RPC (dictionary), *None* in case of errors.