Skip to content

Commit ef4c359

Browse files
wsobelwsobel
authored
Merge pull request #479 from robot-ranger/447-json-schema
447 json schema
2 parents 5e9bfd0 + 68c1a2c commit ef4c359

File tree

2 files changed

+756
-184
lines changed

2 files changed

+756
-184
lines changed

‎README.md‎

Lines changed: 143 additions & 184 deletions
Original file line numberDiff line numberDiff line change
@@ -713,12 +713,14 @@ These can be overridden on a per-adapter basis
713713

714714
* `HttpHeaders` - Additional headers to add to the HTTP Response for CORS Security
715715

716-
> Example: ```
717-
> HttpHeaders {
718-
> Access-Control-Allow-Origin = *
719-
> Access-Control-Allow-Methods = GET
720-
> Access-Control-Allow-Headers = Content-Type
721-
> }```
716+
Example:
717+
```
718+
HttpHeaders {
719+
Access-Control-Allow-Origin = *
720+
Access-Control-Allow-Methods = GET
721+
Access-Control-Allow-Headers = Content-Type
722+
}
723+
```
722724

723725
* `Port` - The port number the agent binds to for requests.
724726

@@ -790,7 +792,7 @@ Enabled in `agent.cfg` by specifying:
790792
```
791793
Sinks {
792794
MqttService {
793-
# Configuration Options...
795+
# Configuration Options below...
794796
}
795797
}
796798
```
@@ -829,7 +831,7 @@ Sinks {
829831

830832
* `ProbeTopic` or `DeviceTopic` - Prefix for the Device Model topic
831833

832-
> Note: The `[device]` will be replace with the uuid of each device. Other patterns can be created,
834+
> Note: `[device]` will be replaced with the uuid of each device. Other patterns can be created,
833835
> for example: `MTConnect/[device]/Probe` will group by device instead of operation.
834836
> `DeviceTopic` will also work.
835837
@@ -1002,9 +1004,6 @@ Sinks {
10021004

10031005
*Default*: Auto-generated
10041006

1005-
> **⚠️Note:** Mqtt Sinks and Mqtt Adapters create separate connections to their respective brokers, but currently use the same client ID by default. Because of this, when using a single broker for source and sink, best practice is to explicitly specify their respective `MqttClientId`
1006-
>
1007-
10081007
Example mqtt adapter block:
10091008
```json
10101009
mydevice {
@@ -1016,172 +1015,16 @@ Sinks {
10161015
}
10171016
```
10181017

1019-
### MQTT JSON Ingress Protocol Version 2.0
1020-
1021-
In general the data format will be {"timestamp": "YYYY-MM-DDThh:mm:ssZ","dataItemId":"value", "dataItemId":{"key1":"value1", ..., "keyn":"valuen}}
1022-
1023-
**NOTE**: See the standard for the complete description of the fields for the data item representations below.
1024-
1025-
A simple set of events and samples will look something like this:
1026-
1027-
```json
1028-
{
1029-
"timestamp": "2023-11-06T12:12:44Z", //Time Stamp
1030-
"tempId": 22.6, //Temperature
1031-
"positionId": 1002.345, //X axis position
1032-
"executionId": "ACTIVE" //Execution state
1033-
}
1034-
```
1035-
1036-
A `CONDITION` requires the key to be the dataItemId and requires the 6 fields as shown in the example below
1037-
1038-
```json
1039-
{
1040-
"timestamp": "2023-11-06T12:12:44Z",
1041-
"dataItemId": {
1042-
"level": "fault",
1043-
"conditionId":"ac324",
1044-
"nativeSeverity": "1000",
1045-
"qualifier": "HIGH",
1046-
"nativeCode": "ABC",
1047-
"message": "something went wrong"
1048-
}
1049-
}
1050-
```
1051-
A `MESSAGE` requires the key to be the dataItemId and requires the nativeCode field as shown in the example below
1052-
1053-
```json
1054-
{
1055-
"timestamp": "2023-11-06T12:12:44Z",
1056-
"messsageId": {
1057-
"nativeCode": "ABC",
1058-
"message": "something went wrong"
1059-
}
1060-
}
1061-
```
1062-
1063-
The `TimeSeries` `REPRESENTATION` requires the key to be the dataItemId and requires 2 fields "count" and "values" and 1 to n comma delimited values.
1064-
**NOTE**: The "frequency" field is optional.
1065-
1066-
```json
1067-
{
1068-
"timestamp": "2023-11-06T12:12:44Z",
1069-
"timeSeries1": {
1070-
"count": 10,
1071-
"frequency": 100,
1072-
"values": [1,2,3,4,5,6,7,8,9,10]
1073-
}
1074-
}
1075-
```
1076-
The `DataSet` `REPRESENTATION` requires the the dataItemId as the key and the "values" field. It may also have the optional "resetTriggered" field.
1077-
1078-
```json
1079-
{
1080-
{
1081-
"timestamp": "2023-11-09T11:20:00Z",
1082-
"dataSetId": {
1083-
"key1": 123,
1084-
"key2": 456,
1085-
"key3": 789
1086-
}
1087-
}
1088-
```
1089-
1090-
Example with the optional "resetTriggered" filed:
1091-
1092-
```json
1093-
{
1094-
"timestamp": "2023-11-09T11:20:00Z",
1095-
"cncregisterset1": {
1096-
"resetTriggered": "NEW",
1097-
"value": {"r1":"v1", "r2":"v2", "r3":"v3" }
1098-
}
1099-
}
1100-
```
1018+
* `AdapterIdentity` - Adapter Identity name used to prefix dataitems within the Agent device ids and names.
11011019

1102-
The `Table` `REPRESENTATION` requires the the dataItemId as the key and the "values" field. It may also have the optional "resetTriggered" field.
1020+
*Default*:
1021+
* If `SuppressIPAddress` == false:\
1022+
`AdapterIdentity` = ```_ {IP}_{PORT}```\
1023+
example:`_localhost_7878`
11031024

1104-
```json
1105-
1106-
{
1107-
"timestamp":"2023-11-06T12:12:44Z",
1108-
"tableId":{
1109-
"row1":{
1110-
"cell1":"Some Text",
1111-
"cell2":3243
1112-
},
1113-
"row2": {
1114-
"cell1":"Some Other Text",
1115-
"cell2":243
1116-
}
1117-
}
1118-
}
1119-
```
1120-
1121-
Example with the optional resetTriggered field:
1122-
1123-
```json
1124-
{
1125-
"timestamp": "2023-11-09T11:20:00Z",
1126-
"a1": {
1127-
"resetTriggered": "NEW",
1128-
"value": {
1129-
"r1": {
1130-
"k1": 123.45,
1131-
"k3": 6789
1132-
},
1133-
"r2": null
1134-
}
1135-
}
1136-
}
1137-
```
1138-
1139-
1140-
1141-
* `AdapterIdentity` - Adapter Identity name used to prefix dataitems within the Agent device ids and names.
1142-
1143-
*Default*:
1144-
* If `SuppressIPAddress` == false:\
1145-
`AdapterIdentity` = ```_ {IP}_{PORT}```\
1146-
example:`_localhost_7878`
1147-
1148-
* If `SuppressIPAddress` == true:\
1149-
`AdapterIdentity` = ```_ sha1digest({IP}_{PORT})```\
1150-
example: `__71020ed1ed`
1151-
1152-
#### MQTT Adapter/Source
1153-
1154-
* `MqttHost` - IP Address or name of the MQTT Broker
1155-
1156-
*Default*: 127.0.0.1
1157-
1158-
* `MqttPort` - Port number of MQTT Broker
1159-
1160-
*Default*: 1883
1161-
1162-
* `Topics` - list of topics to subscribe to. Note : Only raw SHDR strings supported at this time
1163-
1164-
*Required*
1165-
1166-
* `MqttClientId` - Client ID used when connecting to the MQTT Broker
1167-
1168-
*Default*: Auto-generated
1169-
1170-
> **⚠️Note:** Mqtt Sinks and Mqtt Adapters create separate connections to their respective brokers, but currently use the same client ID by default. Because of this, when using a single broker for source and sink, best practice is to explicitly specify a distinct `MqttClientId` for each.
1171-
>
1172-
1173-
> **⚠️Note:** Currently, there is no JSON parser functionality. Agent is expecting a raw SHDR-formatted string
1174-
1175-
Example mqtt adapter block:
1176-
```json
1177-
mydevice {
1178-
Protocol = mqtt
1179-
MqttHost = localhost
1180-
MqttPort = 1883
1181-
MqttClientId = myUniqueID
1182-
Topics = /ingest
1183-
}
1184-
```
1025+
* If `SuppressIPAddress` == true:\
1026+
`AdapterIdentity` = ```_ sha1digest({IP}_{PORT})```\
1027+
example: `__71020ed1ed`
11851028

11861029
### Agent Adapter Configuration
11871030

@@ -1239,8 +1082,8 @@ logger_config configuration items
12391082

12401083
*Default*: NEVER
12411084

1242-
Adapter Agent Protocol Version 2.0
1243-
=======
1085+
# Agent-Adapter Protocols
1086+
## SHDR Version 2.0
12441087

12451088
The principle adapter data format is a simple plain text stream separated by the pipe character `|`. Every line except for commands starts with an optional timestamp in UTC. If the timestamp is not supplied the agent will supply a timestamp of its own taken at the arrival time of the data to the agent. The remainder of the line is a key followed by data – depending on the type of data item is being written to.
12461089

@@ -1345,8 +1188,7 @@ Using the quoting conventions explained in the previous section, the inner conte
13451188

13461189
All the reset rules of data set apply to tables and the values are treated as a unit.
13471190

1348-
Assets
1349-
-----
1191+
## Assets
13501192

13511193
Assets are associated with a device but do not have a data item they are mapping to. They therefore get the special data item name `@ASSET@`. Assets can be sent either on one line or multiple lines depending on the adapter requirements. The single line form is as follows:
13521194

@@ -1372,10 +1214,128 @@ Partial updates to assets is also possible by using the @UPDATE_ASSET@ key, but
13721214

13731215
2012-02-21T23:59:33.460470Z|@UPDATE_ASSET@|KSSP300R.1|OverallToolLength|323.64|CuttingDiameterMax|76.211
13741216

1375-
Commands
1376-
-----
1217+
## MQTT JSON Ingress Protocol Version 2.0
1218+
1219+
In general the data format is {"timestamp": "YYYY-MM-DDThh:mm:ssZ","dataItemId":"value", "dataItemId":{"key1":"value1", ..., "keyn":"valuen}}
1220+
1221+
**NOTE**: See the standard for the complete description of the fields for the data item representations below.
1222+
1223+
A simple set of events and samples will look something like this:
1224+
1225+
```json
1226+
{
1227+
"timestamp": "2023-11-06T12:12:44Z", //Time Stamp
1228+
"tempId": 22.6, //Temperature
1229+
"positionId": 1002.345, //X axis position
1230+
"executionId": "ACTIVE" //Execution state
1231+
}
1232+
```
1233+
1234+
A `CONDITION` requires the key to be the dataItemId and requires the 6 fields as shown in the example below
1235+
1236+
```json
1237+
{
1238+
"timestamp": "2023-11-06T12:12:44Z",
1239+
"dataItemId": {
1240+
"level": "fault",
1241+
"conditionId":"ac324",
1242+
"nativeSeverity": "1000",
1243+
"qualifier": "HIGH",
1244+
"nativeCode": "ABC",
1245+
"message": "something went wrong"
1246+
}
1247+
}
1248+
```
1249+
A `MESSAGE` requires the key to be the dataItemId and requires the nativeCode field as shown in the example below
1250+
1251+
```json
1252+
{
1253+
"timestamp": "2023-11-06T12:12:44Z",
1254+
"messsageId": {
1255+
"nativeCode": "ABC",
1256+
"message": "something went wrong"
1257+
}
1258+
}
1259+
```
1260+
1261+
The `TimeSeries` `REPRESENTATION` requires the key to be the dataItemId and requires 2 fields "count" and "values" and 1 to n comma delimited values.
1262+
>**NOTE**: The "frequency" field is optional.
1263+
1264+
```json
1265+
{
1266+
"timestamp": "2023-11-06T12:12:44Z",
1267+
"timeSeries1": {
1268+
"count": 10,
1269+
"frequency": 100,
1270+
"values": [1,2,3,4,5,6,7,8,9,10]
1271+
}
1272+
}
1273+
```
1274+
The `DataSet` `REPRESENTATION` requires the the dataItemId as the key and the "values" field. It may also have the optional "resetTriggered" field.
1275+
1276+
```json
1277+
{
1278+
{
1279+
"timestamp": "2023-11-09T11:20:00Z",
1280+
"dataSetId": {
1281+
"key1": 123,
1282+
"key2": 456,
1283+
"key3": 789
1284+
}
1285+
}
1286+
```
1287+
1288+
Example with the optional "resetTriggered" filed:
1289+
1290+
```json
1291+
{
1292+
"timestamp": "2023-11-09T11:20:00Z",
1293+
"cncregisterset1": {
1294+
"resetTriggered": "NEW",
1295+
"value": {"r1":"v1", "r2":"v2", "r3":"v3" }
1296+
}
1297+
}
1298+
```
1299+
1300+
The `Table` `REPRESENTATION` requires the the dataItemId as the key and the "values" field. It may also have the optional "resetTriggered" field.
1301+
1302+
```json
1303+
1304+
{
1305+
"timestamp":"2023-11-06T12:12:44Z",
1306+
"tableId":{
1307+
"row1":{
1308+
"cell1":"Some Text",
1309+
"cell2":3243
1310+
},
1311+
"row2": {
1312+
"cell1":"Some Other Text",
1313+
"cell2":243
1314+
}
1315+
}
1316+
}
1317+
```
1318+
1319+
Example with the optional resetTriggered field:
1320+
1321+
```json
1322+
{
1323+
"timestamp": "2023-11-09T11:20:00Z",
1324+
"a1": {
1325+
"resetTriggered": "NEW",
1326+
"value": {
1327+
"r1": {
1328+
"k1": 123.45,
1329+
"k3": 6789
1330+
},
1331+
"r2": null
1332+
}
1333+
}
1334+
}
1335+
```
13771336

1378-
There are a number of commands that can be sent as part of the adapter stream. These change some dynamic elements of the device information, the interpretation of the data, or the associated default device. Commands are given on a single line starting with an asterisk `* ` as the first character of the line and followed by a <key>: <value>. They are as follows:
1337+
## Adapter Commands
1338+
There are a number of commands that can be sent as part of the adapter stream over the SHDR port connection. These change some dynamic elements of the device information, the interpretation of the data, or the associated default device. Commands are given on a single line starting with an asterisk `* ` as the first character of the line and followed by a <key>: <value>. They are as follows:
13791339

13801340
* Specify the Adapter Software Version the adapter supports:
13811341

@@ -1439,8 +1399,7 @@ There are a number of commands that can be sent as part of the adapter stream. T
14391399

14401400
Any other command will be logged as a warning.
14411401

1442-
Protocol
1443-
----
1402+
## Heartbeat Protocol
14441403

14451404
The agent and the adapter have a heartbeat that makes sure each is responsive to properly handle disconnects in a timely manner. The Heartbeat frequency is set by the adapter and honored by the agent. When the agent connects to the adapter, it first sends a `* PING` and then expects the response `* PONG <timeout>` where `<timeout>` is specified in milliseconds. So if the following communications are given:
14461405

0 commit comments

Comments
 (0)