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"
(Updating TableRow command spec) |
|||
(2 intermediate revisions by one other user not shown) | |||
Line 1: | Line 1: | ||
On the embedded target, several processes (tasks/threads/modules/etc, depending on the target) are running and providing simple services. | On the embedded target, several processes (tasks/threads/modules/etc, depending on the target) are running and providing simple services. | ||
− | The | + | The Mihini Agent 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.<br> On a linux target, the | + | 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.<br> On a linux target, the Mihini Agent 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. | 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. | ||
Line 86: | Line 86: | ||
App→RA | App→RA | ||
| | | | ||
− | Register client asset/service to | + | Register client asset/service to Mihini Agent <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 116: | Line 116: | ||
App→RA | App→RA | ||
| | | | ||
− | Register a client as a SMS listener to the | + | Register a client as a SMS listener to the Mihini Agent. <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 125: | Line 125: | ||
App→RA | App→RA | ||
| | | | ||
− | Unregister a client as a SMS listener to the | + | Unregister a client as a SMS listener to the Mihini Agent. <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 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 | + | Notify the Application that an update must be downloaded and installed from the url given into payload. <br> <br> '''Command payload''': <br> <code>componentname</code>: string that contains the application / bundle to update (the path '''does contain''' the assetid of the asset responsible for that update) <br> <code>version</code>: string, empty string (but not null!) to specify de-installation request, non empty string for regular update/install of software component. <br> <code>URL</code>: 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> <code>params</code>: a map whose content depends on the Application and the content of the Update package received by the Mihini Agent. 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 252: | Line 252: | ||
| | | | ||
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: | ||
− | * asset: name of the asset | + | * <code>asset</code>: name of the asset |
− | * queue: triggering policy (nil refers to the default policy) | + | * <code>queue</code>: triggering policy (nil refers to the default policy) |
− | * path: common path prefix for sent data | + | * <code>path</code>: common path prefix for sent data |
− | * data: possibly nested table of path suffix / data pairs <br> <br> '''Response:''' 2 bytes acknowledgement. | + | * <code>data</code>: possibly nested table of path suffix / data pairs <br> <br> '''Response:''' 2 bytes acknowledgement. |
|- | |- | ||
| | | | ||
Line 264: | Line 264: | ||
App→RA | App→RA | ||
| | | | ||
− | Force the immediate flush of a given trigger policy. <br> '''Command payload:''' an hashmap with a field | + | Force the immediate flush of a given trigger policy. <br> '''Command payload:''' an hashmap with a field <code>policy</code> containing the name of the policy to flush. If no name is given, the "default" policy is flushed. <br> '''Response:''' 2 bytes acknowledgement. |
|- | |- | ||
| | | | ||
Line 303: | Line 303: | ||
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: | ||
* <code>table</code>: table identifier | * <code>table</code>: table identifier | ||
− | * <code>row</code>: | + | * <code>row</code>: map of data to push, which format is { columnname1 = value, columnname2 = value, ... } <br> <br> '''Response''': 2 bytes acknowledgement. |
|- | |- | ||
| | | | ||
Line 370: | Line 370: | ||
App→RA | App→RA | ||
| | | | ||
− | Requests reboot of the system running the | + | Requests reboot of the system running the Mihini Agent. The reboot will occur after a small delay. <br> '''Command payload:''' |
− | * <code>reason</code>: string describing the reason to request the reboot, the reason will be displayed in the | + | * <code>reason</code>: string describing the reason to request the reboot, the reason will be displayed in the Mihini Agent logs. |
* '''Response:''' 2 bytes acknowledgement. | * '''Response:''' 2 bytes acknowledgement. | ||
|} | |} |
Latest revision as of 09:23, 11 March 2013
On the embedded target, several processes (tasks/threads/modules/etc, depending on the target) are running and providing simple services.
The Mihini Agent 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 Mihini Agent 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 Mihini Agent
|
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 Mihini Agent. |
51 |
UnregisterSMSListener |
App→RA |
Unregister a client as a SMS listener to the Mihini Agent. |
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 Mihini Agent. The reboot will occur after a small delay.
|