EEPROM

The graphical interface can use the controller’s non-volatile EEPROM memory in some cases. These cases include:

• if interface variables in the online editor have the “save to EEPROM” flag enabled, such variables will automatically be added for EEPROM storage and restored on startup;
• any variables that you add manually will also be automatically saved to EEPROM and restored on startup;
• when using notifications — in this case, the EEPROM stores the controller’s unique identifier and other data.

The RemoteXY library automatically tracks variable changes, and if a variable changes, it will automatically be saved to EEPROM without your intervention. On controller startup, the variable will be restored from EEPROM.

To work with the controller’s non-volatile memory, RemoteXY uses the EEPROM.h library. To make RemoteXY start using EEPROM, it is enough to include the EEPROM.h library before including remotexy.h:

Configuration of EEPROM usage consists of the following steps:

• Add variables. You need to specify which data will be saved to EEPROM. Skip this step if you use the online editor to mark interface variables for EEPROM saving — these variables will be added automatically. Other variables required by RemoteXY, such as the board identifier when using notifications, will also be added automatically.
• Assign initial values. Set initial values for variables that will be saved to EEPROM. These values will be used if EEPROM data is invalid — for example, at first launch or after changing the variable set.
• Allocate memory if necessary. By default, the required memory starting from address 0 will be used. However, you can change this. On ESP controllers, memory allocation is mandatory.
• Initialize EEPROM if you need to access EEPROM data in the setup() function. If not required, initialization will occur automatically on the first call to RemoteXYEngine.handler().

Adding Variables

Add variables that should be saved in EEPROM using the functions listed below. You may add any of your variables

Note. Interface variables marked with the “save to EEPROM” flag in the online editor will be added automatically; you do not need to add them manually. Other variables required by RemoteXY, such as the board identifier when using notifications, will also be added automatically.

RemoteXYEngine.addToEeprom (*variable, size, key) - adds a variable of the specified length size for EEPROM storage.

RemoteXYEngine.addToEeprom (variable, key) - adds a variable of a standard type for EEPROM storage.

In these functions, the key parameter is an arbitrary number that must be unique to the variable. If you change the key for any variable, all EEPROM data will be considered invalid and will not be read at startup.

The order of adding variables is important. If the sequence changes, all EEPROM data will be considered invalid. If you add or remove a variable, all EEPROM data will also be considered invalid.

Assigning Initial Values

Assign initial values to variables that will be saved to EEPROM. If EEPROM data is invalid, the initial values will not be overwritten. Thus, for example, on first launch, the variables will contain correct values. Initial values may be assigned before adding the variables to EEPROM.

You also need to set initial values for interface variables from the RemoteXY structure for which you enabled the EEPROM-saving flag in the online editor.

EEPROM Memory Allocation

The remotexy.h library handles all EEPROM operations independently and usually does not require additional code. However, if you use EEPROM.h for your own needs, you must configure it to avoid address conflicts.

If you use an ESP controller that requires explicit memory allocation using the begin() function, you must request from RemoteXY the amount of memory required.

• uint16_t RemoteXYEngine.getEepromSize () - returns the number of EEPROM cells required by RemoteXY;
• RemoteXYEngine.setEepromOffset (uint16_t offset) - sets the address of the first EEPROM cell for RemoteXY; if not used, RemoteXY will place data starting from address 0;
• int8_t RemoteXYEngine.initEeprom () - initializes EEPROM. Returns 1 if initialization was successful. You may omit calling this function — it will be called automatically on the first call to RemoteXYEngine.handler().

Use RemoteXYEngine.getEepromSize() — it returns how many EEPROM cells are reserved for RemoteXY. By default, RemoteXY places its data starting at address 0.

For ESP controllers, this function returns the memory size for the begin() call.

Use setEepromOffset() to define the first EEPROM address for RemoteXY if needed. If you use the initial EEPROM cells for your own task, you can specify from which cell the memory will be free for RemoteXY.

EEPROM Initialization

The remotexy.h library restores data from EEPROM when RemoteXYEngine.initEeprom() is called. If the function is not invoked explicitly, it will be called automatically when you first invoke RemoteXYEngine.handler().

When RemoteXYEngine.initEeprom() is called, EEPROM data validity is checked. If the data is valid, all added variables will be updated with values from EEPROM. If the data is invalid, the variables retain their initialized values. Then the library begins tracking changes to registered variables each time RemoteXYEngine.handler() is called. When a change is detected, data will be written to EEPROM.

To access values read from EEPROM inside the setup() function, you must explicitly call RemoteXYEngine.initEeprom(). If you do not need EEPROM values in setup(), you may skip initialization.