API 文档概览
约 1601 字大约 5 分钟
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 mgBeShell 提供的模块
系统与核心
文件系统
网络与通信
wifi WiFi 连接管理(STA/AP 模式)
eth W5500 以太网驱动
bt 蓝牙 BLE(Central/Peripheral)
mg Mongoose 网络库(HTTP/WebSocket/MQTT/TCP)
硬件接口
固件升级
ota 空中固件升级(OTA)
存储与外设
GUI 图形界面(LVGL)
快速示例
连接 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.0.0 | WS2812B LED 驱动 |
相关链接
- 快速开始 - 快速上手 BeShell
- 用 JavaScript 连接 WiFi - WiFi 使用指南
- 在 ESP32 上用 JavaScript 开发 WEB 后端 - HTTP 服务器开发
- REPL 使用指南 - 交互式命令行
