DeviceNameHelperRK library - retrieve and store device name easily

[rickkas7]

The device name for a Particle device is stored in the cloud, not locally on the device. While you can retrieve the name from code running on the device, the process can necessarily only be done while connected to the cloud, and it requires time and data.

This library provides an easy-to-use wrapper and also provides a way to store the data locally:

• DeviceNameHelperEEPROM stores the name in the EEPROM emulation. It is preserved across power-down, sleep, reboot, user code flash, and Device OS flash. The EEPROM is typically around 3K. The library requires 44 bytes of EEPROM for the name and some other data.
• DeviceNameHelperRetained stores the name in retained memory. It is preserved across sleep modes and reboot. The retained memory is around 3K on most devices. The library requires 44 bytes of retained memory for the name and some other data.
• DeviceNameHelperFile stores the name in a file on the flash file system. This requires a Gen 3 device (Argon, Boron, B Series SoM, or Tracker SoM) and Device OS 2.0.0 or later. The flash file system is 2MB (4 MB on the Tracker).
• DeviceNameHelperNoStorage stores the name in RAM so it will be fetched on every restart and also after HIBERNATE sleep. But it reduces the amount of code you need to write.

Also:

• The full browsable API documentation can be found in the docs/html folder and here.
• The Github repository for this project is: https://github.com/rickkas7/DeviceNameHelperRK.
• The license is MIT. Can be used in commercial, open-source, and closed-source products. Attribution not required.

All of the classes use a singleton pattern. You use the instance() method of your class to allocate it, if it doesn’t exist, or retrieve the existing instance. For example: DeviceNameHelperEEPROM::instance(). There is also DeviceNameHelperRetained::instance(), etc.

There is one method you must call from setup(), and one from your app’s loop().

For example:

void setup() {
    // You must call this from setup!
    DeviceNameHelperEEPROM::instance().setup(EEPROM_OFFSET);
}

void loop() {
    // You must call this from loop!
    DeviceNameHelperEEPROM::instance().loop();
}

Replace DeviceNameHelperEEPROM with whatever storage method you are using such as DeviceNameHelperRetained or DeviceNameHelperFile.

To use the name, call DeviceNameHelperEEPROM::instance().getName(). This returns a c-string containing the name. The name is limited to DEVICENAMEHELPER_MAX_NAME_LEN characters (31).

To find out if the name has been retrieved, use DeviceNameHelperEEPROM::instance().hasName().

You can also register a name callback, which is called when the name is retrieved from storage at startup, or when it has been retrieved from the cloud.