added custom codec documentation

Cumulocity-IoT · Apr 4, 2023 · a2a73e0 · a2a73e0
1 parent 793a1ab
commit a2a73e0
Show file tree

Hide file tree

Showing 3 changed files with 57 additions and 18 deletions.
diff --git a/readme.md b/readme.md
@@ -141,4 +141,21 @@ Uplink events will also be available on the devices in a form that contains the
 ### Codec IDE
 
 The framework offers the ability to quickly build codec directly from Cumulocity UI with an integrated IDE based on Monaco Editor.
-The IDE is accessible on LoRa/Custom codecs menu
+
+To enable this feature you need to install the custom codec microservice `lora-ns-custom`.
+
+The IDE is accessible on LoRa/Custom codecs menu and is devided in 3 parts:
+
+- Uplink processing (decoder)
+
+![](custom%20codecs%20decoder.png)
+
+- Downlink processing (encoder)
+
+![](custom%20codecs%20encoder.png)
+
+- Operations definition
+
+![](custom%20codecs%20operations.png)
+
+Once you're happy with your codec and you saved it, it will be accessible from any LoRa device Lora tab as a model of the custom codec.
diff --git a/web/1016/lora-package/README.md b/web/1016/lora-package/README.md
@@ -13,14 +13,14 @@ Once microservice feature is enabled, please install the github-proxy microservi
 In devicemanagement-lora application go to menu LoRa/LoRa network servers.
 Simply give a name to your connector, then select the type of LNS you want to connect to (the type you're looking for will only show up if the corresponding microservice is installed).
 
-![](https://github.com/SoftwareAG/cumulocity-lora/raw/v0.30/lora%20ns.png)
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/lora%20ns.png)
 
 Ensure that le LNS you want to connect to Cumulocity is properly configured (some LNS require the creation of an API key for instance).
 Once the type is selected, simply follow the wizard instructions.
 Already provisioned devices will be automatically added to Cumulocity once they send data and their data are forwarded by the LNS to Cumulocity.
 Example for TTN:
 
-![](https://github.com/SoftwareAG/cumulocity-lora/raw/v0.30/lora%20ns%20TTN.png)
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/lora%20ns%20TTN.png)
 
 And another for Chirpstack:
 
@@ -32,48 +32,48 @@ Once the connector is created, Cumulocity will automatically create an HTTP rout
 Moreover, all existing devices in the LNS will be automatically created in Cumulocity once they send data and data are pushed to Cumulocity through the configured HTTP route. Those devices will be created without a codec associated to them, you will therefore need to go to the device detailed view in order to choose the right codec.
 Any payload sent to Cumulocity priori codec selection won't be lost: they will be stored and you will be able to process them once you have chosen the right codec.
 
-![](https://github.com/SoftwareAG/cumulocity-lora/raw/v0.30/lora%20device%20codec%20selection.png)
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/lora%20device%20codec%20selection.png)
 
 ### Provisioning new LoRa devices
 
 In devicemanagement-lora application go to menu LoRa/LoRa devices.
 
-![](https://github.com/SoftwareAG/cumulocity-lora/raw/v0.30/lora%20devices.png)
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/lora%20devices.png)
 
 In order to provision the device in an LNS, you need to check the box labeled "Provision device in LoRa network server": you will then be able to choose the LNS connector related to the LNS you want to provision the device into.
 Depending on the type of LNS connector you choose, different fields will appear to finalise the device provisioning in that specific LNS.
 
 Example for TTN:
 
-![](https://github.com/SoftwareAG/cumulocity-lora/raw/v0.30/lora%20devices%20TTN.png)
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/lora%20devices%20TTN.png)
 
 And another for Chirpstack:
 
-![](https://github.com/SoftwareAG/cumulocity-lora/raw/v0.30/lora%20devices%20Chirpstack.png)
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/lora%20devices%20Chirpstack.png)
 
 ### Provisioning new gateways
 
 In devicemanagement-lora application go to menu LoRa/LoRa gateways.
 
-![](https://github.com/SoftwareAG/cumulocity-lora/raw/v0.30/lora%20gateways.png)
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/lora%20gateways.png)
 
 Depending on the LNS connector you will choose, different fields will appear.
 
 Example with TTN:
 
-![](https://github.com/SoftwareAG/cumulocity-lora/raw/v0.30/lora%20gateways%20TTN.png)
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/lora%20gateways%20TTN.png)
 
 Another with Actility:
 
-![](https://github.com/SoftwareAG/cumulocity-lora/raw/v0.30/lora%20gateways%20Actility.png)
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/lora%20gateways%20Actility.png)
 
 In order to be able to provision a gateway, some LNS require specific authorization. For example TTN requires a user API key, as an application API key will only allow you to manage devices in a specific application.
 
 ### Device management
 
 LoRa devices, identified by a JSON fragment `lora_ns_device_LoRaDevice`, can be managed from a specific view accessible through the submenu "LoRa" on the device detailed view.
 
-![](https://github.com/SoftwareAG/cumulocity-lora/raw/v0.30/lora%20device%20view.png)
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/lora%20device%20view.png)
 
 Several actions can be performed in this view:
 
@@ -101,11 +101,11 @@ You can switch a device to another LNS. When doing so the device will be deprovi
 Depending on the codec configured on the device, various commands will be available.
 Most device will have a command to retrieve their current configuration. When such commands are processed by the device, an uplink containing the device configuration will be received and the configuration will be stored on the device in Cumulocity as a JSON document available in the configuration tab of the device:
 
-![](https://github.com/SoftwareAG/cumulocity-lora/raw/v0.30/lora%20device%20configuration.png)
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/lora%20device%20configuration.png)
 
 You can either update the device configuration by modifying the JSON directly or by sending a command from the LoRa tab. Commands available on the LoRa tab will have their input fields prefilled with the values stored in the device configuration:
 
-![](https://github.com/SoftwareAG/cumulocity-lora/raw/v0.30/lora%20device%20send%20command.png)
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/lora%20device%20send%20command.png)
 
 When a command is sent it will go through the usual Cumulocity operation lifecycle:
 
@@ -119,8 +119,30 @@ Note that not all LNS support downlink update event or that it as to be switched
 
 All LNS events will be available as events on the LNS connector managed object in their raw JSON format as sent by the LNS.
 
-![](https://github.com/SoftwareAG/cumulocity-lora/raw/v0.30/lora%20raw%20LNS%20uplink.png)
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/lora%20raw%20LNS%20uplink.png)
 
 Uplink events will also be available on the devices in a form that contains the fport, the payload in hex format, whether the payload was processed or not and other relevant information.
 
-![](https://github.com/SoftwareAG/cumulocity-lora/raw/v0.30/lora%20device%20raw%20payload.png)
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/lora%20device%20raw%20payload.png)
+
+### Codec IDE
+
+The framework offers the ability to quickly build codec directly from Cumulocity UI with an integrated IDE based on Monaco Editor.
+
+To enable this feature you need to install the custom codec microservice `lora-ns-custom`.
+
+The IDE is accessible on LoRa/Custom codecs menu and is devided in 3 parts:
+
+- Uplink processing (decoder)
+
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/custom%20codecs%20decoder.png)
+
+- Downlink processing (encoder)
+
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/custom%20codecs%20encoder.png)
+
+- Operations definition
+
+![](https://github.com/SoftwareAG/cumulocity-lora/raw/master/custom%20codecs%20operations.png)
+
+Once you're happy with your codec and you saved it, it will be accessible from any LoRa device Lora tab as a model of the custom codec.
diff --git a/web/1016/lora-package/package.json b/web/1016/lora-package/package.json
@@ -1,6 +1,6 @@
 {
   "name": "lora-package",
-  "version": "0.30",
+  "version": "0.31",
   "description": "This is the Cumulocity LoRa plugin.",
   "scripts": {
     "start": "c8ycli server --env.extraWebpackConfig=./extra-webpack.config.js -u https://frpresales.eu-latest.cumulocity.com",
@@ -50,7 +50,7 @@
   "c8y": {
     "application": {
       "name": "LoRa plugin",
-      "description": "LoRa plugin",
+      "description": "Help you manage your LoRa devices and their codecs, gateways and connections to LNS, including TTN, Actility, Loriot, Chirpstack, Orange Live Objects, Objenious, Orbiwise Orbiwan, Kerlink Wanesy. It also includes a framework to build your own LNS connectors and codecs.",
       "contextPath": "sag-ps-iot-pkg-lora-package",
       "key": "sag-ps-iot-pkg-lora-package-application-key",
       "globalTitle": "LoRa plugin",
@@ -63,7 +63,7 @@
           "name": "LoRa plugin",
           "module": "LoraPluginModule",
           "path": "./plugin/lora-plugin.module.ts",
-          "description": "Help you manage your LoRa devices"
+          "description": "Help you manage your LoRa devices and their codecs, gateways and connections to LNS, including TTN, Actility, Loriot, Chirpstack, Orange Live Objects, Objenious, Orbiwise Orbiwan, Kerlink Wanesy. It also includes a framework to build your own LNS connectors and codecs."
         }
       ],
       "remotes": {