使用手册
应用插件

经典蓝牙 连接

Bittly 经典蓝牙连接用于连接并控制各种经典蓝牙设备。 设备连接后，可通过设置脚本，分帧，转发，心跳等功能，实现数据的发送和接收。

Bluetooth-Classic

连接

  • 设备 : 通过搜索设备列表选择目标经典蓝牙设备。
  • 内容模式 : 选择串口通讯的内容模式，支持文本和HEX两种，用于优化数据展示和解析。
  • 字符集 : 当内容模式为文本时，选择用于解析文本数据的字符集。
  • 发送包最大尺寸 : 设定串口通讯的单个发送包的最大尺寸（字节）。超过此尺寸的数据将分多个包发送。设置为0时表示不限制尺寸。
  • 发送包间隔 : 设置发送大于最大尺寸包时，各包之间的发送间隔（毫秒）。

脚本

从开始与串口设备建立连接到关闭连接，串口通讯支持多个回调函数，您可以在这些回调函数中编写自定义的脚本，以实现串口通讯的各种功能。

生命周期回调函数

连接建立前

回调函数 beforeConnect()

beforeConnect函数在串口连接建立前执行，当函数抛出异常时，将不再进行连接操作。

函数定义：

export async function beforeConnect() {
    // your code here
}

连接建立后

回调函数 afterConnect()

afterConnect函数在串口连接建立后执行。 当函数抛出异常时，将断开连接。

函数定义：

export async function afterConnect() {
    // your code here
}

数据接收

回调函数 onData(data)

onData函数在串口接收到数据时执行。 在此函数中，您可以对接收到的数据进行处理， 例如验证，提取等操作，如果函数返回 null, 则忽略收到的数据，不再进行处理。

函数定义：

export async function onData(data) {
    // your code here
    return data;
}

数据帧接收

回调函数 onFrame(frame)

onFrame函数在串口接收到完整的数据帧时执行。 在此函数中，您可以对接收到的数据进行处理， 例如验证，提取等操作，如果函数返回 null, 则忽略收到的数据，不再进行处理。

函数定义：

export async function onFrame(frame) {
    // your code here
    return frame;
}

数据发送前

回调函数： beforeWrite(data)

beforeWrite函数在串口发送数据前执行。 在此函数中，您可以对发送的数据进行处理， 例如验证，追加等操作，如果函数返回 null, 则不再进行发送操作。

函数定义：

export async function beforeWrite(data) {
    // your code here
    return data;
}

数据发送后

回调函数： afterWrite(data)

afterWrite函数在串口发送数据后执行。

函数定义：

export async function afterWrite( data ) {
    // your code here
}

关闭连接前

回调函数： beforeClose()

beforeClose函数在串口关闭连接前执行。

函数定义：

export async function beforeClose() {
    // your code here
}

关闭连接后

回调函数： afterClose()

afterClose函数在串口关闭连接后执行。

函数定义：

export async function afterClose() {
    // your code here
}

心跳

回调函数： heartbeat()

heartbeat 函数用于执行心跳操作，当连接心跳设置为脚本时，该函数将会被周期性执行。

函数定义：

export async function heartbeat() {
    // your code here
}

自定义函数

自定义函数可以被脚本中的其他函数调用，也可以使用在消息模板中，以实现更加灵活的功能。

内部函数仅可以在脚本中使用，不可在消息模板中使用。 例如：

// 自定义函数
function hello() {
    return "hello world";
}

// 函数调用方式
let msg = hello();

如果需要执行写入，延时等需要等待的操作，可以使用 await 关键字来等待操作完成，例如：

// 自定义函数
async function writeHello() {
    await $this.write("hello world");
}

// 函数调用方式
await writeHello();

如果自定义的函数需要在消息模板中使用，可以使用 export 关键字来导出函数，例如：

// 自定义函数
export function hello(name) {
    return `hello ${name}`;
}

// 函数调用方式
// 消息模板： {{ hello("world") }}

在消息模板中调用的函数不可使用 await 关键字定义函数， 因为模板中的函数调用是同步执行的。

脚本上下文

$this - 当前连接

$this 为当前连接对象，您可以通过 $this 对象调用连接的各种方法，例如写入数据等。

$this.write - 写入数据

// 写入字符串
await $this.write("hello world");

// 写入Buffer
await $this.write(Buffer.from("hello world"));

// 写入字节数组
await $this.write([0x01, 0x02, 0x03]);

$this.variable - 获取/设置变量

// 获取变量
let value = $this.variable("name");

// 设置变量
$this.variable("name", "value");

$this.log - 输出日志

// 输出日志
$this.log("hello world");

$ - 全局对象

分帧

当收到数据后，可能收到的数据不是一个完整的数据包，或者存在多余的数据，这时需要对数据进行分帧处理。

无

收到数据后直接提交给后续步骤处理，不做任何处理。

超时

配置项

  • 时间 : 超时时间，单位毫秒。

当收到数据后，如果在超时时间内没有收到更多数据，则标识该数据为一个完整的数据包，提交给后续步骤处理。 如果在超时时间内收到更多数据，则继续等待。

换行

配置项

  • 换行符 : 换行符。支持\r, \n 和 \r\n。

当收到数据后，如果收到换行符，则标识该数据为一个完整的数据包，提交给后续步骤处理。 如果没有收到换行符，则继续等待。

假设换行符为 \n， 收到数据如下：

hello\nworld\n123

则收到的数据帧为：

hello\n

和

world\n

数据末尾的 123 会被保留，等待下一次数据到来。

固定长度

配置项

  • 长度 : 固定长度，单位字节。

当收到数据后，如果收到的数据长度等于固定长度，则标识该数据为一个完整的数据包，提交给后续步骤处理。 如果收到的数据长度小于固定长度，则继续等待。

假设收到数据长度为 13，固定长度为 5，收到的数据如下：

hello12345!!!

则收到的数据帧为：

hello

和

12345

数据末尾的 !!! 会被保留，等待下一次数据到来。

匹配头尾

配置项

  • 帧头 : 帧头标识，可选。
  • 帧尾 : 帧尾标识，可选。
  • 超时 : 超时时间，单位毫秒。

当配置了帧头和帧尾时，则当收到数据后，如果收到的数据包含帧头和帧尾，则标识该数据为一个完整的数据包，提交给后续步骤处理。 如果在帧头之前存在数据，则会被忽略， 即仅仅被帧头帧尾包括的内容会被提交给后续步骤处理。

假设帧头为 hello，帧尾为 world，收到的数据如下：

hello12345world

则收到的数据帧为：

12345

如果配置了帧头而未配置帧尾，接收到的数据将按以下规则处理：若能识别出下一帧的帧头，则将当前帧头至下一帧帧头之前的数据视为完整数据包， 并提交给后续处理。如果未检测到下一帧帧头，则系统将根据设置的超时时间等待，超时后将已接收的数据作为完整数据包处理。

若仅配置了帧尾而未配置帧头，当接收的数据包含帧尾时，将帧尾之前的所有数据视为一个完整的数据包，并提交给后续处理步骤。

当内容模式为文本时， 帧头和帧尾可以配置为文本，例如 hello 和 world。 如果内容模式为HEX时，帧头和帧尾可以配置为十六进制，例如 AA BB 和 EE FF。

正则表达式

配置项

  • 表达式 : 正则表达式。
  • 忽略大小写 : 是否忽略大小写。

当配置分帧模式为正则表达式时，收到数据后则会进行正则表达式匹配，并将匹配的数据内容作为一个完整的数据包提交给后续步骤处理。

例如，配置正则表达式为 hello.*world，收到的数据如下：

hello12345world

则收到的数据帧为：

12345

JSON

当收到数据后，检查数据是否为一个完整的JSON数据包，如果是则提交给后续步骤处理。

例如，收到的数据如下：

{
    "name": "hello",
    "age": 18
} 
{
    "name": "world",

则收到的数据帧为：

{
    "name": "hello",
    "age": 18
}

XML

当收到数据后，检查数据是否为一个完整的XML数据包，如果是则提交给后续步骤处理。

例如，收到的数据如下：

<name>hello</name>
<age>18

则收到的数据帧为：

<name>hello</name>

转发

转发支持将相同类型的参数格式转发到另外一个通讯连接中。

例如， 当前连接为串口连接，串口支持文本和HEX两种参数模式模式， 另外存在一个TCP连接， TCP连接也支持文本和HEX两种参数模式模式， 则可以将串口连接的数据转发到TCP连接中。 即串口连接接收到的数据可以转发到TCP连接中。

同时，转发支持多层级转发，即串口连接接收到的数据可以转发到TCP连接中，TCP连接接收到的数据可以转发到UDP连接中。

心跳

心跳配置用于根据配置的时间间隔向服务器发送心跳包，以保持连接的有效性。

文本

配置项

  • 时间：心跳包发送的时间间隔，单位为毫秒 。
  • 内容：心跳包的内容。 例如： ping

HEX

配置项

  • 时间：心跳包发送的时间间隔，单位为毫秒 。
  • 内容：心跳包的内容。 例如： AA BB CC DD

脚本

配置项

  • 时间：心跳包发送的时间间隔，单位为毫秒 。

当配置为脚本时，需要在脚本中实现心跳包的发送逻辑即 heartbeat 函数 。例如：

export async function heartbeat() {
    $this.write('PING');
}

[#include "variable.md"]

[#include "message.md"]

Windows 配置

在 Windows 系统上， 您需要预先将设备与系统进行配对，并进行串口映射， 以便 Bittly 能够识别设备并进行连接。

这里以 Windows 11 系统连接 HC-06 蓝牙模块为例：

打开 Windows 蓝牙置，扫描并将 HC-06 蓝牙模块配对连接。

选择 更多蓝牙设置 将 HC-06 蓝牙模块映射为串口。

完成串口映射后， 您便可以在 Bittly 中选择对应的蓝牙设备并通过配置的串口进行数据通信。

2025 © Bittly 沪ICP备2023006101号-2