Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Mihini/Embedded Micro Protocol"
(New page: 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)...) |
|||
Line 75: | Line 75: | ||
SendData | SendData | ||
| | | | ||
− | RA& | + | 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''': status: 2 bytes acknowledging the command. | ||
Line 84: | Line 84: | ||
Register | Register | ||
| | | | ||
− | App | + | 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''': status: 2 bytes acknowledging the command. <br> <br> '''Remarks''': | ||
Line 96: | Line 96: | ||
Unregister | Unregister | ||
| | | | ||
− | App | + | App→RA |
| | | | ||
Unregisters a path previously registered with "Register" | Unregisters a path previously registered with "Register" | ||
Line 105: | Line 105: | ||
ConnectToServer | ConnectToServer | ||
| | | | ||
− | App | + | App→RA |
| | | | ||
Forces the agent to connect to the server <br> The connection is made synchronously if no latency is specified (i.e. the connection is finished when response is sent), otherwise when <br> a latency is specified the connection is likely to happen after the response is sent. <br> '''Command payload''': optional positive integer: the latency in seconds before executing the connect to server action. If no latency specified, the connexion is made synchronously <br> '''Response''' '''payload''': status: 2 bytes acknowledging the command. The response has a status == 0 when no latency was specified and the connection to the server was successful. <br> If latency was specified, then status==0 means that the connection request was successfully scheduled | Forces the agent to connect to the server <br> The connection is made synchronously if no latency is specified (i.e. the connection is finished when response is sent), otherwise when <br> a latency is specified the connection is likely to happen after the response is sent. <br> '''Command payload''': optional positive integer: the latency in seconds before executing the connect to server action. If no latency specified, the connexion is made synchronously <br> '''Response''' '''payload''': status: 2 bytes acknowledging the command. The response has a status == 0 when no latency was specified and the connection to the server was successful. <br> If latency was specified, then status==0 means that the connection request was successfully scheduled | ||
Line 114: | Line 114: | ||
RegisterSMSListener | RegisterSMSListener | ||
| | | | ||
− | App | + | App→RA |
| | | | ||
Register a client as a SMS listener to the ReadyAgent. <br> <br> '''Command payload''': a list of two objects: <br> String: Phone number pattern to listen to. <br> String: Message content pattern to listen to. <br> <br> '''Response''' '''payload''': <br> status: 2 bytes acknowledging the command. <br> if the status is OK (=0) <br> id: an unsigned integer, giving the registration id, identifying the sms listening registration for the combination: (sms module instance/phone pattern/message pattern). This is the id to be used to call UnregisterSMSListener command. <br> <br> '''Note''': Patterns syntax should conformed to [[lua patterns]] | Register a client as a SMS listener to the ReadyAgent. <br> <br> '''Command payload''': a list of two objects: <br> String: Phone number pattern to listen to. <br> String: Message content pattern to listen to. <br> <br> '''Response''' '''payload''': <br> status: 2 bytes acknowledging the command. <br> if the status is OK (=0) <br> id: an unsigned integer, giving the registration id, identifying the sms listening registration for the combination: (sms module instance/phone pattern/message pattern). This is the id to be used to call UnregisterSMSListener command. <br> <br> '''Note''': Patterns syntax should conformed to [[lua patterns]] | ||
Line 123: | Line 123: | ||
UnregisterSMSListener | UnregisterSMSListener | ||
| | | | ||
− | App | + | 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> status: 2 bytes acknowledging the command. | ||
Line 132: | Line 132: | ||
NewSMS | NewSMS | ||
| | | | ||
− | RA | + | RA→App |
| | | | ||
Notify an application that a SMS is received <br> '''Command payload:''' a list of 3 objects: <br> String: Phone number of the sender (for incoming messages) / recipient (for outgoing messages) <br> String: payload of the message <br> Integer: the registration id (i.e. the id for the couple message pattern and sender pattern) that matched the incoming sms <br> '''Response:''' 2 bytes acknowledgement. | Notify an application that a SMS is received <br> '''Command payload:''' a list of 3 objects: <br> String: Phone number of the sender (for incoming messages) / recipient (for outgoing messages) <br> String: payload of the message <br> Integer: the registration id (i.e. the id for the couple message pattern and sender pattern) that matched the incoming sms <br> '''Response:''' 2 bytes acknowledgement. | ||
Line 141: | Line 141: | ||
SendSMS | SendSMS | ||
| | | | ||
− | App | + | 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''': status: 2 bytes acknowledging the command | ||
Line 150: | Line 150: | ||
GetVariable | GetVariable | ||
| | | | ||
− | App | + | 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> 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 | ||
Line 159: | Line 159: | ||
SetVariable | SetVariable | ||
| | | | ||
− | App | + | 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> status: 2 bytes acknowledging the command. | ||
Line 168: | Line 168: | ||
RegisterVariable | RegisterVariable | ||
| | | | ||
− | App | + | 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> 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. | ||
Line 177: | Line 177: | ||
NotifyVariable | NotifyVariable | ||
| | | | ||
− | RA | + | 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> status: 2 bytes acknowledging the command. | ||
Line 186: | Line 186: | ||
DeRegisterVariable | DeRegisterVariable | ||
| | | | ||
− | App | + | 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> status: 2 bytes acknowledging the command. | ||
Line 195: | Line 195: | ||
SoftwareUpdate | SoftwareUpdate | ||
| | | | ||
− | RA | + | 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''': status: 2 bytes acknowledging the command <br> <br> '''Note''': There can be only one SoftwareUpdate request at a time. | ||
Line 204: | Line 204: | ||
SoftwareUpdateResult | SoftwareUpdateResult | ||
| | | | ||
− | App | + | 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''': status: 2 bytes acknowledging the command <br> <br> <br> '''Note''': There can be only one SoftwareUpdate request at a time. | ||
Line 213: | Line 213: | ||
SoftwareUpdateStatus | SoftwareUpdateStatus | ||
| | | | ||
− | RA | + | 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> status: an integer representing the current update status. <br> details: a string containing additionnal informations for this status. | ||
Line 222: | Line 222: | ||
SoftwareUpdateRequest | SoftwareUpdateRequest | ||
| | | | ||
− | App | + | 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> status: an integer representing the new required update status. | ||
Line 231: | Line 231: | ||
RegisterUpdateListener | RegisterUpdateListener | ||
| | | | ||
− | App | + | 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 | 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 | ||
Line 240: | Line 240: | ||
UnregisterUpdateListener | UnregisterUpdateListener | ||
| | | | ||
− | App | + | App→RA |
| | | | ||
Unregister the callback previously registered by the application | Unregister the callback previously registered by the application | ||
Line 249: | Line 249: | ||
PData | PData | ||
| | | | ||
− | App | + | App→RA |
| | | | ||
Push some unstructured data to the data manager <br> <br> '''Command payload:''' <br> an hashmap with fields: | Push some unstructured data to the data manager <br> <br> '''Command payload:''' <br> an hashmap with fields: | ||
Line 262: | Line 262: | ||
PFlush | PFlush | ||
| | | | ||
− | App | + | App→RA |
| | | | ||
Force the immediate flush of a given trigger policy. <br> '''Command payload:''' an hashmap with a field "policy" containing the name of the policy to flush. If no name is given, the "default" policy is flushed. <br> '''Response:''' 2 bytes acknowledgement. | Force the immediate flush of a given trigger policy. <br> '''Command payload:''' an hashmap with a field "policy" containing the name of the policy to flush. If no name is given, the "default" policy is flushed. <br> '''Response:''' 2 bytes acknowledgement. | ||
Line 271: | Line 271: | ||
PAcknowledge | PAcknowledge | ||
| | | | ||
− | App | + | App→RA |
| | | | ||
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: | ||
Line 285: | Line 285: | ||
TableNew | TableNew | ||
| | | | ||
− | App | + | App→RA |
| | | | ||
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: | ||
Line 299: | Line 299: | ||
TableRow | TableRow | ||
| | | | ||
− | App | + | App→RA |
| | | | ||
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: | ||
Line 310: | Line 310: | ||
TableSetMaxRows | TableSetMaxRows | ||
| | | | ||
− | App | + | App→RA |
| | | | ||
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: | ||
Line 321: | Line 321: | ||
TableReset | TableReset | ||
| | | | ||
− | App | + | App→RA |
| | | | ||
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: | ||
Line 331: | Line 331: | ||
ConsoNew | ConsoNew | ||
| | | | ||
− | App | + | App→RA |
| | | | ||
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: | ||
Line 346: | Line 346: | ||
ConsoTrigger | ConsoTrigger | ||
| | | | ||
− | App | + | App→RA |
| | | | ||
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: | ||
Line 357: | Line 357: | ||
SendTrigger | SendTrigger | ||
| | | | ||
− | App | + | App→RA |
| | | | ||
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: | ||
Line 368: | Line 368: | ||
Reboot | Reboot | ||
| | | | ||
− | App | + | App→RA |
| | | | ||
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:''' |
Revision as of 10:09, 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.
|