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

Integer — 0 on success, or a Send Error Code on failure

Description

This method provides a mechanism for caching agent data to preserve that information 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.

Added to agent code, server.save() saves its argument, a Squirrel table, in persistent storage. The table may then be accessed using server.load(). The saved table can contain any serializable data type: tables, arrays, strings, integers, floats and bools.

The table must not exceed 64KB in size, otherwise an exception will be thrown.

Any saved data can be cleared by saving an empty table:

server.save({});

The recommended practice for caching device data is to relay its information to the agent using an agent.send()/device.on() pairing. This data may then be added to the table which is in turn passed to server.save(). If the data is device set-up information, for instance, the agent can manage that data, providing it to the imp on request when the device starts up, and keeping it synchronized with settings specified by and display in a mobile app. Periodically, or when the set-up data changes, the agent can cache the information in case it itself is restarted.

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 Device ID yield the agent’s own ID code, which can be seen in the agent’s URL. Any server.save() call made by the agent is indexed by that Agent ID.

If the end-user reconfigures their device, this process is performed again. If the first Plan ID has not been recorded by the app (locally or remotely) and now passed via the BlinkUp SDK to Electric Imp’s device-enrollment server, a new Plan ID will be generated, resulting in a new Agent ID and thus a new agent. This second agent will not be able to access data previously saved by the first 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 other time the device is configured by that end-user. This is the recommended methodology for subsequent re-configurations by the same 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 Plan ID and so will get an entirely new agent with a new data store. Again, this is the correct behaviour in this circumstance as it ensures 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().

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.