Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Mihini/Embedded Micro Protocol"
Line 77: | Line 77: | ||
RA↔App | RA↔App | ||
| | | | ||
− | Data coming from server <br> <br> '''Command payload''': The payload just contains all the data <br> '''Response''' '''payload''': status: 2 bytes acknowledging the command. | + | Data coming from server <br> <br> '''Command payload''': The payload just contains all the data <br> '''Response''' '''payload''': <code>status</code>: 2 bytes acknowledging the command. |
|- | |- | ||
| | | | ||
Line 86: | Line 86: | ||
App→RA | App→RA | ||
| | | | ||
− | Register client asset/service to ReadyAgent <br> <br> '''Command payload''': the path for which this client want to receive messages (a JSON string). <br> '''Response''' '''payload''': status: 2 bytes acknowledging the command. <br> <br> '''Remarks''': | + | Register client asset/service to ReadyAgent <br> <br> '''Command payload''': the path for which this client want to receive messages (a JSON string). <br> '''Response''' '''payload''': <code>status</code>: 2 bytes acknowledging the command. <br> <br> '''Remarks''': |
* It is possible to register several assets for the same IPC connection by sending several Register commands from that IPC. | * It is possible to register several assets for the same IPC connection by sending several Register commands from that IPC. | ||
* When the IPC is closed, the asset is unregistered automatically. | * When the IPC is closed, the asset is unregistered automatically. | ||
Line 125: | Line 125: | ||
App→RA | App→RA | ||
| | | | ||
− | Unregister a client as a SMS listener to the ReadyAgent. <br> <br> '''Command payload''': <br> id: an unsigned integer, the registration id to unregister, as returned by RegisterSMSListener command <br> <br> '''Response''' '''payload''': <br> status: 2 bytes acknowledging the command. | + | Unregister a client as a SMS listener to the ReadyAgent. <br> <br> '''Command payload''': <br> id: an unsigned integer, the registration id to unregister, as returned by RegisterSMSListener command <br> <br> '''Response''' '''payload''': <br> <code>status</code>: 2 bytes acknowledging the command. |
|- | |- | ||
| | | | ||
Line 143: | Line 143: | ||
App→RA | App→RA | ||
| | | | ||
− | Used by the application to send a SMS <br> '''Command payload''': a list of 3 objects: <br> String: Phone number of the recipient of the outgoing message <br> String: payload of the message <br> String: format of the SMS, supported values are "8bits", "7bits", "ucs2" <br> <br> '''Response''' '''payload''': status: 2 bytes acknowledging the command | + | Used by the application to send a SMS <br> '''Command payload''': a list of 3 objects: <br> String: Phone number of the recipient of the outgoing message <br> String: payload of the message <br> String: format of the SMS, supported values are "8bits", "7bits", "ucs2" <br> <br> '''Response''' '''payload''': <code>status</code>: 2 bytes acknowledging the command |
|- | |- | ||
| | | | ||
Line 152: | Line 152: | ||
App→RA | App→RA | ||
| | | | ||
− | Retrieve a variable from the Core Agent. <br> <br> '''Command payload''': a list of 2 objects: <br> String: name of the variable to get (usually a string that is a path !) <br> Integer: maximum depth of the variable retrieval. This is useful when doing a get on a sub tree. This should be a number. <br> '''Response''' '''payload''': <br> status: 2 bytes acknowledging the command. <br> if the status is OK (=0) <br> 2 objects, can be null. The first object is the value of the variable, or null if the variable is a table. The second object is a list of all sub tree names | + | Retrieve a variable from the Core Agent. <br> <br> '''Command payload''': a list of 2 objects: <br> String: name of the variable to get (usually a string that is a path !) <br> Integer: maximum depth of the variable retrieval. This is useful when doing a get on a sub tree. This should be a number. <br> '''Response''' '''payload''': <br> <code>status</code>: 2 bytes acknowledging the command. <br> if the status is OK (=0) <br> 2 objects, can be null. The first object is the value of the variable, or null if the variable is a table. The second object is a list of all sub tree names |
|- | |- | ||
| | | | ||
Line 161: | Line 161: | ||
App→RA | App→RA | ||
| | | | ||
− | Set a variable on the Core Agent. <br> <br> '''Command payload''': a list of 2 objects: <br> 1 String representing the variable to set (usually a string that is a path !) <br> 1 object representing the value of the variable (it can be a hashtable) <br> '''Response payload''': <br> status: 2 bytes acknowledging the command. | + | Set a variable on the Core Agent. <br> <br> '''Command payload''': a list of 2 objects: <br> 1 String representing the variable to set (usually a string that is a path !) <br> 1 object representing the value of the variable (it can be a hashtable) <br> '''Response payload''': <br> <code>status</code>: 2 bytes acknowledging the command. |
|- | |- | ||
| | | | ||
Line 170: | Line 170: | ||
App→RA | App→RA | ||
| | | | ||
− | Register one variable or path to get notification when it changes. <br> <br> '''Command payload''': a list of 2 objects: <br> reg vars: list of strings representing the variables to register to, each string is a path to register to <br> passive vars: list of strings, each string identifying the path of a passive variable <br> <br> '''Response payload''': <br> status: 2 bytes acknowledging the command. <br> registration id : string identifying this registration for variable change, this id is to be given to DeRegisterVariable command. | + | Register one variable or path to get notification when it changes. <br> <br> '''Command payload''': a list of 2 objects: <br> reg vars: list of strings representing the variables to register to, each string is a path to register to <br> passive vars: list of strings, each string identifying the path of a passive variable <br> <br> '''Response payload''': <br> <code>status</code>: 2 bytes acknowledging the command. <br> registration id : string identifying this registration for variable change, this id is to be given to DeRegisterVariable command. |
|- | |- | ||
| | | | ||
Line 179: | Line 179: | ||
RA→App | RA→App | ||
| | | | ||
− | Notify that a variable changed. <br> <br> '''Command payload''': a list of 2 objects: <br> 1 string representing the registration id that provoked this notification <br> 1 map representing the variables data sent in the change notification, map keys are variables full path, map values are variable values, the map contains both registered variables that have changed and passive variables set in register request <br> <br> '''Response payload''': <br> status: 2 bytes acknowledging the command. | + | Notify that a variable changed. <br> <br> '''Command payload''': a list of 2 objects: <br> 1 string representing the registration id that provoked this notification <br> 1 map representing the variables data sent in the change notification, map keys are variables full path, map values are variable values, the map contains both registered variables that have changed and passive variables set in register request <br> <br> '''Response payload''': <br> <code>status</code>: 2 bytes acknowledging the command. |
|- | |- | ||
| | | | ||
Line 188: | Line 188: | ||
App→RA | App→RA | ||
| | | | ||
− | Cancel previous registration for watching variable changes. <br> <br> '''Command payload''': <br> String representing the registration id (sent in RegisterVariable command Response payload) <br> <br> '''Response payload''': <br> status: 2 bytes acknowledging the command. | + | Cancel previous registration for watching variable changes. <br> <br> '''Command payload''': <br> String representing the registration id (sent in RegisterVariable command Response payload) <br> <br> '''Response payload''': <br> <code>status</code>: 2 bytes acknowledging the command. |
|- | |- | ||
| | | | ||
Line 197: | Line 197: | ||
RA→App | RA→App | ||
| | | | ||
− | Notify the Application that an update must be downloaded and installed from the url given into payload. <br> <br> '''Command payload''': <br> componentname: string that contains the application / bundle to update (the path '''does contain''' the assetid of the asset responsible for that update) <br> version: string, empty string (but not null!) to specify de-installation request, non empty string for regular update/install of software component. <br> URL: string; Can be empty when version is empty too, otherwise URL will be a non empty string defining the url (can be local) from which the application has to be updated and an optional username and userpassword ex ''url:username@password'' (username and/or password can be empty). <br> params: a map whose content depends on the Application and the content of the Update package received by the ReadyAgent. Those params provide a way to give application specific update params. <br> <br> '''Response''' '''payload''': status: 2 bytes acknowledging the command <br> <br> '''Note''': There can be only one SoftwareUpdate request at a time. | + | Notify the Application that an update must be downloaded and installed from the url given into payload. <br> <br> '''Command payload''': <br> componentname: string that contains the application / bundle to update (the path '''does contain''' the assetid of the asset responsible for that update) <br> version: string, empty string (but not null!) to specify de-installation request, non empty string for regular update/install of software component. <br> URL: string; Can be empty when version is empty too, otherwise URL will be a non empty string defining the url (can be local) from which the application has to be updated and an optional username and userpassword ex ''url:username@password'' (username and/or password can be empty). <br> params: a map whose content depends on the Application and the content of the Update package received by the ReadyAgent. Those params provide a way to give application specific update params. <br> <br> '''Response''' '''payload''': <code>status</code>: 2 bytes acknowledging the command <br> <br> '''Note''': There can be only one SoftwareUpdate request at a time. |
|- | |- | ||
| | | | ||
Line 206: | Line 206: | ||
App→RA | App→RA | ||
| | | | ||
− | Return the result of the previous SoftwareUpdate request. <br> <br> '''Command payload''': a list of 2 objects: <br> componentname: a string holding the name of the component <br> update status code: integer (see [[Software Update Module]] error code documentation) <br> <br> '''Response''' '''payload''': status: 2 bytes acknowledging the command <br> <br> <br> '''Note''': There can be only one SoftwareUpdate request at a time. | + | Return the result of the previous SoftwareUpdate request. <br> <br> '''Command payload''': a list of 2 objects: <br> componentname: a string holding the name of the component <br> update status code: integer (see [[Software Update Module]] error code documentation) <br> <br> '''Response''' '''payload''': <code>status</code>: 2 bytes acknowledging the command <br> <br> <br> '''Note''': There can be only one SoftwareUpdate request at a time. |
|- | |- | ||
| | | | ||
Line 215: | Line 215: | ||
RA→App | RA→App | ||
| | | | ||
− | Notify the application that the update's status has changed <br> <br> '''Command payload''': a list of 2 objects: <br> status: an integer representing the current update status. <br> details: a string containing additionnal informations for this status. | + | Notify the application that the update's status has changed <br> <br> '''Command payload''': a list of 2 objects: <br> <code>status</code>: an integer representing the current update status. <br> <code>details</code>: a string containing additionnal informations for this status. |
|- | |- | ||
| | | | ||
Line 224: | Line 224: | ||
App→RA | App→RA | ||
| | | | ||
− | Request agent to change the current update status <br> <br> '''Command payload''': <br> status: an integer representing the new required update status. | + | Request agent to change the current update status <br> <br> '''Command payload''': <br> <code>status</code>: an integer representing the new required update status. |
|- | |- | ||
| | | | ||
Line 274: | Line 274: | ||
| | | | ||
Push an acknowledge to data manager, given trigger policy. <br> '''Command payload:''' <br> an hashmap with a fields: | Push an acknowledge to data manager, given trigger policy. <br> '''Command payload:''' <br> an hashmap with a fields: | ||
− | * ticket: the ticket identifying the message to acknowledge, | + | * <code>ticket</code>: the ticket identifying the message to acknowledge, |
− | * status: status code (integer) for the acknowledge (0=OK, other value means error) | + | * <code>status</code>: status code (integer) for the acknowledge (0=OK, other value means error) |
− | * message: error message to send along with status code in the acknowledge | + | * <code>message</code>: error message to send along with status code in the acknowledge |
− | * policy: triggering policy (nil refers to the default policy) | + | * <code>policy</code>: triggering policy (nil refers to the default policy) |
− | * persisted: whether the acknowledge has to be stored in ram or flash. <br> '''Response:''' 2 bytes acknowledgement. | + | * <code>persisted</code>: whether the acknowledge has to be stored in ram or flash. <br> '''Response:''' 2 bytes acknowledgement. |
|- | |- | ||
| | | | ||
Line 288: | Line 288: | ||
| | | | ||
Create a new structured table <br> <br> '''Command payload:''' <br> an hashmap with fields: | Create a new structured table <br> <br> '''Command payload:''' <br> an hashmap with fields: | ||
− | * asset: name of the asset | + | * <code>asset</code>: name of the asset |
− | * storage: "ram" or "flash" | + | * <code>storage</code>: "ram" or "flash" |
− | * policy: triggering policy (nil refers to the default policy) | + | * <code>policy</code>: triggering policy (nil refers to the default policy) |
− | * path: common path prefix for table data | + | * <code>path</code>: common path prefix for table data |
− | * columns: columns configuration, as used by stagedb's constructor. <br> '''Response:''' 2 bytes acknowledgement, plus a table identifier to be used in further operations on this table | + | * <code>columns</code>: columns configuration, as used by stagedb's constructor. <br> '''Response:''' 2 bytes acknowledgement, plus a table identifier to be used in further operations on this table |
|- | |- | ||
| | | | ||
Line 302: | Line 302: | ||
| | | | ||
Push a row of data in an existing data table <br> <br> '''Command payload:''' <br> an hashmap with fields: | Push a row of data in an existing data table <br> <br> '''Command payload:''' <br> an hashmap with fields: | ||
− | * table: table identifier | + | * <code>table</code>: table identifier |
− | * row: list of data to push <br> <br> '''Response''': 2 bytes acknowledgement. | + | * <code>row</code>: list of data to push <br> <br> '''Response''': 2 bytes acknowledgement. |
|- | |- | ||
| | | | ||
Line 313: | Line 313: | ||
| | | | ||
Set a maximum number of rows in the table. The table will auto-flush itself when it reaches that number <br> <br> '''Command payload:''' <br> an hashmap with fields: | Set a maximum number of rows in the table. The table will auto-flush itself when it reaches that number <br> <br> '''Command payload:''' <br> an hashmap with fields: | ||
− | * table: table identifier | + | * <code>table</code>: table identifier |
− | * maxrows: max # of row in the table <br> '''Response:''' 2 bytes acknowledgement. | + | * <code>maxrows</code>: max # of row in the table <br> '''Response:''' 2 bytes acknowledgement. |
|- | |- | ||
| | | | ||
Line 324: | Line 324: | ||
| | | | ||
Remove all content from a table <br> <br> '''Command payload:''' <br> an hashmap with fields: | Remove all content from a table <br> <br> '''Command payload:''' <br> an hashmap with fields: | ||
− | * table: table identifier <br> <br> '''Response:''' 2 bytes acknowledgement. | + | * <code>table</code>: table identifier <br> <br> '''Response:''' 2 bytes acknowledgement. |
|- | |- | ||
| | | | ||
Line 334: | Line 334: | ||
| | | | ||
Setup a new consolidation table <br> <br> '''Command payload:''' <br> an hashmap with fields: | Setup a new consolidation table <br> <br> '''Command payload:''' <br> an hashmap with fields: | ||
− | * src: source table identifier | + | * <code>src</code>: source table identifier |
− | * path: common path prefix for table data | + | * <code>path</code>: common path prefix for table data |
− | * columns: columns configuration, as used by stagedb's constructor | + | * <code>columns</code>: columns configuration, as used by stagedb's constructor |
− | * storage: "ram" or "flash" | + | * <code>storage</code>: "ram" or "flash" |
− | * send_queue: send triggering policy for destination table (nil refers to the default policy) | + | * <code>send_queue</code>: send triggering policy for destination table (nil refers to the default policy) |
− | * conso_queue: consolidation policy for source table (nil refers to the default policy) <br> <br> '''Response:''' 2 bytes acknowledgement, plus destination table identifier to be used in further operations on this table | + | * <code>conso_queue</code>: consolidation policy for source table (nil refers to the default policy) <br> <br> '''Response:''' 2 bytes acknowledgement, plus destination table identifier to be used in further operations on this table |
|- | |- | ||
| | | | ||
Line 349: | Line 349: | ||
| | | | ||
Consolidate content of table immediately <br> <br> '''Command payload:''' <br> an hashmap with fields: | Consolidate content of table immediately <br> <br> '''Command payload:''' <br> an hashmap with fields: | ||
− | * table: table identifier | + | * <code>table</code>: table identifier |
− | * dont_reset: (Boolean) if true, the table's content isn't erased after it's been consolidated. <br> <br> '''Response:''' 2 bytes acknowledgement. | + | * <code>dont_reset</code>: (Boolean) if true, the table's content isn't erased after it's been consolidated. <br> <br> '''Response:''' 2 bytes acknowledgement. |
|- | |- | ||
| | | | ||
Line 360: | Line 360: | ||
| | | | ||
Send content of table to server immediately <br> <br> '''Command payload:''' <br> an hashmap with fields: | Send content of table to server immediately <br> <br> '''Command payload:''' <br> an hashmap with fields: | ||
− | * table: table identifier | + | * <code>table</code>: table identifier |
− | * dont_reset: (Boolean) if true, the table's content isn't erased after it's been sent. <br> '''Response:''' 2 bytes acknowledgement. | + | * <code>dont_reset</code>: (Boolean) if true, the table's content isn't erased after it's been sent. <br> '''Response:''' 2 bytes acknowledgement. |
|- | |- | ||
| | | | ||
Line 371: | Line 371: | ||
| | | | ||
Requests reboot of the system running the ReadyAgent. The reboot will occur after a small delay. <br> '''Command payload:''' | Requests reboot of the system running the ReadyAgent. The reboot will occur after a small delay. <br> '''Command payload:''' | ||
− | * reason: string describing the reason to request the reboot, the reason will be displayed in the ReadyAgent logs. | + | * <code>reason</code>: string describing the reason to request the reboot, the reason will be displayed in the ReadyAgent logs. |
* '''Response:''' 2 bytes acknowledgement. | * '''Response:''' 2 bytes acknowledgement. | ||
|} | |} |
Revision as of 10:16, 1 March 2013
On the embedded target, several processes (tasks/threads/modules/etc, depending on the target) are running and providing simple services.
The ReadyAgent and the different clients (assets) need to exchange data. This micro protocol specify the way of exchanging those data.
The communication is done using a standard IPC, i.e. a socket on localhost. However the protocol does not require that socket must be used, any transport layer that provide the same level of features can be used.
On a linux target, the ReadyAgent proxy opens a socket on localhost, default port is 9999. The client can connect to it when it needs to send data or be able to receive data from a remote server.
All Commands expect a Response. The Response has the same command id and the same request id, but the bit0 of the status byte is set to 1.
Commands and Responses can be interleaved, and a maximum of 256 Commands (same or different ones) can be running at the same time.
A frame (Command or Response) is a set of bytes, composed of a header followed by a payload.
Header is composed of 8 bytes
|
2 bytes |
type |
1 byte:
|
|
1 byte: unsigned integer to code command request id |
|
4 bytes: BigEndian coded unsigned integer. Size of payload in bytes |
Command payload is encoded in JSON
|
' |
Response Payload is composed of bytes which may be interpreted according to the 'command' field from the header, however it contains at least 2 bytes that are interpreted as the status of the response
|
2 bytes: if status == 0 the command went OK, if status != 0 an error occurred. |
|
' |
List of commands and their respective payloads.
ID |
Command ID |
Request Direction |
Description |
---|---|---|---|
1 |
SendData |
RA↔App |
Data coming from server |
2 |
Register |
App→RA |
Register client asset/service to ReadyAgent
|
3 |
Unregister |
App→RA |
Unregisters a path previously registered with "Register" |
4 |
ConnectToServer |
App→RA |
Forces the agent to connect to the server |
7 |
RegisterSMSListener |
App→RA |
Register a client as a SMS listener to the ReadyAgent. |
51 |
UnregisterSMSListener |
App→RA |
Unregister a client as a SMS listener to the ReadyAgent. |
8 |
NewSMS |
RA→App |
Notify an application that a SMS is received |
52 |
SendSMS |
App→RA |
Used by the application to send a SMS |
9 |
GetVariable |
App→RA |
Retrieve a variable from the Core Agent. |
10 |
SetVariable |
App→RA |
Set a variable on the Core Agent. |
11 |
RegisterVariable |
App→RA |
Register one variable or path to get notification when it changes. |
12 |
NotifyVariable |
RA→App |
Notify that a variable changed. |
13 |
DeRegisterVariable |
App→RA |
Cancel previous registration for watching variable changes. |
20 |
SoftwareUpdate |
RA→App |
Notify the Application that an update must be downloaded and installed from the url given into payload. |
21 |
SoftwareUpdateResult |
App→RA |
Return the result of the previous SoftwareUpdate request. |
22 |
SoftwareUpdateStatus |
RA→App |
Notify the application that the update's status has changed |
23 |
SoftwareUpdateRequest |
App→RA |
Request agent to change the current update status |
24 |
RegisterUpdateListener |
App→RA |
Register a callback to be called when the update status has changed. This registration is not specific to the asset, the registration is available for the whole application |
25 |
UnregisterUpdateListener |
App→RA |
Unregister the callback previously registered by the application |
30 |
PData |
App→RA |
Push some unstructured data to the data manager
|
32 |
PFlush |
App→RA |
Force the immediate flush of a given trigger policy. |
33 |
PAcknowledge |
App→RA |
Push an acknowledge to data manager, given trigger policy.
|
40 |
TableNew |
App→RA |
Create a new structured table
|
41 |
TableRow |
App→RA |
Push a row of data in an existing data table
|
43 |
TableSetMaxRows |
App→RA |
Set a maximum number of rows in the table. The table will auto-flush itself when it reaches that number
|
44 |
TableReset |
App→RA |
Remove all content from a table
|
45 |
ConsoNew |
App→RA |
Setup a new consolidation table
|
46 |
ConsoTrigger |
App→RA |
Consolidate content of table immediately
|
47 |
SendTrigger |
App→RA |
Send content of table to server immediately
|
50 |
Reboot |
App→RA |
Requests reboot of the system running the ReadyAgent. The reboot will occur after a small delay.
|