Gecko OS Settings
Settings and NVM

Functions for reading/writing/loading Gecko OS variables. More...

Modules

Macros
Settings specific macros.

Functions

gos_result_t gos_load_app_settings (const char *settings_name)
Load application specific settings. More...
gos_result_t gos_load_app_settings_once (const char *settings_name, uint32_t magic_number)
Load application specific settings only if required. More...
gos_result_t gos_settings_set_str (const char *setting, const char *value)
Set Gecko OS string setting. More...
gos_result_t gos_settings_set_uint32 (const char *setting, uint32_t value)
Set uint32 setting. More...
gos_result_t gos_settings_set_int32 (const char *setting, int32_t value)
Set int32 setting. More...
gos_result_t gos_settings_get_str (const char *setting, char *buffer, uint16_t max_length)
Get string setting. More...
char * gos_settings_get_print_str (const char *setting, char *buffer, uint16_t max_length)
Get string setting for printing. More...
gos_result_t gos_settings_get_uint32 (const char *setting, uint32_t *value_ptr)
Get uint32 setting. More...
gos_result_t gos_settings_save (void)
Save settings to NVM. More...
gos_result_t gos_settings_save_to_file (const char *filename, bool encrypt)
Save settings to file. More...
gos_result_t gos_settings_load_from_file (const char *filename, bool verbose)
Load settings from file. More...
gos_result_t gos_settings_factory_reset ( gos_factory_reset_t reset_type)

Detailed Description

Functions for reading/writing/loading Gecko OS variables.

Function Documentation

◆ gos_load_app_settings()

gos_result_t gos_load_app_settings ( const char * settings_name )

Load application specific settings.

This configures module settings based on the specified configuration file. When the app app is built, the settings file(s) are built into the app image. This app loads the settings when executed.

One or more settings file may specified in the app's .mk file. The filename of the settings file should be passed to this API.

Note
Some Gecko OS settings require a save/reboot to take effect. If one or more of these settings are used in your app's settings file then it is recommended to use gos_load_app_settings_once() API instead.
The settings are only loaded into RAM cache. They are NOT automatically saved to NVM. gos_settings_save() is required to save to NVM.
Parameters
settings_name Settings filename, specified in the app's .mk file.
Returns
gos_result_t result of api call
Examples:
network/http_methods/main.c , network/http_server/main.c , network/softap_tcp_server/main.c , network/tcp_client/main.c , network/tcp_echo_server/main.c , network/tcp_multiclient/main.c , network/websocket_client/main.c , network/websocket_server/main.c , system/application_settings/main.c , wifi/device_setup/main.c , and wifi/web_setup/main.c .

◆ gos_load_app_settings_once()

gos_result_t gos_load_app_settings_once ( const char * settings_name,
uint32_t magic_number
)

Load application specific settings only if required.

This has similar functionality to gos_load_app_settings() except the application specific settings will only be loaded if the magic_number argument is different from the previous time it was called.

IF the magic_number argument is non-zero and different:

  • Load application specific settings
  • Save settings to non-volatile memory (NVM) along with the magic number (calls gos_settings_save() )
  • Reboot device (calls gos_system_reboot() )
  • If the system is rebooted this API does NOT return. In this way settings that require a save/reboot to take effect may be loaded.

ELIF the magic_number argument is zero:

ELIF the magic_number argument is same:

  • Immediately return (no load, save, or reboot)

If one or more of the settings changes in another app release, the settings may be reloaded by modifying the magic_number .

Note
This API may only be called for one magic number. Calling this with another settings file and magic number will override the previous magic number.
Parameters
settings_name Settings filename, specified in the app's .mk file.
magic_number Value to specific to settings for this app's version. The settings will only be reloaded on a factory reset or if the magic number if different from a previous invocation of the API.
Returns
result of api call
Examples:
demo/uart_blaster/main.c , dms/messages/main.c , dms/telemetry/main.c , network/uart_tcp_client/main.c , and system/application_settings/main.c .

◆ gos_settings_factory_reset()

gos_result_t gos_settings_factory_reset ( gos_factory_reset_t reset_type )

Factory reset the Gecko OS Plugin and Kernel settings

See Gecko OS Command API documentation: save .

Refer to gos_factory_reset_t for the various reset types.

Note
This API does NOT return when GOS_NVM_RESET_FACTORY is used.
This API will reset ALL Application, Plugin, and Kernel settings. See gos_nvm_factory_reset() to factory reset ONLY Application settings.
Parameters
reset_type The factory reset type, see gos_factory_reset_t
Returns
The result of the API, see gos_result_t

◆ gos_settings_get_print_str()

char* gos_settings_get_print_str ( const char * setting,
char * buffer,
uint16_t max_length
)

Get string setting for printing.

See Gecko OS Command API documentation: get .

For variables available to get , see Gecko OS Command API documentation: variables .

Returns null-terminated string on failure

Parameters
[in] setting The setting's name
[out] buffer Buffer to hold setting's string value
[in] max_length The length in bytes of the given buffer
Returns
Result of API, see gos_result_t
Examples:
cloud/mqtt_demo/main.c , dms/telemetry/main.c , network/http_server/main.c , and wifi/device_setup/main.c .

◆ gos_settings_get_str()

gos_result_t gos_settings_get_str ( const char * setting,
char * buffer,
uint16_t max_length
)

Get string setting.

See Gecko OS Command API documentation: get .

For variables available to get , see Gecko OS Command API documentation: variables .

Note
The returned string may NOT be null-terminated
Parameters
[in] setting The setting's name
[out] buffer Buffer to hold setting's string value
[in] max_length The length in bytes of the given buffer
Returns
Result of API, see gos_result_t
Examples:
system/application_nvm/main.c .

◆ gos_settings_get_uint32()

gos_result_t gos_settings_get_uint32 ( const char * setting,
uint32_t * value_ptr
)

Get uint32 setting.

See Gecko OS Command API documentation: get .

For variables available to get , see Gecko OS Command API documentation: variables .

Parameters
[in] setting The setting's name
[out] value_ptr Pointer to hold setting's uint32 value
Returns
Result of API, see gos_result_t
Examples:
network/tcp_echo_server/main.c , network/tcp_multiclient/main.c , and wifi/device_setup/main.c .

◆ gos_settings_load_from_file()

gos_result_t gos_settings_load_from_file ( const char * filename,
bool verbose
)

Load settings from file.

See Gecko OS Command API documentation: load .

Application, Plugin, and Kernel settings are loaded from the specified file on extended flash file system to the RAM NVM cache. After the settings are successfully loaded to cache, the settings are saved to NVM, then the system is rebooted.

Note
This will reboot the system after the settings are loaded.
Application settings will be loaded IF getter/setter variables are provided for the given setting.

See gos_settings_save_to_file() for creating a settings file.

Parameters
[in] filename Filename of file to load settings from
[in] verbose Verbosely load the settings file, printing all commands and messages to log bus
Returns
Result of API, see gos_result_t
Examples:
system/settings_file/main.c .

◆ gos_settings_save()

gos_result_t gos_settings_save ( void )

Save settings to NVM.

This saves all Application, Plugin and Kernel settings in the current RAM cache to NVM.

See Gecko OS Command API documentation: save .

Returns
Result of API, see gos_result_t
Examples:
system/application_nvm/main.c .

◆ gos_settings_save_to_file()

gos_result_t gos_settings_save_to_file ( const char * filename,
bool encrypt
)

Save settings to file.

See Gecko OS Command API documentation: save .

This saves ALL variables that have a getter/setter to the device's extended flash file system.

The settings file can be loaded at another time using gos_settings_load_from_file()

Note
All of the device settings are saved to a file on the extended file system in CSV format. It is STRONGLY recommended to use the encrypt option to encrypt the CSV file. Without encryption, settings like 'wlan.passkey' may be read from the extended flash file system.
This will also save applications settings IF the application provides getter/setter variables for the settings.
Parameters
[in] filename Filename of file to save settings
[in] encrypt If true then store the file encrypted, if false then store the file in plaintext
Returns
Result of API, see gos_result_t

◆ gos_settings_set_int32()

gos_result_t gos_settings_set_int32 ( const char * setting,
int32_t value
)

Set int32 setting.

See Gecko OS Command API documentation: set .

For variables available to set , see Gecko OS Command API documentation: variables .

Note
This only updates the setting in the volatile cache. Use gos_settings_save() for the setting to persist through reboots/powercycles.
Parameters
[in] setting The setting's name
[in] value The setting's new int32 value
Returns
Result of API, see gos_result_t

◆ gos_settings_set_str()

gos_result_t gos_settings_set_str ( const char * setting,
const char * value
)

Set Gecko OS string setting.

See Gecko OS Command API documentation: set .

For variables available to set , see Gecko OS Command API documentation: variables .

Note
This only updates the setting in the volatile cache. Use gos_settings_save() for the setting to persist through reboots/powercycles.
Parameters
[in] setting The setting's name
[in] value The setting's new string value
Returns
Result of API, see gos_result_t
Examples:
file/file_encrypt/main.c , and system/application_nvm/main.c .

◆ gos_settings_set_uint32()

gos_result_t gos_settings_set_uint32 ( const char * setting,
uint32_t value
)

Set uint32 setting.

See Gecko OS Command API documentation: set .

For variables available to set , see Gecko OS Command API documentation: variables .

Note
This only updates the setting in the volatile cache. Use gos_settings_save() for the setting to persist through reboots/powercycles.
Parameters
[in] setting The setting's name
[in] value The setting's new uint32 value
Returns
Result of API, see gos_result_t