The nv table property provides data storage that, unlike the imp’s main memory, is protected during deep sleep (see server.sleepfor() and server.sleepuntil()). Its contents are cached in low-power memory before entering deep sleep and are recovered upon restart.
The nv table can’t survive a cold boot, however. To retain data across power cycles, you can make use of the following options:
Use the agent.send()/device.on() mechanism to transfer the data to the agent, which can then use server.save() to cache the data in permanent storage. The agent can later call server.load() to retrieve the data and pass it back to the device.
Use the imp.setuserconfiguration()/imp.getuserconfiguration() mechanism (available in impOS™ 36 and up) to persist the data in the imp’s Flash storage. The data will persist across both warm and cold starts (unlike the nv table), is not dependent on an Internet connection (unlike server.save()), and will be retained until it is actively overwritten. However, data must be stored as a blob or a string, and every write erodes the Flash’s finite write capacity.
The nv table is not instantiated automatically: if you need to store data across deep sleeps, you need to establish a table called nv as a global variable. Just before it goes into deep sleep, impOS will check for a global table variable called nv and preserve it for you. It will automatically re-establish the variable when the device next wakes.
There are some instances when a restart will not preserve your nv table. It is possible to determine whether the nv table should have been preserved by consulting hardware.wakereason():
|WAKEREASON_POWER_ON||0||Powered on (cold boot)||No|
|WAKEREASON_TIMER||1||Woken after sleep time expired||Yes|
|WAKEREASON_SW_RESET||2||Restarted due to a software reset||No|
|WAKEREASON_PIN||3||Woken by wakeup pin going high||Yes|
|WAKEREASON_NEW_SQUIRREL||4||Restarted due to new Squirrel code being loaded||No|
|WAKEREASON_SQUIRREL_ERROR||5||Restarted due to a Squirrel run-time error||No|
|WAKEREASON_NEW_FIRMWARE||6||Restarted due to a firmware upgrade||No|
|WAKEREASON_SNOOZE||7||Woken from a snooze-and-retry event||Yes|
|WAKEREASON_HW_RESET||8||Restarted by RESET_L pin (imp003 only)||No|
The values assigned to the constants may change in a future impOS release.
Most, but not all, Squirrel data-types can be stored in the nv table, ie. those that can be serialized. See the Developer Guide ‘Squirrel Data Serialization’ for details. However, there is a definite maximum size of the serialized data: just under 4KB. Tables which become larger than this can’t be persisted in nv table. Be warned: no error is generated in this case because the imp is already shutting down when the write is attempted.
Because the nv table size is limited, it is important to confirm that there is sufficient room to store the data you need to be preserved during deep sleep. The nv data is stored in BSON (Binary jSON) format. However, formatting your data in JSON form does not provide a guide to the size of its BSON equivalent. The recommended approach, therefore, is to derive by experimentation how much of your data the nv can contain, ie. find out how much of your sample data you recover after saving it to nv (see the note on errors in the paragraph above), and then embed that figure (minus a safety factor) in your code as a constant.
The nv table is not currently available for use within factory firmware.
For more information on saving data, see the Developer Guide ‘Data Persistence In imp Applications’.
The imp004m will not include nv support because of its lack of non-volatile memory in which nv can be preserved during deep sleeps. Attempting to establish and access the nv table on an imp004m will throw the following exception:
"nv table not available on this imp". Users who need to store data across deep sleeps on imp004m can either use hardware.spiflash, or potentially even avoid deep sleep altogether. This is possible because shallow sleep on the imp004m consumes less power than other imps do in shallow sleep.
The nv table is not yet implemented on the imp005 (as of impOS 36).
This example shows how the imp API's nv table is used to preserve a single value across periodic deep sleeps.