BeShell 文档

简体中文

English

简体中文

English

模块: mg

约 2875 字大约 10 分钟

2024-05-25

构建固件和导入到JS

额外组件

该功能需要安装 beshell-mg 组件才能使用。

安装方法：

  1. 编辑项目根目录下的 idf_component.yml 文件，添加依赖：
dependencies:
  become-cool/beshell-mg: '>=1.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：

在.js文件中
import * as mg from '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