add lwm2m api reference (#337)

* add lwm2m api reference * Update deviceshifu-deployment.md * Update deviceshifu-deployment.md Modified some statements * Update edgedevice.md Modify the format * Update edgedevice.md Modify the format * Update deviceshifu-deployment.md Revise document format. * Revising the document format for LwM2M API references. * Update deviceshifu-configmap.md * Fix the document description and markdown format. * Fixing the document format. --------- Co-authored-by: twilikiss <[email protected]>
Edgenesis · Jan 3, 2025 · 040736c · 040736c
1 parent f795568
commit 040736c
Show file tree

Hide file tree

Showing 4 changed files with 116 additions and 66 deletions.
diff --git a/docs/references/api/deviceshifu-configmap.md b/docs/references/api/deviceshifu-configmap.md
@@ -17,9 +17,9 @@ ConfigMap of ***Shifu*** is a Kubernetes-native [Kubernetes ConfigMap](https://k
 - **kind**: ConfigMap
 - **metadata** (ObjectMeta)<br/>the standard [Kubernetes ObjectMeta](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/object-meta/#ObjectMeta)
 - **data** (map[string]string)<br/>Data for ConfigMap.
-    - **driverProperties** ([DeviceShifuDriverProperties](#deviceshifudriverproperties))
-    - **instructions** ([DeviceShifuInstructions](#deviceshifuinstructions))
-    - **telemetries** ([DeviceShifuTelemetries](#deviceshifutelemetries))
+  - **driverProperties** ([DeviceShifuDriverProperties](#deviceshifudriverproperties))
+  - **instructions** ([DeviceShifuInstructions](#deviceshifuinstructions))
+  - **telemetries** ([DeviceShifuTelemetries](#deviceshifutelemetries))
 
 ## DeviceShifuDriverProperties
 
@@ -36,19 +36,20 @@ DeviceShifuInstructions are all the commands and settings that ***deviceShifu***
 - **instructionSettings** ([DeviceShifuInstructionSettings](#deviceshifuinstructionsettings))
 - **instructions** (map[string]DeviceShifuInstruction)
  **Example:**
+
 ```yml
 instructions: |
   instructions:
     get_value: # The name of the command you want to set
       protocolPropertyList:      # The parameters of the command have different configurations according to different protocols
 ```
-  - **[DeviceShifuInstruction](#deviceshifuinstruction)**
+- **[DeviceShifuInstruction](#deviceshifuinstruction)**
 
 ## DeviceShifuInstruction
 
 DeviceShifuInstruction is the command that ***deviceShifu*** can receive.
 
--  **protocolPropertyList** (map[string]string)([DeviceShifuprotocolPropertyList](#deviceshifuprotocolpropertylist))<br/>parameters of the ***deviceShifu*** command, which have various configurations according to different protocols. Please refer to the  examples for more [examples](https://github.com/Edgenesis/shifu/tree/main/examples).
+- **protocolPropertyList** (map[string]string)([DeviceShifuprotocolPropertyList](#deviceshifuprotocolpropertylist))<br/>parameters of the ***deviceShifu*** command, which have various configurations according to different protocols. Please refer to the  examples for more [examples](https://github.com/Edgenesis/shifu/tree/main/examples).
 
 ## DeviceShifuprotocolPropertyList
 
@@ -66,7 +67,9 @@ instructions: |
           MQTTTopic: "/test/test2"
       ...  # You can continue to configure commands and corresponding topics according to your own needs, just continue to add according to this format
 ```
+
 - **OPC UA**
+
 ```yml
 instructions: |
     instructions:
@@ -79,6 +82,21 @@ instructions: |
       ... # You can continue to configure commands and corresponding NodeID according to your own needs, just continue to add according to this format
 ```
 
+- **LwM2M**
+
+```yaml
+instructions: |
+  instructions:
+    float_value:      # The name of the command you want to set 
+      protocolPropertyList:
+        ObjectId: /3442/0/130 # Device instance object ID, Format: /{Object ID}/{Object Instance}/{Resource ID}
+        EnableObserve: false  # Boolean flag to enable/disable observation mode
+    reset:
+      protocolPropertyList:
+        ObjectId: /3303/0/5605
+        EnableObserve: false
+      ... # You can continue to configure commands and corresponding ObjectId according to your own needs, just continue to add according to this format
+```
 
 ## DeviceShifuInstructionSettings
 
@@ -92,7 +110,7 @@ DeviceShifuTelemetries refer to one or more commands that ***deviceShifu*** uses
 
 - **telemetrySettings** ([DeviceShifuTelemetrySettings](#deviceshifutelemetrysettings))
 - **telemetries** (map[string]DeviceShifuTelemetry)
-    - **[DeviceShifuTelemetry](#deviceshifutelemetry)**
+  - **[DeviceShifuTelemetry](#deviceshifutelemetry)**
 
 ## DeviceShifuTelemetrySettings
 
@@ -101,25 +119,25 @@ DeviceShifuTelemetrySettings are the settings related to ***deviceShifu*** monit
 - **defaultPushToServer** (bool)<br/>***deviceShifu*** Defaults all telemetry to the push service. default false.
 - **defaultTelemetryCollectionService** (string)<br/>***deviceShifu*** Defaults telemetry to push addresses.
 - HTTP protocol
-    - **telemetryUpdateIntervalInMilliseconds** (int64)<br/>millisecond interval at which ***deviceShifu*** detects Telemetry. The default value is 3000.
-    - **telemetryTimeoutInMilliseconds** (int64)<br/>timeout for ***deviceShifu*** to connect to the device. The default value is 3000.
-    - **telemetryInitialDelayInMilliseconds** (int64)<br/>delay time for the initial detection of ***deviceShifu***. The default value is 3000.
+  - **telemetryUpdateIntervalInMilliseconds** (int64)<br/>millisecond interval at which ***deviceShifu*** detects Telemetry. The default value is 3000.
+  - **telemetryTimeoutInMilliseconds** (int64)<br/>timeout for ***deviceShifu*** to connect to the device. The default value is 3000.
+  - **telemetryInitialDelayInMilliseconds** (int64)<br/>delay time for the initial detection of ***deviceShifu***. The default value is 3000.
 - TCP socket protocol
-    - **telemetryUpdateIntervalInMilliseconds** (int64)<br/>millisecond interval at which ***deviceShifu*** detects Telemetry. Default is 1000. (Detection method: ***deviceShifu*** tries to establish a socket connection with the device once every 1000 milliseconds, and determines if the device is on by whether the connection is successful.)
+  - **telemetryUpdateIntervalInMilliseconds** (int64)<br/>millisecond interval at which ***deviceShifu*** detects Telemetry. Default is 1000. (Detection method: ***deviceShifu*** tries to establish a socket connection with the device once every 1000 milliseconds, and determines if the device is on by whether the connection is successful.)
 - MQTT protocol
-    - **telemetryUpdateIntervalInMiliseconds** (int64)<br/>***deviceShifu*** detects the millisecond interval between the MQTT and the receipt of the last msg. Default value is 3000.
+  - **telemetryUpdateIntervalInMiliseconds** (int64)<br/>***deviceShifu*** detects the millisecond interval between the MQTT and the receipt of the last msg. Default value is 3000.
 - PLC4X
-    - **telemetryUpdateIntervalInMiliseconds** (int64)<br/>***deviceShifu*** The interval (in milliseconds) for detecting Telemetry. (Detection method: using PLC4X to send ping to the device.)
+  - **telemetryUpdateIntervalInMiliseconds** (int64)<br/>***deviceShifu*** The interval (in milliseconds) for detecting Telemetry. (Detection method: using PLC4X to send ping to the device.)
 
 ## DeviceShifuTelemetry
 
 DeviceShifuTelemetry describes which commands ***deviceShifu*** uses to monitor the status of IoT devices.
 
 - **properties** (DeviceShifuTelemetryProperties)
-    - **instruction** (string)<br/>Indicates the command used for telemetry, and must be a valid command as defined by [DeviceShifuInstruction](#deviceshifuinstruction) above.
-    - **initialDelayMs** (int)<br/>Indicates the delay (in milliseconds) to start telemetry.
-    - **intervalMs** (int)<br/>Indicates the interval of telemetry (milliseconds).
-    - **pushSettings** ([DeviceShifuTelemetryPushSettings](#deviceshifutelemetrypushsettings))<br/>Used to set up this telemetry push service.
+  - **instruction** (string)<br/>Indicates the command used for telemetry, and must be a valid command as defined by [DeviceShifuInstruction](#deviceshifuinstruction) above.
+  - **initialDelayMs** (int)<br/>Indicates the delay (in milliseconds) to start telemetry.
+  - **intervalMs** (int)<br/>Indicates the interval of telemetry (milliseconds).
+  - **pushSettings** ([DeviceShifuTelemetryPushSettings](#deviceshifutelemetrypushsettings))<br/>Used to set up this telemetry push service.
 
 ## DeviceShifuTelemetryPushSettings
 

diff --git a/docs/references/api/deviceshifu-deployment.md b/docs/references/api/deviceshifu-deployment.md
@@ -21,54 +21,53 @@ Deployment under the ***Shifu*** architecture is a Kubernetes-native [Deployment
 ## General Configuration for Deviceshifu Deployment
 
 - **spec.template.spec.containers[0].env**
-    - **EDGEDEVICE_NAME** (string)<br/>name of the EdgeDevice to which DeviceShifu corresponds to.
-    - **EDGEDEVICE_NAMESPACE** (string)<br/>namespace of the EdgeDevice corresponding to DeviceShifu.
+  - **EDGEDEVICE_NAME** (string)<br/>name of the EdgeDevice to which DeviceShifu corresponds to.
+  - **EDGEDEVICE_NAMESPACE** (string)<br/>namespace of the EdgeDevice corresponding to DeviceShifu.
 - **spec.template.spec.volumes[0].configMap**
-    - **volume**
-        - **name**<br/>name of the ConfigMap to be mounted.
-        - **configMap**<br/>name of the DeviceShifu configuration ConfigMap.
-            - **name** (string)
+  - **volume**
+    - **name**<br/>name of the ConfigMap to be mounted.
+    - **configMap**<br/>name of the DeviceShifu configuration ConfigMap.
+      - **name** (string)
 - **spec.template.spec.containers[0].volumeMounts[].name**
-    - **volumeMount**
-        - **name** (string)<br/>name of the ConfigMap to be mounted.
-    - **mountPath** (string)<br/>path of the mounted ConfigMap, which has to be `/etc/edgedevice/config`.
+  - **volumeMount**
+    - **name** (string)<br/>name of the ConfigMap to be mounted.
+  - **mountPath** (string)<br/>path of the mounted ConfigMap, which has to be `/etc/edgedevice/config`.
 - **spec.template.spec.serviceAccountName** (string)<br/>service account name used by DeviceShifu to update EdgeDevice information, which has to be `edgedevice-sa`
 
 ## OPC UA DeviceShifu Deployment
 
 For a detailed example, please refer to [https://github.com/Edgenesis/shifu/tree/main/examples/opcuaDeviceShifu](https://github.com/Edgenesis/shifu/tree/main/examples/opcuaDeviceShifu).
 
 - **spec.template.spec.volumes[].configMap**
-    - **volume**
-        - **name**<br/>name of the ConfigMap to be mounted.
-        - **configMap**<br/>name of the ConfigMap of the OPC UA certificate.
-        - **name** (string)
+  - **volume**
+    - **name**<br/>name of the ConfigMap to be mounted.
+    - **configMap**<br/>name of the ConfigMap of the OPC UA certificate.
+    - **name** (string)
 - **spec.template.spec.containers[0].volumeMounts[].name**
-    - **volumeMount**
-        - **name** (string)<br/>name of the ConfigMap to be mounted.
-        - **mountPath** (string)<br/>path of the mounted ConfigMap, which has to be `/etc/edgedevice/certificate`.
+  - **volumeMount**
+    - **name** (string)<br/>name of the ConfigMap to be mounted.
+    - **mountPath** (string)<br/>path of the mounted ConfigMap, which has to be `/etc/edgedevice/certificate`.
 
 ## Siemens PLC DeviceShifu Deployment
 
 For a detailed example, please refer to [https://github.com/Edgenesis/shifu/tree/main/examples/siemensPLCDeviceShifu](https://github.com/Edgenesis/shifu/tree/main/examples/siemensPLCDeviceShifu).
 
 - **spec.template.spec.containers[1].image**
-    - **name** (string)<br/>driver image of the Siemens PLC, which has to be `edgehub/plc-device:v0.0.1` (for now).
+  - **name** (string)<br/>driver image of the Siemens PLC, which has to be `edgehub/plc-device:v0.0.1` (for now).
 - **spec.template.spec.containers[1].env**
-    - **PLC_ADDRESS** (string)<br/>IP address of the PLC, e.g. `192.168.0.1`.
-    - **PLC_RACK** (string)<br/>RACK value of the PLC.
-    - **PLC_SLOT** (string)<br/>SLOT value of the PLC.
-    - **PLC_CONTAINER_PORT**<br/>port of the PLC drive container, which has to be `11111` (for now).
+  - **PLC_ADDRESS** (string)<br/>IP address of the PLC, e.g. `192.168.0.1`.
+  - **PLC_RACK** (string)<br/>RACK value of the PLC.
+  - **PLC_SLOT** (string)<br/>SLOT value of the PLC.
+  - **PLC_CONTAINER_PORT**<br/>port of the PLC drive container, which has to be `11111` (for now).
 
 ## RTSP DeviceShifu Deployment
 
-For a detailed example, please refer to https://github.com/Edgenesis/shifu/tree/main/examples/rtspDeviceShifu
+For a detailed example, please refer to [rtspDeviceShifu](https://github.com/Edgenesis/shifu/tree/main/examples/rtspDeviceShifu)
 
 - **spec.template.spec.containers[1].image**
-    - **name** (string)<br/>driver image for the RTSP camera, which has to be `edgehub/camera-python:v0.0.1` (for now).
+  - **name** (string)<br/>driver image for the RTSP camera, which has to be `edgehub/camera-python:v0.0.1` (for now).
 - **spec.template.spec.containers[1].env**
-    - **IP_CAMERA_ADDRESS** (string)<br/>IP address of the camera, `192.168.0.1`
-    - **IP_CAMERA_USERNAME** (string)<br/>user name of the camera RTSP stream.
-    - **IP_CAMERA_PASSWORD** (string)<br/>password for the camera RTSP stream.
-    - **IP_CAMERA_CONTAINER_PORT**
-        port of the RTSP camera driver container, which has to be `11111` (for now).
+  - **IP_CAMERA_ADDRESS** (string)<br/>IP address of the camera, `192.168.0.1`
+  - **IP_CAMERA_USERNAME** (string)<br/>user name of the camera RTSP stream.
+  - **IP_CAMERA_PASSWORD** (string)<br/>password for the camera RTSP stream.
+  - **IP_CAMERA_CONTAINER_PORT**<br/>port of the RTSP camera driver container, which has to be `11111` (for now).
diff --git a/docs/references/api/edgedevice.md b/docs/references/api/edgedevice.md
@@ -34,7 +34,7 @@ Hardware model of an EdgeDevice, e.g. `Siemens S7-1200`.
 Indicates how the EdgeDevice connects to Shifu.
 
 - **connection** (Connection) required
-    - **Connection** (string)<br/>Indicates the connection method, which has to be Ethernet (for now).
+  - **Connection** (string)<br/>Indicates the connection method, which has to be Ethernet (for now).
 
 ### Address
 
@@ -47,27 +47,60 @@ Connection address of the EdgeDevice, the format varies depending on the [protoc
 Connection protocol of the EdgeDevice.
 
 - **protocol** (Protocol) required
-    - **Protocol** (string)<br/>indicates the connection protocol, which has to be `HTTP`, `HTTPCommandline`, `MQTT`, `OPCUA`, `Socket` or `PLC4X` (for now).
+  - **Protocol** (string)<br/>indicates the connection protocol, which has to be `HTTP`, `HTTPCommandline`, `MQTT`, `OPCUA`, `Socket`, `PLC4X` or `LwM2M`(for now).
 
 ### ProtocolSettings
 
 Settings of EdgeDevice connection protocol.
 
 - **protocolSettings** (ProtocolSettings)
-    - **MQTTSetting** (MQTTSetting) 
-        - **MQTTTopic** (string)<br/>subscription of MQTT topic, e.g. `/test/test`.
-    - **OPCUASetting** (OPCUASetting)
-        - **OPCUAEndpoint** (string)<br/>server address of OPC UA, e.g. `opc.tcp://192.168.0.1:4840/test/server`.
-        - **SecurityMode** (string)<br/>message encryption mode of OPC UA, which has to be `None` (for now).
-        - **Username** (string)<br/>connection authentication username of OPC UA, e.g. `operator`.
-        - **Password** (string)<br/>connection authentication password of OPC UA, e.g. `password`.
-        - **ConnectionTimeoutInMilliseconds** (int64)<br/>requested connection milliseconds for OPC UA, e.g. `1000`.
-    - **SocketSetting** (SocketSetting)
-        - **encoding** (string)<br/>encoding of the socket connection, optionally `utf-8` or `hex`, the default value is `utf-8`.
-        - **NetworkType** (string)<br/>protocol of the socket link, which has to be `tcp` (for now).
-        - **bufferLength** (int)<br/>buffer size of the socket when transferring data, the default value is 1024.
-    - **PLC4XSetting** (PLC4XSetting)
-        - **protocol** ([Plc4xProtocol](#plc4xprotocolenum))<br/>protocol used by plc4x to connect to the device.
+  - **MQTTSetting** (MQTTSetting)
+    - **MQTTTopic** (string)<br/>subscription of MQTT topic, e.g. `/test/test`.
+
+  - **OPCUASetting** (OPCUASetting)
+    - **OPCUAEndpoint** (string)<br/>server address of OPC UA, e.g. `opc.tcp://192.168.0.1:4840/test/server`.
+    - **SecurityMode** (string)<br/>message encryption mode of OPC UA, which has to be `None` (for now).
+    - **Username** (string)<br/>connection authentication username of OPC UA, e.g. `operator`.
+    - **Password** (string)<br/>connection authentication password of OPC UA, e.g. `password`.
+    - **ConnectionTimeoutInMilliseconds** (int64)<br/>requested connection milliseconds for OPC UA, e.g. `1000`.
+
+  - **SocketSetting** (SocketSetting)
+    - **encoding** (string)<br/>encoding of the socket connection, optionally `utf-8` or `hex`, the default value is `utf-8`.
+    - **NetworkType** (string)<br/>protocol of the socket link, which has to be `tcp` (for now).
+    - **bufferLength** (int)<br/>buffer size of the socket when transferring data, the default value is 1024.
+
+  - **PLC4XSetting** (PLC4XSetting)
+    - **protocol** ([Plc4xProtocol](#plc4xprotocolenum))<br/>protocol used by plc4x to connect to the device.
+
+  - **LwM2MSetting** (LwM2MSetting)
+    - **endpointName** (string)<br/>the unique identifier for the LwM2M client, e.g. `leshan-client`.
+    - **securityMode** (string)<br/>the security mode setting for the LwM2M protocol, which can be one of the following:
+      - `None` (for no security)
+      - `DTLS` (for Datagram Transport Layer Security)
+    - **dtlsMode** (string)<br/>the DTLS mode, applicable if `securityMode` is set to `DTLS`. Options include:
+      - `PSK` (Pre-Shared Key)
+    - **cipherSuites** (array of strings)<br/>the list of DTLS cipher suites, applicable when `securityMode` is `DTLS`. The following ciphersuites are currently supported:[CipherSuites](#ciphersuitesenum)
+    - **pskIdentity** (string)<br/>the identity for the pre-shared, applicable when `dtlsMode` is set to `PSK`. Example: `hint`.
+    - **pskKey** (string)<br/>the key for the pre-shared key, applicable when `dtlsMode` is `PSK`. Example: `ABC123`.
+
+#### CipherSuites(enum)
+
+```go
+TLS_ECDHE_ECDSA_WITH_AES_128_CCM     = "TLS_ECDHE_ECDSA_WITH_AES_128_CCM"
+TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8   = "TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8"
+TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 = "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"
+TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256   = "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
+TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 = "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384"
+TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384   = "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
+TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA  = "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA"
+TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA    = "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA"
+TLS_PSK_WITH_AES_128_CCM               = "TLS_PSK_WITH_AES_128_CCM"
+TLS_PSK_WITH_AES_128_CCM_8             = "TLS_PSK_WITH_AES_128_CCM_8"
+TLS_PSK_WITH_AES_256_CCM_8             = "TLS_PSK_WITH_AES_256_CCM_8"
+TLS_PSK_WITH_AES_128_GCM_SHA256       = "TLS_PSK_WITH_AES_128_GCM_SHA256"
+TLS_PSK_WITH_AES_128_CBC_SHA256        = "TLS_PSK_WITH_AES_128_CBC_SHA256"
+TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256  = "TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256"
+```
 
 #### Plc4xProtocol(enum)
 
@@ -98,4 +131,4 @@ Current status information
 Current state of EdgeDevice.
 
 - **edgedevicephase** (EdgeDevicePhase)
-    - EdgeDevicePhase (string)<br/>State of EdgeDevice, has to be `Pending`, `Running`, `Failed` or `Unknown`.
+  - EdgeDevicePhase (string)<br/>State of EdgeDevice, has to be `Pending`, `Running`, `Failed` or `Unknown`.
diff --git a/docs/references/api/telemetryService.md b/docs/references/api/telemetryService.md
@@ -10,13 +10,13 @@ TelemetryService defines the configuration of the telemetry push service, associ
 - **apiVersion**: shifu.edgenesis.io/v1alpha1
 - **kind**: `TelemetryService`
 - **metadata**
-    - **name**<br/>Indicates the name of this telemetry service, the content corresponds to `telemetryCollectionService` in Configmap.
-    - **namespace**<br/>Indicates the namespace where the telemetry service is located, please make sure it is under the same namespace as the `configmap` file.
+  - **name**<br/>Indicates the name of this telemetry service, the content corresponds to `telemetryCollectionService` in Configmap.
+  - **namespace**<br/>Indicates the namespace where the telemetry service is located, please make sure it is under the same namespace as the `configmap` file.
 
 - **spec** ([Spec](#edgedevicespec))<br/>Describes the specification of an EdgeDevice.
-    - **type** (string)<br/>Describes the protocol of the push service.
-    - **address** (string)<br/>Describes the address of the push service.
-    - **serviceSettings** ([ServiceSettings](#servicesettings))<br/>Describes the push settings for the push service.
+  - **type** (string)<br/>Describes the protocol of the push service.
+  - **address** (string)<br/>Describes the address of the push service.
+  - **serviceSettings** ([ServiceSettings](#servicesettings))<br/>Describes the push settings for the push service.
 
 ## ServiceSettings