指令脚本

指令脚本用于在指令执行生命周期中进行对指令参数，响应数据等进行处理。

生命周期

在指令执行时，可通过自定义生命周期函数来改变指令执行逻辑。例如，如果我们要在指令发送之前修改请求参数内容，那么我们可以通过实现beforeRequest 函数来实现参数内容修改，函数实现可参考下方函数说明。

init
 v
beforeRequest
 v
afterRequest
 v
onData --\
 |  ^    |
 |  `----/
 v
afterCancel

函数说明

init 初始化函数，用于初始化指令脚本。例如：

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

beforeRequest

请求前函数，用于在指令将请求参数构建完成之后且进行数据发送之前执行。

函数默认行为：

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

参数：

data - 请求数据, 数据类型由通讯连接类型决定，例如串口， TCP， UDP为 Buffer， HTTP 时则为 Object 类型。

通过该回调函数可修改发送的数据，例如添加校验码，修改数据等。例如：

返回值：返回修改后的数据。

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

/**
 * 请求前函数
 * @param {Buffer} data - 请求数据 
 * @returns {Buffer}
 */
export async function beforeRequest( data ) {
    // 假设 data 为 Buffer类型， 可以通过Buffer的方法进行数据处理
    // 具体参考： https://nodejs.org/api/buffer.html
    data.writeUInt8(
        data.length, // 数据总长度
        1 // 第二个字节, 下标从0开始
    );
    return data;
}

afterRequest 请求后函数，在指令请求后执行。例如：

export async function afterRequest() {
    return data;
}

onData 数据接收函数，在指令接收到数据时执行。例如：

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

afterCancel 取消后函数，在指令取消后执行。例如：

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

自定义函数

当指令参数构建逻辑比较复杂， Bittly 内置函数无法实现时，可通过自定义函数来实现，并在请求参数模板中，通过 {{ 函数名() }} 的方式来进行调用。例如，我们定义 hello 函数如下：

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

那么，假如我们使用文本参数编辑器来编辑参数内容，可通过如下方式进行调用 :

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

则参数构建完成后，发送给目标设备的内容为：

test, hello, sige

在自定义函数中，可通过脚本上下文变量 $this 和 $ 来调用 Bittly 内置的功能函数。

脚本上下文

指令脚本上下文变量用于在指令脚本中获取指令执行上下文信息，以及调用通用工具函数。

$this - 当前指令实例

$this.parameter - 当前指令请求参数实例, 用于访问当前指令请求参数。在使用 $this.parameter 获取请求参数时，其提供的获取方法由对应的参数编辑器提供，。

例如，如果当前请求参数格式为结构体，则可以通过以下方式获取请求参数：

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

$this.log(... args) - 记录日志信息。例如：

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

$ - 通用工具函数

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

name - 环境变量名称

返回值：<string> 环境变量值

根据名称获取环境变量值，当指定名称不存在时，将会抛出异常从而导致指令无法继续执行。

例如：

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

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

例如：

let time = $.timestamp();

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

min - 最小值
max - 最大值

例如：

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

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

length - 字符串长度

例如：

let value = $.randomString(10);

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

template - 模板字符串

例如：

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

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

mode - CRC模式
buffers - 缓冲区数组

例如：

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

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

buffers - 缓冲区数组

例如：

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