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/Device Management"
(→Commands) |
|||
(2 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
− | = Commands = | + | = Commands = |
− | + | ||
− | This | + | This page references all generic commands used by the platform. The commands are serialized and sent using M3DA Protocol. |
− | In order to send command from the server to the device, or from the device to the server, an M3DA data writing is to be done on a node path, encapsulated into an <code>M3DA::Message</code> object as stated into the protocol specification. | + | This is an "applicative level" specification opposed to the "serialization level" specification from the M3DA Protocol document. |
+ | |||
+ | In order to send command from the server to the device, or from the device to the server, an M3DA data writing is to be done on a node path, encapsulated into an <code>M3DA::Message</code> object as stated into the protocol specification. | ||
{| border="1" | {| border="1" | ||
|- | |- | ||
− | ! | + | ! |
− | '''Command Name''' | + | '''Command Name''' |
− | ! | + | ! |
− | '''Command Arguments<br> | + | '''Command Arguments<br>''' '''<sub>name → description (type)</sub>''' |
− | '''<sub>name | + | |
− | ! | + | ! |
− | '''Comments''' | + | '''Comments''' |
|- | |- | ||
− | !colspan="3" style="background: #FFFFCC;"| == ''Main'' == | + | ! colspan="3" style="background: #FFFFCC;" | == ''Main'' == |
|- | |- | ||
− | | | + | | |
− | ReadNode | + | ReadNode |
− | | | + | | |
− | "1" | + | "1" → path.of.the.node.to.read (string), |
− | ... | + | ... |
− | "n" | + | "n" → path.of.the.node.to.read (string) |
− | | | + | | |
− | Read a node or several nodes and its/their children (if any) from a tree. <br> The node can be either terminal (a leaf: to get the value of a property) or have sub nodes. In the later case the content of the node and all its sub nodes will be transmitted. <br> This command provokes the sending of Data Messages that will contain the data associated to that node. The data of the message is composed of a map that hold the properties as key, and their value as value. <br> <br> If a node contains a child, Data Messages will be sent recursively in order to present all the data of the sub nodes as well. If the specified node does not exist or contains no data, a nil value will be sent.<br> <br> '''Note''': ''path.of.the.node.to.read'' is a path that is not necessarily linked to the device or asset topology. In particular, the assetID is not repeated in that path. <br> Ex: Request bearer configuration it should use: "ReadNode config.network.bearers" | + | Read a node or several nodes and its/their children (if any) from a tree. <br> The node can be either terminal (a leaf: to get the value of a property) or have sub nodes. In the later case the content of the node and all its sub nodes will be transmitted. <br> This command provokes the sending of Data Messages that will contain the data associated to that node. The data of the message is composed of a map that hold the properties as key, and their value as value. <br> <br> If a node contains a child, Data Messages will be sent recursively in order to present all the data of the sub nodes as well. If the specified node does not exist or contains no data, a nil value will be sent.<br> <br> '''Note''': ''path.of.the.node.to.read'' is a path that is not necessarily linked to the device or asset topology. In particular, the assetID is not repeated in that path. <br> Ex: Request bearer configuration it should use: "ReadNode config.network.bearers" |
+ | |||
+ | <br> | ||
+ | |||
+ | '''Note''': the path can be set to "" (empty string) to request the full tree content. However, as the tree can contain a great amount of data, this particuliar request must be done with caution. | ||
|- | |- | ||
− | | | + | | |
− | Connect | + | Connect |
− | | | + | | |
− | | | + | | |
− | Ask the Mihini Agent to connect to the platform server. <br> | + | Ask the Mihini Agent to connect to the platform server. <br> The command must be addressed to the device (M3DA::Message.path = "@sys"). |
− | The command must be addressed to the device (M3DA::Message.path = "@sys"). | + | |
|- | |- | ||
− | | | + | | |
− | Reboot | + | Reboot |
− | | | + | | |
− | | | + | | |
− | Ask the device or one of its asset to reboot. <br> The device or the asset is designated thanks to the path of the M3DA::Message that wrap this command. | + | Ask the device or one of its asset to reboot. <br> The device or the asset is designated thanks to the path of the M3DA::Message that wrap this command. |
|- | |- | ||
− | | | + | | |
− | ResetToFactoryDefault | + | ResetToFactoryDefault |
− | | | + | | |
---- | ---- | ||
− | |||
− | + | "restart" | "1" → restart after setting reset (boolean|number) | |
− | + | ||
− | + | | | |
− | + | Reset agent settings to factory defaults. All persisted data about agent settings and installed software are lost. <br> <br> '''Impacted''' modules/functionalities: | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | ''' | + | |
− | ** M3DA security credentials are '''not''' cleared | + | **ReadyAgent persisted '''config''' is reset to '''defaultconfig <br>''' |
− | Note: | + | |
+ | '''( depending on the differences between defaultconfig.lua and persisted config, this operation may impact: server url, hearbeat, ..., or any ReadyAgent config parameter)''' | ||
+ | |||
+ | **Treemgr mapping are reset: it will be regenerated from .map files on next boot | ||
+ | **'''Persisted M3DA data''': asset and device data are reset | ||
+ | **'''Applications''' installed in ApplicationContainer are erased | ||
+ | **Update module: | ||
+ | ***deletion of any update in progress | ||
+ | ***'''software version list''' is cleared | ||
+ | |||
+ | '''Not impacted''' modules/functionalities: | ||
+ | |||
+ | **M3DA security credentials are '''not''' cleared | ||
+ | |||
+ | Note: | ||
+ | |||
+ | **This command is dependent on ReadyAgent integration, so ResetToFactoryDefault command implementation can differ from a device to another to fit integration needs, ReadyAgent product provides a generic implementation matching previous remarks<br> | ||
+ | |||
+ | <br> <br> | ||
− | |||
− | |||
− | |||
---- | ---- | ||
− | -> If this is a boolean value and it is true, it requests the agent to be restarted with a default timeout (6 seconds)<br> | + | |
− | -> If this is a number and it is greater than zero, it requests the agent to be restarted in "restart" seconds | + | -> If this is a boolean value and it is true, it requests the agent to be restarted with a default timeout (6 seconds)<br> -> If this is a number and it is greater than zero, it requests the agent to be restarted in "restart" seconds |
+ | |||
|- | |- | ||
− | !colspan="3" style="background: #FFFFCC;"| == ''Software update'' == | + | ! colspan="3" style="background: #FFFFCC;" | == ''Software update'' == |
|- | |- | ||
− | | | + | | |
− | ExecuteScript | + | ExecuteScript |
− | | | + | |
− | "url" | + | | |
− | signature | + | "url" | "1" → url to retrieve the Lua script (string) <br> <br> signature | "2" → signature of the script (string) |
− | | | + | |
− | -> url to retrieve the Lua script <br> The Lua script can be either Lua source file or precompiled Lua bytecode file. <br> -> signature of Lua Script <br> The signature will fit the security level defined within the ReadyAgent. <br> First step: Signature will be '''MD5 hash''', and will be sent in '''hexa''' in an ascii string. | + | | |
+ | -> url to retrieve the Lua script <br> The Lua script can be either Lua source file or precompiled Lua bytecode file. <br> -> signature of Lua Script <br> The signature will fit the security level defined within the ReadyAgent. <br> First step: Signature will be '''MD5 hash''', and will be sent in '''hexa''' in an ascii string. | ||
+ | |||
|- | |- | ||
− | | | + | | |
− | SoftwareUpdate | + | SoftwareUpdate |
− | | | + | |
− | "url" | + | | |
− | "signature" | + | "url" | "1" → url to download the package (string) <br> <br> "signature" | "2" → signature of the package (string) |
− | | | + | |
− | -> url provided by the server where the Software Update Package can be downloaded. <br> Must '''not''' end by a trailing "/" character, unless archive name contains one (not recommended) <br> -> signature of the Software Update Package <br> The signature will fit the security level defined within the ReadyAgent. <br> First step: Signature will be '''MD5 hash''', and will be sent in '''hexa''' in an ascii string which size must be 32 chars (prefixing zeros chars must be sent!), and in lower case only. | + | | |
+ | -> url provided by the server where the Software Update Package can be downloaded. <br> Must '''not''' end by a trailing "/" character, unless archive name contains one (not recommended) <br> -> signature of the Software Update Package <br> The signature will fit the security level defined within the ReadyAgent. <br> First step: Signature will be '''MD5 hash''', and will be sent in '''hexa''' in an ascii string which size must be 32 chars (prefixing zeros chars must be sent!), and in lower case only. | ||
+ | |||
|- | |- | ||
− | !colspan="3" style="background: #FFFFCC;"| == ''TCP Remote Connection'' == | + | ! colspan="3" style="background: #FFFFCC;" | == ''TCP Remote Connection'' == |
|- | |- | ||
− | | | + | | |
− | TCPRemoteConnect | + | TCPRemoteConnect |
− | | | + | |
− | | | + | | |
− | Install a TCP tunnel | + | | |
+ | Install a TCP tunnel | ||
+ | |||
|- | |- | ||
− | !colspan="3" style="background: #FFFFCC;"| == ''Log Upload'' == | + | ! colspan="3" style="background: #FFFFCC;" | == ''Log Upload'' == |
|- | |- | ||
− | | | + | | |
− | LogUpload | + | LogUpload |
− | | | + | |
− | "url" | + | | |
− | "logtype" | + | "url" | "1" → url (string) <br> "logtype" | "2" → log type (string in \{"ram" or "flash" \} ) |
− | | | + | |
− | The url where the logs are to be uploaded. Has to be of the form "ftp://" to request ftp upload, else "http://" for HTTP Post upload <br> string equal to: "ram" to retrieve logs in ram (i.e. only from current ReadyAgent execution), or "flash" to get the logs from flash space <br> Note: The content of flash or ram buffer depends on the log policy defined in ReadyAgent Config | + | | |
+ | The url where the logs are to be uploaded. Has to be of the form "ftp://" to request ftp upload, else "http://" for HTTP Post upload <br> string equal to: "ram" to retrieve logs in ram (i.e. only from current ReadyAgent execution), or "flash" to get the logs from flash space <br> Note: The content of flash or ram buffer depends on the log policy defined in ReadyAgent Config | ||
+ | |||
|- | |- | ||
− | !colspan="3" style="background: #FFFFCC;"| == ''Application Container'' == | + | ! colspan="3" style="background: #FFFFCC;" | == ''Application Container'' == |
|- | |- | ||
− | | | + | | |
− | appcon.start | + | appcon.start |
− | | | + | |
− | "appname" | + | | |
− | | | + | "appname" | "1" → application name (string) |
− | Start an application | + | |
+ | | | ||
+ | Start an application | ||
+ | |||
|- | |- | ||
− | | | + | | |
− | appcon.stop | + | appcon.stop |
− | | | + | |
− | "appname" | + | | |
− | | | + | "appname" | "1" → application name (string) |
− | Stop an application | + | |
+ | | | ||
+ | Stop an application | ||
+ | |||
|- | |- | ||
− | | | + | | |
− | appcon.autostart | + | appcon.autostart |
− | | | + | |
− | "appname" | + | | |
− | "autostart" | + | "appname" | "1" → application name (string)<br> "autostart" | "2" → autostart flag(boolean) |
− | | | + | |
− | Configure an application to start automatically or not. | + | | |
+ | Configure an application to start automatically or not. | ||
+ | |||
|} | |} | ||
− | = Variables = | + | = Variables = |
+ | |||
{| border="1" | {| border="1" | ||
|- | |- | ||
− | ! | + | ! |
− | Variable | + | Variable |
− | ! | + | |
− | Read/Write | + | ! |
− | ! | + | Read/Write |
− | Description | + | |
+ | ! | ||
+ | Description | ||
+ | |||
|- | |- | ||
− | | | + | | |
− | <code>@sys.appcon.list</code> | + | <code>@sys.appcon.list</code> |
− | | | + | |
− | RO | + | | |
− | | | + | RO |
− | list of all applications currently managed by appcon, as a single string of space-separated names | + | |
+ | | | ||
+ | list of all applications currently managed by appcon, as a single string of space-separated names | ||
+ | |||
|- | |- | ||
− | | | + | | |
− | <code>@sys.appcon.apps.<appname>.started</code> | + | <code>@sys.appcon.apps.<appname>.started</code> |
− | | | + | |
− | RW | + | | |
− | | | + | RW |
− | whether the application is currently started (Boolean) | + | |
+ | | | ||
+ | whether the application is currently started (Boolean) | ||
+ | |||
|- | |- | ||
− | | | + | | |
− | <code>@sys.appcon.apps.<appname>.autostart</code> | + | <code>@sys.appcon.apps.<appname>.autostart</code> |
− | | | + | |
− | RW | + | | |
− | | | + | RW |
− | whether the application starts automatically (Boolean) | + | |
+ | | | ||
+ | whether the application starts automatically (Boolean) | ||
+ | |||
|- | |- | ||
− | | | + | | |
− | <code>@sys.appcon.apps.<appname>.runnable</code> | + | <code>@sys.appcon.apps.<appname>.runnable</code> |
− | | | + | |
− | RO | + | | |
− | | | + | RO |
− | whether it is a runnable application | + | |
+ | | | ||
+ | whether it is a runnable application | ||
+ | |||
|- | |- | ||
− | | | + | | |
− | <code>@sys.appcon.apps.<appname>.<daemonattr></code> | + | <code>@sys.appcon.apps.<appname>.<daemonattr></code> |
− | | | + | |
− | RO | + | | |
− | | | + | RO |
− | The current value of every daemon attribute <daemonattr>. Current attributes include: <br> appname, priviledged, prog, wd, pid, startcount, lastexittype, lastexitcode | + | |
+ | | | ||
+ | The current value of every daemon attribute <daemonattr>. Current attributes include: <br> appname, priviledged, prog, wd, pid, startcount, lastexittype, lastexitcode | ||
+ | |||
|} | |} | ||
− | |||
− | = Events = | + | TBCompleted |
+ | |||
+ | = Events = | ||
+ | |||
TBD | TBD |
Latest revision as of 11:06, 2 August 2013
Commands
This page references all generic commands used by the platform. The commands are serialized and sent using M3DA Protocol.
This is an "applicative level" specification opposed to the "serialization level" specification from the M3DA Protocol document.
In order to send command from the server to the device, or from the device to the server, an M3DA data writing is to be done on a node path, encapsulated into an M3DA::Message
object as stated into the protocol specification.
Command Name |
Command Arguments |
Comments |
---|---|---|
== Main == | ||
ReadNode |
"1" → path.of.the.node.to.read (string), ... "n" → path.of.the.node.to.read (string) |
Read a node or several nodes and its/their children (if any) from a tree.
Note: the path can be set to "" (empty string) to request the full tree content. However, as the tree can contain a great amount of data, this particuliar request must be done with caution. |
Connect |
Ask the Mihini Agent to connect to the platform server. | |
Reboot |
Ask the device or one of its asset to reboot. | |
ResetToFactoryDefault |
"restart" | "1" → restart after setting reset (boolean|number) |
Reset agent settings to factory defaults. All persisted data about agent settings and installed software are lost.
( depending on the differences between defaultconfig.lua and persisted config, this operation may impact: server url, hearbeat, ..., or any ReadyAgent config parameter)
Not impacted modules/functionalities:
Note:
-> If this is a boolean value and it is true, it requests the agent to be restarted with a default timeout (6 seconds) |
== Software update == | ||
ExecuteScript |
"url" | "1" → url to retrieve the Lua script (string) |
-> url to retrieve the Lua script |
SoftwareUpdate |
"url" | "1" → url to download the package (string) |
-> url provided by the server where the Software Update Package can be downloaded. |
== TCP Remote Connection == | ||
TCPRemoteConnect |
Install a TCP tunnel | |
== Log Upload == | ||
LogUpload |
"url" | "1" → url (string) |
The url where the logs are to be uploaded. Has to be of the form "ftp://" to request ftp upload, else "http://" for HTTP Post upload |
== Application Container == | ||
appcon.start |
"appname" | "1" → application name (string) |
Start an application |
appcon.stop |
"appname" | "1" → application name (string) |
Stop an application |
appcon.autostart |
"appname" | "1" → application name (string) |
Configure an application to start automatically or not. |
Variables
Variable |
Read/Write |
Description |
---|---|---|
|
RO |
list of all applications currently managed by appcon, as a single string of space-separated names |
|
RW |
whether the application is currently started (Boolean) |
|
RW |
whether the application starts automatically (Boolean) |
|
RO |
whether it is a runnable application |
|
RO |
The current value of every daemon attribute <daemonattr>. Current attributes include: |
TBCompleted
Events
TBD