Module airvantage.asset Interface to ReadyAgent asset management.
The #asset instances should be created with airvantage.newAsset.

Type `airvantage.asset`

airvantage.asset.newasset(id)

Creates and returns a new #asset instance.

Type `asset`

asset:close()	Closes the racon.asset.
asset.newTable(path, columns, storage, sendPolicy)	Creates and returns a airvantage.table#table instance.
asset:pushData(path, data, sendpolicy)	Pushes some unstructured data to the agent.
asset:setUpdateHook(hook)	Changes the hook function to be called when the asset receives a software update request from the portal.
asset:start()	Registers a newly created racon.asset with the ReadyAgent.
asset.tree	airvantage.asset data tree.

Type `airvantage.asset`

Field(s)

`airvantage.asset.newasset(id)`

Creates and returns a new #asset instance.
The newly created racon.asset is not registered with the ReadyAgent. No message can be sent or received by the instance at this point. See #asset.start to register the newly created instance.

Parameter

id: string defining the assetid identifying the instance of this new asset.

Return values

#asset: instance on success.
nil followed by an error message otherwise.

Type `asset`

@type asset

Field(s)

`asset:close()`

Closes the racon.asset.
Closes the link with the ReadyAgent so no new messages can be received.

Return value

"ok" on success.

`asset.newTable(path, columns, storage, sendPolicy)`

Creates and returns a airvantage.table#table instance.

Parameters

path: (relative to the asset root) where the data will be sent.
columns: list of either racon.table.columnspec or column names (to use default values).
storage: either "file" or "ram", how the table must be persisted.
sendPolicy: name of the policy controlling when the table content is sent to the server.

Return values

airvantage.table#table: to store and consolidate structured data.
nil + error message otherwise.

`asset:pushData(path, data, sendpolicy)`

Pushes some unstructured data to the agent.
This data will be sent to the server according to the specified send policy. Data can be a flat set of key/values in a record, or can contain nested sub-records. It can even be simple value out of a record, in which case the last path segment will be used as a datastore key.

Parameters

path: the datastore path under which data will be stored relative to the asset node.
data: a table of key/value pairs or a simple value (not a table)
sendpolicy: name of the policy controlling when the data is sent to the server.

Return values

"ok" on success.
nil followed by an error message otherwise.

`asset:setUpdateHook(hook)`

Changes the hook function to be called when the asset receives a software update request from the portal.

Notes:

 - There can be only one SoftwareUpdate request at a time.
 - Only one hook can be registered for the whole asset
 - It is not possible to signify asynchronous reporting of update status, for now the only way to send update result is to return the status in the hook.
 - If no user update hook is set: then the error code 472 meaning not supported / not implemented will be returned. 
 - Any error coming from this update request means that the whole update process will be set as failed.
 - When an update request asks for installing a version that is already installed then the application should return success value.
   In deed, in some cases ReadyAgent won't received the update hook result, e.g. asset reboot, device reboot etc, in those cases, 
   the update request will be sent again to the asset with same hook parameters,
   and the asset hook is expected to answer with success code when that request have been executed successfully before.

Parameter

hook:
the new function to handle software update request.
hook signature: hook(componentname, version, path, parameters) - componentname (a string) is the identifier of the component to update, the name is defined in update manifest file, here it is provided without the assetid at the beginning. - version (a string) is the version of the component to install version can be empty string (but not nil!) to specify de-installation request, non empty string for regular update/install of software component. - path (a string) can be empty when version is empty too, otherwise path will be a non empty string defining the absolute path of the file/folder to use to update the application. - parameters (a table), can be nil, when set it contains the content of parameters, those params provide a way to give application specific update paramaters. - return value: an integer, 200 for success, any other value means error. Values from 480 to 499 are reserved for applicative error codes, so it is highly recommanded to use one (or more) of those to signify an error coming from this update hook. Non-integer return values will be rejected and be replaced by default value 471.

Return values

"ok" on success.
nil followed by an error message otherwise.

`asset:start()`

Registers a newly created racon.asset with the ReadyAgent.
Sends the EMP Register command to the ReadyAgent registering a new asset. Incoming pending messages can be received after a call to this function. In the event of an unrecoverable error or an explicit call to racon.asset:close, the instance emits a "closed" event.

Return values

"ok" on success.
nil followed by an error message otherwise.

`asset.tree`

airvantage.asset data tree.
The airvantage.asset contains a data tree, in the field tree.

When the server sends data to an asset, the way it reacts is determined by the tree:

if there's a function in the tree under a path which is the prefix of the data's path, this function is called as a handler;
if there's no specific handler, but a handler is found, in a __default field in a prefix of the data's path, this generic handler is used. If several generic handlers are found, the one corresponding to the longest prefix is chosen.
if no handler is found at all, the value sent by the server is written in the tree, under its path.

For instance, if the server sends myAsset.foo.bar=123:

if there's a function in one of myAsset.tree.foo.bar,myAsset.tree.foo or myAsset.tree, this function is called;
if there's no such function, but at least one default handler is found in either myAsset.tree.foo.__default or myAsset.tree.__default, the one with the longest path is called;
if no handler is found, the value 123 is written in myAsset.tree.foo.bar.

Handlers are function which receive as parameters:

the asset instance;
the map of keys/values sent by the server; keys are paths relative to the node where the handler is attached;
the path where the handler is attached; concatenated in front of each key, it allows to retrieve absolute paths.

They must return: * the status code 0 to indicate success; * a non-zero numeric status code to indicate failure, optionally followed by an error message.

The data tree comes with a pre-wired functions on the special path id.commands (i.e ReadNode on id.commands.ReadNode).

Handler functions should be installed on the data tree before the asset is started: otherwise, some server messages might be lost.