Jump to: navigation, search

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<->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''': status: 2 bytes acknowledging the command.
Line 84: Line 84:
 
Register
 
Register
 
|
 
|
App-&gt;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 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-&gt;RA
+
App&rarr;RA
 
|
 
|
 
Unregisters a path previously registered with "Register"
 
Unregisters a path previously registered with "Register"
Line 105: Line 105:
 
ConnectToServer
 
ConnectToServer
 
|
 
|
App-&gt;RA
+
App&rarr;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-&gt;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 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-&gt;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 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-&gt;App
+
RA&rarr;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-&gt;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''': status: 2 bytes acknowledging the command
Line 150: Line 150:
 
GetVariable
 
GetVariable
 
|
 
|
App-&gt;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> 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-&gt;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> status: 2 bytes acknowledging the command.
Line 168: Line 168:
 
RegisterVariable
 
RegisterVariable
 
|
 
|
App-&gt;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> 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-&gt;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> status: 2 bytes acknowledging the command.
Line 186: Line 186:
 
DeRegisterVariable
 
DeRegisterVariable
 
|
 
|
App-&gt;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> status: 2 bytes acknowledging the command.
Line 195: Line 195:
 
SoftwareUpdate
 
SoftwareUpdate
 
|
 
|
RA-&gt;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> 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-&gt;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''': 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-&gt;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> 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-&gt;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> status: an integer representing the new required update status.
Line 231: Line 231:
 
RegisterUpdateListener
 
RegisterUpdateListener
 
|
 
|
App-&gt;RA
+
App&rarr;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-&gt;RA
+
App&rarr;RA
 
|
 
|
 
Unregister the callback previously registered by the application
 
Unregister the callback previously registered by the application
Line 249: Line 249:
 
PData
 
PData
 
|
 
|
App-&gt;RA
+
App&rarr;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-&gt;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 "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-&gt;RA
+
App&rarr;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-&gt;RA
+
App&rarr;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-&gt;RA
+
App&rarr;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-&gt;RA
+
App&rarr;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-&gt;RA
+
App&rarr;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-&gt;RA
+
App&rarr;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-&gt;RA
+
App&rarr;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-&gt;RA
+
App&rarr;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-&gt;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 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

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 ReadyAgent

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 ReadyAgent.

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 ReadyAgent.

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 ReadyAgent. 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: list of data to push

    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 ReadyAgent. 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 ReadyAgent logs.
  • Response: 2 bytes acknowledgement.