imp.setuserconfiguration(userData)

Description

This method is used to store user-defined data within the imp’s Flash storage: on-die Flash for the imp001 through imp004m and imp006, and in encrypted off-die storage for the imp005. As such, the data will persist across both warm and cold starts (unlike the nv table) and is not dependent on an Internet connection (unlike server.save()). The data is retained across device group changes and the blessing process. The data will be retained until it is actively overwritten. As such, it can be used to in the factory to save data for use by the device during its lifetime.

Up to 4KB (4096 bytes) of user data may be stored — Squirrel will throw the error "value too long in imp.setuserconfiguration(value)" if the data you are attempting to write is too large.

When new data is written, any existing content is deleted, even if the new data is smaller in size than the data previously written.

Although the imp.setuserconfiguration() takes data stored as a blob or a string — all other data types are rejected — it is possible persist other data types by first serializing them into a blob using Electric Imp’s Serializer library.

To clear the user data, pass in null as your userData.

On all imps, the user-defined data is stored securely within on-die flash or, with the imp005, on external flash and encrypted with per-device keys.

Important This is the only way to clear the persisted data. Methods such as imp.clearconfiguration(), BlinkUp™ (either to add new network settings, or to clear existing network settings) or simply changing the device group to which a device is assigned will not clear the user data. Any other user may therefore be able to read the contents of the storage by calling imp.getuserconfiguration() from within Squirrel.

You should also note that devices’ user data will be maintained between, for example, beta- and release-channel versions of the same code, so these versions should have either mutually compatible data structures, or a distinctive marker so your code can easily identify and reject incompatible data.

Note The imp’s Flash storage has a finite write capacity (see the imp API’s notes on Flash architecture) which places a limit on the number of times user data can be written to the imp using imp.setuserconfiguration(). impOS’ implementation of the Flash code provides a minimum lifespan of 60,000 writes (two 4KB pages available with three writes per page before erase; 10,000 minimum writes per page of the imp Flash specification (2 x 3 x 10,000 = 60,000), and users should have significantly more writes than this.