Registry Store

From NESTFE Wiki

Contents 1 Overview 2 API 3 Setting Up 4 Implementation 5 Restoring GPS Location

Overview

RegistryStore is a tool to make Registry attributes persistent across reboots (ie. the value is not lost). It also allows different program images to share values through registry attributes. RegistryStore works by saving/restoring the attributes to/from internal flash (this code therefore currently only works on nodes that use the MSP430, eg telos, telosb, trio, etc.).

Not all attributes are saved, only those listed in the application's RegistryStore.h file. Because the attributes are stored in a single location, all program images that run on this mote must know the format of that location. Therefore, all such applications should share the same RegistryStore.h file. For example, all Trio/Kraken applications use the RegistryStore.h file found in tinyos-1.x/contrib/nestfe/nesc/lib/kraken. As long as attributes are always appended (never removed) from this file, the data in the flash will always be interpreted correctly. If an attribute is to be appended to the file, the correct protocol is to cvs update, append the attribute, and immediately commit.

A complete sample application can be found in contrib/hood/apps/TestRegistry. The Registry libraries can be found in tos/lib/Registry. Some documentation of the API is below.

API

To use RegistryStore, one must simply include the RegistryStoreC module. Applications that use the KrakenC library automatically include RegistryStoreC.

The Registry attributes that are to be saved in flash must be listed in the RegistryStore.h file as a row in the storedAttributes matrix. The format of the row is attributeID, flash address, attributeSize. The first attribute should be at byte address 0, and the last should not go past byte 94. An example line could be:

enum registryStore{
  REGISTRY_STORE_SIZE = 94,
  NUM_STORED_ATTRS=1
};

uint8_t storedAttributes[NUM_STORED_ATTRS][3] = {
  {ATTRIBUTE_LOCATION, 0, 8}
};

Which indicates that the attribute being stored is LOCATION, it is being stored at byte address 0, and is 8 bytes large. The bytes should always be integer values, not sizeof functions, in case the size of a struct changes. The ATTRIBUTE_LOCATION enum is defined in Registry.h, which gets automatically generated and placed in the build directory for your application, as are the IDs for all other attributes. The attribute IDs should be defined in terms of their enums not as a raw integer, in case the same attribute has a different ID in different program images.

Once the RegistryStoreC module is included, the mote can use the following interface:

interface RegistryStore {
  command result_t clearAll();
  command result_t save(uint8_t attr);
  command result_t restore(uint8_t attr);
  command result_t saveAll();
  command result_t restoreAll();
}

This interface is also available as Rpc commands in the pytos environment.

The save/restore functions take an integer parameter which indicates an attribute by its index in the savedAttributes matrix. For example:

>>> app.RegistryStoreC.RegistryStore.save(1)

will save the attribute in the second row of the savedAttributes array. Your nesc application will not know when save is called, however, since there is no event signalled on save() as there is when update() is signalled on a Registry set call. In addition, the value will not be put in a Registry Attribute (RAM) when it is saved with to ROM with RegistryStore. One strategy is to call restore from the nodes every time the nodes boot up. To save a value to the nodes from pyTOS you'd call save and then reboot them, verifying that they have the right value. You call restore on the motes by wiring to RegistryStoreC.RegistryStore and then calling:

RegistryStore.restore(1); 

where ATTRIBUTE_X is the enum used in RegistryStore.h.

Setting Up

In order to use the API described above, the user must:

1. use the new makesystem by setting the Makerules environment variable to point to the tinyos-1.x/tools/make/Makerules file
2. add the following include directories to their makefile

CFLAGS += -I$(TOSDIR)/../tos/lib/Registry
CFLAGS += -I$(TOSDIR)/../tos/lib/RegistryStore
CFLAGS += -I$(TOSDIR)/../tos/lib/Rpc
CFLAGS += -I$(TOSDIR)/../beta/Drip
CFLAGS += -I$(TOSDIR)/../beta/Drain

1. include the RegistryStoreC module somewhere in their application

1. invoke the registry.extra file in their make process by either declaring "registry" on the command line when making the application as follows

make telosb registry

or adding registry to the GOALS variable in their makefile

GOALS+=registry

For problems, the Pytos Installation Instructions setup instructions may contain more details.

Implementation

RegistryStore uses the InternalFlash interface and the InternalFlashC module. These are currently only available for the MSP430 architecture.

Restoring GPS Location

After a reset of the node, the GPS Location needs to be restored from the internal flash. In order to restore this attribute, you should run the following command:

app.RegistryStoreC.RegistryStore.restore(1)

because "1" is the row number of ATTRIBUTE_GPSLOCATION in the /nestfe/nesc/lib/kraken/RegistryStore.h file.