Jump to: navigation, search

Difference between revisions of "Mihini/Embedded Micro Protocol"

(Updating TableRow command spec)
 
(3 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 ReadyAgent and the different clients (assets) need to exchange data. This micro protocol specify the way of exchanging those data.
+
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 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.
+
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 77: Line 77:
 
RA&harr;App
 
RA&harr;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&rarr;RA
 
App&rarr;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 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&rarr;RA
 
App&rarr;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 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&rarr;RA
 
App&rarr;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 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 143: Line 143:
 
App&rarr;RA
 
App&rarr;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&rarr;RA
 
App&rarr;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&rarr;RA
 
App&rarr;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&rarr;RA
 
App&rarr;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&rarr;App
 
RA&rarr;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&rarr;RA
 
App&rarr;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&rarr;App
 
RA&rarr;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> <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 206: Line 206:
 
App&rarr;RA
 
App&rarr;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&rarr;App
 
RA&rarr;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&rarr;RA
 
App&rarr;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 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&rarr;RA
 
App&rarr;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 <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 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>: map of data to push, which format is { columnname1 = value, columnname2 = value, ... } <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 370: Line 370:
 
App&rarr;RA
 
App&rarr;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 Mihini Agent. 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 Mihini Agent logs.
 
* '''Response:''' 2 bytes acknowledgement.
 
* '''Response:''' 2 bytes acknowledgement.
 
|}
 
|}

Latest revision as of 08: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

command

2 bytes

type

1 byte:

  • bit0: 0-command, 1-response
  • bit1-7: reserved (set to 0)

requestid

1 byte: unsigned integer to code command request id

payloadsize

4 bytes: BigEndian coded unsigned integer. Size of payload in bytes


Command payload is encoded in JSON

payload

'payloadsize' bytes


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

status

2 bytes: if status == 0 the command went OK, if status != 0 an error occurred.
the status value is to be interpreted as a swi_status_t

payload

'payloadsize-2' bytes of JSON


List of commands and their respective payloads.

ID

Command ID

Request Direction

Description

1

SendData

RA↔App

Data coming from server

Command payload: The payload just contains all the data
Response payload: status: 2 bytes acknowledging the command.

2

Register

App→RA

Register client asset/service to Mihini Agent

Command payload: the path for which this client want to receive messages (a JSON string).
Response payload: status: 2 bytes acknowledging the command.

Remarks:

  • 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.
  • If several assets were registered, closing IPC will unregister all the assets linked to that IPC.

3

Unregister

App→RA

Unregisters a path previously registered with "Register"

4

ConnectToServer

App→RA

Forces the agent to connect to the server
The connection is made synchronously if no latency is specified (i.e. the connection is finished when response is sent), otherwise when
a latency is specified the connection is likely to happen after the response is sent.
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
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.
If latency was specified, then status==0 means that the connection request was successfully scheduled

7

RegisterSMSListener

App→RA

Register a client as a SMS listener to the Mihini Agent.

Command payload: a list of two objects:
String: Phone number pattern to listen to.
String: Message content pattern to listen to.

Response payload:
status: 2 bytes acknowledging the command.
if the status is OK (=0)
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.

Note: Patterns syntax should conformed to lua patterns

51

UnregisterSMSListener

App→RA

Unregister a client as a SMS listener to the Mihini Agent.

Command payload:
id: an unsigned integer, the registration id to unregister, as returned by RegisterSMSListener command

Response payload:
status: 2 bytes acknowledging the command.

8

NewSMS

RA→App

Notify an application that a SMS is received
Command payload: a list of 3 objects:
String: Phone number of the sender (for incoming messages) / recipient (for outgoing messages)
String: payload of the message
Integer: the registration id (i.e. the id for the couple message pattern and sender pattern) that matched the incoming sms
Response: 2 bytes acknowledgement.

52

SendSMS

App→RA

Used by the application to send a SMS
Command payload: a list of 3 objects:
String: Phone number of the recipient of the outgoing message
String: payload of the message
String: format of the SMS, supported values are "8bits", "7bits", "ucs2"

Response payload: status: 2 bytes acknowledging the command

9

GetVariable

App→RA

Retrieve a variable from the Core Agent.

Command payload: a list of 2 objects:
String: name of the variable to get (usually a string that is a path !)
Integer: maximum depth of the variable retrieval. This is useful when doing a get on a sub tree. This should be a number.
Response payload:
status: 2 bytes acknowledging the command.
if the status is OK (=0)
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

10

SetVariable

App→RA

Set a variable on the Core Agent.

Command payload: a list of 2 objects:
1 String representing the variable to set (usually a string that is a path !)
1 object representing the value of the variable (it can be a hashtable)
Response payload:
status: 2 bytes acknowledging the command.

11

RegisterVariable

App→RA

Register one variable or path to get notification when it changes.

Command payload: a list of 2 objects:
reg vars: list of strings representing the variables to register to, each string is a path to register to
passive vars: list of strings, each string identifying the path of a passive variable

Response payload:
status: 2 bytes acknowledging the command.
registration id : string identifying this registration for variable change, this id is to be given to DeRegisterVariable command.

12

NotifyVariable

RA→App

Notify that a variable changed.

Command payload: a list of 2 objects:
1 string representing the registration id that provoked this notification
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

Response payload:
status: 2 bytes acknowledging the command.

13

DeRegisterVariable

App→RA

Cancel previous registration for watching variable changes.

Command payload:
String representing the registration id (sent in RegisterVariable command Response payload)

Response payload:
status: 2 bytes acknowledging the command.

20

SoftwareUpdate

RA→App

Notify the Application that an update must be downloaded and installed from the url given into payload.

Command payload:
componentname: string that contains the application / bundle to update (the path does contain the assetid of the asset responsible for that update)
version: string, empty string (but not null!) to specify de-installation request, non empty string for regular update/install of software component.
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).
params: 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.

Response payload: status: 2 bytes acknowledging the command

Note: There can be only one SoftwareUpdate request at a time.

21

SoftwareUpdateResult

App→RA

Return the result of the previous SoftwareUpdate request.

Command payload: a list of 2 objects:
componentname: a string holding the name of the component
update status code: integer (see Software Update Module error code documentation)

Response payload: status: 2 bytes acknowledging the command


Note: There can be only one SoftwareUpdate request at a time.

22

SoftwareUpdateStatus

RA→App

Notify the application that the update's status has changed

Command payload: a list of 2 objects:
status: an integer representing the current update status.
details: a string containing additionnal informations for this status.

23

SoftwareUpdateRequest

App→RA

Request agent to change the current update status

Command payload:
status: an integer representing the new required 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

Command payload:
an hashmap with fields:

  • asset: name of the asset
  • queue: triggering policy (nil refers to the default policy)
  • path: common path prefix for sent data
  • data: possibly nested table of path suffix / data pairs

    Response: 2 bytes acknowledgement.

32

PFlush

App→RA

Force the immediate flush of a given trigger policy.
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.
Response: 2 bytes acknowledgement.

33

PAcknowledge

App→RA

Push an acknowledge to data manager, given trigger policy.
Command payload:
an hashmap with a fields:

  • ticket: the ticket identifying the message to acknowledge,
  • status: status code (integer) for the acknowledge (0=OK, other value means error)
  • message: error message to send along with status code in the acknowledge
  • policy: triggering policy (nil refers to the default policy)
  • persisted: whether the acknowledge has to be stored in ram or flash.
    Response: 2 bytes acknowledgement.

40

TableNew

App→RA

Create a new structured table

Command payload:
an hashmap with fields:

  • asset: name of the asset
  • storage: "ram" or "flash"
  • policy: triggering policy (nil refers to the default policy)
  • path: common path prefix for table data
  • columns: columns configuration, as used by stagedb's constructor.
    Response: 2 bytes acknowledgement, plus a table identifier to be used in further operations on this table

41

TableRow

App→RA

Push a row of data in an existing data table

Command payload:
an hashmap with fields:

  • table: table identifier
  • row: map of data to push, which format is { columnname1 = value, columnname2 = value, ... }

    Response: 2 bytes acknowledgement.

43

TableSetMaxRows

App→RA

Set a maximum number of rows in the table. The table will auto-flush itself when it reaches that number

Command payload:
an hashmap with fields:

  • table: table identifier
  • maxrows: max # of row in the table
    Response: 2 bytes acknowledgement.

44

TableReset

App→RA

Remove all content from a table

Command payload:
an hashmap with fields:

  • table: table identifier

    Response: 2 bytes acknowledgement.

45

ConsoNew

App→RA

Setup a new consolidation table

Command payload:
an hashmap with fields:

  • src: source table identifier
  • path: common path prefix for table data
  • columns: columns configuration, as used by stagedb's constructor
  • storage: "ram" or "flash"
  • send_queue: 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)

    Response: 2 bytes acknowledgement, plus destination table identifier to be used in further operations on this table

46

ConsoTrigger

App→RA

Consolidate content of table immediately

Command payload:
an hashmap with fields:

  • table: table identifier
  • dont_reset: (Boolean) if true, the table's content isn't erased after it's been consolidated.

    Response: 2 bytes acknowledgement.

47

SendTrigger

App→RA

Send content of table to server immediately

Command payload:
an hashmap with fields:

  • table: table identifier
  • dont_reset: (Boolean) if true, the table's content isn't erased after it's been sent.
    Response: 2 bytes acknowledgement.

50

Reboot

App→RA

Requests reboot of the system running the Mihini Agent. The reboot will occur after a small delay.
Command payload:

  • reason: string describing the reason to request the reboot, the reason will be displayed in the Mihini Agent logs.
  • Response: 2 bytes acknowledgement.