指令脚本

指令脚本用于在指令执行过程中对指令参数、请求数据和响应数据进行自定义处理。您可以在指令生命周期阶段编写处理逻辑，也可以定义自定义函数供请求参数模板调用。脚本同时提供上下文变量，用于访问当前指令的配置属性及运行时数据。

生命周期函数

Bittly 指令脚本采用生命周期机制，将一次完整的指令执行过程拆分为多个阶段，并在关键阶段提供回调函数。 Bittly 指令生命周期回调函数遵循严格的生命周期模型：

初始化 → 发送前 → 发送后 → 接收 → 结束清理

掌握这一模型，可以实现：

  • 严谨的请求控制
  • 精确的响应匹配
  • 稳定的资源管理
  • 可维护的脚本结构
回调函数 执行阶段 是否每次指令执行都会触发
init 执行器初始化时 ❌ 否
beforeRequest 请求参数写入前 ✅ 是
afterRequest 请求参数写入后 ✅ 是
onData 收到响应时 ✅ 是（可能多次）
afterCancel 指令结束时 ✅ 是

初始化函数 - init

init 是Bittly 指令的初始化函数。当指令执行器初始化时执行一次，用于完成运行前的初始化工作。

默认函数形式

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

默认情况下为空实现，不执行任何操作。

请求前回调 - beforeRequest

beforeRequest 是 Bittly 指令执行生命周期中的发送前回调函数。当指令参数构建完成后、数据真正发送之前执行。您可在该阶段对即将发送的数据进行修改或补充处理。

典型用途包括：

  • 添加校验码（CRC / LRC / Checksum）
  • 写入数据长度
  • 填充时间戳
  • 动态修改指令字段
  • 数据加密或签名

默认回调形式

默认行为：原样返回请求数据，不做修改。

export async function beforeRequest(data) {
    return data;
}

参数说明

data - 请求数据

数据类型由当前通讯连接类型决定：

通讯类型 数据类型
串口（Serial） Buffer
TCP / UDP Buffer
Modbus RTU Buffer
HTTP Object
WebSocket Buffer 或 string

返回值

  • 必须返回修改后的数据
  • 返回值将作为最终发送的数据
  • 当返回值无效时指令将不再执行，而抛出异常

示例 1：写入数据总长度

将请求参数中的第二个字节设置为数据总长度：

/**
 * 请求前函数
 * @param {Buffer} data - 请求数据 
 * @returns {Buffer}
 */
export async function beforeRequest(data) {
    data.writeUInt8(
        data.length, // 数据总长度
        1            // 第二个字节（下标从 0 开始）
    );
    return data;
}

示例 2：条件修改参数

export async function beforeRequest(data) {
    if (data[0] === 0x01) {
        data[2] = 0xFF;
    }
    return data;
}

请求后回调 - afterRequest

afterRequest 是 Bittly 指令执行生命周期中的请求阶段回调函数。当指令参数写入完成、请求数据已发送后立即执行。

⚠ 此时仅表示“请求已发出”，并不代表已收到响应数据。

响应数据应通过 onData 回调进行处理。

默认回调形式

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

默认情况下该函数为空实现，不执行任何操作。

数据接收回调 - onData

onData 是 Bittly 指令执行的生命周期回调函数，在指令接收到数据时被调用，该回调函数在指令未完成之前会被多次调用，直到指令完成。

通过该回调，您可以对接收到的数据进行处理、过滤或修改，然后将其作为指令实际响应内容。

默认回调

默认情况下，onData 会原样返回收到的数据，不做任何修改。

export async function onData(data) {
    return data;
}

参数说明

  • data：接收到的指令数据，数据类型根据 通讯连接类型 而不同， 例如当通讯连接为串口时，参数可能是 Buffer 或 string。

数据处理与修改 您可以在回调中对收到的数据进行修改，例如更改某个字节或字段，然后返回修改后的数据作为指令响应内容：

export async function onData(data) {
    data[2] = 0x01; // 修改第三个字节
    return data;
}

数据过滤与丢弃 如果收到的数据不是当前指令的响应，您可以返回 null 丢弃该数据。例如，当请求参数包含消息 ID 时，可在回调中进行匹配：

export async function onData(data) {
    if (data[0] !== expectedMsgId) {
        return null; // 丢弃非当前指令的响应
    }
    return data;
}

调试与日志记录 可在回调中输出调试信息或日志，帮助分析指令返回的数据：

export async function onData(data) {
    $this.log('收到原始数据:', data);
    return data;
}

指令结束回调 - afterCancel

afterCancel 是 Bittly 指令执行生命周期中的结束回调函数。 当指令执行完成或被手动取消时，该函数会被调用。

默认回调形式

默认情况下该函数为空实现，不执行任何操作。

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

触发时机说明

afterCancel 会在以下场景触发：

  1. 指令正常执行完毕
  2. 用户主动点击取消
  3. 指令执行过程中发生异常导致终止
  4. 超时机制触发后终止指令

自定义函数

当指令参数的构建逻辑较为复杂，Bittly 内置函数无法满足需求时，可以通过 自定义函数 实现，并在请求参数模板中通过 {{ 函数名() }} 的方式调用。

例如，定义一个 hello 函数：

export function hello( name ) {
    return `hello, ${name}`;
}

在参数编辑器中构建请求参数时，可以这样调用该函数：

test, {{ hello('sige') }}

当指令执行并完成参数模板解析后，最终发送给目标设备的内容为：

test, hello, sige

在自定义函数中，可以通过脚本上下文变量访问 Bittly 提供的能力：

  • $this：访问当前指令实例及其相关数据
  • $：调用 Bittly 提供的内置功能函数

通过这些上下文变量，自定义函数不仅可以生成参数，还可以访问指令配置、运行状态以及调用系统内置工具函数，从而实现更灵活的数据处理逻辑。

脚本上下文

指令脚本提供一组 上下文变量（Context），用于在脚本执行过程中访问指令的运行数据、参数信息，以及调用 Bittly 提供的通用工具函数。

$this — 指令实例上下文

$this 表示当前正在执行的 指令实例，可用于访问指令参数、运行数据以及调用部分内置方法。

$this.parameter - 请求参数

当指令的请求参数类型为 结构体 时，可以通过 attribute 方法获取指定字段的值。

let data = $this.parameter.attribute("1.name");

$this.log() - 输出日志

输出日志到控制台

$this.log("message", "message2");

$ - 通用工具函数

$ 提供了一组 Bittly 内置的通用工具函数，可在指令脚本或自定义函数中直接调用，用于获取环境变量、生成随机数据以及进行常见的数据计算。

$.envValueGet( name ) - 获取环境变量值。

获取指定名称的环境变量值。

参数

  • name <string> — 环境变量名称

返回值

  • <string> — 环境变量值

当指定名称的环境变量不存在时，将抛出异常，并终止当前指令的执行。

示例

let value = $.envValueGet("envName");

$.timestamp() - 获取当前时间戳。

获取当前时间戳。

返回值

  • <number> — 当前时间戳

示例

let time = $.timestamp();

$.random(min, max) - 获取指定范围内的随机数。

生成指定范围内的随机数。

参数

  • min <number> — 最小值
  • max <number> — 最大值

返回值

  • <number> — 随机数

示例

let value = $.random(1, 100);

$.randomString(length) - 获取指定长度的随机字符串。

生成指定长度的随机字符串。

参数

  • length <number> — 字符串长度

返回值

  • <string> — 随机字符串

示例

let value = $.randomString(10);

$.fake( template ) - 生成模拟数据。

根据模板生成模拟数据。

该功能基于模板语法生成随机数据，例如邮箱、姓名、地址等，常用于测试或设备模拟。

参数

  • template <string> — 数据模板

返回值

  • <string> — 生成的模拟数据

示例

let value = $.fake("{{internet.email}}");

$.crc(mode, buffers) - 计算CRC校验码。

计算指定模式的 CRC 校验码。

参数

  • mode <string> — CRC 计算模式
  • buffers <number[]> — 待计算的字节数组

返回值

  • <number> — CRC 计算结果

示例

let value = $.crc("crc16modbus", [0x01, 0x02, 0x03]);

$.checksum( buffers ) - 计算校验和。

计算数据的校验和（Checksum）。

参数

  • buffers <number[]> — 待计算的字节数组

返回值

  • <number> — 校验和结果

示例

let value = $.checksum([0x01, 0x02, 0x03]);