模块: mg
约 2875 字大约 10 分钟
2024-05-25
构建固件和导入到JS
额外组件
该功能需要安装 beshell-mg 组件才能使用。
安装方法:
- 编辑项目根目录下的
idf_component.yml文件,添加依赖:
dependencies:
become-cool/beshell-mg: '>=1.1.1'- 或在 ESP-IDF 环境的命令行中执行:
idf.py add-dependency "become-cool/beshell-mg>=1.1.1"在 C++ 里加入以下代码, 然后重新编译构建固件:
// 为了控制固件的尺寸,BeShell 的 module 是按需引入的。
beshell.use<be::mg::Mg>() ;在JS中导入 mg module:
import * as mg from 'mg'import mg简介
BeShell 集成了 Mongoose 库,用来处理网络应用层的协议,包括 HTTP(S)、WebSocket、MQTT、SNTP、SMTP 等。
关于 mg 模块的例子请参考: 在 ESP32 上用 JavaScript 开发 WEB 后端
事件
error: 发生错误
open: 客户端连接
poll: 轮询事件
resolve: 域名解析完成
connect: 客户端连接建立完成
accept: 客户端连接接受完成
read: 客户端数据接收完成
write: 客户端数据发送完成
close: 客户端连接关闭
http.msg: HTTP 请求/响应消息接收完成
ws.open: WebSocket 握手完成
ws.msg: WebSocket 消息接收完成
ws.ctl: WebSocket 控制消息接收完成
mqtt.cmd: MQTT 低级命令接收完成
mqtt.msg: MQTT PUBLISH 消息接收完成
mqtt.open: MQTT CONNACK 接收完成
sntp.time: SNTP 时间接收完成模块函数
函数 listenHttp
原型: listenHttp (addrOrOptions:string|object, callback:function)
创建一个处理 http 协议的服务器实例。
此函数的例子参考:简单 HTTP Web 后端的例子
第一个参数可以是 [ip:port] 格式的字符串表示服务器地址,例如 "0.0.0.0:8080"
第一个参数也可以是一个对象:
{
addr: string ,
ssl: boolean ,
callback: (ev:string, req, rspn)=>void
}
回调函数的原型:
callback(event:string, request:[HTTPRequest](HTTPRequest.html), response:[HTTPResponse](HTTPResponse.html)): void
其中 event 参数参考:mg 事件
参数:
addrOrOptions
类型string, object
参数说明该参数可以是 [ip:port] 格式的字符串表示服务器地址,或选项对象
callback
类型function
参数说明服务器事件回调函数,该函数接收三个参数:事件名称、请求对象、响应对象
返回值:
函数 connect
原型: connect (url:string, callback:function)
创建并执行一个客户端连接
该函数的第一个参数是连接地址,第二个参数是一个回调函数,该函数接收三个参数:事件名称、请求对象。
回调函数的原型:
callback(event:string, request:[HTTPRequest](HTTPRequest.html)): void
其中 event 参数参考:mg 事件
参数:
url
类型string
参数说明连接地址,例如
"http://www.example.com/path"callback
类型function
参数说明事件回调函数
返回值:
函数 connPeer
原型: connPeer (idx:number)
返回指定客户端连接的对端地址 [ip:port]
参数:
idx
类型number
参数说明表示第几个客户端
返回值:
类型string
函数 connCount
原型: connCount ()
连接到服务器的客户端数量
返回值:
类型number
函数 getDNS
原型: getDNS ()
返回当前 dns 服务器地址
返回值:
类型string
函数 setDNS
原型: setDNS (url:string)
设置 dns 服务器地址
参数:
url
类型string
参数说明eg: 1.1.1.1:53
返回值:
undefined
函数 getDNSTimeout
原型: getDNSTimeout ()
返回当前 dns 请求超时时间设定,单位毫秒
返回值:
类型number
函数 setDNSTimeout
原型: setDNSTimeout (ms:number)
设置 dns 请求超时时间,单位毫秒
参数:
ms
类型number
参数说明
返回值:
undefined
函数 addDNSCache
原型: addDNSCache (domain:string, ip:string, ttl:number=0)
添加一条 DNS 缓存记录
参数:
domain
类型string
参数说明域名
ip
类型string
参数说明IP地址(如 "1.2.3.4")
ttl
类型number
默认值0
参数说明有效期(毫秒),0 表示永久有效
返回值:
类型undefined
函数 removeDNSCache
原型: removeDNSCache (domain:string)
移除指定域名的 DNS 缓存
参数:
domain
类型string
参数说明域名
返回值:
类型undefined
函数 clearDNSCache
原型: clearDNSCache ()
清空所有 DNS 缓存
返回值:
类型undefined
函数 parseUrl
原型: parseUrl (url:string)
解析 URL 字符串
参数:
url
类型string
参数说明要解析的 URL 字符串
返回值:
类型object (详见下方类型定义)
说明解析后的 URL 对象
返回值类型定义:
{
host: string, // 主机名
port: number, // 端口号
uri: string // URI 路径
}函数 setLog
原型: setLog (log:number)
设置 mg 的日志级别
- 0: none
- 1: error
- 2: info
- 3: debug
- 4: verbose
参数:
log
类型number
参数说明
返回值:
类型undefined
函数 setCA
原型: setCA (cert:ArrayBuffer)
tls 需要较大 ram ,通常启用 WiFi 后剩余 ram 不足,此时会打印错误 mg_error 4 setup err 0x7f00 。 可以尝试将 mbedtls 的内容放在 psram 中( CONFIG_MBEDTLS_EXTERNAL_MEM_ALLOC=y )
参数:
cert
类型ArrayBuffer
参数说明TLS证书数据
返回值:
类型undefined
函数 request
原型: request (url:string, handle:function)
通用 HTTP 请求函数
返回一个 Promise,用于执行 HTTP 请求。支持处理各种 HTTP 事件。
示例:
import * as mg from 'mg'
await mg.request('http://example.com/api', (conn, event, data, timeTick) => {
if(event=='new') {
// 连接刚创建
}
else if(event=='connect') {
// 连接成功
conn.send('GET /api HTTP/1.0\r\nHost: example.com\r\n\r\n')
}
else if(event=='http.msg') {
// 收到完整响应
console.log(data.body())
}
})事件类型:
new: 连接刚创建connect: 连接成功http.msg: 收到完整 HTTP 响应http.chunk: 收到数据块(启用分块传输时)close: 连接关闭error: 发生错误timeout: 请求超时
参数:
url
类型string
参数说明请求地址,例如
"http://www.example.com/path"handle
类型function
参数说明事件处理函数,接收参数 (conn, event, data, timeTick)
返回值:
类型Promise<ArrayBuffer>
说明返回包含响应体的 Promise
函数 get
原型: get (url:string, handle:function=null)
发送 HTTP GET 请求
简化版的 HTTP 请求函数,自动发送 GET 请求并返回响应体。
示例:
import * as mg from 'mg'
let body = await mg.get('http://example.com/data')
console.log(body)参数:
url
类型string
参数说明请求地址
handle
类型function
默认值null
参数说明可选的事件处理函数
返回值:
类型Promise<ArrayBuffer>
说明返回包含响应体的 Promise
函数 download
原型: download (url:string, localPath:string=null, progress_cb:function=null)
下载文件
支持分块下载大文件,并可选择保存到本地文件系统。
示例:
import * as mg from 'mg'
// 下载到内存
await mg.download('http://example.com/file.bin', null, (total, current, chunk) => {
console.log(`Progress: ${current}/${total}`)
})
// 下载到文件
await mg.download('http://example.com/file.bin', '/data/file.bin', (total, current) => {
console.log(`Downloaded: ${(current/total*100).toFixed(1)}%`)
})参数:
url
类型string
参数说明下载地址
localPath
类型string
默认值null
参数说明本地保存路径,为 null 时不保存到文件
progress_cb
类型function
默认值null
参数说明进度回调函数,接收参数 (total, current, chunk)
异常:
- 连接意外断开时抛出错误
返回值:
类型Promise<undefined>
说明下载完成时 resolve
函数 post
原型: post (url:string, ab:ArrayBuffer)
发送 HTTP POST 请求
发送 POST 请求,请求体为 ArrayBuffer。
示例:
import * as mg from 'mg'
let data = new Uint8Array([1, 2, 3, 4]).buffer
let response = await mg.post('http://example.com/upload', data)
console.log(response)参数:
url
类型string
参数说明请求地址
ab
类型ArrayBuffer
参数说明请求体数据
返回值:
类型Promise<ArrayBuffer>
说明返回包含响应体的 Promise
