diff --git a/docs/configuration/cron-expressions.md b/docs/configuration/cron-expressions.md index afacd143..3aa8a849 100644 --- a/docs/configuration/cron-expressions.md +++ b/docs/configuration/cron-expressions.md @@ -5,7 +5,7 @@ sidebar_position: 3 # CRON Expressions We use CRON expressions configure the behavioral timing of our devices. This CRON configuration can be adjusted during -device configuration using the [Lobaro Maintenance Tool](./lobaro-tool/index.md) +device configuration using the [Lobaro Maintenance Tool](./lobaro-tool) or remotely over the air. The CRON expressions consists of 6 fields, separated by space: e.g. `0 0/15 * * * *` , which describes time points every diff --git a/docs/configuration/img/3F-result-in-ascii.png b/docs/configuration/img/3F-result-in-ascii.png new file mode 100644 index 00000000..48b4b7ac Binary files /dev/null and b/docs/configuration/img/3F-result-in-ascii.png differ diff --git a/docs/configuration/img/Downlink-TTN-get-fw.png b/docs/configuration/img/Downlink-TTN-get-fw.png new file mode 100644 index 00000000..55914968 Binary files /dev/null and b/docs/configuration/img/Downlink-TTN-get-fw.png differ diff --git a/docs/configuration/img/lorawan-downlink-3F-answer.png b/docs/configuration/img/lorawan-downlink-3F-answer.png new file mode 100644 index 00000000..8979dc17 Binary files /dev/null and b/docs/configuration/img/lorawan-downlink-3F-answer.png differ diff --git a/docs/configuration/img/lorawan-downlink-3F-downlink.png b/docs/configuration/img/lorawan-downlink-3F-downlink.png new file mode 100644 index 00000000..7023dadb Binary files /dev/null and b/docs/configuration/img/lorawan-downlink-3F-downlink.png differ diff --git a/docs/configuration/img/ttn-downlink.png b/docs/configuration/img/ttn-downlink.png new file mode 100644 index 00000000..ce3012ef Binary files /dev/null and b/docs/configuration/img/ttn-downlink.png differ diff --git a/docs/configuration/index.md b/docs/configuration/index.md index 576398fa..675cddac 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/index.md @@ -17,7 +17,7 @@ img={require('./img/Lobaro-Config-in-Log.png')} style={{width:'60%',paddingTop:'10px',paddingBottom:'10px'}} /> Any Lobaro device configuration can be set and read out either locally via a PC with the [Lobaro configuration USB -adapter](./usb-cfg-adapter) and the [Lobaro Maintenance Tool](./lobaro-tool/index.md) or over the air remotely +adapter](./usb-config-adapter) and the [Lobaro Maintenance Tool](./lobaro-tool/index.md) or over the air remotely using the Lobaro IoT platform and mobile radio (NB-IoT, LTE-M) or any LoRaWAN network server using downlinks on the special cfg port. diff --git a/docs/configuration/lobaro-tool/index.md b/docs/configuration/lobaro-tool/index.md index ba450b23..191febd6 100644 --- a/docs/configuration/lobaro-tool/index.md +++ b/docs/configuration/lobaro-tool/index.md @@ -5,7 +5,7 @@ sidebar_position: 1 # Lobaro Maintenance Tool The Lobaro Maintenance Tool can be used to configure and diagnose Lobaro devices locally using a PC and our special -[USB configuration adapter](../usb-cfg-adapter.md). It's available as free [download](#download) for all common +[USB configuration adapter](../usb-config-adapter). It's available as free [download](#download) for all common operating systems. Lobaro Configuration Tool= ` | 61 | | +| b | Reboot device without saving | `None ` | 62 | | +| g | Get config parameter value | `Name of parameter` | 67 | | +| r | Reset config parameter value | `Name of parameter` | 72 | | +| s | Set config parameter value | `= ` | 73 | | +| S | Set config parameter value & Save and reboot | `= ` | 53 | Not supported on all devices | +| w | Save config and reboot device | `None ` | 77 | | + +:::warning +Depending on the firmware version not all commands might be supported on all devices. +Please refer to the manual of your product for more details. +::: + +#### `?` + +Request firmware and version. This command triggers the device to send what firmware it is running and in which version. +This can be used to test if the remote configuration is working. + +#### `g` + +Get the value of the config parameter ``. This command makes the device sent a response +containing `=` as +parameter giving you the current value of a configuration parameter. + +#### `r / r*` + +Reset config parameter `` to its default value. As a confirmation the device sends a response +containing `=`, reporting the new value of the parameter.Sending the special value * will reset all config +parameters. + +#### `s=` + +Set config parameter `` to ``. Sets the parameter to the value given in the parameter. As a confirmation it +sends a response containing `=`, reporting the new value of the parameter. + +#### `a=` + +Append `` to the config parameter ``. This command appends the value given to the current value of the +parameter. This is intended to allow setting values that are too long for a single Downlink message. As a confirmation +it sends the length of the config parameter's value after the appending. Append works for config parameters of type +string. + +#### `b` + +Reboot device without saving. This command restarts the device. Any changes too the config that have been committed +before will be lost! This command does not send a Response. + +#### `w or wFORCE` + +Save config and reboot device. This command saves all configuration changes to a temporarily configuration and restarts +the device. Only if the device boots successfully and reaches normal operation mode is the new configuration made +permanent. If any fatal configuration error occurs or if the LoRaWAN OTAA Join does not succeed, the previous +configuration will be restored and the device restarted again. This command does not send a Response.If you add the +special argument FORCE to the command, the configuration will be made permanent without testing the configuration. + +:::danger +Using **wFORCE** can leave your device useless and unreachable! + +Do not use **wFORCE** unless you have a very good reason. If the device is set to an invalid configuration it will no +longer +be reachable by the Network Server. From such a state it can only be recovered with physical access and a config +adapter. It will also most likely drain the battery quickly. +::: + +:::warning +For commands `s`, `S` and `a` make sure the number of characters to send matches with the possibilities your devices +spreading factor: + +* SF 7 = 242 bytes max. LoRaWAN downlink payload +* SF 12 = 51 bytes max. LoRaWAN downlink payload + +Consider splitting bigger configuration changed in multiple smaller downlinks. +::: + +## Examples + +### Changing device configuration + +The following is a short example of how you can update two configuration values remotely (that includes rebooting the +device). + +Most LoRaWAN devices (all that are running in Class A, which are by fast the most) can only be reached when they contact +the network. Network Servers (like The Things Network) provide a mechanism to enqueue messages for a specific device. +The messages will be sent as downlink the next time that device contacts the network. Normally, multiple messages can be +enqueued and will all be transmitted as soon as possible. Please be advised that the gateways communicating with your +device must respect their duty cycle, so there is a very limited amount of downlinks that can be sent for a given time ( +downlinks are expensive). + +For this example we want to set Time Synchronization to sync the internal clock every 10 days, and we want to deactivate +Adaptive Date Rate (ADR). These are both LoRaWAN configuration parameters that are present on most devices (find details +under LoRaWAN Configuration), but you can of course also change parameters specific to your device, e.g. Modbus +configuration or wMBus configuration, with this feature. + +We will need to send three commands: + +* **s**TimeSync=10 + * set time synchronization to 10 day interval +* **s**ADR=false + * disable adaptive data rate +* **w** + * write changes to device configuration and reboot + +The actual s-commands will of course differ for your case, but the w command at the end **must** always be the same. + +After sending the final command, the device will reboot and try the new configuration. If the boot process and the +connection to the network are successful, the device will make the changes permanent. If there is a problem (if you +accidentally set an invalid value, e.g. sADR=flase or if you changed your AppKey to wrong value and your OTAA fails), +the device will revert to the previous configuration. + +#### Downlink on TTN + +How you sent your downlinks depends on the LoRaWAN Network Server you use to connect your devices. You will most likely +need to convert the commands (that are all ASCII) to some different representation, e.g. Hex or Base64. + +In The Things Network you find the downlink panel on the "Device Overview" page for each device, directly below the +panel that shows you OTAA/ABP information (DevEUI, AppKey, ...). It is shown in the following screenshot. + +TTN LoRaWAN downlink configuration + +You will have to encode the commands in hex. In the screenshot you see `73 54 69 6d 65 53 79 6e 63 3d 31 30` as the +message to send; that is the hex representation of `sTimeSync=10`. The Port used for remote configuration for our +devices +is 128. When you enter multiple messages to send, be sure to set the correct scheduling (last). The preselected replace +will overwrite your previously enqueued messages. + +### Getting the firmware version + +For this example the "Request firmware and version" `?` (0x3F) command has to used. We use TTN as network server. + +#### Downlink on TTN + +TTN LoRaWAN downlink get firmware version + +Will result in: + +TTN LoRaWAN downlink get firmware version + +#### Uplink on TTN + +The device answers with this uplink: + +TTN LoRaWAN uplink get firmware version + +This response can be converted to ASCII again, e.g. using +any [online converter](https://www.rapidtables.com/convert/number/hex-to-ascii.html): + +TTN LoRaWAN uplink to ascii conversion get firmware version + +The result is: `?app-hybrid-modbus v0.4.0+battery` + +### Configure a device via script + +#### Example configuration command to be send + +Example command (ASCII encoding): +`SMbCmd=0 0/10 * * * *:R,9600,8N1:010300160002,010300260002,fa0400050001` + +:::warning +For commands `s`, `S` and `a` make sure the number of characters to send matches with the possibilities your devices +spreading factor: + +* SF 7 = 242 bytes max. LoRaWAN downlink payload +* SF 12 = 51 bytes max. LoRaWAN downlink payload + +Consider splitting bigger configuration changed in multiple smaller downlinks. +::: + +Example command (Base64 encoding): +`U01iQ21kPTAgMC8xMCAqICogKiAqOlIsOTYwMCw4TjE6MDEwMzAwMTYwMDAyLDAxMDMwMDI2MDAwMixmYTA0MDAwNTAwMDE=` + +#### Curl Script for TTN + +Curl script to be used with TTN: + +```shell +curl --location \ --header 'Authorization: Bearer NNSXS.XJAZK3VF3YBMXX_API_KEY_KR2HFG6ABXXXXXX.CP4WZUOXXXXXXXB5WW4UUSMNXRLUJ7LVO2U' \ +--header 'Content-Type: application/json' \ +--header 'User-Agent: my-integration/my-integration-version' \ +--request POST \ --data '{"downlinks":[{ "frm_payload": +"U01iQ21kPTAgMC8xMCAqICogKiAqOlIsOTYwMCw4TjE6MDEwMzAwMTYwMDAyLDAxMDMwMDI2MDAwMixmYTA0MDAwNTAwMDE=", +"f_port":128 }] }' \ +'https://eu1.cloud.thethings.network/api/v3/as/applications/your-ttn-applicationID/devices/eui-your_TTN_end_deviceID/down/push' +``` + +See also: https://www.thethingsindustries.com/docs/integrations/webhooks/scheduling-downlinks/ +:::tip +You should use your own data for the API KEY, your-ttn-applicationID and your your_TTN_end_deviceID +::: + +#### Chirpstack V3 + +Curl script to be used with Chirpstack V3: + +```shell +curl -X POST --header 'Content-Type: application/json' +--header 'Accept: application/json' +--header 'Grpc-Metadata-Authorization: +Bearer xxxxxxxxx_API_KEY_xxxxxxx' -d +'{ "deviceQueueItem": { "confirmed": false, "data": +"U01iQ21kPTAgMC8xMCAqICogKiAqOlIsOTYwMCw4TjE6MDEwMzAwMTYwMDAyLDAxMDMwMDI2MDAwMixmYTA0MDAwNTAwMDE=", +"fPort": 128 + } }' +'http://192.198.0.101:8080/api/devices/ChirpStack_DevEUI/queue' +``` + +:::tip +You should use your own data for the API KEY, your Chirpstack_IP_Adress and your your_ChirpStack_DevEUI +::: + +#### Chirpstack V4 + +The actual API has now switched from the Swagger API with UI to gRPC integration, but for compatibility and transition +reasons the chirpstack-rest-api can be installed as an additional component. However, experience has shown that there +are changes that need to be considered. "deviceQueueItem" became ""queueItem" and by default the API can now be reached +on port 8090 and no longer 8080. + +Curl script to be used with Chirpstack V4: + +```shell +curl -X POST --header 'Content-Type: application/json' +--header 'Accept: application/json' +--header 'Grpc-Metadata-Authorization: +Bearer xxxxxxxxx_API_KEY_xxxxxxx' -d +'{ "queueItem": { "confirmed": false, "data": +"U01iQ21kPTAgMC8xMCAqICogKiAqOlIsOTYwMCw4TjE6MDEwMzAwMTYwMDAyLDAxMDMwMDI2MDAwMixmYTA0MDAwNTAwMDE=", +"fPort": 128 + } }' +'http://192.198.0.101:8090/api/devices/ChirpStack_DevEUI/queue' +``` \ No newline at end of file diff --git a/docs/configuration/usb-cfg-adapter.md b/docs/configuration/usb-config-adapter.md similarity index 100% rename from docs/configuration/usb-cfg-adapter.md rename to docs/configuration/usb-config-adapter.md diff --git a/docs/knowledge-base/doc-playground/index.md b/docs/knowledge-base/doc-playground/index.md index 202a7ec1..79adbeaf 100644 --- a/docs/knowledge-base/doc-playground/index.md +++ b/docs/knowledge-base/doc-playground/index.md @@ -172,16 +172,16 @@ Some **content** with _Markdown_ `syntax`. Check [this `api`](#). ### Controlled column width -| Cron definition
| Description | -|------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| -| ` 0 0 11 1W,15W * * ` | 11am on the days closest to the 1st and the 15th day each month that are not Saturdays or Sundays. | -| ` 0 0 15 1,L * * ` | 3pm on the first and last day of each month. | -| ` 0 0 1 ? * 2L ` | 1am on the last Tuesday of each month. | -| ` H H H(0-2) * * * ` | Every day at a fixed pseudo random time between 00:00:00 and 02:59:59.Same time each day for a given device, but different time for different devices. | -| ` H H(0-9)/10 * * * *` | Every 10 minutes, but at a fixed time, randomly but consistently picked for each device. | +| Cron definition | Description | +|-----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| +| ` 0 0 11 1W,15W * * ` | 11am on the days closest to the 1st and the 15th day each month that are not Saturdays or Sundays. | +| ` 0 0 15 1,L * * ` | 3pm on the first and last day of each month. | +| ` 0 0 1 ? * 2L ` | 1am on the last Tuesday of each month. | +| ` H H H(0-2) * * * ` | Every day at a fixed pseudo random time between 00:00:00 and 02:59:59.Same time each day for a given device, but different time for different devices. | +| ` H H(0-9)/10 * * * *` | Every 10 minutes, but at a fixed time, randomly but consistently picked for each device. | ```markdown title="Tables" -| Cron definition
| Description | +| Cron definition | Description | |------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| | ` 0 0 11 1W,15W * * ` | 11am on the days closest to the 1st and the 15th day each month that are not Saturdays or Sundays. | | ` 0 0 15 1,L * * ` | 3pm on the first and last day of each month. |