server.save(dataToSave, formatType)

Description

This method provides a mechanism for caching data across software (agent) and hardware (server) restarts. A common use of this technique is to preserve an application’s settings across such situations.

When called, server.save() saves its first 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 the specified (or default) format.

By default, the table is serialized into JSON. As such, the table can contain any serializable data type: tables, arrays, ‘safe’ strings (ie. strings that contain no \0 characters), integers, floats and Boolean values. Key-value pairs which are incompatible with this encoding are removed from the data as it is saved; an error, including a call stack, will be logged if this occurs, but no exception is thrown.

The formatType parameter allows you to specify an alternative serialization format by passing in the integer 2. This makes use of a binary format which is able to serialize a greater quantity of information into the available 64KB. It is also able to serialize blobs, unsafe strings and special floating point values, such as NaN.

The existing, JSON-based encoding can be explicitly selected by passing in the integer 1. Passing any value other than 1 or 2 will cause an exception to be thrown.

Whichever format you choose (or default to), the saved table can subsequently be retrieved using the method server.load(). This returns the stored data as a Squirrel table irrespective of the storage format.

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

server.save({});

• For more guidance on making use of server.save() and related methods, please see Data Persistence In Electric Imp Applications.

• For general advice on saving memory, much of which applies to server.save() data, which has a 64KB maximum, please see Writing Efficient Squirrel.

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 the same end-user.

If the device is passed to a different end-user, the new user should not have access to the previous user’s saved data. The new user will run a freshly downloaded instance of your BlinkUp SDK-based app on their own mobile device and so should not have a preserved pan ID. They should 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. You should therefore avoid indexing preserved plan IDs solely be device ID, as this could result in the new user using the same agent ID as the old user (because the device ID and plan ID have not changed). Index plan IDs, especially when stored remotely from the BlinkUp app, by some other, user-specific means.

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