wirepas-mqtt-library 1.3.0rc1
Library to interact with a Wirepas Network through MQTT/Protobuf API
License: Apache-2
Keywords: wirepas connectivity iot mesh gateway backend

Wirepas MQTT Library
        ====================
        
        This Python wheel is designed to ease the development of tools on top
        of Wirepas Gateway to backend Api (MQTT with protobuf payloads).
        
        Connection through MQTT is wrapped and messages in protobuf format are
        generated and parsed for you.
        
        Its main focus is to control a full network without to handle
        individually the connection to every gateways.
        
        Most api can be used in a synchronous or asynchronous way to feat your design.
        
        Automatically generated documentation is hosted `here <https://wirepas.github.io/wirepas-mqtt-library/>`__.
        
        
        Installation
        ------------
        
        Install from PyPi
        ~~~~~~~~~~~~~~~~~
        
        This package is available from
        `PyPi <https://pypi.org/project/wirepas-mqtt-library/>`__.
        
        .. code:: shell
        
                pip install wirepas-mqtt-library
        
        From the source
        ~~~~~~~~~~~~~~~
        
        This wheel can be install from source directly if you need modifications.
        
        .. code:: shell
        
                pip install -e .
        
        Basic example
        -------------
        
        Steps to write a script to send a message
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Import the module
        ^^^^^^^^^^^^^^^^^
        
        Once the wheel is installed, you can import the module easily
        
        .. code:: python
        
            from wirepas_mqtt_library import WirepasNetworkInterface
        
        Create a Wirepas Network Interface object
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        .. code:: python
        
            wni = WirepasNetworkInterface(host,
                                          port,
                                          username,
                                          password)
        
        This object will allow you to interact with the network. For example,
        you can retrieve the list of gateways
        
        .. code:: python
        
            wni.get_gateways()
        
        Or print the list of sinks for a given network
        
        .. code:: python
        
            line = ""
            for gw, sink, config in wni.get_sinks():
                line += "[%s:%s] " % (gw, sink)
        
            print(line)
        
        Send a message with broadcast address from all sinks of a given network
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        .. code:: python
        
            for gw, sink, config in wni.get_sinks():
                try:
                    res = wni.send_message(gw, sink, 0xFFFFFFFF, 1, 1, "This is a test message".encode())
                    if res != wmm.GatewayResultCode.GW_RES_OK:
                        print("Cannot send data to %s:%s res=%s" % (gw, sink, res))
                except TimeoutError:
                    print("Cannot send data to %s:%s", gw, sink)
        
        Architecture
        -------------
        
        Threading model
        ~~~~~~~~~~~~~~~~
        
        When creating a WirepasNetworkInterface object, few threads will be involved.
        
        * **Network (MQTT) thread**: all the internal MQTT operations will happen on this dedicated thread but no code from your application will be executed on it
        
        * | **Worker thread(s)**: these threads will be used to call all your callbacks.
          | It can be either asynchronous reception of gateway responses or the data you have registered to.
          | If long operation are expected in your callback (like IO operation), you can specify the number of threads to use when creating
          | your WirepasNetworkInterface object to avoid a bottleneck. In fact, multiple threads will allow to handle
          | a new callback if another one is executing long operations.
          | By default there is a single thread.
        
        * **Your calling thread**: Any call made in synchronous mode (cb=None) will lock your calling thread until it a response is receive or a timeout has elapsed
        
        Synchronous vs Asynchronous
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Most of the WirepasNetworkInterface methods can be called synchronously or asynchronously.
        When synchronous, answer from the gateway is awaited before returning.
        from the gateway and a TimeoutError Exception will be generated if the
        gateway doesn't answer within the default 2s timeout.
        
        .. code:: python
        
            # Send a message as broadcast from sink sink_id attached to gateway gw_id on endpoint 1
            # in a synchronous way
            res = wni.send_message(gw, sink, 0xFFFFFFFF, 1, 1, "This is a test message".encode())
            if res != wmm.GatewayResultCode.GW_RES_OK:
                print("Sending data synchronously failed: res=%s" % res)
        
        But if you specify a callback, it will be called when the answer is
        received or never if the gateway doesn't answer.
        
        .. code:: python
        
            def on_message_sent_cb(res, param):
                if res != wmm.GatewayResultCode.GW_RES_OK:
                    print("Sending data asynchronously failed: res=%s. Caller param is %s" % (res, param))
        
            param = 1234
            # Send a message as broadcast from sink sink_id attached to gateway gw_id on endpoint 1
            # in an asynchronous way
            wni.send_message(gw_id, sink_id, 0xFFFFFFFF, 1, 1, "This is a test message".encode(), cb=on_message_sent_cb, param=param)
        
        
        License
        -------
        
        Licensed under the Apache License, Version 2.0.