diff --git a/Makefile b/Makefile index 66b5f77..72cac99 100644 --- a/Makefile +++ b/Makefile @@ -13,6 +13,7 @@ $(eval pytest := $(venv)/bin/pytest) $(eval bumpversion := $(venv)/bin/bumpversion) $(eval twine := $(venv)/bin/twine) $(eval sphinx-build := $(venv)/bin/sphinx-build) +$(eval sphinx-autobuild := $(venv)/bin/sphinx-autobuild) $(eval invoke := $(venv)/bin/invoke) @@ -106,6 +107,9 @@ docs-html: virtualenv-docs touch doc/source/index.rst $(sphinx-build) -j auto -n -W --keep-going -b html doc/source doc/build/html +docs-autobuild: virtualenv-docs + $(sphinx-autobuild) --open-browser doc/source doc/build/html + # Run link checker on documentation. docs-linkcheck: virtualenv-docs $(sphinx-build) -j auto -n -W --keep-going -b linkcheck doc/source doc/build/html diff --git a/doc/source/handbook/decoders/index.rst b/doc/source/handbook/decoders/index.rst index 4617df1..fd0f1fb 100644 --- a/doc/source/handbook/decoders/index.rst +++ b/doc/source/handbook/decoders/index.rst @@ -21,3 +21,4 @@ shipped with Kotori. tasmota airrohr + tts-ttn diff --git a/doc/source/handbook/decoders/tts-ttn-uplink.json b/doc/source/handbook/decoders/tts-ttn-uplink.json new file mode 100644 index 0000000..596f615 --- /dev/null +++ b/doc/source/handbook/decoders/tts-ttn-uplink.json @@ -0,0 +1,8 @@ +{ + "uplink_message": { + "decoded_payload": { + "temperature_1": 53.3, + "voltage_4": 3.3 + } + } +} diff --git a/doc/source/handbook/decoders/tts-ttn.rst b/doc/source/handbook/decoders/tts-ttn.rst new file mode 100644 index 0000000..97851f8 --- /dev/null +++ b/doc/source/handbook/decoders/tts-ttn.rst @@ -0,0 +1,93 @@ +.. include:: ../../_resources.rst + +.. _tts-ttn-decoder: + +############### +TTS/TTN decoder +############### + + +***** +About +***** + +Receive and decode telemetry data from devices on the `The Things Stack (TTS)`_ +/ `The Things Network (TTN)`_. + +.. figure:: https://upload.wikimedia.org/wikipedia/commons/b/bb/The_Things_Network_logo.svg + :target: https://de.wikipedia.org/wiki/The_Things_Network + :alt: The Things Network logo + :width: 100px + + +************* +Configuration +************* + +Getting the system configured properly is important, please read this section carefully. + + +The Things Network Console +========================== + +First, you will need to use `The Things Network Console`_ at +https://console.cloud.thethings.network/, in order to `configure an outbound Webhook`_. + +.. figure:: https://user-images.githubusercontent.com/453543/236702766-850c9bb3-06e8-4372-8192-0cb521d598a0.png + :target: https://user-images.githubusercontent.com/453543/236702766-850c9bb3-06e8-4372-8192-0cb521d598a0.png + :alt: The Things Network Console Webhook configuration + :width: 640px + + *The Things Network Console Webhook configuration* + +Please configure the following settings: + +- ``Webhook ID``: An arbitrary label identifying the Webhook. +- ``Webhook format``: Choose ``JSON`` here. +- ``Base URL``: Like outlined at the :ref:`daq-http` documentation section, this + setting will obtain the full URL to the data acquisition channel, modulo the + ``/data`` suffix, which will be added per "Enabled event types" configuration + option. +- ``Filter event data``: If you want to filter the submitted telemetry payload, + and only submit the nested ``decoded_payload`` data structure, you can use a + path accessor expression like ``up.uplink_message.decoded_payload``. +- ``Enabled event types``: For the event type ``Uplink message``, add the URL + path suffix ``/data``. + +Example +------- + +This would be a corresponding set of example default values:: + + Webhook ID: expert-bassoon + Webhook format: JSON + Base URL: https://daq.example.org/api/mqttkit-1/testdrive/area-42/node-1 + Filter event data: up.uplink_message.decoded_payload + Enabled event types: /data + + +******* +Example +******* + +Now, JSON data payloads submitted from the TTN infrastructure to your system, like this +example, will be decoded by Kotori transparently. + +.. literalinclude:: tts-ttn-uplink.json + :language: json + +.. todo:: + + Provide an example how a corresponding message can be submitted to TTN + from the terminal, in order to emulate the real scenario, but demonstrate + the telemetry data acquisition works well, almost end-to-end. In the meanwhile, + submit an example JSON message payload to Kotori's HTTP API directly:: + + http https://github.com/daq-tools/kotori/raw/main/doc/source/handbook/decoders/tts-ttn-uplink.json \ + | http POST https://daq.example.org/api/mqttkit-1/testdrive/area-42/node-1/data + + +.. _configure an outbound Webhook: https://www.thethingsindustries.com/docs/integrations/webhooks/ +.. _The Things Stack (TTS): https://www.thethingsindustries.com/docs/ +.. _The Things Network (TTN): https://www.thethingsnetwork.org/ +.. _The Things Network Console: https://www.thethingsnetwork.org/docs/network/console/ diff --git a/requirements-docs.txt b/requirements-docs.txt index 3224d48..9c2c001 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,3 +1,4 @@ -Sphinx<6 +pygments<3 +sphinx<6 +sphinx-autobuild sphinx-material<1 -Pygments<3