From 53224413c84ea23838e25d2d60aa8fa57db08a07 Mon Sep 17 00:00:00 2001 From: wbc6080 Date: Wed, 23 Oct 2024 11:16:46 +0800 Subject: [PATCH] update device-method docs Signed-off-by: wbc6080 --- docs/developer/mapper-framework.md | 56 +++++++++++++++++-- .../current/developer/mapper-framework.md | 52 ++++++++++++++++- 2 files changed, 100 insertions(+), 8 deletions(-) diff --git a/docs/developer/mapper-framework.md b/docs/developer/mapper-framework.md index d251fa9234..e24532051a 100644 --- a/docs/developer/mapper-framework.md +++ b/docs/developer/mapper-framework.md @@ -96,11 +96,11 @@ Now we provide Influx2,Redis,TDengine database interfaces, we will add more data #### Pull The HTTP server was created to provide API services. It supports directly obtaining device data from the device. -The URLs listed below are given in the form of local IP. You can use these services from any network accessible to mapper. +The URLs listed below are given in the form of local IP. You can use these services from any network accessible to Mapper. -Port `7777` is enabled by default. +Port `7777` is enabled by default. User can change the Mapper API port in [config file](https://github.com/kubeedge/kubeedge/blob/master/staging/src/github.com/kubeedge/mapper-framework/_template/mapper/config.yaml). -`deviceInstance-ID` according to your own CRD definition. +`deviceInstance-ID` according to your own CRD definition. `propertyName` according to your own CRD definition. #### Ping @@ -119,7 +119,7 @@ Port `7777` is enabled by default. #### Device Data 1. Get device's Data Method=**GET** - Url: https://127.0.0.1:7777/api/v1/device/deviceInstance-ID/propertyName + Url: https://127.0.0.1:7777/api/v1/device/{deviceInstance-ID}/{propertyName} Response: ```json { @@ -138,7 +138,7 @@ Port `7777` is enabled by default. #### Device MetaData 1. Get device's Model Method=**GET** - Url: https://127.0.0.1:7777/api/v1/meta/model/deviceInstance-ID + Url: https://127.0.0.1:7777/api/v1/meta/model/{deviceInstance-ID} Response: ```json { @@ -159,6 +159,52 @@ Port `7777` is enabled by default. } ``` +#### Device Write +In version 1.19, the feature of Mapper supporting device writing is implemented, which enhances the original Mapper API capabilities. +Users can obtain all the device methods of a device that can be called externally through the API, and initiate a write request to +the device through the returned call command. + +The URLs listed below are given as local IPs. You can use these services from any network accessible to Mapper. + +Port `7777` is enabled by default. User can change the Mapper API port in [config file](https://github.com/kubeedge/kubeedge/blob/master/staging/src/github.com/kubeedge/mapper-framework/_template/mapper/config.yaml). + +`deviceInstance-ID` according to your own CRD definition. +`propertyName` according to your own CRD definition. + +1. Get all device methods of a device + Url: https://127.0.0.1:7777/api/v1/devicemethod/{deviceInstance-ID} + Response: + ```json + { + "Data": { + "Methods": [ + { + "Name": "setValue", + "Path": "/api/v1/devicemethod/default/random-instance-01/setValue/{propertyName}/{data}", + "Parameters": [ + { + "PropertyName": "random-int", + "ValueType": "int" + } + ] + } + ] + } + } + ``` + +After obtaining the calling command of the device method, the user can create a device write request: + +2. Create device write request + Url: https://127.0.0.1:7777/api/v1/devicemethod/{deviceInstance-ID}/{deviceMethodName}/{propertyName}/{data} + Response: + ```json + { + "statusCode": 200, + "Message": "Write data ** to device ** successfully." + } + ``` + diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/developer/mapper-framework.md b/i18n/zh/docusaurus-plugin-content-docs/current/developer/mapper-framework.md index 7164e38ba2..810187cc3f 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/developer/mapper-framework.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/developer/mapper-framework.md @@ -87,7 +87,7 @@ spec: #### 拉取数据 我们创建HTTP服务用以提供API拉取功能，支持直接从设备拉取设备数据。下面列出的 URL 以本地 IP 的形式给出。你可以从Mapper可访问的任何网络使用这些服务。 -默认情况下启用端口“7777”。 +默认情况下启用端口“7777”。你可以在Mapper的[config文件](https://github.com/kubeedge/kubeedge/blob/master/staging/src/github.com/kubeedge/mapper-framework/_template/mapper/config.yaml)中自行设置端口号。 `deviceInstance-ID` 根据你自己的 CRD 定义。 @@ -109,7 +109,7 @@ spec: #### 设备数据处理 1. 获取设备数据 Method=**GET** - Url: https://127.0.0.1:7777/api/v1/device/deviceInstance-ID/propertyName + Url: https://127.0.0.1:7777/api/v1/device/{deviceInstance-ID}/{propertyName} Response: ```json { @@ -128,7 +128,7 @@ spec: #### 设备元数据 1. 获取设备模型 Method=**GET** - Url: https://127.0.0.1:7777/api/v1/meta/model/deviceInstance-ID + Url: https://127.0.0.1:7777/api/v1/meta/model/{deviceInstance-ID} Response: ```json { @@ -149,6 +149,52 @@ spec: } ``` +#### 设备写入 +在1.19版本中实现了Mapper支持设备写入的特性，增强了原有Mapper API能力。用户能够通过API获取某个设备所有可供外部调用的设备方法，通过返回的调用命令向设备发起写入请求。 +下面列出的 URL 以本地 IP 的形式给出。你可以从Mapper可访问的任何网络使用这些服务。 + +默认情况下启用端口“7777”。你可以在Mapper的[config文件](https://github.com/kubeedge/kubeedge/blob/master/staging/src/github.com/kubeedge/mapper-framework/_template/mapper/config.yaml)中自行制定端口号 + +`deviceInstance-ID` 根据你自己的 CRD 定义。 + +`propertyName` 根据你自己的 CRD 定义。 + +1. 获取设备的所有设备方法 + Url: https://127.0.0.1:7777/api/v1/devicemethod/{deviceInstance-ID} + Response: + ```json + { + "Data": { + "Methods": [ + { + "Name": "setValue", + "Path": "/api/v1/devicemethod/default/random-instance-01/setValue/{propertyName}/{data}", + "Parameters": [ + { + "PropertyName": "random-int", + "ValueType": "int" + } + ] + } + ] + } + } + ``` + +获取设备方法的调用命令后，用户可以创建设备写入请求： + +2. 创建设备写入请求 + Url: https://127.0.0.1:7777/api/v1/devicemethod/{deviceInstance-ID}/{deviceMethodName}/{propertyName}/{data} + Response: + ```json + { + "statusCode": 200, + "Message": "Write data ** to device ** successfully." + } + ``` + + +