Review and update of binary mode for v0.3

martinjaeger · martinjaeger · commit 6112e678c4f0 · 2020-04-19T08:41:29.000+02:00
diff --git a/docs/2a_general.md b/docs/2a_general.md
@@ -14,17 +14,17 @@ ThingSet defines three types of messages: Requests, responses and publication me
 
 ### Request/response or client/server model
 
-The communication between two specific devices uses a request/response messaging pattern via so-called communication channels. A channel can be established either directly (e.g. serial interface, USB, Bluetooth) or via a network or bus with several devices attached (e.g. CAN, Ethernet, WiFi, LoRa). In case of a network, each device/node has to be uniquely addressable.
+The communication between two specific devices uses a request/response messaging pattern. A connection can be established either directly (e.g. serial interface, USB, Bluetooth) or via a network or bus with several devices attached (e.g. CAN, Ethernet, WiFi, LoRa). In case of a network, each device/node has to be uniquely addressable.
 
 ![Communication Channels](./images/communication_channels.png)
 
-The device acts as the server and responds to the requests by a client. The client might be a laptop or mobile phone with a human interface application or a gateway.
+The device acts as the server and responds to the requests by a client. The client might be a display, a mobile phone application or a gateway.
 
 The data transfer is always synchronous: The client sends a request, waits for the response (status code and requested data), processes the response and possibly starts with additional requests.
 
 ### Publication messages
 
-Monitoring data is not intended for only a single device, but could be interesting for several devices (e.g. data logger, display, human interface device, etc.). Thus, the monitoring data is exchanged via a publish/subscribe messaging pattern.
+Monitoring data is not intended for only a single device, but could be interesting for several devices (e.g. data logger and display). Thus, the monitoring data can be exchanged via a publish/subscribe messaging pattern.
 
 Publication messages are directly broadcast through the network. Unlike in MQTT, there is no intermediate broker to store the messages and published messages are not confirmed by recipients, so there is no guarantee if the message was received.
 
@@ -34,17 +34,17 @@ Similar to Modbus, the ThingSet protocol supports two different modes: A human-r
 
 In the text mode, payload data is encoded in JSON format ([RFC 8259](https://tools.ietf.org/html/rfc8259)). This mode is recommended when using serial communication interfaces as the low layer protocol, as it can be easily used directly on a terminal.
 
-The binary mode uses the CBOR binary encoding ([RFC 7049](https://tools.ietf.org/html/rfc7049)) instead of JSON payload data in order to reduce the protocol overhead for ressource-constrained devices or low bandwith communication protocols like CAN and LoRa.
+The binary mode uses the CBOR ([RFC 7049](https://tools.ietf.org/html/rfc7049)) instead of JSON for payload data encoding in order to reduce the protocol overhead for ressource-constrained devices or low bandwith communication protocols like CAN and LoRa.
 
 A device may implement both variants of the protocol, but it is also allowed to support only the mode most suitable for the application.
 
 ## Data Structure
 
-All accessible data of a device is [structured as a tree](https://en.wikipedia.org/wiki/Tree_(data_structure)). Actual data is stored in leaf nodes, called data nodes. The data can be any kind of measurements (e.g. temperature), device configuration (e.g. setpoint of a controller) or similar. Internal nodes are used to structure the data and define paths for data access.
+All accessible data of a device is [structured as a tree](https://en.wikipedia.org/wiki/Tree_(data_structure)). Internal nodes are used to define paths or endpoints for data access. Actual data is stored in the leaf nodes and can be any kind of measurements (e.g. temperature), device configuration (e.g. setpoint of a controller) or similar information.
 
-Each node is identified by a unique node ID and a name. The ID can be chosen by the firmware developer. The name of a data node must be unique per device. It is a short case-sensitive ASCII string containing only alphanumeric characters, an underscore, dots or dashes without any whitespace characters. The underscore is only used to specify the unit of the data (if applicable, also see below). No additional underscore is allowed in the name.
+Each node is identified by a unique node ID and a name. The ID can be chosen by the firmware developer. The name is a short case-sensitive ASCII string containing only alphanumeric characters, an underscore, dots or dashes without any whitespace characters. The underscore is only used to specify the unit of the data (if applicable, also see below). No additional underscore is allowed in the name and it should be unique per device at least for nodes that are used in publication messages.
 
-The numeric IDs are used to define the relations between each nodes and to directly access data nodes in the binary protocol for reduced message size. For all interactions with users and in the text-based mode, only the node names and paths consisting of node names are used.
+The numeric IDs are used to define the relations between nodes and to directly access data nodes in the binary protocol for reduced message size. For all interactions with users and in the text-based mode, only the node names and paths (consisting of multiple node names) are used.
 
 ### Example
 
@@ -71,8 +71,8 @@ For explanation of the protocol, the following simplified data structure of an M
     },
     "exec": {
         "reset": null,
-        "auth": "password"
     },
+    "auth": ["Password"],
     "pub": {
         "serial": {
             "Enable": true,
@@ -88,11 +88,11 @@ For explanation of the protocol, the following simplified data structure of an M
 }
 ```
 
-The data nodes are structured in 5 different categories info, conf, input, output and rec. By convention, data node names use [upper camel case](https://en.wikipedia.org/wiki/Camel_case), inner nodes nodes use lower case names.
+The data nodes are structured in the main different categories info, conf, input, output and rec. By convention, data node names use [upper camel case](https://en.wikipedia.org/wiki/Camel_case), inner nodes nodes use lower case names.
 
-The exec category is special, as it contains functions that can be called. In order to distinguish it from a normal data node, executable node names are lower case.
+The exec category is special, as it provides functions that can be called. In order to distinguish functions from a normal data nodes, executable node names are lower case.
 
-The pub node is used to configure different types of publication messages, so it doesn't hold actual data nodes.
+The pub node is used to configure different types of publication messages, so it doesn't hold normal data nodes.
 
 ### Categories
 
@@ -101,20 +101,20 @@ The following categories for data nodes are used for the ThingSet protocol by de
 | Category | Description | Access  |
 |----------|-------------|---------|
 | info     | Device information (e.g. manufacturer, software version) | read access |
-| conf     | Configurable settings, stored in non-volatile memory after change | read/write access, may be protected with user password |
+| conf     | Configurable settings, stored in non-volatile memory after change | read/write access, expert settings may be password-protected |
 | input    | Input nodes (e.g. actuators) | write access |
 | output   | Output nodes (e.g. sensor data) | read access |
-| rec      | Recorded (history-dependent) data (e.g. error counters) | read access, restricted write access to reset |
+| rec      | Recorded (history-dependent) data (e.g. min/max values) | read access, restricted write access to reset |
 | cal      | Factory-calibrated settings | read/write access, protected
 | exec     | Executable functions | partly access restricted |
 
 The nodes of input and output categories are used for instantaneous data. Changes to input nodes are only stored in RAM, so they get lost after a reset of the device. In contrast to that, conf data is stored in non-volatile memory (e.g. flash or EEPROM) after a change. As non-volatile memory has a limited amount of write cycles, configuration data should not be changed continously.
 
 The recorded data category is used for history-dependent data like error memory, energy counters or min/max values of certain measurements. In contrast to data of output category, recorded data cannot be obtained through measurement after reset, so the current state has to be stored in non-volatile memory on a regular basis.
 
-Factory calibration is only accessible for the manufacturer after authentication.
+Factory calibration data nodes are only accessible for the manufacturer after authentication.
 
-Excecutable data means that they trigger a function call in the device firmware. Currently, only void functions without any parameters are supported.
+Excecutable data means that they trigger a function call in the device firmware. Child nodes of the executable node can be used to define parameters that can be passed to the function.
 
 Data node IDs are stored as unsigned integers. The firmware developer should assign the lowest IDs to the most used data objects, as they consume less bytes during transfer (see CBOR representation of unsigned integers).
 
@@ -139,7 +139,7 @@ The first byte of a ThingSet message is either a text-mode identifier ('?', '=',
 
 ### Requests
 
-The protocol supports the typical [CRUD operations](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete). Request codes match with CoAP in order to allow transparent translation and routing between ThingSet and HTTP APIs or CoAP devices.
+The protocol supports the typical [CRUD operations](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete). Request codes match with CoAP to allow transparent translation and routing between ThingSet and HTTP APIs or CoAP devices.
 
 | Code | Text ID | Method | Description                                 |
 |------|---------|--------|---------------------------------------------|
@@ -149,6 +149,8 @@ The protocol supports the typical [CRUD operations](https://en.wikipedia.org/wik
 | 0x05 | ?       | FETCH  | Retrieve a subset of data from a node       |
 | 0x07 | =       | iPATCH | Update (overwrite) data of a node           |
 
+The CoAP PUT and PATCH methods are not explicitly implemented. PUT is equivalent to an update of all sub-nodes of a resource using a PATCH request. PATCH requests for ThingSet are always idempotent, so only the iPATCH request code is supported. The two different text IDs for POST requests are synonyms. It is decided based on the type of the node if the request is understood as a function call or a request to create a resource.
+
 Additional request codes may be introduced in the future. Codes 0x0A, 0x0D and 0x20-0x7F are reserved, as they represent the ASCII characters for readable text including LF and CR.
 
 ### Responses
diff --git a/docs/2b_text_mode.md b/docs/2b_text_mode.md
@@ -1,26 +1,26 @@
 # Text Mode
 
-The following description of the ThingSet text mode grammar uses ABNF according to [RFC 5234](https://tools.ietf.org/html/rfc5234) and [RFC 7405](https://tools.ietf.org/html/rfc7405).
+The following description of the ThingSet text mode grammar uses ABNF according to [RFC 5234](https://tools.ietf.org/html/rfc5234).
 
-For rule names prefixed with `json-` consider the JSON specification in [RFC 8259](https://tools.ietf.org/html/rfc8259). For the ThingSet protocol, JSON data must be in the most compact form, i.e. not contain any unnecessary whitespaces or line breaks.
+For rule names prefixed with `json-` consider the JSON specification in [RFC 8259](https://tools.ietf.org/html/rfc8259). In context of the ThingSet protocol, JSON data must be in the most compact form, i.e. not contain any unnecessary whitespaces or line breaks.
 
 ### Requests
 
 Each request message consists of a first character as the request method identifier, a path specifying the endpoint of the request and a JSON string for the payload data (if applicable).
 
-    request = get / fetch / patch / append / delete / exec
+    txt-request = txt-get / txt-fetch / txt-patch / txt-create / txt-delete / txt-exec
 
-    get    = "?" path [ "/" ]                       ; CoAP equivalent: GET request
+    txt-get    = "?" path [ "/" ]                   ; CoAP equivalent: GET request
 
-    fetch  = "?" path " " json-array                ; CoAP equivalent: FETCH request
+    txt-fetch  = "?" path " " json-array            ; CoAP equivalent: FETCH request
 
-    patch  = "=" path " " json-object               ; CoAP equivalent: iPATCH request
+    txt-patch  = "=" path " " json-object           ; CoAP equivalent: iPATCH request
 
-    append = "+" path " " json-value                ; CoAP equivalent: POST request
+    txt-create = "+" path " " json-value            ; CoAP equivalent: POST request
 
-    delete = "-" path " " json-value                ; CoAP equivalent: DELETE request
+    txt-delete = "-" path " " json-value            ; CoAP equivalent: DELETE request
 
-    exec   = "!" path [ " " json-value ]            ; CoAP equivalent: POST request
+    txt-exec   = "!" path [ " " json-value ]        ; CoAP equivalent: POST request
 
     path = node-name [ "/" node-name ]
 
@@ -30,31 +30,33 @@ The path to access a specific node is a JSON pointer ([RFC 6901](https://tools.i
 
 ### Response
 
-The response starts with a colon ':' followed by the the status code and a plain text description of the status finished with a '.'. The description message content is not strictly specified and can be either the description from the table in the [General Concept chapter](2a_general.md) or a more verbose message. However, it must contain only one dot at the end of the description, signifying the end of the description.
+The response starts with a colon ':' followed by the the status code and a plain text description of the status finished with a '.'. The description is not strictly specified and can be according to the table in the [General Concept chapter](2a_general.md) or a more verbose message. However, it must contain only one dot at the end of the description, signifying the end of the description.
 
 The bytes after the dot contain the requested data.
 
-    response = ":" status [ " " json-value ]            ; response code and data
+    txt-response = ":" status [ " " json-value ]    ; response code and data
 
     status = status-code [ " " status-msg ] "."
 
     status-code = 2( hex )
 
     status-msg  = *( ALPHA / SP )
 
-    hex = DIGIT / %x41-46                               ; upper-case HEXDIG
+    hex = DIGIT / %x41-46                           ; upper-case HEXDIG
 
 ### Publication message
 
-    pub-msg = "# " json-map                             ; publication message
+The publication message is very simple and consists of a hash sign and a whitespace at the beginning, followed by a map of data node name/value pairs.
+
+    txt-pubmsg = "# " json-map                      ; publication message
 
 ## Read data
 
-The GET function allows to read all child nodes of the specified path. If a forward slash is appended at the end of the path, only an array with the node names of the next level is returned. Otherwise all content below that path (names and values) is returned.
+The GET function allows to read all child nodes of the specified path. If a forward slash is appended at the end of the path, only an array with the child node names is returned. Otherwise all content below that path (names and values) is returned.
 
 The FETCH function allows to retrieve only subset of the child nodes, defined by an array with the node names passed to the function.
 
-Only those data objects are returned which are at least readable. Thus, the result might differ after authentication.
+Only those data nodes are returned which are at least readable. Thus, the result might differ after authentication.
 
 **Example 1:** Discover all child nodes of the root node (i.e. categories)
 
@@ -64,7 +66,7 @@ Only those data objects are returned which are at least readable. Thus, the resu
 **Example 2:** Retrieve all content of output path (keys + values)
 
     ?output
-    :85 Content. {"Bat_V":14.2,"Bat_A":0.13,"Ambient_degC":22}
+    :85 Content. {"Bat_V":14.2,"Bat_A":5.13,"Ambient_degC":22}
 
 **Example 3:** List all sub-nodes of output path as an array
 
@@ -80,7 +82,7 @@ Only those data objects are returned which are at least readable. Thus, the resu
 
 Requests to overwrite the value of a data node.
 
-Data of category *conf* will be written into persistent memory, so it is not allowed to change settings periodically. Only data of category *input* can be changed regularly.
+Data of category conf will be written into persistent memory, so it is not allowed to change settings periodically. Only data of category input can be changed regularly.
 
 **Example 1:** Disable charging
 
@@ -121,22 +123,20 @@ Executes a function identified by a data object name of category "exec"
 
 ## Authentication
 
-Some of the device parameters like calibration or config settings should be protected against unauthorized change. The protocol provides a simple authentication method. Multiple user levels can be implemented in the firmware using different passwords. The manufacturer would use a different one to authenticate than a normal user and thus get more rights to access data objects.
+Some of the device parameters like calibration or config settings should be protected against unauthorized change. A simple authentication method is suggested where multiple user levels can be implemented in the firmware using different passwords. The manufacturer would use a different one to authenticate than a normal user and thus get more rights to access data objects.
 
 The password is transferred as a plain text string. Encryption has to be provided by lower layers.
 
 Internally, the authentication function is implemented as a data node of exec type.
 
-    !exec/auth "mypass"
+    !auth "mypass"
     :83 Valid.
 
-After successful authentication, the device exposes restricted data objects via the normal data object access commands. The authentication stays valid until another auth command is received, either without password or with a password that doesn't match.
+After successful authentication, the device exposes restricted data nodes via the normal data access requests. The authentication stays valid until another auth command is received, either without password or with a password that doesn't match.
 
 ## Publication messages
 
-A publication request configures the device to publish certain data on a regular basis through a defined communication channel (UART, CAN, LoRa, etc.). If implemented in the firmware, the publication interval may be adjustable.
-
-The publication subsystem is configured via the pub endpoint.
+The pub node is used to configure the device to publish certain data on a regular basis through a defined communication channel (UART, CAN, LoRa, etc.). If implemented in the firmware, the publication interval may be adjustable.
 
 **Example 1:** List all available publication channels
 
@@ -148,10 +148,10 @@ The publication subsystem is configured via the pub endpoint.
     ?pub/serial {"Enable":true}
     :84 Changed.
 
-With this setting, the following message is automatically sent by the device once per hour:
+With this setting, the following message is automatically sent by the device once per second:
 
     # {"Bat_V":14.1,"Bat_A":5.13}
 
 Publication messages are broadcast to all connected devices. No response is sent from devices receiving the message.
 
-The data nodes to be published in each message can be configured using POST and DELETE requests to the pub/serial/IDs channel, as shown in the examples above.
+The data nodes to be published in each message can be configured using POST and DELETE requests to the pub/serial/IDs endpoint, as shown in the examples above.
diff --git a/docs/2c_binary_mode.md b/docs/2c_binary_mode.md
