User Extensions

In the subdirectory Extensions you can find the file H32Extension_Template.ino. This contains a class UserExtension that is a template for extending the functionality of the H32_Basic firmware.

Preparations

To prepare a user extension, rename the file the MyCoolExtension.ino and move it into the main directory. In the next step change the name of the class from UserExtension to MyCoolExtension (this includes the prefix for the member methods).

Implementation

The extension mechanism allows you to implement callback functions at specific times during the normal operation of the H32_Basic firmware. We have the following methods that are called during the respective execution phase:

Method	Explanation
init(H32_Measurements &measurements)	This method is called for all extensions when the system is initialized. Here you can initialize your device. The measurements are initialized lazily, if you access them, you get current data, if no extension accesses a measurements, they will be taken on read time
wiFiInitialized(bool wiFiInitialized)	This method is called for all extensions when the WiFi initialization has ended. The boolean signals whether this was successful
read(H32_Measurements &measurements)	This method is executed when the measurements take place.
collect(unordered_map<char *, double> &data)	In this method all additional data is collected. If you want data to be sent then you have to add your data to the map. The key is a descriptive name, the value is your measurement. Multiple values can be added.
api_call(char* api_key, char *api_additional, H32_Measurements &measurements, unordered_map<char *, double> &additional_data)	This method allows you to send data using the api_key and the additional information however you like. All data collected is available in the parameters. This method is only called if a WiFi connection has been established.
api_call_no_wifi(char* api_key, char *api_additional, H32_Measurements &measurements, unordered_map<char *, double> &additional_data)	This method allows you to send data using the api_key and the additional information however you like. All data collected is available in the parameters. This method is only called if no WiFi connection was established. This allows to implement your own data transfer e.g. using LoRa.
bool veto_backoff()	This method returns true if no delay should be added to the sleep time. This allows to keep the configured sleep time when the user extension has transferred data even if no WiFi connection can be established

Registering the Extension

Registering the extension is done automatically using the following lines in the code:

namespace {
  Extension *extension = new UserExtension();
}

The parent constructor automatically registers the new object and adds it to the beginning of the extension queue. We place this code in an anonymous namespace so that the normal namespace is not cluttered.

If you want to ensure that your extension is added to the end of the queue, then you have to use the following line instead:

  Extension *extension = new UserExtension(true);

This makes sense if you have multiple extensions registered and want to e.g., correlate the data of the others during the collect()-phase, or if you want to display the data on a connected display (and don't ask my why you'd want to connect a display).