-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge request release 3.1.0 See merge request smartme.io/arancino/arancino-library!42
- Loading branch information
Showing
101 changed files
with
3,341 additions
and
3,236 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,139 +1,8 @@ | ||
| ## Cortex Protocol | ||
| Arancino Library uses a simple protocol, called **Cortex**, to communicate with the Arancino Module over serial connection. Cortex Protocol is designed to be easy to read and processed. Arancino Library, Arancino Module and Cortex Protocol are designed to be monodirectional and synchronous. In this scenario the Arancino Library within the microcontroller acts as *master*, and the Arancino Module as *slave*. | ||
|
|
||
|
|
||
| Each command sent using Cortex Protocol is composed by a *command identifier* and one or more *parameters*. *Command identifiers* and *parameters* are separated by a separator character, and the command ends with an end character. Each command sent will receive a response, formed by a Response Code and one or more returned values. All the items are separated by the same separtor character and ends with the same end character. The commands receive Response within a timeout interval of `100ms`. If no Response is received, the Command will be skipped. | ||
|
|
||
| ### Commands identifier: | ||
|
|
||
|
|
||
| | API | Command Identifiers | | ||
| | ------------------ |:-------------:| | ||
| | [`begin`](#begin) | START | | ||
| | [`set`](#set) | SET | | ||
| | [`get`](#get) | GET | | ||
| | [`mset`](#mset) | MSET | | ||
| | [`mget`](#mget) | MGET | | ||
| | [`del`](#del) | DEL | | ||
| | [`keys`](#keys) | KEYS | | ||
| | [`hget`](#hget) | HGET | | ||
| | [`hset`](#hset) | HSET | | ||
| | [`hkeys`](#hkeys) | HKEYS | | ||
| | [`hvals`](#hvals) | HVALS | | ||
| | [`hdel`](#hdel) | HDEL | | ||
| | [`flush`](#flush) | FLUSH | | ||
| | [`publish`](#publish) | PUB | | ||
| | [`mset`](#mset) | MSET | | ||
| | [`mget`](#mget) | MGET | | ||
| | [`store`](#store) | STORE | | ||
| | [`storetags`](#storetags)| STORETAGS| | ||
|
|
||
| ### Commands separator chars | ||
| **Important**: Do not use these character codes to compose string values to pass to the API | ||
|
|
||
| | Separator | Char Code | | ||
| | --------------------- |:-------------:| | ||
| | Command Sepatator | `4` | | ||
| | Array separator | `16` | | ||
| | NULL character | `25` | | ||
| | End of transmission | `30` | | ||
|
|
||
|
|
||
| ### Response Codes | ||
| | Response Code | Type | Description | Note | | ||
| |-------|-----------|-------------|------| | ||
| | `100` | Success | Generic operation successfully completed || | ||
| | `101` | Success | Setted value into a new field || | ||
| | `103` | Success | Setted value into an existing field || | ||
| | `200` | Error | Generic Error | | | ||
| | `201` | Error | Retrivied Null Value | Deprecated| | ||
| | `202` | Error | Error during SET command || | ||
| | `203` | Error | Command not found || | ||
| | `204` | Error | Error during SET command || | ||
| | `205` | Error | Invalid parameter number || | ||
| | `206` | Error | Generic Redis Error || | ||
| | `207` | Error | Key exists in the Standard Data Store || | ||
| | `208` | Error | Key exists in the Persistent Data Store || | ||
| | `209` | Error | Non compatibility between Arancino Daemon and Library || | ||
| | `210` | Error | Generic Invalid Arguments || | ||
| | `211` | Error | Invalid Value || | ||
| | `212` | Error | Not yet implemented functionality || | ||
| Arancino Library uses a simple protocol, called **Cortex**, to communicate with the Arancino Module using multiple connection Interfaces (MQTT,Serial,Bluetooth). Cortex Protocol is designed to be easy to read and processed. Arancino Library, Arancino Module and Cortex Protocol are designed to be monodirectional and synchronous. In this scenario the Arancino Library within the microcontroller acts as *master*, and the Arancino Module as *slave*. | ||
|
|
||
| Each command sent using Cortex Protocol is composed by a *command identifier* and one or more *parameters*. *Command identifiers* and *parameters* are formatted inside a *JSON* and the message itself is compressed into a *MessagePack*. Each command sent will receive a response, formed by a Response Code and one or more returned values. The commands receive Response within a timeout interval. If no Response is received, the Command will be skipped. | ||
|
|
||
| ### Commands and Protocol | ||
| As exaplained above, when an API function is called, a command is sent over the `SerialUSB` and a response is received. | ||
| In the next paragraphs, for simplicity we are considering each command returns an *OK* response and using the following representation for *Separator Codes*: | ||
|
|
||
| - Command Sepatator → `4` → `#` | ||
| - Array separator → `16` → `%` | ||
| - End of transmission → `30` →` @` | ||
|
|
||
| #### begin | ||
| - Command Sent: `START#<lib vers>#<fwname>#<fwversion>#<compiletime>#<coreversion>@` | ||
| - Response Received: `100@` | ||
|
|
||
| #### set | ||
| - Command Sent: `SET#<key>#<value>@` | ||
| - Response Received: `100@` | ||
|
|
||
| #### get | ||
| - Command Sent: `GET#<key>@` | ||
| - Response Received: `100#<value>@` | ||
|
|
||
| #### mset | ||
| - Command Sent: `MSET#<key-1>%<key-2>...%<key-n>#<val-1>%<val-2>...%<val-n>@` | ||
| - Response Received: `100#@` | ||
|
|
||
| #### mget | ||
| - Command Sent: `MGET#<key-1>%<key-2>...%<key-n>@` | ||
| - Response Received: `100#<val-1>#<val-2>...#<val-n>]@` | ||
|
|
||
| #### del | ||
| - Command Sent: `DEL#<key>@` | ||
| - Response Received: `100#1@` | ||
|
|
||
| #### keys | ||
| - Command Sent: `KEYS#<pattern>@` | ||
| - Response Received: `100[#<key-1>#<key-2>#<key-n>]@` | ||
|
|
||
| #### hset | ||
| - Command Sent: `HSET#<key>#<field>#<value>@` | ||
| - Response Received: 101@ | ||
|
|
||
| #### hget | ||
| - Command Sent: `HGET#<key>#<field>@` | ||
| - Response Received: `100#<value>@` | ||
|
|
||
| #### hgetall | ||
| - Command Sent: `HGETALL#<key>@` | ||
| - Response Received: `100#<field-1>#<value-1>#<field-2>#<value-2>@` | ||
|
|
||
| #### hkeys | ||
| - Command Sent: `HKEYS#<key>@` | ||
| - Response Received: `100HKEYS#<key>@` | ||
|
|
||
| #### hvals | ||
| - Command Sent: `HVALS#<key>@` | ||
| - Response Received: `100#<value-1>#<value-2>@` | ||
|
|
||
| #### hdel | ||
| - Command Sent: `HDEL#<key>#<field>@` | ||
| - Response Received: `100#1@` | ||
|
|
||
| #### flush | ||
| - Command Sent: `FLUSH@` | ||
| - Response Received: `100@` | ||
|
|
||
| #### storetag | ||
| - Command Sent: `STORE#<key>#<tag1>%<tag2>%<tag3>#<value1>%<value2>%<value3>#<timestamp>@` | ||
| - Response Received: `100@` | ||
|
|
||
| - Command Sent: `STORE#<key>#<tag1>%<tag2>%<tag3>#<value1>%<value2>%<value3>@` | ||
| - Response Received: `100@` | ||
|
|
||
| #### store | ||
| - Command Sent: `STORE#<key>#<values>@` | ||
| - Response Received: `100#<timestamp>@` | ||
|
|
||
| - Command Sent: `STORE#<key>#<values>#<timestamp>@` | ||
| - Response Received: `100#<timestamp>@` | ||
| As exaplained above, when an API function is called, a command is sent over the `ArancinoInterface` and a response is received. | ||
| More details about the command structure and relative responses may be found in the [Cortex Protocol](Cortex_Protocol/README.md) section. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,88 @@ | ||
| # `DEL` | ||
| Delete the specified *keys*. | ||
|
|
||
| >Note: | ||
| > | ||
| >- A *key* is ignored if it does not exist. | ||
| >- The specified *keys* will be deleted even if they were previously stored in a *persistent* way based on the `pers` configuration. You can only delete "application" keys (`"type":"appl"`) | ||
| ## **Command** | ||
|
|
||
| **Arguments:** | ||
|
|
||
| | Args Type | Desc | Mandatory | | ||
| | ----- | --------- | --------- | | ||
| | `items`: String Array | Array of *keys* to delete | **Yes** | | ||
|
|
||
| **Configuration:** | ||
|
|
||
| | Key | Desc | Mandatory | | ||
| | :------ | :-------------------------------------- | -------------------------------- | | ||
| | `pers:` Number | Allows to del keys from the persistent datatstore. To use only with `"type": "appl"`. Allowed values: `0` is *False* and `1` is *True* | **No** | | ||
| | `ack:` Number | Indicates whether a *response* (the ack) should be sent for the *command*. *True* by default. Allowed values: `0` is *False* and `1` is *True*| **No** | | ||
| | `sgntr`: String | Signature used for ECDSA Authentication | **No**: used only in *Secure Mode* | | ||
|
|
||
| **Example:** | ||
|
|
||
| ```json | ||
| { | ||
| "cmd": "DEL", | ||
| "args":{ | ||
| "items":[ | ||
| "<key1>" | ||
| ] | ||
| }, | ||
| "cfg":{ | ||
| "ack": 1, | ||
| "pers": 0, | ||
| "sgntr": "<Signature>" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ```json | ||
| { | ||
| "cmd": "DEL", | ||
| "args":{ | ||
| "items":[ | ||
| "<key-1>", "<key-2>", "<key-n>" | ||
| ] | ||
| }, | ||
| "cfg":{ | ||
| "ack": 0, | ||
| "pers": 1, | ||
| "sgntr": "<Signature>" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## **Response** | ||
|
|
||
| **Arguments:** Empty | ||
| | Key | Desc | Mandatory | | ||
| | ------- | ----------------------------------------- | -------------------------------- | | ||
| | `keys`: Number | Number of deleted keys | **Yes** | | ||
|
|
||
| **Configuration:** | ||
|
|
||
| | Key | Desc | Mandatory | | ||
| | ------- | ----------------------------------------- | -------------------------------- | | ||
| | `chlng` | Challenge useful to sign the next command | No: used only in Secure Protocol | | ||
|
|
||
| **Examples:** | ||
|
|
||
| ```json | ||
| { | ||
| "rsp_code": "100", | ||
| "args":{ | ||
| "keys": <n> | ||
| }, | ||
| "cfg":{ | ||
| "chlng": "<challenge>" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| >Note: | ||
| > | ||
| >- List of possible Error Codes for `DEL`: `200`,`206` **Da controllare per aggiunta anche di errori presenti durante il protocollo sicuro |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| #### `FLUSH` | ||
| Delete all the keys. | ||
|
|
||
| >Note: | ||
| > | ||
| >- This command never fails. | ||
| ## **Command** | ||
|
|
||
| **Arguments:** Empty | ||
|
|
||
| **Configuration:** | ||
|
|
||
| | Key | Desc | Mandatory | | ||
| | :------ | :-------------------------------------- | -------------------------------- | | ||
| | `pers:` Number | Allows to delete persistent or volatile keys. False by default. Allowed values: `0` is _False_ and `1` is _True_ | **No** | | ||
| | `ack:` Number | Indicates whether a *response* (the ack) should be sent for the *command*. *True* by default. Allowed values: `0` is *False* and `1` is *True*| **No** | | ||
| | `sgntr`: String | Signature used for ECDSA Authentication | No: used only in Secure Protocol | | ||
|
|
||
| **Example:** | ||
|
|
||
| ```json | ||
| { | ||
| "cmd": "FLUSH", | ||
| "args":{}, | ||
| "cfg":{ | ||
| "pers": 0, | ||
| "ack": 1, | ||
| "sgntr": "<Signature>" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## **Response** | ||
|
|
||
| **Arguments:** None | ||
|
|
||
| **Configuration:** | ||
|
|
||
| | Key | Desc | Mandatory | | ||
| | ------- | ----------------------------------------- | -------------------------------- | | ||
| | `chlng`: String | Challenge useful to sign the next command | No: used only in Secure Protocol | | ||
|
|
||
| **Examples:** | ||
|
|
||
| ```json | ||
| { | ||
| "rsp_code": "100", | ||
| "args":{}, | ||
| "cfg":{ | ||
| "chlng": "<challenge>" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| >Note: | ||
| > | ||
| >- List of possible Error Codes for `FLUSH`: `200`, `206` **Da controllare per l'aggiunta anche di errori presenti durante il protocollo sicuro |
Oops, something went wrong.