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.
Raw data
{
"_id": null,
"home_page": "https://github.com/wirepas/wirepas-mqtt-library",
"name": "wirepas-mqtt-library",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "wirepas connectivity iot mesh gateway backend",
"author": "Wirepas Ltd",
"author_email": "opensource@wirepas.com",
"download_url": "https://files.pythonhosted.org/packages/7d/f6/af5d4f01b680eea726bef6d9c701afaeeed171eab9dfb8d68e9a1e8fec4e/wirepas_mqtt_library-1.2.4.tar.gz",
"platform": null,
"description": "Wirepas MQTT Library\n====================\n\nThis Python wheel is designed to ease the development of tools on top\nof Wirepas Gateway to backend Api (MQTT with protobuf payloads).\n\nConnection through MQTT is wrapped and messages in protobuf format are\ngenerated and parsed for you.\n\nIts main focus is to control a full network without to handle\nindividually the connection to every gateways.\n\nMost api can be used in a synchronous or asynchronous way to feat your design.\n\nAutomatically generated documentation is hosted `here <https://wirepas.github.io/wirepas-mqtt-library/>`__.\n\n\nInstallation\n------------\n\nInstall from PyPi\n~~~~~~~~~~~~~~~~~\n\nThis package is available from\n`PyPi <https://pypi.org/project/wirepas-mqtt-library/>`__.\n\n.. code:: shell\n\n pip install wirepas-mqtt-library\n\nFrom the source\n~~~~~~~~~~~~~~~\n\nThis wheel can be install from source directly if you need modifications.\n\n.. code:: shell\n\n pip install -e .\n\nBasic example\n-------------\n\nSteps to write a script to send a message\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nImport the module\n^^^^^^^^^^^^^^^^^\n\nOnce the wheel is installed, you can import the module easily\n\n.. code:: python\n\n from wirepas_mqtt_library import WirepasNetworkInterface\n\nCreate a Wirepas Network Interface object\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n.. code:: python\n\n wni = WirepasNetworkInterface(host,\n port,\n username,\n password)\n\nThis object will allow you to interact with the network. For example,\nyou can retrieve the list of gateways\n\n.. code:: python\n\n wni.get_gateways()\n\nOr print the list of sinks for a given network\n\n.. code:: python\n\n line = \"\"\n for gw, sink, config in wni.get_sinks():\n line += \"[%s:%s] \" % (gw, sink)\n\n print(line)\n\nSend a message with broadcast address from all sinks of a given network\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n.. code:: python\n\n for gw, sink, config in wni.get_sinks():\n try:\n res = wni.send_message(gw, sink, 0xFFFFFFFF, 1, 1, \"This is a test message\".encode())\n if res != wmm.GatewayResultCode.GW_RES_OK:\n print(\"Cannot send data to %s:%s res=%s\" % (gw, sink, res))\n except TimeoutError:\n print(\"Cannot send data to %s:%s\", gw, sink)\n\nArchitecture\n-------------\n\nThreading model\n~~~~~~~~~~~~~~~~\n\nWhen creating a WirepasNetworkInterface object, few threads will be involved.\n\n* **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\n\n* | **Worker thread(s)**: these threads will be used to call all your callbacks.\n | It can be either asynchronous reception of gateway responses or the data you have registered to.\n | If long operation are expected in your callback (like IO operation), you can specify the number of threads to use when creating\n | your WirepasNetworkInterface object to avoid a bottleneck. In fact, multiple threads will allow to handle\n | a new callback if another one is executing long operations.\n | By default there is a single thread.\n\n* **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\n\nSynchronous vs Asynchronous\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nMost of the WirepasNetworkInterface methods can be called synchronously or asynchronously.\nWhen synchronous, answer from the gateway is awaited before returning.\nfrom the gateway and a TimeoutError Exception will be generated if the\ngateway doesn't answer within the default 2s timeout.\n\n.. code:: python\n\n # Send a message as broadcast from sink sink_id attached to gateway gw_id on endpoint 1\n # in a synchronous way\n res = wni.send_message(gw, sink, 0xFFFFFFFF, 1, 1, \"This is a test message\".encode())\n if res != wmm.GatewayResultCode.GW_RES_OK:\n print(\"Sending data synchronously failed: res=%s\" % res)\n\nBut if you specify a callback, it will be called when the answer is\nreceived or never if the gateway doesn't answer.\n\n.. code:: python\n\n def on_message_sent_cb(res, param):\n if res != wmm.GatewayResultCode.GW_RES_OK:\n print(\"Sending data asynchronously failed: res=%s. Caller param is %s\" % (res, param))\n\n param = 1234\n # Send a message as broadcast from sink sink_id attached to gateway gw_id on endpoint 1\n # in an asynchronous way\n wni.send_message(gw_id, sink_id, 0xFFFFFFFF, 1, 1, \"This is a test message\".encode(), cb=on_message_sent_cb, param=param)\n\n\nLicense\n-------\n\nLicensed under the Apache License, Version 2.0.\n\n\n\n",
"bugtrack_url": null,
"license": "Apache-2",
"summary": "Library to interact with a Wirepas Network through MQTT/Protobuf API",
"version": "1.2.4",
"project_urls": {
"Homepage": "https://github.com/wirepas/wirepas-mqtt-library"
},
"split_keywords": [
"wirepas",
"connectivity",
"iot",
"mesh",
"gateway",
"backend"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "02086f14f7b7fe6f2f812d5729a5621880393f569856d564775b777766448d59",
"md5": "e57c3f06d05cfea13f297cfbbf8a2c2c",
"sha256": "060d2bd238d6373501f2e0e931560d34d6f5735e4fd76f3745e7a38f9131da30"
},
"downloads": -1,
"filename": "wirepas_mqtt_library-1.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e57c3f06d05cfea13f297cfbbf8a2c2c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 27390,
"upload_time": "2024-01-18T13:53:25",
"upload_time_iso_8601": "2024-01-18T13:53:25.403282Z",
"url": "https://files.pythonhosted.org/packages/02/08/6f14f7b7fe6f2f812d5729a5621880393f569856d564775b777766448d59/wirepas_mqtt_library-1.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7df6af5d4f01b680eea726bef6d9c701afaeeed171eab9dfb8d68e9a1e8fec4e",
"md5": "dc505bba675df6e59352ba71201aaca8",
"sha256": "bcf85e5d5c521443c064595d83380eae617837140190c1bb8ab4b2b8a0b620a8"
},
"downloads": -1,
"filename": "wirepas_mqtt_library-1.2.4.tar.gz",
"has_sig": false,
"md5_digest": "dc505bba675df6e59352ba71201aaca8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 26782,
"upload_time": "2024-01-18T13:53:27",
"upload_time_iso_8601": "2024-01-18T13:53:27.309055Z",
"url": "https://files.pythonhosted.org/packages/7d/f6/af5d4f01b680eea726bef6d9c701afaeeed171eab9dfb8d68e9a1e8fec4e/wirepas_mqtt_library-1.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-18 13:53:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wirepas",
"github_project": "wirepas-mqtt-library",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "wirepas-mqtt-library"
}
JSON
