This library makes it easy to store device-specific configuration settings in retained memory, EEPROM emulation, or a file. You can set the data using a Particle function, publish, or webhook.
The webhook examples include storing configuration in the Device Notes field in the console, and storing the data in a Google Sheets spreadsheet. The Sheets example only requires a Google G Suite account - no need to purchase any special cloud hosting!
Storage Methods
The storage methods provide a way to store the data locally so it’s available immediately after restart, and to avoid having to get the data from the cloud as frequently. You can set an adjustable refresh period, if desired, or only fetch once.
Retained Memory
Retained memory is preserved:
- Across reboot
- Across sleep modes including HIBERNATE
It is not preserved:
- When removing power (including use the Gen 3 EN pin)
- Most code flashes
- Most Device OS upgrades
There is around 3K of retained memory on most devices.
retained CloudConfigData<256> retainedConfig;
void setup() {
// You must call this from setup!
CloudConfig::instance()
.withUpdateMethod(new CloudConfigUpdateFunction("setConfig"))
.withStorageMethod(new CloudConfigStorageRetained(&retainedConfig, sizeof(retainedConfig)))
.setup();
}
EEPROM
Emulated EEPROM is a good choice on Gen2 devices because it’s preserved:
- Across reboot
- Across sleep modes including HIBERNATE
- When removing power (including use the Gen 3 EN pin)
- Most code flashes
- Most Device OS upgrades
There is around 3K of emulated EEPROM on most devices.
size_t EEPROM_OFFSET = 0;
void setup() {
// You must call this from setup!
CloudConfig::instance()
.withUpdateMethod(new CloudConfigUpdateFunction("setConfig"))
.withStorageMethod(new CloudConfigStorageEEPROM<256>(EEPROM_OFFSET))
.setup();
}
On Gen 3 devices, it may make more sense to use the flash file system file option instead. On the Argon, Boron, B Series SoM, and Tracker SoM, emulated EEPROM is just a file on the flash file system, so there is no efficiency advantage to using EEPROM over files.
Flash File System File
On Gen 3 devices (Argon, Boron, B Series SoM, and Tracker SoM) running Device OS 2.0.0 or later, you can store the data in a file on the flash file system.
The file system is 2 MB, except on the Tracker SoM, where it’s 4 MB.
Using a file is easy, just pass the pathname to the CloudConfigStorageFile constructor.
void setup() {
// You must call this from setup!
CloudConfig::instance()
.withDataCallback(logJson)
.withUpdateMethod(new CloudConfigUpdateFunction("setConfig"))
.withStorageMethod(new CloudConfigStorageFile<256>("/usr/cloudconfig"))
.setup();
}
Data Update Methods
The data update methods allow the data to be updated from the cloud.
Function
The configuration data can be updated by making a Particle.function call to the device. Since it’s a “push” method, there’s no way for the device to request it be sent the configuration data, so it’s best suited for EEPROM or file storage methods.
Function update is a good choice if:
- You will be pushing the changes from your own server.
- Each device has its own configuration.
- You want confirmation that the device received the update.
- The device may be in sleep mode or offline.
- You are using unclaimed product devices (also works if claimed).
Subscription
Subscription is a good choice if:
- You want to update all devices at once efficiently.
- Devices are generally always online.
Note that devices must be claimed to an account to use subscriptions; you cannot use subscriptions with unclaimed product devices.
Since it’s a “push” method, there’s no way for the device to request it be sent the configuration data, so it’s best suited for EEPROM or file storage methods. The webhook method is based on subscription, but works as both “push” and “pull” so it can both request the current configuration and receive configuration updates spontaneously.
Webhook
There are two examples of using a webhook: Device Notes and Google Sheets. You can easily base your own webhook-based system for getting configuration data from your own server using this method.
Device Notes
The Device Notes example allows you to store the configuration data for each device in the Device Notes field in the console. One of the major benefits is that you don’t need any external services and you can edit the data in the Particle console, though you do need to edit the JSON data as text. See also the Google Sheets example, below.
Google Sheets
This is a great option for storing per-device configuration for a set of devices in a Google Sheets spreadsheet. It makes adding and updating configuration easy, and you can see the values for your fleet at a glance.
The setup process is a bit involved, so it’s in a separate page. However, once you’ve got it set up, updating configuration values is as easy as editing a Google spreadsheet. Also, it uses Apps Script, which is included in your G Suite subscription, so you don’t need to purchase separate Google Cloud computing resources!
The second part of the tutorial adds the Update Selected button so you can send the configuration to selected devices (that are online) immediately!
Learn More
- Github repository: https://github.com/rickkas7/CloudConfigRK (include docs and examples)
- License: MIT (Can use in open and closed-source projects including commercial projects. No attribution required.)
- Full browsable API docs