STG (Settings) Library

Top  Previous  Next

The STG library offers a persistent, convenient storage for your device's settings (operational parameters). It can also play a pivotal role in the device control and monitoring. The library is extremely easy to use — just define a list of all desired settings using a setting configurator and employ simple API calls to work with them.

Setting configurator allows you to specify the names, types, value constraints, etc. of your device's settings and the STG library uses this to automatically calculate memory addresses for storing settings, protect the settings with a checksum, verify the validity of their values, etc. You code is then able to reference setting values by their names, like this: s=stg_get("IP",0), stg_set("IP",0,"192.168.1.40").

The library keeps your settings in the non-volatile memory or RAM. The non-volatile memory used can be the EEPROM memory (stor.) or the flash disk (fd.). For RAM, you can choose to go with "regular" RAM (the one that stores variables), or "custom" RAM, for which you can create your own access routines.

 

Library Info

Supported platforms:

Any platform.

Files to include:

settings.tbs, settings.tbh (from current_library_set\settings\trunk\).

Dependencies:

FILENUM library when the Use Flash Disk option is selected.

API procedures:

Use API procedures to interact with the library.

stg_start() — starts the STG library, parses the descriptor file, restores all volatile (RAM) settings to default values.

stg_check_all() — verifies each setting by reading its value.

stg_get_def() — returns the default value for the specified setting's member.

stg_restore_multiple() — initializes (sets the default values for) all or multiple settings.

stg_restore_member() — initializes (sets the default value for) the specified setting's member.

stg_get_num_settings() — returns the number of settings defined in your project.

stg_get_num_members() — returns the number of members for the specified setting.

stg_find() — returns the number of the specified setting or zero if the setting wasn't found.

stg_stype_get() — returns the type of the specified setting.

stg_get() — reads (gets) the value of the specified setting's member; reports errors through callback_stg_error().

stg_set() — writes (sets) the value of the specified setting's member; reports errors through callback_stg_error().

stg_sg() — writes (sets) or reads (gets) the specified setting's member; directly returns the execution result.

stg_sg_ts() — available when the Timestamp option is enabled (checked), reads or writes the setting modification time /date.

Event procedures:

---

Callback procedures:

Implement the bodies of callback procedures elsewhere in your project.

callback_stg_error() — informs of the error during the execution of stg_get() or set_set().

callback_stg_pre_get() — informs that the setting member's value is being read through one of the STG library's procedures; allows to update the setting member's value before it is returned by the STG library.

callback_stg_post_set() — informs that the setting member's value is being written to through one of the STG library's procedures; allows to respond to the value change.

callback_stg_vm_read() — should implement necessary code for reading a byte of data from "custom" volatile memory. Needed only when the Custom RAM option is enabled (checked).

callback_stg_vm_write() — should implement necessary code for writing a byte of data to "custom" volatile memory. Needed only when the Custom RAM option is enabled (checked).

Required buffer space:

---