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 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:: demo/3d_demo/main.c , demo/accelerometer_stream/main.c , network/http_methods/main.c , network/http_server/main.c , network/http_server_stream/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_cmd_stream/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:

Load application specific settings only (no save or reboot)
This is the same as calling gos_load_app_settings()

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 ONCE per application execution. Subsequent calls to this API will return GOS_NOT_ALLOWED .

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:: cloud/dps_demo/main.c , demo/uart_blaster/main.c , dms/messages/main.c , dms/telemetry/main.c , hurricane/arducam/settings.c , hurricane/marble/main.c , hurricane/security_camera/settings.c , network/ethernet_bridge/main.c , network/https_server/main.c , network/uart_tcp_client/main.c , system/application_settings/main.c , and system/indicator/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 , demo/3d_demo/main.c , demo/accelerometer_stream/main.c , dms/telemetry/main.c , hurricane/arducam/network.c , network/http_server/main.c , network/http_server_stream/main.c , network/websocket_cmd_stream/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 , and system/indicator/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

Gecko OS Settings Settings and NVM

Modules

Functions

Detailed Description

Function Documentation

◆ gos_load_app_settings()

◆ gos_load_app_settings_once()

◆ gos_settings_factory_reset()

◆ gos_settings_get_print_str()

◆ gos_settings_get_str()

◆ gos_settings_get_uint32()

◆ gos_settings_load_from_file()

◆ gos_settings_save()

◆ gos_settings_save_to_file()

◆ gos_settings_set_int32()

◆ gos_settings_set_str()

◆ gos_settings_set_uint32()

Gecko OS Settings
Settings and NVM