From c37b9f3158e229e55feeca1130635e6132d6a0d7 Mon Sep 17 00:00:00 2001 From: Sergey Mitskevich Date: Fri, 23 Sep 2022 12:29:05 +0200 Subject: [PATCH] New API. --- .../References/API/Device_Parameter_API.md | 48 +++++++ Overvis/References/API/README.md | 4 + Overvis/References/API/Raw_Readings_API.md | 122 ++++++++++++++++++ Overvis/References/API/_sidebar.md | 3 +- 4 files changed, 176 insertions(+), 1 deletion(-) create mode 100644 Overvis/References/API/Raw_Readings_API.md diff --git a/Overvis/References/API/Device_Parameter_API.md b/Overvis/References/API/Device_Parameter_API.md index 9279425..564de0d 100644 --- a/Overvis/References/API/Device_Parameter_API.md +++ b/Overvis/References/API/Device_Parameter_API.md @@ -1,5 +1,53 @@ # Overvis API v1.0 :: Device Parameter API +## `POST /org/:orgId/params/get-id-by-reference/` - Get parameter identifier by reference + +This request take parameter reference string (https://docs.overvis.com/#/Overvis/References/Visualizations?id=device-parameters-can-be-referenced-in-one-of-the-following-ways) as argument ans returns ID of this parameter inside system. + +``` +POST /org/:orgId/params/get-id-by-reference/ +``` +*Required account permissions:* `operator` + +### Parameters - `Params` +| Name | Type | Description | +|:---------|:-----------|:--------------------------------------| +| `orgId` | `Number` | System IDs of organization. | + +### Parameters - `Body` +| Name | Type | Description | +|:---------|:-----------|:--------------------------------------| +| `emptyName` | `String` | Parameter reference string. | + +### Examples + +```bash +TOKEN=`curl -s -H "Content-Type: application/json" \ + -d '{"apiKey": "513cf747-eb5c-4d5f-931f-d22c9872c73c", "password": "DCdcSLmkoZkU5zGI9gpInDbo" }' \ + "https://ocp.overvis.com/api/v1/authenticate/" | \ + jq -r ".token"` && \ +curl -s -S -H "Content-Type: application/json" -H "Authorization: token $TOKEN" \ + -d '"11-22-33-44-55-66>1>5000"' \ + "https://ocp.overvis.com/api/v1/org/1/params/get-id-by-reference/" | \ + jq -C +``` + +### Success response example + +```json +551 +``` + +### Error response example + +```json +{ + "errorCode": "ObjectNotFound", + "errorMessage": "Parameter not found." +} +``` + + ## `GET /params/read-realtime/` - Read current value of the parameter from the device Performs reading from the device and returns values of the requested parameters.

More than one value can be requested at a time. Results will be returned as a dictionary where key is a parameter ID. Returned values are automatically converted from Modbus registers (16 bit groups) to the actual parameter value number depending on the parameter type.

If some parameter ID is not found, it will be ommited from the result. diff --git a/Overvis/References/API/README.md b/Overvis/References/API/README.md index 65e37d0..fca1aae 100644 --- a/Overvis/References/API/README.md +++ b/Overvis/References/API/README.md @@ -87,8 +87,12 @@ All dates returned in responses are in UTC. Example: `2018-05-14T16:28:59.948845 - [`GET /alert/:alertId/` - Get Alert Data](./Alert_API.md#GetAlertData) - [`GET /alert/:alertId/status/` - Get Alert Status Information](./Alert_API.md#GetAlertStatus) - [Device Parameter API](./Device_Parameter_API.md) + - [`POST /org/:orgId/params/get-id-by-reference/` - Get parameter identifier by reference](./Device_Parameter_API.md#GetParamIdByReference) - [`GET /params/read-realtime/` - Read current value of the parameter from the device](./Device_Parameter_API.md#RealtimeReadParams) - [`POST /param/:paramId/write/` - Write parameter value to the device](./Device_Parameter_API.md#WriteParam) +- [Raw Readings API](./Raw_Readings_API.md) + - [`POST /raw/read-multiple-register-group/` - Raw read multiple register group](./Raw_Readings_API.md#RawReadMultipleRegisterGroup) + - [`POST /raw/read-register-group/` - Raw read register group](./Raw_Readings_API.md#RawReadRegisterGroup) - [Visualization API](./Visualization_API.md) - [`GET /v1/vis/:visId/data/` - Get Visualization Data](./Visualization_API.md#GetVisualizationData) - [`GET /v1/vis/:visId/data/save/` - Save Visualization Data](./Visualization_API.md#SaveVisualizationData) diff --git a/Overvis/References/API/Raw_Readings_API.md b/Overvis/References/API/Raw_Readings_API.md new file mode 100644 index 0000000..962f4e3 --- /dev/null +++ b/Overvis/References/API/Raw_Readings_API.md @@ -0,0 +1,122 @@ +# Overvis API v1.0 :: Raw Readings API + +## `POST /raw/read-multiple-register-group/` - Raw read multiple register group + +Read multiple register group using provided controllers/devices data and starting address. + +``` +POST /raw/read-multiple-register-group/ +``` +*Required account permissions:* `viewer` + +### Parameters - `Body` +| Name | Type | Description | +|:---------|:-----------|:--------------------------------------| +| `emptyName` | `Array` | Request body should contain an array of objects with proeprties provided below. | +| `deviceModbusId` | `number` | Identifier of device inside modbus network. | +| `address` | `number` | Starting address. | +| `kind` | `String` | Kind of register group:
- `holding` - 16-bit word. Read-Write.
- `coil` - Single bit. Read-Write.
- `discrete-input` - Single bit. Read-Only.
- `input` - 16-bit word. Read-Only. | +| `registersNum` | `number` | Count of registers that should be read. | +| `connection` | `Object` | Object that describe connection type.
- `kind` - Connection type, can be one of these values: "connect-code", "activation-code", "direct", "backward", "net-id".
- `code` - That property should be defined when connection kind is "connect-code" or "activation-code". When connection kind is "connect-code" that property should be string type. When connection kind is "activation-code" that property should be number type.
- `ip` - That property should be defined when connection kind is "direct".
- `port` - That property should be defined when connection kind is "direct".
- `mac` - That property should be defiend when connection kind is "backward".
- `connectCode` - That property can be optionally defined when connection kind is "backward".
- `networkId` - That property should be defined when connection kind is "net-id". | + +### Examples + +```bash +TOKEN=`curl -s -H "Content-Type: application/json" \ + -d '{"apiKey": "513cf747-eb5c-4d5f-931f-d22c9872c73c", "password": "DCdcSLmkoZkU5zGI9gpInDbo" }' \ + "https://ocp.overvis.com/api/v1/authenticate/" | \ + jq -r ".token"` && \ +curl -s -S -H "Content-Type: application/json" -H "Authorization: token $TOKEN" \ + -d '[{"deviceModbusId": 1, "address": 3, "registersNum": 5, "kind": "holding", "connection": {"kind": "backward", "mac": "11:22:33:44:55:66"}}, {"deviceModbusId": 111, "address": 459, "registersNum": 1, "kind": "holding", "connection": {"kind": "backward", "mac": "11:22:33:44:55:66"}}]' \ + "https://ocp.overvis.com/api/v1/raw/read-multiple-register-group/" | \ + jq -C +``` + +### Success response example + +```json +[ + { + "deviceModbusId": 1, + "address": 3, + "registersNum": 5, + "result": {"ok":[65535,65535,65535,65535,65535]} + }, + { + "deviceModbusId": 111, + "address": 459, + "registersNum": 1, + "result": {"ok":[9600]} + } +] +``` + +### Error response example + +```json +[ + { + "deviceModbusId": 22, + "address": 3, + "registersNum": 5, + "result": {"err":"MODBUS exception during reading register 3h: GatewayTargetDeviceFailedToRespond"} + }, + { + "deviceModbusId": 45, + "address": 459, + "registersNum": 1, + "result": {"err":"MODBUS exception during reading register 459h: GatewayTargetDeviceFailedToRespond"} + } +] +``` + + +## `POST /raw/read-register-group/` - Raw read register group + +Read register group using provided controller/device data and starting address. + +``` +POST /raw/read-register-group/ +``` +*Required account permissions:* `viewer` + +### Parameters - `Body` +| Name | Type | Description | +|:---------|:-----------|:--------------------------------------| +| `deviceModbusId` | `number` | Identifier of device inside modbus network. | +| `address` | `number` | Starting address. | +| `kind` | `String` | Kind of register group:
- `holding` - 16-bit word. Read-Write.
- `coil` - Single bit. Read-Write.
- `discrete-input` - Single bit. Read-Only.
- `input` - 16-bit word. Read-Only. | +| `registersNum` | `number` | Count of registers that should be read. | +| `connection` | `Object` | Object that describe connection type.
- `kind` - Connection type, can be one of these values: "connect-code", "activation-code", "direct", "backward", "net-id".
- `code` - That property should be defined when connection kind is "connect-code" or "activation-code". When connection kind is "connect-code" that property should be string type. When connection kind is "activation-code" that property should be number type.
- `ip` - That property should be defined when connection kind is "direct".
- `port` - That property should be defined when connection kind is "direct".
- `mac` - That property should be defiend when connection kind is "backward".
- `connectCode` - That property can be optionally defined when connection kind is "backward".
- `networkId` - That property should be defined when connection kind is "net-id". | + +### Examples + +```bash +TOKEN=`curl -s -H "Content-Type: application/json" \ + -d '{"apiKey": "513cf747-eb5c-4d5f-931f-d22c9872c73c", "password": "DCdcSLmkoZkU5zGI9gpInDbo" }' \ + "https://ocp.overvis.com/api/v1/authenticate/" | \ + jq -r ".token"` && \ +curl -s -S -H "Content-Type: application/json" -H "Authorization: token $TOKEN" \ + -d '{"deviceModbusId": 1, "address": 3, "registersNum": 5, "kind": "holding", "connection": {"kind": "backward", "mac": "11:22:33:44:55:66"}}' \ + "https://ocp.overvis.com/api/v1/raw/read-register-group/" | \ + jq -C +``` + +### Success response example + +```json +{ + "ok": [65535,65535,65535,65535,65535] +} +``` + +### Error response example + +```json +{ + "errorCode": "IncorrectRequest", + "errorMessage": "body.connection.kind should be equal to one of the allowed values, body.connection.kind should be equal to one of the allowed values, body.connection.kind should be equal to one of the allowed values, body.connection.kind should be equal to one of the allowed values, body.connection.kind should be equal to one of the allowed values, body.connection should match some schema in anyOf" +} +``` + + diff --git a/Overvis/References/API/_sidebar.md b/Overvis/References/API/_sidebar.md index 0add407..0071972 100644 --- a/Overvis/References/API/_sidebar.md +++ b/Overvis/References/API/_sidebar.md @@ -1,4 +1,4 @@ -- [Overvis API Reference](./) +[Overvis API Reference](./README.md) - [Publicly Accessible API](./Publicly_Accessible_API.md) - [Authentication API](./Authentication_API.md) @@ -8,4 +8,5 @@ - [Readings API](./Readings_API.md) - [Alert API](./Alert_API.md) - [Device Parameter API](./Device_Parameter_API.md) + - [Raw Readings API](./Raw_Readings_API.md) - [Visualization API](./Visualization_API.md)