Skip to main content

server.save(dataToSave)

Stores data in server-side persistent storage

Availability

Agent

Parameters

Name Type Description
dataToSave Table The data you wish to preserve, placed in a table

Returns

Nothing

Description

This method provides a mechanism for caching data through software (agent and device) and hardware (server and imp) restarts. A common use of this technique is to preserve a device’s settings across hardware reboots.

When called, server.save() saves its argument in persistent storage. The argument must be a Squirrel table; an exception will be thrown if it is not. An exception will also be thrown if the table serializes into more than 64KB of JSON. The table can contain any serializable data type: tables, arrays, ‘safe’ strings (ie. contains no null characters), integers, floats and Boolean values.

Note Key-value pairs which are incompatible with the underlying JSON encoding are removed from the data as it is saved; an error, includes a call stack, will be logged (but no exception thrown) if this occurs.

The saved table may subsequently be retrieved using the method server.load().

Any saved data can be cleared by passing in an empty table:

server.save({});

Persisting Device Data

server.save() is intended for use on the agent. The recommended practice for caching device data is to relay its information to the agent using agent.send() and device.on(). This data may then be added to the table that is to be passed into server.save().

Production Devices And BlinkUp

Production devices (those made for sale) are assigned their agent when they are first configured by an end-user using BlinkUp™. When this takes place, the app performing BlinkUp receives a code, called a ‘plan ID’, to identify the end-user. The specific combination of this plan ID and the device’s unique ID yield the agent’s own ID, which can be seen in the agent’s URL. Any server.save() call is indexed by that agent ID.

If the end-user reconfigures their device, this process is repeated. If the first plan ID has not been recorded by the app (locally or remotely) and passed via the BlinkUp SDK to Electric Imp’s enrollment server, a new plan ID will be generated, resulting in a new agent ID. This means that the new agent instance will not be able to access data saved by the previous agent even though the device is the same.

If you require that server.save() data persists across end-user BlinkUps, you must ensure that the same plan ID, once issued at the first configuration, is re-used every subsequent time that the device is configured by that end-user.

If the device is passed to a different end-user, the new user will not have access to the previous user’s saved data. This is because the new user will run a freshly downloaded instance of your BlinkUp SDK-based app on their own mobile device. As such, they will not have a preserved pan ID and so will get an entirely new agent with a new, empty data store. This ensures that the device appears as a ‘clean sheet’ to the new end-user.

Agent Lifespan

If a device remains offline for more than 30 days, its agent will be shut down. However, this does not affect any data previously persisted by the agent. When the device comes back online, a new agent will be instantiated and that agent will be able to retrieve the previously persisted data using server.load() (it has the same agent ID as before).

The only instance in which the persisted data will not be accessible is when the device is re-activated using BlinkUp and it is assigned a new Plan ID (see above).

Example Code

This snippet responds to an HTTP request sent by a control app to change one of a device’s settings. When this happens, the agent updates its settings table and saves it to permanent storage so the change survives agent and/or device restarts.