storage

Lua operations are reset when the device restarts. However, by using the storage library, you can save data to the internal flash memory and retrieve it later.

There are two types of storage available:

Storage Capacity

Data is stored within a total capacity of approximately 1 MB, which is shared with your Lua scripts. Please note that the available storage space is very limited.

• kvs: While easy to use, it loads all data into memory at once. Therefore, you should keep the data size within a few kilobytes.
• file: This allows for larger data handling but requires more complex programming, such as managing partial access. Even with files, it is recommended to keep the size within approximately 100 KB.

Read/Write Cycles

Writing to flash memory shortens its lifespan. It is essential to design your application to minimize the frequency of write operations as much as possible.

storage.kvsSave()

You can save an object using storage.kvsSave(). If an error occurs, a return value will indicate the status.

obj = {
  a=1,
  b="hello",
  bool=true,
  c={ x=10, y=20, z={ foo="bar" } }
}

result = storage.kvsSave(obj)

storage.kvsLoad()

To read the existing kvs data, use storage.kvsLoad().

data = storage.kvsLoad();

Writing to a File

Whether a file already exists or you are creating a new one, you must first open it by specifying the filename using storage.fileOpen(filename).

To write data to an open file, use the following functions:

storage.fileWrite()

The fileWrite() function overwrites the file. Any existing data in the file will be deleted and replaced with the new data.

storage.fileWrite("ABC");

storage.fileAppend()

To add data to the end of the existing content, use storage.fileAppend(data).

storage.fileAppend("appended");

storage.fileClose()

Finally, call storage.fileClose() to close the file and complete the process.

storage.fileClose();

Reading from a File

Reading a file also requires the use of fileOpen() and fileClose().

storage.fileGetSize()

You can check the file size (in bytes) using this function.

storage.fileGetSize();

storage.fileRead()

To read the actual data, specify the offset and the length as shown below. The length must be 1024 bytes or less.

-- data = storage.fileRead(offset, length);
data = storage.fileRead(0, length);

Example

-- Open the file
storage.fileOpen("text.txt")

-- Write data
storage.fileWrite("ABC");
length = storage.fileGetSize();
os.log("File size: " .. length);
data = storage.fileRead(0, length);
os.log(data);

-- Append data
storage.fileAppend("abcdefg");
storage.fileAppend("HIJKLKLMN");
length = storage.fileGetSize();
os.log("File size: " .. length);
data = storage.fileRead(0, length);
os.log(data);

-- Ranged Read (Read 7 bytes starting from offset 3)
data = storage.fileRead(3, 7);
os.log(data);

-- Overwrite existing content
storage.fileWrite("ZYZ");
length = storage.fileGetSize();
os.log("File size: " .. length);
data = storage.fileRead(0, length);
os.log(data);

-- Close the file
storage.fileClose();