Using storage on Azure Sphere

BETA feature

This topic describes how to use storage on an Azure Sphere device. Azure Sphere provides two types of storage, read-only flash storage and mutable storage.

Read-only storage is used to store application image packages on a device so the contents can't be modified without updating the application. This can include any data such as user interface assets, static configuration data, binary resources including firmware images used to update external MCUs, or initialization data for mutable storage. Memory available for applications provides additional details about the amount of storage available.

Mutable storage stores data that persists when a device reboots. For example, if you want to manage system time using the local time zone, you can store the time zone settings in mutable storage. Some other examples are settings a user can modify, or downloaded configuration data. The mutable storage sample shows how to use mutable storage in an application.

Using read-only storage

You can use these Applibs functions to manage read-only storage. For an example that uses these functions see Connect to web services using curl.

Add a file to an image package

To include a file in an image package for read-only storage you can add the file to your project as a resource:

  1. In Solution Explorer, right-click on the Resources folder, select Add>New Item…, and add the files.

  2. Right-click on the file in Solution Explorer and select Properties.

  3. In the General tab in the Properties dialog box, set Content to Yes.

The file should now appear in the image package.

Using mutable storage

BETA feature

When you configure mutable storage for your application, it is assigned to the component ID of the application and can't be accessed by an application that has a different component ID. If the component ID of the application changes, the new application will not have access to the mutable storage of the previous application.

If you delete an application from a device, the mutable storage assigned to the application is also deleted. If the same application is then loaded back onto the device, the mutable storage will be empty. However, if you update the application without deleting it, the mutable storage contents are maintained.

The azsphere device sideload show-quota command displays the amount of mutable storage currently in use.

You can use these Applibs functions to manage mutable storage data:

Mutable storage requirements

Applications that use mutable storage must enable beta APIs, include the appropriate header files, and add mutable storage settings to the application manifest.

Enable beta APIs

Complete the steps in beta API features to enable your app to use beta APIs for Azure Sphere.

Header files

Include the storage and unistd headers in your project:

 #include <applibs/storage.h>
 #include <unistd.h>

Application manifest

To use the APIs in this topic, you must add the MutableStorage capability to the application manifest and then set the SizeKB field. The SizeKB field is an integer that specifies the size of your mutable storage in kibibytes. The maximum value is 64 and the storage is allocated according to the erase block size of the device. The allocation is done by rounding up the SizeKB value to the next block size if the value isn't a whole multiple of the block size of the device.

Note

The MT3620 has an erase block size of 8 KB, so any values that are not multiples of 8 will be rounded up. For example, if you specify 12 KB in the 'MutableStorage' capability, you will receive 16 KB on an MT3620.

In the example below, the MutableStorage storage capability is added to the application manifest with a size of 8 KB.

{
  "SchemaVersion": 1,
  "Name" : "Mt3620App_Mutable_Storage",
  "ComponentId" : "9f4fee77-0c2c-4433-827b-e778024a04c3",
  "EntryPoint": "/bin/app",
  "CmdArgs": [],
   "Capabilities": {
    "AllowedConnections": [],
    "AllowedTcpServerPorts": [],
    "AllowedUdpServerPorts": [],
    "MutableStorage": { "SizeKB": 8 },
    "Gpio": [],
    "Uart": [],
    "WifiConfig": false,
    "NetworkConfig": false,
    "SystemTime": false
  }
}

Write persistent data

To write data to persistent storage, start by calling the Applibs function Storage_OpenMutableFile to retrieve a file descriptor for a persistent data file. Next call the write function to write the data to the persistent data file. If the amount of data you attempt to write exceeds your mutable storage allocation, the write function might succeed; however, the only data written will be the portion that doesn't exceed the storage allocation. To ensure all the data is written you must check the return value of the write function call.

Read persistent data

To read data from persistent storage call Storage_OpenMutableFile to retrieve a file descriptor for the persistent data file, and then call the read function to read the data.

Delete persistent data

To delete data from persistent storage call Storage_DeleteMutableFile.