From 4c8dea6206d75db82192a75d9bf64d694a803868 Mon Sep 17 00:00:00 2001 From: rhoninlee Date: Thu, 18 Apr 2024 14:37:56 +0800 Subject: [PATCH 1/9] add lwM2M gateway --- docs/design/gateway/lwM2M-gateway.md | 154 +++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 docs/design/gateway/lwM2M-gateway.md diff --git a/docs/design/gateway/lwM2M-gateway.md b/docs/design/gateway/lwM2M-gateway.md new file mode 100644 index 000000000..6715b6561 --- /dev/null +++ b/docs/design/gateway/lwM2M-gateway.md @@ -0,0 +1,154 @@ +# LwM2M Gateway design + +## Why need LwM2M Gateway + +For telemetryService only support push data to the server, but for LwM2M protocol, it support both push and pull data from the device. it is hard to implement the pull data feature in the telemetryService. +So we need a gateway make deviceShifu to adapt the LwM2M protocol. to support pull data call from server and auto push data to the server. + +## Goal + +### Design Goal + +- [LwM2M protocol using v1.0.x version](https://www.openmobilealliance.org/release/LightweightM2M/V1_0-20170208-A/OMA-TS-LightweightM2M-V1_0-20170208-A.pdf). +- LwM2M protocol under UDP. +- Support using LwM2M protocol to communicate with the server. +- Support both `read` and `write` requests. +- Support Notify and Observe feature. + +### Non-Goal + +- Support LwM2M v1.1.x or later version. +- Datagram Transport Layer Security (DTLS) support. +- Over TCP or other protocol. +- Bootstrap Server. +- Support all the LwM2M Object. +- Support all the LwM2M Resource. + +## LwM2M Gateway Design + +For LwM2M Gateway, it will as a LwM2M client to connect a server and it will handle all request from the server over the LwM2M protocol. + +### Centralized Or Distributed Gateway? + +- Centralized: All device connect to the same gateway, and the gateway will connect to the server. + When a device enable the gateway feature, it will register to the gateway and the gateway will call the server to update the device info. Each device will have a unique ObjectId like `/33953` and their instruction will be a instance of the ObjectId like `/33953/1`. +- Distributed: Each device connect to a gateway, and the gateway will connect to the server. + When a device enable the gateway feature, it will create a pod to host the gateway and register to the server. Then the server will call the gateway to update the device info or get the data. + +in the current design, we will use the centralized gateway. + +### What will the gateway do? + +1. If bootStrap is enable, the gateway will get the server info from the bootStrap server. +2. Start the LwM2M Client and get all the device info from the deviceShifu. +3. Register to the server and update the device info. +4. Listen on the LwM2M default port 5683 and handle the request from the server. +5. When server enable Observe feature, the gateway will notify the server when the data changed or timeout. +6. When server send the read or write request, the gateway will call the deviceShifu to get the data or set the data. + +```mermaid +sequenceDiagram + participant ds as DeviceShifu + participant gw as Gateway + participant s as Server + participant bs as BootStrap Server + + alt bootstrap is enable + gw ->> bs: Get Server Info + bs ->> gw: Reply Server Info + end + + gw ->> s: Register + s ->> gw: Created + + note over ds,bs: read or write data + s ->> gw: Get Device Info + gw ->> ds: Get Device Info + ds ->> gw: Device Info + gw ->> s: return Device Info + + note over ds,bs: observe data + s ->> gw: observe object + gw ->> ds: Created + loop Get Device Data in a interval + gw ->> ds: Get Device Data + ds ->> gw: Get Device Data + alt data changed or timeout + gw ->> s: Notify Data + end + end + +``` + +### Protocol Specification + +```yaml +apiVersion: shifu.edgenesis.io/v1alpha1 +kind: ShifuGateWay +metadata: + name: LwM2M-gateway + namespace: shifu-services +spec: + address: 0.0.0.0:5683 + gatewaySettings: + LwM2MSetting: + BootstrapServer: "http://bootstrap-server:8080" + EndpointName: "LwM2M-gateway" +--- +apiVersion: shifu.edgenesis.io/v1alpha1 +kind: ShifuGateWayConfig +metadata: + name: LwM2M-device1 + namespace: shifu-services +spec: + gatewayName: LwM2M-gateway + instructions: + - EdgeDeviceName: device1 + name: object1 + accessMode: read/write/readwrite + - EdgeDeviceName: device1 + name: object2 + accessMode: read/write/readwrite +``` + +When Deploy ShifuGateWay, controller will create a deployment and service for the gateway. and when deploy ShifuGateWayConfig, controller will patch the gateway to update the device info. + +Here is the example of the deployment and service: +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: LwM2M-gateway + namespace: shifu-services +spec: + replicas: 1 + selector: + matchLabels: + app: LwM2M-gateway + template: + metadata: + labels: + app: LwM2M-gateway + spec: + containers: + - name: LwM2M-gateway + image: LwM2M-gateway:latest + ports: + - containerPort: 5683 + type: UDP +... +--- +apiVersion: v1 +kind: Service +metadata: + name: LwM2M-gateway + namespace: shifu-services +spec: + selector: + app: LwM2M-gateway + ports: + - protocol: UDP + port: 5683 + targetPort: 5683 + type: LoadBalancer +``` From 2dff1f219ed040e32c88477c3980a0e253363dd9 Mon Sep 17 00:00:00 2001 From: rhoninlee Date: Fri, 19 Apr 2024 13:13:52 +0800 Subject: [PATCH 2/9] add flow diagram --- docs/design/gateway/lwM2M-gateway.md | 45 ++++++++++++++++++++++++---- 1 file changed, 39 insertions(+), 6 deletions(-) diff --git a/docs/design/gateway/lwM2M-gateway.md b/docs/design/gateway/lwM2M-gateway.md index 6715b6561..838f36911 100644 --- a/docs/design/gateway/lwM2M-gateway.md +++ b/docs/design/gateway/lwM2M-gateway.md @@ -28,14 +28,47 @@ So we need a gateway make deviceShifu to adapt the LwM2M protocol. to support pu For LwM2M Gateway, it will as a LwM2M client to connect a server and it will handle all request from the server over the LwM2M protocol. -### Centralized Or Distributed Gateway? -- Centralized: All device connect to the same gateway, and the gateway will connect to the server. - When a device enable the gateway feature, it will register to the gateway and the gateway will call the server to update the device info. Each device will have a unique ObjectId like `/33953` and their instruction will be a instance of the ObjectId like `/33953/1`. -- Distributed: Each device connect to a gateway, and the gateway will connect to the server. - When a device enable the gateway feature, it will create a pod to host the gateway and register to the server. Then the server will call the gateway to update the device info or get the data. +When a device enable the gateway feature, it will register to the gateway and the gateway will call the server to update the device info. Each device will have a unique ObjectId like `/33953` and their. +instruction will be a instance of the ObjectId like `/33953/1`. -in the current design, we will use the centralized gateway. +```mermaid +flowchart BT +s1[Server] +s2[Server] + +subgraph EdgeNode + subgraph Shifu + gw1[LwM2M Gateway] + gw2[LwM2M Gateway] + + ds1[deviceShifu-lwM2M] + ds2[deviceShifu-MQTT] + ds3[deviceShifu-HTTP] + + end +end + +d1[Device] +d2[Device] +d3[Device] + + + +d1 -->|lwM2M| ds1 -->|HTTP| gw1 +ds2 -->|MQTT| gw1 +d2 -->|MQTT| ds2 -->|HTTP| gw2 +d3 -->|HTTP| ds3 -->|HTTP| gw2 + + +gw1 <-->|lwM2M| s1 +gw2 <-->|lwM2M| s2 + + + + + +``` ### What will the gateway do? From ba8c38d5d0df2f4edf3059dd8ab2e3f5f2ea7230 Mon Sep 17 00:00:00 2001 From: rhoninlee Date: Tue, 8 Oct 2024 15:55:17 +0800 Subject: [PATCH 3/9] update gateway design --- docs/design/gateway/lwM2M-gateway.md | 163 +++++++++++++-------------- 1 file changed, 76 insertions(+), 87 deletions(-) diff --git a/docs/design/gateway/lwM2M-gateway.md b/docs/design/gateway/lwM2M-gateway.md index 838f36911..92dd68d55 100644 --- a/docs/design/gateway/lwM2M-gateway.md +++ b/docs/design/gateway/lwM2M-gateway.md @@ -3,6 +3,7 @@ ## Why need LwM2M Gateway For telemetryService only support push data to the server, but for LwM2M protocol, it support both push and pull data from the device. it is hard to implement the pull data feature in the telemetryService. + So we need a gateway make deviceShifu to adapt the LwM2M protocol. to support pull data call from server and auto push data to the server. ## Goal @@ -11,6 +12,7 @@ So we need a gateway make deviceShifu to adapt the LwM2M protocol. to support pu - [LwM2M protocol using v1.0.x version](https://www.openmobilealliance.org/release/LightweightM2M/V1_0-20170208-A/OMA-TS-LightweightM2M-V1_0-20170208-A.pdf). - LwM2M protocol under UDP. +- Datagram Transport Layer Security (DTLS) support. - Support using LwM2M protocol to communicate with the server. - Support both `read` and `write` requests. - Support Notify and Observe feature. @@ -18,7 +20,6 @@ So we need a gateway make deviceShifu to adapt the LwM2M protocol. to support pu ### Non-Goal - Support LwM2M v1.1.x or later version. -- Datagram Transport Layer Security (DTLS) support. - Over TCP or other protocol. - Bootstrap Server. - Support all the LwM2M Object. @@ -28,46 +29,39 @@ So we need a gateway make deviceShifu to adapt the LwM2M protocol. to support pu For LwM2M Gateway, it will as a LwM2M client to connect a server and it will handle all request from the server over the LwM2M protocol. - When a device enable the gateway feature, it will register to the gateway and the gateway will call the server to update the device info. Each device will have a unique ObjectId like `/33953` and their. instruction will be a instance of the ObjectId like `/33953/1`. ```mermaid flowchart BT -s1[Server] -s2[Server] + +ls[lwm2m-server] subgraph EdgeNode subgraph Shifu - gw1[LwM2M Gateway] - gw2[LwM2M Gateway] - - ds1[deviceShifu-lwM2M] - ds2[deviceShifu-MQTT] - ds3[deviceShifu-HTTP] - + subgraph ds1[deviceshifu-lwM2M] + dsh[deviceshifu-http] + gl1[lwm2m-gateway] + dsh <-->|HTTP| gl1 + end + subgraph ds2[deviceshifu-MQTT] + dsm[deviceshifu-MQTT] + gl2[lwm2m-gateway] + dsm <-->|HTTP| gl2 + end end end -d1[Device] -d2[Device] -d3[Device] - - - -d1 -->|lwM2M| ds1 -->|HTTP| gw1 -ds2 -->|MQTT| gw1 -d2 -->|MQTT| ds2 -->|HTTP| gw2 -d3 -->|HTTP| ds3 -->|HTTP| gw2 - - -gw1 <-->|lwM2M| s1 -gw2 <-->|lwM2M| s2 - +dh[device-http] +dm[device-mqtt] +dh -->|HTTP| dsh +gl1 -->|lwM2M| ls +dm -->|MQTT| dsm +gl2 -->|lwM2M| ls ``` ### What will the gateway do? @@ -86,7 +80,7 @@ sequenceDiagram participant s as Server participant bs as BootStrap Server - alt bootstrap is enable + opt bootstrap is enable gw ->> bs: Get Server Info bs ->> gw: Reply Server Info end @@ -113,75 +107,70 @@ sequenceDiagram ``` -### Protocol Specification +#### Detail Design + +##### Read Request + +When the server send the read request to the gateway, the gateway will call the deviceShifu instruction with `GET` method. +The gateway will get the data from the deviceShifu and return the data to the server. + +##### Write Request + +When the server send the write request to the gateway, the gateway will call the deviceShifu instruction with `PUT` method with the data in the request body. and return with changed status code to server + +##### Execute Request + +When the server send the execute request to the gateway, the gateway will call the deviceShifu instruction with `POST` method without request body. + +##### Observe and Notify + +When the server enable the observe feature, the gateway will get the data from the deviceShifu in a interval and notify the server when the data changed or timeout. + +### Gateway Configuration + +To connect to the server, the gateway need some configuration like the server address, the endpoint name, the security mode, and the psk key in Edgedevice yaml file. the LwM2MSettings is same with the deviceShifu LwM2MSettings. ```yaml apiVersion: shifu.edgenesis.io/v1alpha1 -kind: ShifuGateWay +kind: EdgeDevice metadata: - name: LwM2M-gateway - namespace: shifu-services + name: edgedevice + namespace: devices spec: - address: 0.0.0.0:5683 - gatewaySettings: - LwM2MSetting: - BootstrapServer: "http://bootstrap-server:8080" - EndpointName: "LwM2M-gateway" ---- -apiVersion: shifu.edgenesis.io/v1alpha1 -kind: ShifuGateWayConfig -metadata: - name: LwM2M-device1 - namespace: shifu-services -spec: - gatewayName: LwM2M-gateway - instructions: - - EdgeDeviceName: device1 - name: object1 - accessMode: read/write/readwrite - - EdgeDeviceName: device1 - name: object2 - accessMode: read/write/readwrite + gatewaySettings: + protocol: lwm2m + address: leshan.eclipseprojects.io:5684 + LwM2MSettings: + endpointName: lwm2m-device + securityMode: DTLS + dtlsMode: PSK + cipherSuites: + - TLS_PSK_WITH_AES_128_CCM_8 + pskIdentity: lwm2m-hint + pskKey: ABC123 ``` -When Deploy ShifuGateWay, controller will create a deployment and service for the gateway. and when deploy ShifuGateWayConfig, controller will patch the gateway to update the device info. +To mapping the LwM2M Object and Resource to the deviceShifu, we add a field `gatewayPropertyList` for instruction in the deviceShifu ConfigMap. Which mean the instruction will forward to the resource in the LwM2M protocol. ObjectId is the LwM2M Object Id and DataType is the LwM2M Resource Type. + +Data Type support: `int`, `float`, `string`, `bool`. By default, the data type is `string`. -Here is the example of the deployment and service: ```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: LwM2M-gateway - namespace: shifu-services -spec: - replicas: 1 - selector: - matchLabels: - app: LwM2M-gateway - template: - metadata: - labels: - app: LwM2M-gateway - spec: - containers: - - name: LwM2M-gateway - image: LwM2M-gateway:latest - ports: - - containerPort: 5683 - type: UDP -... ---- apiVersion: v1 -kind: Service +kind: ConfigMap metadata: - name: LwM2M-gateway - namespace: shifu-services -spec: - selector: - app: LwM2M-gateway - ports: - - protocol: UDP - port: 5683 - targetPort: 5683 - type: LoadBalancer + name: configmap + namespace: deviceshifu +data: + instructions: | + instructions: + instruction1: + gatewayPropertyList: + ObjectId: 1/0/0 + DataType: int ``` + +### Test Plan + +- Using [Leshan](https://github.com/eclipse-leshan/leshan) as the LwM2M server, connect a HTTP device to the server. +- Normal mode test: read and write data and execute from device. +- Observe mode test: read and write data from device, and check the data change or timeout. \ No newline at end of file From 5622b6db7e8ec799f4f8ce9b0e181d5443d916fe Mon Sep 17 00:00:00 2001 From: rhoninlee Date: Wed, 9 Oct 2024 14:22:31 +0800 Subject: [PATCH 4/9] ensure what is server --- docs/design/gateway/lwM2M-gateway.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/design/gateway/lwM2M-gateway.md b/docs/design/gateway/lwM2M-gateway.md index 92dd68d55..8f788f962 100644 --- a/docs/design/gateway/lwM2M-gateway.md +++ b/docs/design/gateway/lwM2M-gateway.md @@ -2,7 +2,7 @@ ## Why need LwM2M Gateway -For telemetryService only support push data to the server, but for LwM2M protocol, it support both push and pull data from the device. it is hard to implement the pull data feature in the telemetryService. +Telemetry service which serve push data from device to the data server, it didn't have the feature to pull data from device the to the data server, while LwM2M normally needs to pull data from the device to the data server. in order to support this, a LwM2M Gateway is required to do this job. So we need a gateway make deviceShifu to adapt the LwM2M protocol. to support pull data call from server and auto push data to the server. @@ -27,7 +27,7 @@ So we need a gateway make deviceShifu to adapt the LwM2M protocol. to support pu ## LwM2M Gateway Design -For LwM2M Gateway, it will as a LwM2M client to connect a server and it will handle all request from the server over the LwM2M protocol. +For the LwM2M Gateway, it will use an LwM2M client to connect server, and it will handle all requests from the server over the LwM2M protocol. When a device enable the gateway feature, it will register to the gateway and the gateway will call the server to update the device info. Each device will have a unique ObjectId like `/33953` and their. instruction will be a instance of the ObjectId like `/33953/1`. From 3e13815bea3b0ccc492356c9685d51293c5121fb Mon Sep 17 00:00:00 2001 From: rhoninlee Date: Thu, 10 Oct 2024 14:14:41 +0800 Subject: [PATCH 5/9] update design with latest code --- docs/design/gateway/lwM2M-gateway.md | 70 ++++++++++++++-------------- 1 file changed, 36 insertions(+), 34 deletions(-) diff --git a/docs/design/gateway/lwM2M-gateway.md b/docs/design/gateway/lwM2M-gateway.md index 8f788f962..b17d72f8a 100644 --- a/docs/design/gateway/lwM2M-gateway.md +++ b/docs/design/gateway/lwM2M-gateway.md @@ -27,26 +27,29 @@ So we need a gateway make deviceShifu to adapt the LwM2M protocol. to support pu ## LwM2M Gateway Design -For the LwM2M Gateway, it will use an LwM2M client to connect server, and it will handle all requests from the server over the LwM2M protocol. +For the LwM2M Gateway will include two parts, the LwM2M Client connect to the LwM2M Server and the deviceShifu connect to the deviceShifu. -When a device enable the gateway feature, it will register to the gateway and the gateway will call the server to update the device info. Each device will have a unique ObjectId like `/33953` and their. -instruction will be a instance of the ObjectId like `/33953/1`. +When deviceShifu enable gateway feature, gateway will initialize the LwM2M client's object map. Then create a LwM2M Client to connect to the LwM2M Server with the configuration in the EdgeDevice yaml file, and register to the server with object map. + +Then, the gateway will handle the request from the server by calling deviceShifu instruction with the LwM2M Object and Resource. + +Before the gateway stop, it will deregister from the server and stop the LwM2M Client. ```mermaid flowchart BT -ls[lwm2m-server] +ls[LwM2M-server] subgraph EdgeNode subgraph Shifu - subgraph ds1[deviceshifu-lwM2M] + subgraph ds1[deviceshifu-LwM2M] dsh[deviceshifu-http] - gl1[lwm2m-gateway] + gl1[LwM2M-gateway] dsh <-->|HTTP| gl1 end subgraph ds2[deviceshifu-MQTT] dsm[deviceshifu-MQTT] - gl2[lwm2m-gateway] + gl2[LwM2M-gateway] dsm <-->|HTTP| gl2 end end @@ -58,43 +61,37 @@ dm[device-mqtt] dh -->|HTTP| dsh -gl1 -->|lwM2M| ls +gl1 -->|LwM2M| ls dm -->|MQTT| dsm -gl2 -->|lwM2M| ls +gl2 -->|LwM2M| ls ``` ### What will the gateway do? -1. If bootStrap is enable, the gateway will get the server info from the bootStrap server. -2. Start the LwM2M Client and get all the device info from the deviceShifu. -3. Register to the server and update the device info. -4. Listen on the LwM2M default port 5683 and handle the request from the server. -5. When server enable Observe feature, the gateway will notify the server when the data changed or timeout. -6. When server send the read or write request, the gateway will call the deviceShifu to get the data or set the data. +1. Start the LwM2M Client and get all the device info from the deviceShifu. +2. Register to the server and update the device info. +3. handle the request from the server. +4. When server enable Observe feature, the gateway will notify the server when the data changed or timeout. +5. When server send the read or write request, the gateway will call the deviceShifu to get the data or set the data. +6. Before gateway shutdown, deregister from the server and stop the LwM2M Client. ```mermaid sequenceDiagram participant ds as DeviceShifu participant gw as Gateway participant s as Server - participant bs as BootStrap Server - - opt bootstrap is enable - gw ->> bs: Get Server Info - bs ->> gw: Reply Server Info - end gw ->> s: Register s ->> gw: Created - note over ds,bs: read or write data + note over ds: read or write data s ->> gw: Get Device Info gw ->> ds: Get Device Info ds ->> gw: Device Info gw ->> s: return Device Info - note over ds,bs: observe data + note over ds: observe data s ->> gw: observe object gw ->> ds: Created loop Get Device Data in a interval @@ -104,31 +101,30 @@ sequenceDiagram gw ->> s: Notify Data end end - ``` -#### Detail Design +### Detail Design -##### Read Request +#### Read Request When the server send the read request to the gateway, the gateway will call the deviceShifu instruction with `GET` method. The gateway will get the data from the deviceShifu and return the data to the server. -##### Write Request +#### Write Request When the server send the write request to the gateway, the gateway will call the deviceShifu instruction with `PUT` method with the data in the request body. and return with changed status code to server -##### Execute Request +#### Execute Request When the server send the execute request to the gateway, the gateway will call the deviceShifu instruction with `POST` method without request body. -##### Observe and Notify +#### Observe and Notify When the server enable the observe feature, the gateway will get the data from the deviceShifu in a interval and notify the server when the data changed or timeout. ### Gateway Configuration -To connect to the server, the gateway need some configuration like the server address, the endpoint name, the security mode, and the psk key in Edgedevice yaml file. the LwM2MSettings is same with the deviceShifu LwM2MSettings. +To connect to the server, the gateway need some configuration like the server address, the endpoint name, the security mode, and the psk key in Edgedevice yaml file. the LwM2MSetting is same with the deviceShifu LwM2MSetting. ```yaml apiVersion: shifu.edgenesis.io/v1alpha1 @@ -137,16 +133,22 @@ metadata: name: edgedevice namespace: devices spec: + sku: "LwM2M Device" + connection: Ethernet + address: -- + protocol: LwM2M + protocolSettings: + LwM2MSettings: gatewaySettings: - protocol: lwm2m + protocol: LwM2M address: leshan.eclipseprojects.io:5684 - LwM2MSettings: - endpointName: lwm2m-device + LwM2MSetting: + endpointName: LwM2M-device securityMode: DTLS dtlsMode: PSK cipherSuites: - TLS_PSK_WITH_AES_128_CCM_8 - pskIdentity: lwm2m-hint + pskIdentity: LwM2M-hint pskKey: ABC123 ``` From bbcb8f17777edc4cb69365956a66c879b447e327 Mon Sep 17 00:00:00 2001 From: rhoninlee Date: Thu, 10 Oct 2024 14:19:11 +0800 Subject: [PATCH 6/9] add timeout and disconnect action --- docs/design/gateway/lwM2M-gateway.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/design/gateway/lwM2M-gateway.md b/docs/design/gateway/lwM2M-gateway.md index b17d72f8a..465d861d1 100644 --- a/docs/design/gateway/lwM2M-gateway.md +++ b/docs/design/gateway/lwM2M-gateway.md @@ -75,6 +75,8 @@ gl2 -->|LwM2M| ls 4. When server enable Observe feature, the gateway will notify the server when the data changed or timeout. 5. When server send the read or write request, the gateway will call the deviceShifu to get the data or set the data. 6. Before gateway shutdown, deregister from the server and stop the LwM2M Client. +7. When server disconnect, the gateway will try to reconnect to the server and register again. +8. When call deviceShifu instruction timeout, the gateway will return the error message to the server. ```mermaid sequenceDiagram @@ -139,6 +141,7 @@ spec: protocol: LwM2M protocolSettings: LwM2MSettings: + ... gatewaySettings: protocol: LwM2M address: leshan.eclipseprojects.io:5684 From 3b1aef29a9235904df67eac34d3f848562db8527 Mon Sep 17 00:00:00 2001 From: rhoninlee Date: Thu, 10 Oct 2024 17:43:31 +0800 Subject: [PATCH 7/9] improve doc --- docs/design/gateway/lwM2M-gateway.md | 122 +++++++++++++++++---------- 1 file changed, 78 insertions(+), 44 deletions(-) diff --git a/docs/design/gateway/lwM2M-gateway.md b/docs/design/gateway/lwM2M-gateway.md index 465d861d1..daa0df3b7 100644 --- a/docs/design/gateway/lwM2M-gateway.md +++ b/docs/design/gateway/lwM2M-gateway.md @@ -2,7 +2,7 @@ ## Why need LwM2M Gateway -Telemetry service which serve push data from device to the data server, it didn't have the feature to pull data from device the to the data server, while LwM2M normally needs to pull data from the device to the data server. in order to support this, a LwM2M Gateway is required to do this job. +Telemetry service which serve push data from device to the data server, it didn't have the feature to pull data from the device and post data from cloud to device, while LwM2M normally needs to do it. In order to support this, a LwM2M Gateway is required to do this job. So we need a gateway make deviceShifu to adapt the LwM2M protocol. to support pull data call from server and auto push data to the server. @@ -10,14 +10,26 @@ So we need a gateway make deviceShifu to adapt the LwM2M protocol. to support pu ### Design Goal -- [LwM2M protocol using v1.0.x version](https://www.openmobilealliance.org/release/LightweightM2M/V1_0-20170208-A/OMA-TS-LightweightM2M-V1_0-20170208-A.pdf). +- make device as a LwM2M device registered to the LwM2M server. +- Provide a way to connect deviceShifu to the LwM2M server. +- LwM2M Server can read, write and execute the deviceShifu instruction by the LwM2M protocol. + +### Non-Goal + +- Support all features in the LwM2M protocol. +- According [standard of OMA](HTTPs://github.com/OpenMobileAlliance/lwm2m-registry) recognize and generate the LwM2M Object and Resource. +- Bootstrap Server. + +### Features + +- [LwM2M protocol using v1.0.x version](HTTPs://www.openmobilealliance.org/release/LightweightM2M/V1_0-20170208-A/OMA-TS-LightweightM2M-V1_0-20170208-A.pdf). - LwM2M protocol under UDP. - Datagram Transport Layer Security (DTLS) support. - Support using LwM2M protocol to communicate with the server. -- Support both `read` and `write` requests. +- Support `read`, `write` and `Execute` requests. - Support Notify and Observe feature. -### Non-Goal +### Unsupported Features - Support LwM2M v1.1.x or later version. - Over TCP or other protocol. @@ -27,13 +39,9 @@ So we need a gateway make deviceShifu to adapt the LwM2M protocol. to support pu ## LwM2M Gateway Design -For the LwM2M Gateway will include two parts, the LwM2M Client connect to the LwM2M Server and the deviceShifu connect to the deviceShifu. - -When deviceShifu enable gateway feature, gateway will initialize the LwM2M client's object map. Then create a LwM2M Client to connect to the LwM2M Server with the configuration in the EdgeDevice yaml file, and register to the server with object map. - -Then, the gateway will handle the request from the server by calling deviceShifu instruction with the LwM2M Object and Resource. +The LwM2M Gateway includes two parts, the LwM2M client connect to the LwM2M Server and the HTTP client connect to the deviceShifu. -Before the gateway stop, it will deregister from the server and stop the LwM2M Client. +When the server send the read or write request to the gateway, the gateway will call the deviceShifu instruction to get the data or set the data. When the server enable the Observe feature, the gateway will get the data from the deviceShifu in a interval. When the data changed or timeout, the gateway will notify the server with the changed data. ```mermaid flowchart BT @@ -42,32 +50,41 @@ ls[LwM2M-server] subgraph EdgeNode subgraph Shifu - subgraph ds1[deviceshifu-LwM2M] - dsh[deviceshifu-http] + subgraph ds1[deviceShifu-HTTP] + dsh[deviceShifu-HTTP] gl1[LwM2M-gateway] dsh <-->|HTTP| gl1 end - subgraph ds2[deviceshifu-MQTT] - dsm[deviceshifu-MQTT] + subgraph ds2[deviceShifu-MQTT] + dsm[deviceShifu-MQTT] gl2[LwM2M-gateway] dsm <-->|HTTP| gl2 end + subgraph ds3[deviceShifu-LwM2M] + dsl[deviceShifu-LwM2M] + gl3[LwM2M-gateway] + dsl <-->|HTTP| gl3 + end end end -dh[device-http] -dm[device-mqtt] +dh[device-HTTP] +dm[device-MQTT] +dl[device-LwM2M] dh -->|HTTP| dsh gl1 -->|LwM2M| ls dm -->|MQTT| dsm -gl2 -->|LwM2M| ls +gl2 -->|LwM2M| ls + +dl -->|LwM2M| dsl +gl3 -->|LwM2M| ls ``` -### What will the gateway do? +### What does the gateway will do? 1. Start the LwM2M Client and get all the device info from the deviceShifu. 2. Register to the server and update the device info. @@ -80,29 +97,46 @@ gl2 -->|LwM2M| ls ```mermaid sequenceDiagram - participant ds as DeviceShifu - participant gw as Gateway - participant s as Server - - gw ->> s: Register - s ->> gw: Created - - note over ds: read or write data - s ->> gw: Get Device Info - gw ->> ds: Get Device Info - ds ->> gw: Device Info - gw ->> s: return Device Info - - note over ds: observe data - s ->> gw: observe object - gw ->> ds: Created - loop Get Device Data in a interval - gw ->> ds: Get Device Data - ds ->> gw: Get Device Data - alt data changed or timeout - gw ->> s: Notify Data - end - end + participant ds as DeviceShifu + participant gw as Gateway + participant s as Server + + note over ds,s: Register + gw ->> s: Register + s ->> gw: Created + + note over ds,s: Read Data + s ->> gw: [LwM2M GET /ObjectID] Read Data + gw ->> ds: [HTTP GET /Instruction] Get Data + ds ->> gw: [HTTP Response] Data + gw ->> s: [LwM2M Response] Data + + note over ds,s: Write Data + s ->> gw: [LwM2M PUT /ObjectID] Write Data + gw ->> ds: [HTTP PUT /Instruction] Set Data + ds ->> gw: [HTTP Response] OK + gw ->> s: [LwM2M Response] Changed + + note over ds,s: Execute + s ->> gw: [LwM2M POST /ObjectID] Execute + gw ->> ds: [HTTP POST /Instruction] Execute + ds ->> gw: [HTTP Response] OK + gw ->> s: [LwM2M Response] OK + + note over ds,s: observe data + s ->> gw: [LwM2M GET /ObjectID] Enable Observe Object + gw ->> s: [LwM2M] Created + loop Get Device Data in a interval + gw ->> ds: [HTTP GET /Instruction] Get Device Data + ds ->> gw: [HTTP Response] Get Device Data + alt data changed or timeout + gw ->> s: [LwM2M Response] New Data + end + end + + note over ds,s: de-register + gw ->> s: [LwM2M /Delete]De-register + s ->> gw: [LwM2M Response] Deleted ``` ### Detail Design @@ -122,7 +156,7 @@ When the server send the execute request to the gateway, the gateway will call t #### Observe and Notify -When the server enable the observe feature, the gateway will get the data from the deviceShifu in a interval and notify the server when the data changed or timeout. +When the server enable the observe feature, the gateway will get the data from the deviceShifu in a interval. When the data changed or timeout, the gateway will notify the server with the changed data. ### Gateway Configuration @@ -164,7 +198,7 @@ apiVersion: v1 kind: ConfigMap metadata: name: configmap - namespace: deviceshifu + namespace: deviceShifu data: instructions: | instructions: @@ -176,6 +210,6 @@ data: ### Test Plan -- Using [Leshan](https://github.com/eclipse-leshan/leshan) as the LwM2M server, connect a HTTP device to the server. +- Using [Leshan](HTTPs://github.com/eclipse-leshan/leshan) as the LwM2M server, connect a HTTP device to the server. - Normal mode test: read and write data and execute from device. - Observe mode test: read and write data from device, and check the data change or timeout. \ No newline at end of file From ee1dca5973c2dcab51d511492ed2612516082d92 Mon Sep 17 00:00:00 2001 From: rhoninlee Date: Thu, 10 Oct 2024 18:58:05 +0800 Subject: [PATCH 8/9] fix typo and grammar --- docs/design/gateway/lwM2M-gateway.md | 76 +++++++++++++--------------- 1 file changed, 36 insertions(+), 40 deletions(-) diff --git a/docs/design/gateway/lwM2M-gateway.md b/docs/design/gateway/lwM2M-gateway.md index daa0df3b7..11d5549f8 100644 --- a/docs/design/gateway/lwM2M-gateway.md +++ b/docs/design/gateway/lwM2M-gateway.md @@ -2,46 +2,43 @@ ## Why need LwM2M Gateway -Telemetry service which serve push data from device to the data server, it didn't have the feature to pull data from the device and post data from cloud to device, while LwM2M normally needs to do it. In order to support this, a LwM2M Gateway is required to do this job. - -So we need a gateway make deviceShifu to adapt the LwM2M protocol. to support pull data call from server and auto push data to the server. +A telemetry service typically pushes data from devices to a data server but does not have the capability to pull data from the device or post data from the cloud to the device. LwM2M (Lightweight Machine to Machine) protocol, however, usually requires both these features. To support this, an LwM2M Gateway is necessary to enable the deviceShifu to adapt to the LwM2M protocol, supporting pull data calls from the server and auto-pushing data to the server. ## Goal ### Design Goal -- make device as a LwM2M device registered to the LwM2M server. -- Provide a way to connect deviceShifu to the LwM2M server. -- LwM2M Server can read, write and execute the deviceShifu instruction by the LwM2M protocol. +- Enable the device to act as an LwM2M device registered with the LwM2M server. +- Provide a method to connect deviceShifu to the LwM2M server. +- Allow the LwM2M server to read, write, and execute instructions on deviceShifu via the LwM2M protocol. ### Non-Goal -- Support all features in the LwM2M protocol. -- According [standard of OMA](HTTPs://github.com/OpenMobileAlliance/lwm2m-registry) recognize and generate the LwM2M Object and Resource. -- Bootstrap Server. +- Support for all features in the LwM2M protocol. +- Automatic recognition and generation of LwM2M Objects and Resources according to the [OMA Standard](https://github.com/OpenMobileAlliance/lwm2m-registry). ### Features -- [LwM2M protocol using v1.0.x version](HTTPs://www.openmobilealliance.org/release/LightweightM2M/V1_0-20170208-A/OMA-TS-LightweightM2M-V1_0-20170208-A.pdf). -- LwM2M protocol under UDP. +- Support for [LwM2M protocol v1.0.x](https://www.openmobilealliance.org/release/LightweightM2M/V1_0-20170208-A/OMA-TS-LightweightM2M-V1_0-20170208-A.pdf). +- LwM2M protocol over UDP. - Datagram Transport Layer Security (DTLS) support. -- Support using LwM2M protocol to communicate with the server. -- Support `read`, `write` and `Execute` requests. +- Support for LwM2M protocol communication with the server. +- Support for `read`, `write` and `Execute` requests. - Support Notify and Observe feature. ### Unsupported Features -- Support LwM2M v1.1.x or later version. -- Over TCP or other protocol. -- Bootstrap Server. -- Support all the LwM2M Object. -- Support all the LwM2M Resource. +- Support for LwM2M v1.1.x or later. +- Support over TCP or other protocols. +- Bootstrap server. +- Support for all LwM2M Objects. +- Support for all LwM2M Resources. ## LwM2M Gateway Design -The LwM2M Gateway includes two parts, the LwM2M client connect to the LwM2M Server and the HTTP client connect to the deviceShifu. +The LwM2M Gateway consists of two main components: an LwM2M client that connects to the LwM2M server and an HTTP client that connects to deviceShifu. -When the server send the read or write request to the gateway, the gateway will call the deviceShifu instruction to get the data or set the data. When the server enable the Observe feature, the gateway will get the data from the deviceShifu in a interval. When the data changed or timeout, the gateway will notify the server with the changed data. +When the server sends a read or write request to the gateway, the gateway calls the deviceShifu instructions to either retrieve or set the data. If the server enables the Observe feature, the gateway regularly collects data from the deviceShifu. If the data changes or a timeout occurs, the gateway notifies the server with the updated data. ```mermaid flowchart BT @@ -84,16 +81,16 @@ dl -->|LwM2M| dsl gl3 -->|LwM2M| ls ``` -### What does the gateway will do? +### What Does the Gateway Do? -1. Start the LwM2M Client and get all the device info from the deviceShifu. -2. Register to the server and update the device info. -3. handle the request from the server. -4. When server enable Observe feature, the gateway will notify the server when the data changed or timeout. -5. When server send the read or write request, the gateway will call the deviceShifu to get the data or set the data. -6. Before gateway shutdown, deregister from the server and stop the LwM2M Client. -7. When server disconnect, the gateway will try to reconnect to the server and register again. -8. When call deviceShifu instruction timeout, the gateway will return the error message to the server. +1. Start the LwM2M client and obtain all device information from deviceShifu. +2. Register the device with the server and update the device information. +3. Handle requests from the server. +4. If the server enables the Observe feature, notify the server when data changes or a timeout occurs. +5. Handle read or write requests by calling deviceShifu to get or set the data. +6. Before shutting down, deregister from the server and stop the LwM2M client. +7. If the server disconnects, the gateway will attempt to reconnect and re-register. +8. If a deviceShifu instruction times out, the gateway will return an error message to the server. ```mermaid sequenceDiagram @@ -143,24 +140,23 @@ sequenceDiagram #### Read Request -When the server send the read request to the gateway, the gateway will call the deviceShifu instruction with `GET` method. -The gateway will get the data from the deviceShifu and return the data to the server. +When the server sends a read request, the gateway will call the deviceShifu instruction using the `GET` method. The gateway retrieves the data from deviceShifu and returns it to the server. #### Write Request -When the server send the write request to the gateway, the gateway will call the deviceShifu instruction with `PUT` method with the data in the request body. and return with changed status code to server +When the server sends a write request, the gateway will call the deviceShifu instruction using the `PUT` method with the data provided in the request body and return a changed status code to the server. #### Execute Request -When the server send the execute request to the gateway, the gateway will call the deviceShifu instruction with `POST` method without request body. +When the server sends an execute request, the gateway will call the deviceShifu instruction using the `POST` method without a request body. #### Observe and Notify -When the server enable the observe feature, the gateway will get the data from the deviceShifu in a interval. When the data changed or timeout, the gateway will notify the server with the changed data. +When the server enables the Observe feature, the gateway will collect data from deviceShifu at regular intervals. If the data changes or a timeout occurs, the gateway will notify the server with the updated data. ### Gateway Configuration -To connect to the server, the gateway need some configuration like the server address, the endpoint name, the security mode, and the psk key in Edgedevice yaml file. the LwM2MSetting is same with the deviceShifu LwM2MSetting. +To connect to the server, the gateway requires configuration details such as the server address, endpoint name, security mode, and PSK key in the EdgeDevice YAML file. The LwM2MSettings are the same as those in the deviceShifu LwM2MSettings. ```yaml apiVersion: shifu.edgenesis.io/v1alpha1 @@ -189,9 +185,9 @@ spec: pskKey: ABC123 ``` -To mapping the LwM2M Object and Resource to the deviceShifu, we add a field `gatewayPropertyList` for instruction in the deviceShifu ConfigMap. Which mean the instruction will forward to the resource in the LwM2M protocol. ObjectId is the LwM2M Object Id and DataType is the LwM2M Resource Type. +To map the LwM2M Object and Resource to deviceShifu, we add a `gatewayPropertyList` field for instructions in the deviceShifu ConfigMap. This indicates that the instruction will forward to the LwM2M protocol resource. The ObjectId represents the LwM2M Object Id, and DataType represents the LwM2M Resource Type. -Data Type support: `int`, `float`, `string`, `bool`. By default, the data type is `string`. +Supported Data Types: `int`, `float`, `string`, `bool`. By default, the data type is `string`. ```yaml apiVersion: v1 @@ -210,6 +206,6 @@ data: ### Test Plan -- Using [Leshan](HTTPs://github.com/eclipse-leshan/leshan) as the LwM2M server, connect a HTTP device to the server. -- Normal mode test: read and write data and execute from device. -- Observe mode test: read and write data from device, and check the data change or timeout. \ No newline at end of file +- Use [Leshan](HTTPs://github.com/eclipse-leshan/leshan) as the LwM2M server to connect an HTTP device to the server. +- Normal Mode Test: Perform read, write, and execute operations on the device via the LwM2M Gateway. +- Observe Mode Test: Enable the observe mode from the server, read and write data from the device, and validate that the gateway correctly notifies the server when data changes or a timeout occurs. \ No newline at end of file From b1825d31c9c9f275fde4d67aa8eb5c9b8bc9c6be Mon Sep 17 00:00:00 2001 From: rhoninlee Date: Fri, 11 Oct 2024 11:42:13 +0800 Subject: [PATCH 9/9] handle comment --- docs/design/gateway/lwM2M-gateway.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/design/gateway/lwM2M-gateway.md b/docs/design/gateway/lwM2M-gateway.md index 11d5549f8..00dc9f2a7 100644 --- a/docs/design/gateway/lwM2M-gateway.md +++ b/docs/design/gateway/lwM2M-gateway.md @@ -2,7 +2,7 @@ ## Why need LwM2M Gateway -A telemetry service typically pushes data from devices to a data server but does not have the capability to pull data from the device or post data from the cloud to the device. LwM2M (Lightweight Machine to Machine) protocol, however, usually requires both these features. To support this, an LwM2M Gateway is necessary to enable the deviceShifu to adapt to the LwM2M protocol, supporting pull data calls from the server and auto-pushing data to the server. +A telemetry service typically pushes data from devices to a data server but does not have the capability to pull data from the device or post data from the cloud to the device. LwM2M (Lightweight Machine to Machine) protocol, however, usually requires both these features. To support this, an LwM2M Gateway is necessary to enable the deviceShifu to adapt to the LwM2M protocol, handle requests from the LwM2M server, and push data to the cloud. ## Goal @@ -23,7 +23,7 @@ A telemetry service typically pushes data from devices to a data server but does - LwM2M protocol over UDP. - Datagram Transport Layer Security (DTLS) support. - Support for LwM2M protocol communication with the server. -- Support for `read`, `write` and `Execute` requests. +- Support for `Read`, `Write` and `Execute` requests. - Support Notify and Observe feature. ### Unsupported Features @@ -120,7 +120,7 @@ sequenceDiagram ds ->> gw: [HTTP Response] OK gw ->> s: [LwM2M Response] OK - note over ds,s: observe data + note over ds,s: Observe data s ->> gw: [LwM2M GET /ObjectID] Enable Observe Object gw ->> s: [LwM2M] Created loop Get Device Data in a interval @@ -131,7 +131,7 @@ sequenceDiagram end end - note over ds,s: de-register + note over ds,s: De-register gw ->> s: [LwM2M /Delete]De-register s ->> gw: [LwM2M Response] Deleted ```