Module airvantage

Provides interfaces with the M2M Cloud Services Platform.

The Racon Application Services functionality (managing transfer and remote storage of application data and commands) is exposed in the airvantage.asset module.

Type airvantage

airvantage.acknowledge(ackid, status, errmsg, policy, persisted)	Acknowledges a server message received with an acknowledgment ticket id.
airvantage.connectToServer(latency)	Forces a connection to the server.
airvantage.init()	Initializes the module.
airvantage.newAsset(id)	Creates and returns a new airvantage.asset#asset instance.
airvantage.triggerPolicy(policy)	Forces the tables and unstructured data attached to a given policy to be sent or consolidated immediately.

Type airvantage

Field(s)

airvantage.acknowledge(ackid, status, errmsg, policy, persisted)

Acknowledges a server message received with an acknowledgment ticket id.

In most realistic cases, the appropriate way to acknowledge a message is to have the handler function return a status code, 0 for success or a non-null number to signal failure. Most applications should therefore not call this function explicitly.

Parameters

• ackid : the id to acknowledge

• status : a boolean, true for success, false for failure

• errmsg : an optional error message string

• policy : optional triggering policy to send the acknowledgment, defaults to "now".

• persisted : if true, the ACK message will be persisted in flash by the agent, and kept even if a reboot occurs before the policy is triggered.

airvantage.connectToServer(latency)

Forces a connection to the server.

This connection will not flush outgoing data handled through policies, but it will poll the server for new messages addressed to assets on this gateway device.

If using nil as latency, the connection is synchronous, i.e. once this function returns, the requested connection to the server is closed. Otherwise the connection will happen after this call returns.

Note: - 0 value means the connection will be asynchronous, but will be done as soon as possible.

Parameter

• latency : optional positive integer, latency in seconds before initiating the connection to the server, use nil value to specify synchronous connection.

Return values

1. non-nil upon success;

2. nil + error message upon failure.

airvantage.init()

Initializes the module.

Return values

1. non-nil upon success;

2. nil + error message upon failure.

airvantage.newAsset(id)

Creates and returns a new airvantage.asset#asset instance.

The newly created airvantage.asset#asset is not started when returned, it can therefore neither send nor receive messages at this point.

This intermediate, unstarted set allows to configure message handlers before any message is actually transferred to the #asset.

See airvantage.asset#asset.start to start the newly created instance.

Parameter

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

Return values

1. airvantage.asset#asset: instance on success.

2. nil followed by an error message otherwise.

airvantage.triggerPolicy(policy)

Forces the tables and unstructured data attached to a given policy to be sent or consolidated immediately.

A connection to the server is done only if data needs to be sent as the result to this trigger operation. Put another way, if no data is attached to the triggered policy(ies), then no connection to the server is done. See airvantage.connectToServer for complementary function.

For a description of how policies allow to manage data reporting from the assets to the server, see the Racon technical article.

Parameter

• #string policy : name of the policy queue to be flushed. Flush all policies if policy=='*'; only flush the default policy if policy is omitted.

Return values

1. "ok" on success.

2. nil followed by an error message otherwise.