JsonStructureDpa v1
This document is draft under construction
This message category is used for the main purpose of the daemon: Performing DPA requests and getting back DPA responses.
The messages of this category are generally called JsonDpaMessage and can be referred as:
- JsonDpaRequest is sent from a sender to the daemon.
- JsonDpaResponse is sent from the daemon to the sender as the direct reply to the JsonDpaRequest or as an asynchronous JsonDpaResponse.
If there is an optional parameter and it is present in the JsonDpaRequest then it must be repeated in the matching JsonDpaResponse.
The parameters described in this chapter are common and used in more message types. The parameters special for a particular message type are described in following chapters.
-
"ctype": "<STRING>"defines the category. It has to bedpahere. -
"type": "<STRING>"is a type of the DPA message and it is the key identification of an expected structure of the rest of the message. If received as a JsonDpaRequest the daemon passes the message to a parser component configured for the receiving channel to get the DPA request to be sent to IQRF network. If sent from the daemon as a JsonDpaResponse it plays the same role for the addressee of the message. -
"msgid": "<STRING>"is the message identification unique for a sender. If used in JsonDpaRequest, it is repated in the counterpart JsonDpaResponse. Then it can be used by the sender to match outgoing and incoming messages. -
"nadr": "<WORD>"is the node address as defined in "foursome". -
"pnum": "<BYTE>"is periphery number as defined in "foursome". -
"pcmd": "<BYTE>"is periphery command as defined in "foursome". -
"hwpid": "<WORD>"is hardware profile identification as defined in "foursome". It can be optional, in this case the default value isffff. -
"rcode": "<BYTE>"is the response code. -
"request": "<BINARY>"are bytes to be sent as a DPA request IQRF network. -
"request_ts": "<TIMESTAMP>"is request sent to IQRF net timestamp. -
"response": "<BINARY>"are bytes received as a DPA response from IQRF network. -
"response_ts": "<TIMESTAMP>"is response received from IQRF net timestamp. -
"confirmation": "<BINARY>"are bytes received as a DPA confirmation from IQRF network. -
"confirmation_ts": "<TIMESTAMP>"is confirmation received from IQRF net timestamp. -
"data": "<BINARY>"are bytes forming an optional data part of a DPA if applicable. -
"cmd": "<STRING>"is a string defining required command to be done. The content is specific to a particular"type"parameter. -
"status": "<STRING>"is a string with textual form of response code returned by a JsonDpaResponse. Possible values are described in dedicated chapter. -
"timeout": "<INT>"is the timeout value for DPA request. if zero, the timeout is infinite else it represents time in milliseconds. If omitted the default timer value is used.
The messages shall be as brief as possible. However sometimes it is required to get more verbose information, e.g. for debugging or statistic information. These parameters can be optionally added to any JsonDpaRequest and get back (must be repeated) required information by JsonDpaResponse. The parameters values are ignored in JsonDpaRequest (can be empty).
If the parameter is optional in the message declaration it is wrapped by [] brackets.
{
"ctype":"dpa",
"type":"<STRING>",
"msgid":"<STRING>",
"[timeout]":"<INT>",
"request":"<BINARY>",
"[request_ts]":"",
"[confirmation]":".",
"[confirmation_ts]":"",
"[response]":".",
"[response_ts]":""
}Is responded:
{
"ctype": "dpa",
"type": "<STRING>",
"msgid": "<STRING>",
"[timeout]": "<INT>",
"request": "<BINARY>",
"[request_ts]": "<TIMESTAMP>",
"[confirmation]": "<BINARY>",
"[confirmation_ts]": "<TIMESTAMP>",
"response": "<BINARY>",
"[response_ts]": "<TIMESTAMP>",
"status": "STATUS_NO_ERROR"
}Note the encoders verbosity can be configurable and the information can be sent by default for all JsonDpaResponse.
The response code is passed by "rcode": <WORD> as a number or by "status": <STRING>
in the textual representation. The textual form comes from DPA.h declarations with
some additions:
| NUMBER | STRING | Comment |
|---|---|---|
| -2 | ERROR_PROMISE_TIMEOUT | not used in rtype |
| -1 | ERROR_TIMEOUT | not used in rtype |
| 0 | STATUS_NO_ERROR | |
| 1 | ERROR_FAIL | |
| 2 | ERROR_PCMD | |
| 3 | ERROR_PNUM | |
| 4 | ERROR_ADDR | |
| 5 | ERROR_DATA_LEN | |
| 6 | ERROR_DATA | |
| 7 | ERROR_HWPID | |
| 8 | ERROR_NADR | |
| 9 | ERROR_IFACE_CUSTOM_HANDLER | |
| 0xA | ERROR_MISSING_CUSTOM_DPA_HANDLER | |
| 0xB ... 0x1F | ... | not used as response code |
| 0x20 ... 0x3F | ERROR_USER_... | depends on user implementation |
| [0x40 ... 0xFF] | ... | not used as response code |
These types can hold any DPA messages:
This is the most generic type. It can hold any DPA messages.
JsonDpaRequest:
{
"ctype": "dpa",
"type": "raw",
"msgid": "<STRING>",
"[timeout]": "<INT>",
"request": "<BINARY>",
"[request_ts]": "",
"[confirmation]": "",
"[confirmation_ts]": "",
"[response]": "",
"[respons_ts]": ""
}JsonDpaResponse:
{
"ctype": "dpa",
"type": "raw",
"msgid": "<STRING>",
"[timeout]": "<INT>",
"request": "<BINARY>",
"[request_ts]": "<TIMESTAMP>",
"[confirmation]": "<BINARY>",
"[confirmation_ts]": "<TIMESTAMP>",
"response": "<BINARY>",
"[response_ts]": "<TIMESTAMP>",
"status": "<STRING>"
}This is more detailed generic type to hold DPA message. It has per-parsed DPA message header:
JsonDpaRequest:
{
"ctype": "dpa",
"type": "raw-hdp",
"msgid": "<STRING>",
"[timeout]": "<INT>",
"nadr": "<WORD>",
"pnum": "<BYTE>",
"pcmd": "<BYTE>",
"hwpid": "<WORD>",
"[rcode]": "",
"[rdata]": "<BINARY>",
"[request]": "",
"[request_ts]": "",
"[confirmation]": "",
"[confirmation_ts]": "",
"[response]": "",
"[response_ts]": ""
}JsonDpaResponse:
{
"ctype": "dpa",
"type": "raw-hdp",
"msgid": "<STRING>",
"[timeout]": "<INT>",
"nadr": "<WORD>",
"pnum": "<BYTE>",
"pcmd": "<BYTE>",
"hwpid": "<WORD>",
"rcode": "<BYTE>",
"dpaval": "<BYTE>",
"[rdata]": "<BINARY>",
"[request]": "<BINARY>",
"[request_ts]": "<TIMESTAMP>",
"[confirmation]": "<BINARY>",
"[confirmation_ts]": "<TIMESTAMP>",
"[response]": "<BINARY>",
"[response_ts]": "<TIMESTAMP>",
"status": "<STRING>"
}This is a family of types holding DPA messages for embedded periferies. Usage of these types simplifies encoding and parsing of binary data transported from or to IQRF network. Note it is not mandatory to use them and it is possible to transfer DPA messages in their generic raw or raw-hdp form.
...
Work in progress!
JsonDpaRequest:
{
"ctype": "dpa",
"type": "std-per-sen",
"nadr": "1",
"cmd": "ENUM",
"device": "PROTRONIX"
}JsonDpaResponse:
{
"ctype": "dpa",
"type": "std-per-sen",
"nadr": "1",
"cmd": "ENUM",
"device": "PROTRONIX",
"sensors": [
{
"type": "Temperature",
"sid": 1
},
{
"type": "CO2",
"sid": 2
},
{
"type": "Humidity",
"sid": 128
}
],
"status": "NO_ERROR"
}JsonDpaRequest:
{
"ctype": "dpa",
"type": "std-per-sen",
"nadr": "1",
"cmd": "READ",
"device": "PROTRONIX",
"sensors": [
"Temperature1",
"CO2_1",
"Humidity1"
]
}JsonDpaResponse:
{
"ctype": "dpa",
"type": "std-per-sen",
"nadr": "1",
"cmd": "READ",
"device": "PROTRONIX",
"sensors": [
{
"name": "Temperature1",
"value": 37.8125
},
{
"name": "CO2_1",
"value": 525.0
},
{
"name": "Humidity1",
"value": 40.0
}
],
"status": "ERROR_DATA_LEN"
}JsonDpaRequest:
{
"ctype": "dpa",
"type": "std-per-sen",
"nadr": "1",
"cmd": "READT",
"device": "PROTRONIX",
"sensors": [
"Temperature1",
"CO2_1",
"Humidity1"
]
}JsonDpaResponse:
{
"ctype": "dpa",
"type": "std-per-sen",
"nadr": "1",
"cmd": "READ",
"device": "PROTRONIX",
"sensors": [
{
"type": "Temperature",
"name": "Temperature1",
"value": 22.375,
"units": "Celsius"
},
{
"type": "CO2",
"name": "CO2_1",
"value": 50000.0,
"units": "ppm"
},
{
"type": "Humidity",
"name": "Humidity1",
"value": 25.0,
"units": "%"
}
],
"status": "NO_ERROR"
}Work in progress!