This is the documentation for the latest (main) development branch. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

NVS API Reference

Data structure

nvs module

Copyright 2022-2024 Beijing WinnerMicroelectronics Co.,Ltd.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Defines

WM_NVS_MAX_KEY_LEN

nvs key max size Max size of nvs key, use the config size of CONFIG_NVS_ITEM_NAME_MAX_SIZE

Typedefs

typedef struct wm_nvs_entry_iterator_t *wm_nvs_iterator_t

iterator , handle for poll all nvs items

Enums

enum wm_nvs_type_t

nvs item data type

Values:

enumerator WM_NVS_TYPE_ANY

any type

enumerator WM_NVS_TYPE_STRING

string with 0

enumerator WM_NVS_TYPE_RAW

raw data

enumerator WM_NVS_TYPE_INT8

int8_t

enumerator WM_NVS_TYPE_UINT8

uint8_t

enumerator WM_NVS_TYPE_INT16

int16_t

enumerator WM_NVS_TYPE_UINT16

uint16_t

enumerator WM_NVS_TYPE_INT32

int32_t

enumerator WM_NVS_TYPE_UINT32

uint32_t

enumerator WM_NVS_TYPE_INT64

int64_t

enumerator WM_NVS_TYPE_UINT64

uint64_t

enumerator WM_NVS_TYPE_DOUBLE

float

Functions

int wm_nvs_init(void)

Initialize nvs.

Attention

This API must be called before all other nvs API can be called

Returns:

  • WM_ERR_SUCCESS: succeed

  • WM_ERR_NO_MEM: no memery

  • WM_ERR_FAILED: failed

int wm_nvs_get_str(const char *key, char *out_value, size_t *length)

Set string data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] string data

  • length – [inout] input out_value buffer size, output real value size return WM_ERR_INVALID_PARAM if buf is not enough; “hello” need 6 bytes, the out_value will be: “hello”\0

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error or buffer is not enough

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_set_str(const char *key, const char *value)

Save string data.

Parameters:

  • key – [in] nvs name

  • value – [out] string data,must be end of \0

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_get_blob(const char *key, void *blob, size_t *blob_len)

Get binary data.

Notes: If blob is empty, blob_len returns the actual length to hold the data.

Parameters:

  • key – [in] nvs name

  • blob – [out] binary data

  • blob_len – [inout] binary data length

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error or buffer is not enough

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_set_blob(const char *key, const void *blob, size_t blob_len)

Save binary data.

Parameters:

  • key – [in] nvs name

  • blob – [in] binary data

  • blob_len – [in] binary data length

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_del(const char *key)

Delete the nvs data for the key.

Parameters:

key – [in] nvs name

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_reset(void)

reset nvs

Attention

Calling this api removes all configurations

Returns:

  • WM_ERR_SUCCESS: succeed

  • WM_ERR_FAILED: failed

void wm_nvs_print(void)

Show all nvs information.

Returns:

None

int wm_nvs_set_i8(const char *key, int8_t value)

Save int8 data.

Parameters:

  • key – [in] nvs name

  • value – [in] int8 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_set_u8(const char *key, uint8_t value)

Save uint8 data.

Parameters:

  • key – [in] nvs name

  • value – [in] uint8 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_set_i16(const char *key, int16_t value)

Save int16 data.

Parameters:

  • key – [in] nvs name

  • value – [in] int16 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_set_u16(const char *key, uint16_t value)

Save uint16 data.

Parameters:

  • key – [in] nvs name

  • value – [in] uint16 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_set_i32(const char *key, int32_t value)

Save int32 data.

Parameters:

  • key – [in] nvs name

  • value – [in] int32 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_set_u32(const char *key, uint32_t value)

Save uint32 data.

Parameters:

  • key – [in] nvs name

  • value – [in] uint32 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_set_i64(const char *key, int64_t value)

Save int64 data.

Parameters:

  • key – [in] nvs name

  • value – [in] int64 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_set_u64(const char *key, uint64_t value)

Save uint64 data.

Parameters:

  • key – [in] nvs name

  • value – [in] uint64 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_set_float(const char *key, double value)

Save float data.

Parameters:

  • key – [in] nvs name

  • value – [in] float value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_get_i8(const char *key, int8_t *out_value)

Get int8 data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] int8 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_u8(const char *key, uint8_t *out_value)

Get uint8 data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] uint8 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_i16(const char *key, int16_t *out_value)

Get int16 data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] int16 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_u16(const char *key, uint16_t *out_value)

Get uint16 data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] uint16 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_i32(const char *key, int32_t *out_value)

Get int32 data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] int32 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_u32(const char *key, uint32_t *out_value)

Get uint32 data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] uint32 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_i64(const char *key, int64_t *out_value)

Get int64 data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] int64 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_u64(const char *key, uint64_t *out_value)

Get uint64 data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] uint64 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_float(const char *key, double *out_value)

Get float data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] float value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_entry_find(const char *prefix, wm_nvs_type_t type, wm_nvs_iterator_t *output_iterator)

find iterator, used for poll all or specified items note: it will lock nvs until wm_nvs_entry_next end or wm_nvs_release_iterator is called. only current task can access before unlock.

Parameters:

  • prefix – [in] nvs key name prefix,NULL for all keys

  • type – [in] data type,WM_NVS_TYPE_ANY for all types

  • output_iterator – [out] iterator

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAIL fail

int wm_nvs_entry_next(wm_nvs_iterator_t *iterator)

change to next iterator

Parameters:

iterator – [inout] iterator to next item out iterator: ! NULL : next item NULL : iterator end, the memery is released, the mutex is unlocked.

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAIL iterator end or fail

int wm_nvs_entry_info(wm_nvs_iterator_t iterator, wm_nvs_entry_t *info)

get iterator info

Parameters:

  • iterator – [in] iterator

  • info – [out] iterator entry information

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAIL fail

int wm_nvs_entry_data(wm_nvs_iterator_t iterator, void *data, size_t *data_len)

get iterator data

Parameters:

  • iterator – [in] iterator

  • data – [out] iterator entry information

  • data_len – [inout] data len, input buffer len, output real len, return WM_ERR_INVALID_PARAM if input data_len is not enough

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAIL fail

int wm_nvs_release_iterator(wm_nvs_iterator_t iterator)

get iterator data

Parameters:

iterator – [in] iterator release memory and unlock

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

int wm_nvs_get_info(const char *key, wm_nvs_type_t *type, size_t *size)

get item type and size

Parameters:

  • key – [in] nvs item name

  • type – [out] data type, wm_nvs_type_t

  • size – [out] data size

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND

int wm_nvs_get_status(wm_nvs_status_t *status)

get nvs status

Parameters:

status – [out] nvs status, wm_nvs_status_t

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

struct wm_nvs_entry_t

iterator entry information

Public Members

wm_nvs_type_t type

data type

const char *key

item key

size_t data_len

data length

struct wm_nvs_status_t

nvs status

Public Members

uint32_t total_size

total size

uint32_t total_free

total free size

uint32_t max_free_block_size

max free block size

uint16_t sector_num

sector num

uint16_t item_num

save item num

Interface definition:

int wm_nvs_init(void)

Initialize nvs.

Attention

This API must be called before all other nvs API can be called

Returns:

  • WM_ERR_SUCCESS: succeed

  • WM_ERR_NO_MEM: no memery

  • WM_ERR_FAILED: failed

int wm_nvs_get_str(const char *key, char *out_value, size_t *length)

Set string data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] string data

  • length – [inout] input out_value buffer size, output real value size return WM_ERR_INVALID_PARAM if buf is not enough; “hello” need 6 bytes, the out_value will be: “hello”\0

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error or buffer is not enough

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_set_str(const char *key, const char *value)

Save string data.

Parameters:

  • key – [in] nvs name

  • value – [out] string data,must be end of \0

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_get_blob(const char *key, void *blob, size_t *blob_len)

Get binary data.

Notes: If blob is empty, blob_len returns the actual length to hold the data.

Parameters:

  • key – [in] nvs name

  • blob – [out] binary data

  • blob_len – [inout] binary data length

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error or buffer is not enough

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_set_blob(const char *key, const void *blob, size_t blob_len)

Save binary data.

Parameters:

  • key – [in] nvs name

  • blob – [in] binary data

  • blob_len – [in] binary data length

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_del(const char *key)

Delete the nvs data for the key.

Parameters:

key – [in] nvs name

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_reset(void)

reset nvs

Attention

Calling this api removes all configurations

Returns:

  • WM_ERR_SUCCESS: succeed

  • WM_ERR_FAILED: failed

void wm_nvs_print(void)

Show all nvs information.

Returns:

None

int wm_nvs_set_i8(const char *key, int8_t value)

Save int8 data.

Parameters:

  • key – [in] nvs name

  • value – [in] int8 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_set_u8(const char *key, uint8_t value)

Save uint8 data.

Parameters:

  • key – [in] nvs name

  • value – [in] uint8 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_set_i16(const char *key, int16_t value)

Save int16 data.

Parameters:

  • key – [in] nvs name

  • value – [in] int16 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_set_u16(const char *key, uint16_t value)

Save uint16 data.

Parameters:

  • key – [in] nvs name

  • value – [in] uint16 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_set_i32(const char *key, int32_t value)

Save int32 data.

Parameters:

  • key – [in] nvs name

  • value – [in] int32 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_set_u32(const char *key, uint32_t value)

Save uint32 data.

Parameters:

  • key – [in] nvs name

  • value – [in] uint32 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_set_i64(const char *key, int64_t value)

Save int64 data.

Parameters:

  • key – [in] nvs name

  • value – [in] int64 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_set_u64(const char *key, uint64_t value)

Save uint64 data.

Parameters:

  • key – [in] nvs name

  • value – [in] uint64 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_set_float(const char *key, double value)

Save float data.

Parameters:

  • key – [in] nvs name

  • value – [in] float value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAILED save item fail

int wm_nvs_get_i8(const char *key, int8_t *out_value)

Get int8 data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] int8 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_u8(const char *key, uint8_t *out_value)

Get uint8 data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] uint8 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_i16(const char *key, int16_t *out_value)

Get int16 data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] int16 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_u16(const char *key, uint16_t *out_value)

Get uint16 data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] uint16 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_i32(const char *key, int32_t *out_value)

Get int32 data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] int32 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_u32(const char *key, uint32_t *out_value)

Get uint32 data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] uint32 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_i64(const char *key, int64_t *out_value)

Get int64 data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] int64 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_u64(const char *key, uint64_t *out_value)

Get uint64 data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] uint64 value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_get_float(const char *key, double *out_value)

Get float data.

Parameters:

  • key – [in] nvs name

  • out_value – [out] float value

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND item is not found

int wm_nvs_entry_find(const char *prefix, wm_nvs_type_t type, wm_nvs_iterator_t *output_iterator)

find iterator, used for poll all or specified items note: it will lock nvs until wm_nvs_entry_next end or wm_nvs_release_iterator is called. only current task can access before unlock.

Parameters:

  • prefix – [in] nvs key name prefix,NULL for all keys

  • type – [in] data type,WM_NVS_TYPE_ANY for all types

  • output_iterator – [out] iterator

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAIL fail

int wm_nvs_entry_next(wm_nvs_iterator_t *iterator)

change to next iterator

Parameters:

iterator – [inout] iterator to next item out iterator: ! NULL : next item NULL : iterator end, the memery is released, the mutex is unlocked.

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAIL iterator end or fail

int wm_nvs_entry_info(wm_nvs_iterator_t iterator, wm_nvs_entry_t *info)

get iterator info

Parameters:

  • iterator – [in] iterator

  • info – [out] iterator entry information

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAIL fail

int wm_nvs_entry_data(wm_nvs_iterator_t iterator, void *data, size_t *data_len)

get iterator data

Parameters:

  • iterator – [in] iterator

  • data – [out] iterator entry information

  • data_len – [inout] data len, input buffer len, output real len, return WM_ERR_INVALID_PARAM if input data_len is not enough

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_FAIL fail

int wm_nvs_release_iterator(wm_nvs_iterator_t iterator)

get iterator data

Parameters:

iterator – [in] iterator release memory and unlock

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

int wm_nvs_get_info(const char *key, wm_nvs_type_t *type, size_t *size)

get item type and size

Parameters:

  • key – [in] nvs item name

  • type – [out] data type, wm_nvs_type_t

  • size – [out] data size

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error

  • WM_ERR_NOT_FOUND

int wm_nvs_get_status(wm_nvs_status_t *status)

get nvs status

Parameters:

status – [out] nvs status, wm_nvs_status_t

Returns:

  • WM_ERR_SUCCESS on success

  • WM_ERR_INVALID_PARAM param error