Update MQTT API descriptions

wimmar · wimmar · commit ac367c486efa · 2022-03-11T17:37:21.000+01:00
diff --git a/docs/.vuepress/components/MqttTable.vue b/docs/.vuepress/components/MqttTable.vue
@@ -3,7 +3,7 @@
 </template>
 
 <script>
-import PacketsTable from "@shared/vue/components/rtls/PacketsTable";
+import PacketsTable from "@shared-front/vue/components/rtls/PacketsTable";
 
 export default {
   components: {
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -182,7 +182,8 @@ module.exports = {
         plugins: plugins,
         resolve: {
             alias: {
-                "@shared": path.join(__dirname, "../../../backends/portal_backend/shared"),
+                "@shared": path.join(__dirname, "../../../backend/shared"),
+                "@shared-front": path.join(__dirname, "../../../frontends/shared-frontend"),
             }
         },
         module: {
@@ -397,7 +398,7 @@ function getFAQSidebar() {
 
 function getAPISidebar() {
     return [{
-            title: "Engine interface",
+            title: "Live data interfaces",
             collapsable: false,
             children: [
                 ["/api/api_engine_local_mqtt", "Local MQTT JSON data"],
@@ -417,7 +418,7 @@ function getAPISidebar() {
         // },
         // {
         {
-            title: "Device interface",
+            title: "Device interfaces",
             collapsable: false,
             children: [
                 ["/api/api_console", "Console (CLI)"],
diff --git a/docs/api/README.md b/docs/api/README.md
@@ -6,22 +6,22 @@ There are different ways to integrate with the RTLOC system, depending on your n
 
 
 ## Real-time device data
-The position and sensor data for each device can be accessed in real-time in a few ways:
+The position and sensor data for each device can be accessed in real-time in the following ways:
 
-* We provide direct **positioning and sensor data** in two formats: binary and JSON
-  - **[`Binary format`](/api/api_application.html)** - Allows for fast and very compact transmission over TCP/UDP.
-  - **[`JSON format`](/api/api_web.html)** - Receive data in JSON over direct websocket or through an MQTT broker (TCP or websocket).
+* **[`Local JSON over MQTT`](/api/api_engine_local_mqtt.html)**:
+  - Easy to understand, easy to integrate JSON format
+  - Pub/sub per topic type because of MQTT
+  - Most-complete API with zone information, events
+  - Access data over websocket from a browser (MQTT over websocket) or over TCP (MQTT over TCP) in a script or program
 
-* This (binary or JSON) data can be accessed over TCP/UDP, websockets, or MQTT
-  - [`Direct TCP/UDP/WS(S)`](/api/api_conns.html)
-  - **[`MQTT`](/api/api_conns.html)** (over TCP or websocket)
+* **[`Cloud JSON over MQTT`](/api/api_engine_cloud_mqtt.html)**: Use your own broker to receive the above data
 
-  > MQTT can be connected to over TCP or (secure) websocket
+* **[`Binary over TCP`](/api/api_engine_local_bin.html)**:
+  - Compact format, requiring some more decoding effort
+  - Includes raw data direct from the engine, no zone/event/race data
 
 ## Meta data
 
-* Access **meta information** about your projects, users and more (information in database) through our [`REST API`](/api/api_rest.html)
-
 * **Single device** (tag / anchor) information can be read through the CLI or via Bluetooth (BLE).
   - [`BLE API`](/api/api_ble.html) - Make a wireless connection with one of the tags with our BLE interface.
   - [`Device CLI`](/api/api_console.html) - Access the RTLS hardware (anchors and tags) via one of the [interfaces](/embedded/#interfaces).
diff --git a/docs/api/api_ble.md b/docs/api/api_ble.md
@@ -8,6 +8,4 @@ It allows for:
 * ...and more
 
 Download the specification [here](http://callitrix.com/assets/docs/files/api_ble.pdf) or see below. Service ID: *680c21d9-c946-4c1f-9c11-baa1c21329e7*.
-![API_overview](./img/api_ble.png)
-
-(detailed overview coming soon)
+![API_overview](./img/api_ble.png)
diff --git a/docs/api/api_cloud.md b/docs/api/api_cloud.md
diff --git a/docs/api/api_engine_cloud_mqtt.md b/docs/api/api_engine_cloud_mqtt.md
@@ -1,4 +1,4 @@
-# Local live data
+# Cloud live (MQTT JSON) data [Alpha]
 
 Real-time data (position data, tag/anchor statuses, sensor data, etc.) can be received over MQTT (Message Queuing Telemetry Transport, pub/sub), either direct over TCP or over Websocket.
 
@@ -16,12 +16,12 @@ Each message has the following base format:
 
 ``` JSON
 {
-  "time": "", // Current time
+  "time": "", // Time: GPS time of anchor if available, otherwise PC time
   "meta": { // Meta information
     "data_source": "live",
     ...
   },
-  "value": { // Actual data
+  "value": { // Value: message data
     ...
   }
 }
@@ -41,7 +41,6 @@ Example *tag-data* message:
     "data_source":"replay-cx"
   },
   "value": {
-    {
       "frame": 658885,
       "tags": {
         "2012": {
diff --git a/docs/api/api_engine_local_mqtt.md b/docs/api/api_engine_local_mqtt.md
@@ -1,17 +1,16 @@
-# Local live data
+# Local live (MQTT JSON) data
 
 Real-time data (position data, tag/anchor statuses, sensor data, etc.) can be received over MQTT (Message Queuing Telemetry Transport, pub/sub), either direct over TCP or over Websocket.
 
 ## 1. Connection protocol
 
-You can receive data in a pub/sub fashion, through an Mosquitto (MQTT) broker.
-You can use our MQTT broker (some limitations may apply) or set up your own.
+You can receive data using an Mosquitto (MQTT) **client** which connects to our local broker. This can be over websocket in a browser or over TCP from a backend program or script.
 
 Make sure your RTLS setup is publishing MQTT data to the broker.
 Use the following configuration for your MQTT client(s):
 
 * Host: *localhost (same PC) or PC's IP address*
-* Port: 1883 (TCP), 8083 (WS)
+* Port: 1883 (TCP), 8083 (Websocket)
 * Username: 
 * Password:
 
@@ -20,17 +19,15 @@ The MQTT topic and data format per type of message is outlined in the [JSON form
 ### MQTT clients
 
 Clients can connect to the MQTT broker over TCP/TLS or a secure Websocket (WSS).
-Example client libraries:
+Some example client libraries:
 
-* Javascript (browser): [MQTT.js](https://www.npmjs.com/package/mqtt) (Recommended for web applications), [Eclipse Paho](https://www.eclipse.org/paho/clients/js/), ...
+* Javascript (browser): [MQTT.js](https://www.npmjs.com/package/mqtt) (Recommended for web applications, websocket), [Eclipse Paho](https://www.eclipse.org/paho/clients/js/), ...
 
 * Python: [Paho MQTT](https://pypi.org/project/paho-mqtt/), ...
 
 * C#: [MQTTnet](https://github.com/chkr1011/MQTTnet), Eclipse Paho, ...
 
-* ...
-
-### Code examples
+### Code example
 The following example uses the [MQTT.js](https://www.npmjs.com/package/mqtt) client library to connect to our MQTT broker. It uses a demo account and displays demo data (replayed RTLS data continuously fed into our broker).
 
 ``` js
@@ -63,17 +60,19 @@ client.on('message', function (topic, message) {
 })
 ```
 
+> For websocket, use *ws://localhost:8883* instead (change protocol and port)
+
 ## 2. Data Format
 Each message has the following base format:
 
 ``` JSON
 {
-  "time": "", // Current time
+  "time": "", // Time: Based on GPS time of anchor if available, otherwise PC time
   "meta": { // Meta information
     "data_source": "live",
     ...
   },
-  "value": { // Actual data
+  "value": { // Value: message data
     ...
   }
 }
@@ -93,7 +92,6 @@ Example *tag-data* message:
     "data_source":"replay-cx"
   },
   "value": {
-    {
       "frame": 658885,
       "tags": {
         "2012": {
diff --git a/docs/api/api_firmware.md b/docs/api/api_firmware.md
@@ -1,4 +1,8 @@
-# Firmware API
+# Firmware Library
+
+Working with a firmware library allows you to bring your own functionality to the (tag) device while interfacing with our powerful UWB capabilities.
+
+Here's an overview of (some of the) functions available in the library.
 
 ## General
 ### `set subversion`
diff --git a/docs/reference/terminology.md b/docs/reference/terminology.md
@@ -1,69 +1,43 @@
 # Terminology
 
-## General
-`RTLS` - Real-time location system.
+## RTLOC App
+- `Client` - A company or organization owning a license.
 
-`Positioning` - Calculate the positions of (moving) tags.
+- `Project` - A project is a physical setup. It is associated with one purchased license, one engine, one floorplan (and other configurations). A client can have multiple RTLS projects. These are different setups at different locations that can run simultaneously.
 
-## RTLOC terminology
-`Client` - A company or organization owning a license.
-
-`Project` - A client can have multiple RTLS projects. These are different setups at different locations that can run simultaneously.
-
-## Technology
-Some more information on the different technologies we harness. Click here for a full comparison.
-
-`UWB` - Ultra-wide band. A wireless technology that uses a wide spectrum of frequency bands to transmit large amounts of data over a short distance with very low power. All nodes are equipped with UWB. It is used for ranging and communication purposes.
-
-`RFID` - Radio-frequency identification.
-
-`BT` - Bluetooth.
-
-`BLE` - Bluetooth Low Energy. All tags are by default equipped with a BLE chip for short range communication.
-
-`ENET` - Ethernet. All anchors and listeners are by default equipped with ethernet.
-
-`Lora` - Long Range digital wireless data communication technology.
+- `Desktop License` - License needed to run RTLS functionality on-premise (local / desktop)
 
 ## RTLS System
-`Node` - One of the elements of the RTLS system. Could be an anchor, tag or listener.
-
-`Anchor` - A reference node in the RTLS. Comparable with the satellites for GPS.
+- `RTLS` - Real-time location system.
 
-`Tag` - A node that is tracked.
+- `Node` - One of the elements of the RTLS system. Could be an anchor, tag or listener.
 
-`Listener` - A node that only listens to data in the air and forwards that data to a PC.
+- `Anchor` - A reference node in the RTLS. Comparable with the satellites for GPS.
 
-`Autopositioning` - Calculation / estimation of the positions of the anchors by the system, as opposed to manually submitting accurate coordinates. This will provide less accurate position data than submitting accurate coordinates.
+- `Tag` - A node that is tracked.
 
-`Backhaul` - Way of transporting data within the system. Can be wired of wireless.
+- `Listener` - A node that only listens to data in the air and forwards that data to a PC.
 
-`Engine` / `cxRTLS` - Powerful RTLS engine & UWB debugging app
+- `Autopositioning` - Calculation / estimation of the positions of the anchors by the system, as opposed to manually submitting accurate coordinates. This will provide less accurate position data than submitting accurate coordinates.
 
-`Engine` / `cxEngine` - Algorithm implementation, calculates positions from distances
+- `Backhaul` - Way of transporting data within the system. Can be wired of wireless.
 
-`Viewer` / `cxViewer` - (3D) Position viewer
+- `Engine` / `cxRTLS` - Powerful RTLS engine & UWB debugging app
 
-`API` - Application Protocol Interface. Chout out [our RTLS API](/positioning/apis_overview.html).
+- `Engine` / `cxEngine` - Algorithm implementation, calculates positions from distances
 
-`Task` -
+- `API` - Application Protocol Interface. Chout out [our RTLS API](/positioning/apis_overview.html).
 
-`Console` - The console through which you can directly communicate with one of the nodes. This node can be attached via UART, USB or Ethernet.
+- `Console` - The console through which you can directly communicate with one of the nodes. This node can be attached via UART, USB or Ethernet.
 Click here for more information.
 
-`HW` - Hardware
+- `Hz` - Hertz. The derived unit of frequency [1/s].
 
-`SW` - Software
+- `Hairs` - UWB message visual indications in our sniffer
 
-`FW` - Firmware
+- `TagSpeed` - Part of the UWB configuration, containing 
 
-`Hz` - Hertz. The derived unit of frequency [1/s].
-
-`Hairs` - UWB message visual indications in our sniffer
-
-`TagSpeed` - Part of the UWB configuration, containing 
-
-`MANET` - Mobile Adhoc Network.
+- `MANET` - Mobile Adhoc Network.
 
 ### Sensors
 - `Accelerometer` - Measures acceleration forces. These forces may be static (such as gravity) or dynamic.
@@ -72,7 +46,18 @@ Click here for more information.
 
 - `Magnetometer` - Measures magnetic fields.
 
-## Other Technology
+## Technology General
+
+`UWB` - Ultra-wide band. A wireless technology that uses a wide spectrum of frequency bands to transmit large amounts of data over a short distance with very low power. All nodes are equipped with UWB. It is used for ranging and communication purposes.
+
+`RFID` - Radio-frequency identification.
+
+`BLE` - Bluetooth Low Energy. All tags are by default equipped with a BLE chip for short range communication.
+
+`ENET` - Ethernet. All anchors and listeners are by default equipped with ethernet.
+
+`Lora` - Long Range digital wireless data communication technology.
+
 `IP66` - International Protection Marking. Rating of our enclosures. Dust- and waterproof.
 More information [here](https://en.wikipedia.org/wiki/IP_Code).
 
