模块: sleep

约 4274 字大约 14 分钟

2026-08-26

构建固件和导入到JS

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

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

在JS中导入 sleep module：

在.js文件中

import * as sleep from 'sleep'

在REPL命令行下

import sleep

简介

系统睡眠模块, 提供 ESP32 的 light/deep/modem 睡眠以及各种唤醒源的设置

三种睡眠方式在调用逻辑上有本质区别:

light() / modem(): 同步阻塞函数。调用后当前 JS 线程挂起 (事件循环停止, 定时器/网络回调等不再执行), 直到唤醒源触发才返回, 返回值为唤醒源字符串, 之后的代码继续执行, JS 运行环境完全保留
deep(): 调用后不会返回。唤醒时设备整体重启, 脚本从头重新执行, JS 运行环境无法恢复, 唤醒原因需在重启后用 wakeupCause() 查询

唤醒源字符串: "timer" "ext0" "ext1" "gpio" "uart" "touch" "wifi.data" "wifi.disconnected" "wifi.beacon-timeout" 等

示例：

import * as sleep from "sleep"

// 1. 最简单的 light sleep: 睡 5 秒 (同步阻塞, 5 秒后才执行下一行)
let source = sleep.light(5000)
console.log("wakeup source:", source)   // "timer"

// 2. light sleep + 按钮唤醒: 定时与 GPIO 唤醒源叠加, 任一触发即返回
import * as gpio from "gpio"
gpio.setMode(4, "input")
gpio.pull(4, "up")
sleep.enableLightGPIOWakeup(4, 0)        // GPIO 4 接地时唤醒
source = sleep.light(60000)              // 最多睡 60 秒, 按钮可提前唤醒
console.log("wakeup source:", source)   // "gpio" 或 "timer"

// 3. deep sleep: 睡 1 小时后重启 (此行之后的代码不会执行)
//    需要跨睡眠保存的数据先写入 NVS
sleep.deep(3600_000)
console.log("这行永远不会执行")

// 4. deep sleep + 按钮唤醒, 重启后判断唤醒原因
//    (脚本开头)
if(sleep.wakeupCause() == "ext0") {
    console.log("被按钮唤醒")
}
//    ... 正常工作逻辑 ...
sleep.enableExt0Wakeup(33, 1)            // GPIO 33 高电平唤醒
sleep.deep()                             // 不返回, 唤醒即重启

// 5. modem sleep: 保持 WiFi 连接的睡眠, 有下行数据时唤醒
//    (要求 WiFi STA 已连接)
source = sleep.modem(10000)              // 有下行数据或 10 秒超时返回
console.log("wakeup source:", source)   // "wifi.data" / "timer" / ...

模块函数

函数 light

原型: light (ms:number=)

进入 light sleep (轻睡眠)

这是一个同步阻塞函数: 调用后 CPU 暂停执行, 当前 JS 线程挂起, 事件循环停止运转 (setTimeout/Promise 回调/网络事件等都不会执行)。唤醒源触发后函数才返回唤醒源字符串, 其后的语句继续执行; SRAM/PSRAM 数据保持, beshell/QuickJS 以及 mongoose 等网络库的状态完全保留。请勿用 sleep.light(ms).then(...) 之类的异步方式调用。

传入 ms 参数等价于先调用 enableTimerWakeup(ms) 再进入睡眠; 不传参数则一直睡眠, 直到已配置的唤醒源触发。

警告: 不传 ms 且没有配置任何唤醒源时, 将永远无法唤醒。

警告: 在 ESP32-S3/C3/C6 等芯片上, 若使用原生 USB (USB Serial/JTAG) 作为 console, 当前版本的 light() 返回后 USB REPL 将失效: 唤醒后 USB 串口无法恢复 (重连串口、物理拔插均可能无法识别设备, 通常需重启设备才能恢复)。这是 ESP-IDF 官方已知限制: 该类芯片的 USJ 外设不支持 light sleep 保活 (见 ESP-IDF 文档 Light-sleep Limitations); 本模块曾尝试 BBPLL 保活 + 唤醒后复位 USJ/模拟拔插强制重枚举, 均无法稳定恢复。 如需保留 USB REPL 请改用 deep() (唤醒即重启, USB 正常重新枚举)。 UART0 串口 console 不受此问题影响。

唤醒后将唤醒源字符串作为返回值。

示例：

import * as sleep from "sleep"

// 定时 5 秒唤醒
let source = sleep.light(5000)
console.log("wakeup source:", source)

// 由 GPIO 唤醒
sleep.enableLightGPIOWakeup(4, 0)
source = sleep.light()
console.log("wakeup source:", source)  // "gpio"

参数:

ms
类型number
默认值
参数说明定时唤醒时间, 单位毫秒, 可选

控件

模块: sleep