Getting Started

 Top  Previous  Next

Minimal steps

1. Add settings.tbs and settings.tbh files to your project (they are in current_library_set\settings\trunk).
2. Add include "settings\trunk\settings.tbh" to the includes section of the global.tbh file. If you decided to put #define statements directly into the descriptor file (recommended), then also add includepp "settings.txt" below the first statement. We will assume that you did this.
3. Create empty callback procedure bodies (presumably in the device.tbs): callback_stg_error(), callback_stg_pre_get(), and callback_stg_post_set(). Hint: copy from declarations in settings.tbh or from our code example.
4. Add an empty settings.txt descriptor file to your project and define desired settings. You can also start with our sample file and edit it as needed.
5. In the On_sys_init() event handler (or some other place you deem logical), add a call to the stg_start(). This function may fail, so check the returned status code.
6. Add this line to settings.txt: #define STG_DEBUG_PRINT 1 -- this will print a wealth of information in the output pane. You do need this to make things right!
7. When stg_start() executes you will (most probably) encounter various errors and warnings -- they will be appear in the output pane if debug printing is enabled (and this is why it is advisable to enable it). We have provided an example of dealing with such messages -- see An Embryonic Project (part of our Sample Project).

Once you are satisfied with the operation of the library, remember to remove the STG_DEBUG_PRINT line from global.tbh (this will save you some memory).

 

Additional Steps

1. You can change the name of the settings descriptor file by adding a line like this to settings.txt: #define STG_DESCRIPTOR_FILE "mysettings.txt". Don't forget to also change includepp statement in global.tbh accordingly.
2. By default, non-volatile settings are stored in the EEPROM. You can also store the settings on the flash disk. EEPROM offers limited (but usually sufficient) storage with a faster access, while the flash disk offers a virtually unlimited storage with a slower access. Go with the EEPROM whenever possible. If you want to use the flash disk, add #define STG_STORAGE_MEMORY 1 to settings.txt.
3. Also, for the flash memory storage, you may want to change the filename of the file that will keep the settings. The default filename is settings.dat. Change this by adding a line like this to settings.txt: #define STG_FILENAME "someothername.abc".
4. You may increase the reliability of settings by keeping two independent copies of their values. The STG library will handle both copies automatically. Should the first copy fail, the library will read the values off the secondary copy and attempt to restore the first copy as well. The penalty is in the reduced performance of the library (increased setting access time) and doubling of the EEPROM (or flash) memory storage needs. Add #define STG_REDUNDANCY 1 to settings.txt to enable the second copy of your settings (see Operation Details for explanation how memory is allocated for both copies).
5.Repeatedly writing into the EEPROM (flash) will eventually cause it to fail -- granted, this is a very remote possibility, but it is still a possibility. Sometimes, it is wise to put certain settings into RAM -- this way, you don't have to worry about killing the EEPROM, yet you have all the benefits of accessing your data through this convenient library. To create RAM settings, set correct STG_RAM_ARRAY_SIZE and designate desired settings as storage type "R". You can even store settings in some "custom" RAM. For that, add #define STG_RAM_TYPE 1 to your project and implement callback_stg_vm_read() and callback_stg_vm_write(). For example, some real-time clock (RTC) ICs have a small amount of RAM which is usually accessed through special RTC registers. Implement custom access routines for this RAM, and you have created volatile RAM storage which is, in fact, non-volatile! Adding #define STG_REDUNDANCY 2 will instruct the library to keep two copies of your RAM settings for improved reliability.