API 文档概览

约 1755 字大约 6 分钟

2024-05-25

BeShell API 文档

本文档涵盖了 BeShell 框架提供的 Native Module（原生模块） API。

BeShell 支持两种类型的模块：

Native Module（原生模块）：由 C++ 和嵌入到 C++ 的 JavaScript 实现，提供硬件访问、系统功能和高性能操作，本文档主要介绍这类模块。
User Module（用户模块）：由 JavaScript 文件（.js）实现，通过 ESM 的 import 语法加载，与 Native Module 使用相同的导入语法。

所有模块（无论是 Native Module 还是 User Module）都遵循 ESM（ECMAScript Modules） 标准，使用相同的 import 语法加载。

架构概述

BeShell 的功能划分为组件（Component） -> 模块（Module） -> 类/对象/函数 三个层次：

组件（Component）

组件是 ESP-IDF 的构建单元。

类型	说明	用途
核心组件	`beshell` 主库	包含基础功能和常用模块
扩展组件	`beshell-*` 系列	编译时间长或非必用的功能

为什么使用扩展组件？

扩展组件的设计目的是为了加快编译时间和减小固件体积。将编译时间长、依赖复杂或非必用的功能拆分为独立组件，开发者可以按需引入，避免不必要的编译开销。

模块（Module）

模块是 JavaScript 运行时的功能单元。本文档介绍的 Native Module 由 C++ 实现，通过 import 语句加载到 JavaScript 环境中。

BeShell 的模块系统遵循 ESM（ECMAScript Modules） 标准，支持标准的 ES6 模块语法：

// 命名空间导入
import * as fs from 'fs'

// 默认导入
import wifi from 'wifi'

// 命名导入
import { W5500 } from 'eth'

// 动态导入
const mg = await import('mg')

模块分为两类：

类型	说明	C++ 配置
内置模块	固件启动时自动加载	无需 `use()`
按需模块	需要显式 use 和 import	`beshell.use<Module>()`

为什么按需 use？

按需 use 的设计是为了控制固件大小和运行时内存占用。每个模块都会占用 Flash 空间和 RAM，按需引入可以创建精简的固件，适合资源受限的场景。

使用流程

详细步骤说明

1. 安装组件（仅扩展组件需要）

如果功能属于扩展组件，先编辑 idf_component.yml：

dependencies:
  become-cool/beshell-mg: '>=1.1.1'

或使用命令行：

idf.py add-dependency "become-cool/beshell-mg>=1.1.1"

2. C++ 层 use 模块（仅按需模块需要）

在固件主程序中 use 需要的模块：

#include <BeShell.hpp>

void app_main() {
    beshell.use<be::WiFi>()      // WiFi 模块
         .use<be::FS>()          // 文件系统
         .use<be::mg::Mg>() ;    // Mongoose 网络
    
    beshell.setup() ;
    beshell.loop() ;
}

3. JavaScript 层 import 模块

在 JS 代码中导入模块：

// 在 .js 文件中
import * as wifi from 'wifi'
import * as fs from 'fs'
import * as mg from 'mg'

// 在 REPL 命令行下
import wifi
import fs
import mg

BeShell 提供的模块

系统与核心

process 系统功能：重启、内存、版本、MAC 地址等

repl 交互式命令行环境，支持多通道远程控制

loader 模块加载器，支持字节码编译

nvs 非易失性存储，键值对持久化

sleep 系统睡眠（light/deep/modem）与唤醒源

logger 日志捕获：将系统输出以循环日志形式持久化到 Flash 分区

文件系统

fs 文件系统操作（LittleFS/FATFS/SPIFFS）

flash Flash 分区管理

网络与通信

wifi WiFi 连接管理（STA/AP 模式）

eth 以太网驱动（W5500 等）

bt 蓝牙 BLE（Central/Peripheral）

mg Mongoose 网络库（HTTP/WebSocket/MQTT/TCP）

硬件接口

gpio GPIO 控制、中断、PWM、ADC

serial 串口外设（UART/I2C/SPI/CDC）

动画与多媒体

animator 动画（缓动函数、关键帧时间线、值过渡）

audio-player 音频播放器（MP3/WAV/PCM，I2S 输出）

固件升级

ota 空中固件升级（OTA）

存储与外设

sdcard SD 卡驱动（SPI 模式）

ws2812b WS2812B LED 灯带驱动（Strip / Section / Rainbow 动画）

GUI 图形界面（LVGL）

lvgl 基于 LVGL 9.0 的图形界面库，提供完整的控件体系和样式、事件、动画能力

快速示例

连接 WiFi 并启动 HTTP 服务器

import * as wifi from 'wifi'
import * as mg from 'mg'

// 连接 WiFi
wifi.on('connected', (ev, info) => {
    console.log('WiFi connected:', info.ip)
    
    // 创建 HTTP 服务器
    const server = new mg.HTTPServer()
    server.on('request', (ev, req, res) => {
        res.setStatus(200)
        res.setHeader('Content-Type', 'text/html')
        res.end('<h1>Hello from BeShell!</h1>')
    })
    server.listen(80)
})

wifi.connect({
    ssid: 'YourSSID',
    password: 'YourPassword'
})

读写文件

import * as fs from 'fs'

// 写入文件
fs.writeFile('/data/hello.txt', 'Hello, BeShell!')

// 读取文件
const content = fs.readFile('/data/hello.txt')
console.log(content.toString())

// 列出目录
const files = fs.readdir('/data')
console.log(files)

控制 GPIO

import * as gpio from 'gpio'

// 设置 GPIO 模式
gpio.setMode(2, 'output')

// 输出高电平
gpio.write(2, 1)

// 读取输入
gpio.setMode(4, 'input')
const value = gpio.read(4)
console.log('GPIO 4:', value)

// PWM 输出
import * as pwm from 'gpio'
pwm.pwm.setup({
    pin: 5,
    frequency: 1000,
    duty: 50
})

串口通信

import * as serial from 'serial'

// 配置 UART2
serial.uart2.setup({
    tx: 17,
    rx: 16,
    baudrate: 115200
})

// 发送数据
serial.uart2.write('Hello UART!\n')

// 接收数据
serial.uart2.on('data', (data) => {
    console.log('Received:', data.toString())
})

扩展组件安装参考

组件	最新版本	功能
beshell-mg	>=1.1.1	HTTP/WebSocket/MQTT 网络协议
beshell-bt	>=1.0.2	蓝牙 BLE 支持
beshell-ota	>=1.0.0	空中固件升级
beshell-drv-eth	>=1.0.0	W5500 以太网驱动
beshell-drv-sdcard	>=1.0.0	SD 卡驱动
beshell-drv-ws2812b	>=1.1.0	WS2812B LED 灯带驱动与动画
beshell-AudioPlayer	>=1.0.1	音频播放器（MP3/WAV/PCM）
beshell-lvgl	>=1.0.2	LVGL 图形界面库

GPIO

Animator(动画)

Serial

REPL

BT(蓝牙)

Mongoose(网络库)

LVGL(图形界面库)

控件

以太网驱动

WS2812B驱动

FastAccelStepper驱动

AudioPlayer(音频播放)