BeShell 文档

简体中文

English

简体中文

English

模块: NVS

约 3151 字大约 11 分钟

2026-03-17

构建固件和导入到JS

在 C++ 里加入以下代码, 然后重新编译构建固件：

// 为了控制固件的尺寸，BeShell 的 module 是按需引入的。
beshell.use<be::NVS>() ;

在JS中导入 nvs module：

在.js文件中
import * as nvs from 'nvs'

模块函数

函数 readInt8

原型: readInt8 (key:string)

从 NVS 读取有符号 8 位整数值

从默认命名空间 "beshell" 中读取指定 key 的 int8 值

参数:

  • key

    类型string

    参数说明要读取的键名

返回值:

类型number, null

说明读取到的整数值（-128 ~ 127），不存在时返回 null

函数 readInt16

原型: readInt16 (key:string)

从 NVS 读取有符号 16 位整数值

从默认命名空间 "beshell" 中读取指定 key 的 int16 值

参数:

  • key

    类型string

    参数说明要读取的键名

返回值:

类型number, null

说明读取到的整数值（-32768 ~ 32767），不存在时返回 null

函数 readInt32

原型: readInt32 (key:string)

从 NVS 读取有符号 32 位整数值

从默认命名空间 "beshell" 中读取指定 key 的 int32 值。

示例：

import * as nvs from "nvs"

// 写入整数
nvs.writeInt32("counter", 42)

// 读取整数
const count = nvs.readInt32("counter")
console.log("Count:", count)  // 42

// 读取不存在的键返回 null
const notExist = nvs.readInt32("nonexistent")
console.log(notExist)  // null

// 用于存储时间戳
nvs.writeInt32("lastBoot", Date.now())
const lastBoot = nvs.readInt32("lastBoot")
console.log("Last boot:", new Date(lastBoot))

参数:

  • key

    类型string

    参数说明要读取的键名

返回值:

类型number, null

说明读取到的整数值，不存在时返回 null

函数 readInt64

原型: readInt64 (key:string)

从 NVS 读取有符号 64 位整数值

从默认命名空间 "beshell" 中读取指定 key 的 int64 值

参数:

  • key

    类型string

    参数说明要读取的键名

返回值:

类型number, null

说明读取到的整数值，不存在时返回 null

函数 readUint8

原型: readUint8 (key:string)

从 NVS 读取无符号 8 位整数值

从默认命名空间 "beshell" 中读取指定 key 的 uint8 值。 适合存储小范围数值（0-255），如状态标志、模式选择等。

示例：

import * as nvs from "nvs"

// 存储设备模式（0=正常, 1=省电, 2=性能）
nvs.writeUint8("deviceMode", 1)

// 读取设备模式
const mode = nvs.readUint8("deviceMode")
console.log("Device mode:", mode)

// 存储布尔值（0=false, 1=true）
nvs.writeUint8("firstBoot", 0)
const isFirstBoot = nvs.readUint8("firstBoot") !== 0
console.log("First boot:", isFirstBoot)

参数:

  • key

    类型string

    参数说明要读取的键名

返回值:

类型number, null

说明读取到的整数值（0 ~ 255），不存在时返回 null

函数 readUint16

原型: readUint16 (key:string)

从 NVS 读取无符号 16 位整数值

从默认命名空间 "beshell" 中读取指定 key 的 uint16 值

参数:

  • key

    类型string

    参数说明要读取的键名

返回值:

类型number, null

说明读取到的整数值（0 ~ 65535），不存在时返回 null

函数 readUint32

原型: readUint32 (key:string)

从 NVS 读取无符号 32 位整数值

从默认命名空间 "beshell" 中读取指定 key 的 uint32 值

参数:

  • key

    类型string

    参数说明要读取的键名

返回值:

类型number, null

说明读取到的整数值，不存在时返回 null

函数 writeInt8

原型: writeInt8 (key:string, value:number)

向 NVS 写入有符号 8 位整数值

将 int8 值写入默认命名空间 "beshell" 中指定的 key

参数:

  • key

    类型string

    参数说明要写入的键名

  • value

    类型number

    参数说明要写入的整数值（-128 ~ 127）

异常:

  • value 不是数字

返回值:

类型bool

说明写入成功返回 true，失败返回 false

函数 writeInt16

原型: writeInt16 (key:string, value:number)

向 NVS 写入有符号 16 位整数值

将 int16 值写入默认命名空间 "beshell" 中指定的 key

参数:

  • key

    类型string

    参数说明要写入的键名

  • value

    类型number

    参数说明要写入的整数值（-32768 ~ 32767）

异常:

  • value 不是数字

返回值:

类型bool

说明写入成功返回 true，失败返回 false

函数 writeInt32

原型: writeInt32 (key:string, value:number)

向 NVS 写入有符号 32 位整数值

将 int32 值写入默认命名空间 "beshell" 中指定的 key。

示例：

import * as nvs from "nvs"

// 写入计数器
nvs.writeInt32("bootCount", 1)

// 读取并递增
let count = nvs.readInt32("bootCount") || 0
count++
nvs.writeInt32("bootCount", count)
console.log("Boot count:", count)

// 写入时间戳
nvs.writeInt32("lastUpdate", Date.now())

// 写入负数
nvs.writeInt32("temperature", -5)
console.log("Temperature:", nvs.readInt32("temperature"))

参数:

  • key

    类型string

    参数说明要写入的键名

  • value

    类型number

    参数说明要写入的整数值

异常:

  • value 不是数字

返回值:

类型bool

说明写入成功返回 true，失败返回 false

函数 writeInt64

原型: writeInt64 (key:string, value:number)

向 NVS 写入有符号 64 位整数值

将 int64 值写入默认命名空间 "beshell" 中指定的 key

参数:

  • key

    类型string

    参数说明要写入的键名

  • value

    类型number

    参数说明要写入的整数值

异常:

  • value 不是数字

返回值:

类型bool

说明写入成功返回 true，失败返回 false

函数 writeUint8

原型: writeUint8 (key:string, value:number)

向 NVS 写入无符号 8 位整数值

将 uint8 值写入默认命名空间 "beshell" 中指定的 key

参数:

  • key

    类型string

    参数说明要写入的键名

  • value

    类型number

    参数说明要写入的整数值（0 ~ 255）

异常:

  • value 不是数字

返回值:

类型bool

说明写入成功返回 true，失败返回 false

函数 writeUint16

原型: writeUint16 (key:string, value:number)

向 NVS 写入无符号 16 位整数值

将 uint16 值写入默认命名空间 "beshell" 中指定的 key

参数:

  • key

    类型string

    参数说明要写入的键名

  • value

    类型number

    参数说明要写入的整数值（0 ~ 65535）

异常:

  • value 不是数字

返回值:

类型bool

说明写入成功返回 true，失败返回 false

函数 writeUint32

原型: writeUint32 (key:string, value:number)

向 NVS 写入无符号 32 位整数值

将 uint32 值写入默认命名空间 "beshell" 中指定的 key

参数:

  • key

    类型string

    参数说明要写入的键名

  • value

    类型number

    参数说明要写入的整数值

异常:

  • value 不是数字

返回值:

类型bool

说明写入成功返回 true，失败返回 false

函数 erase

原型: erase (key:string)

删除 NVS 中指定的键值对

从默认命名空间 "beshell" 中删除指定 key 的数据。

示例：

import * as nvs from "nvs"

// 删除一个键
const deleted = nvs.erase("myKey")
console.log("Deleted:", deleted)

// 删除后再读取会返回 null
const value = nvs.readString("myKey")
console.log(value)  // null

参数:

  • key

    类型string

    参数说明要删除的键名

返回值:

类型bool

说明删除成功返回 true，失败返回 false

函数 readString

原型: readString (key:string, buff_size:number=128)

从 NVS 读取字符串值

从默认命名空间 "beshell" 中读取指定 key 的字符串值。

示例：

import * as nvs from "nvs"

// 写入字符串
nvs.writeString("username", "admin")

// 读取字符串
const username = nvs.readString("username")
console.log("Username:", username)

// 读取不存在的键返回 null
const notExist = nvs.readString("nonexistent")
console.log(notExist)  // null

// 存储 JSON 数据
const config = { wifi: { ssid: "MyWiFi", password: "secret" } }
nvs.writeString("config", JSON.stringify(config))

// 读取并解析 JSON
const saved = nvs.readString("config")
const parsed = JSON.parse(saved)
console.log(parsed.wifi.ssid)

参数:

  • key

    类型string

    参数说明要读取的键名

  • buff_size

    类型number

    默认值128

    参数说明缓冲区大小

异常:

  • buff_size 必须大于 0
  • NVS 打开失败
  • 内存分配失败

返回值:

类型string, null

说明读取到的字符串值，不存在时返回 null

函数 writeString

原型: writeString (key:string, value:string)

向 NVS 写入字符串值

将字符串值写入默认命名空间 "beshell" 中指定的 key。

示例：

import * as nvs from "nvs"

// 写入简单字符串
nvs.writeString("deviceName", "ESP32-C3")

// 写入 JSON 字符串
const config = { brightness: 80, volume: 50 }
nvs.writeString("settings", JSON.stringify(config))

// 写入后再读取
const name = nvs.readString("deviceName")
console.log("Device:", name)

参数:

  • key

    类型string

    参数说明要写入的键名

  • value

    类型string

    参数说明要写入的字符串值

返回值:

类型bool

说明写入成功返回 true，失败返回 false