租户及客户管理

ThingsBoard 平台部署完成并启动之后，将自动创建三个账户，分别为系统管理员、租户管理员以及用户。使用对应账号登陆系统可执行不同的操作，默认账号及密码如下：

System Administrator:   sysadmin@thingsboard.org / sysadmin
Tenant Administrator:   tenant@thingsboard.org / tenant
Customer User:          customer@thingsboard.org / customer

租户及租户账号管理

租户管理

租户创建

使用系统管理员账号（System Administrator）登陆系统，进入租户菜单，页面展示当前系统所有的租户信息。点击页面右上角“+”号进行新租户的创建。

点击“+”后弹出租户的新增页面，填写对应的数据后点击“添加”即可完成租户的创建。

租户修改

添加完成后，点击租户名称，在右侧弹出的详情页当中进入编辑模式即可对租户的信息进行修改。

信息修改完成后，点击右上角的对号即可保存更改，点击叉号取消更改。

租户删除

在租户菜单的展示列表中，点击对应租户数据行末的垃圾桶图标即可对租户进行删除操作。

租户账号管理

租户账号创建

在租户菜单的展示列表中，点击对应租户行末的圆形图标可以对租户的账号进行创建。

创建完成后，将直接以该账号登录系统。

租户账号修改

点击要修改的账号名，右侧弹出账号的详情信息，点击对应图标进入编辑模式即可对账号信息进行修改。

租户账号删除

点击要删除的账号末尾的垃圾桶图标，进行租户账号的删除操作。

客户及客户账号管理

客户管理

客户创建

使用上一节中创建的租户管理员账号登录系统，点击客户菜单，点击右上角“+”弹出创建对话框，填写信息进行客户的创建。

客户修改

客户的修改与租户修改类似，按照下图进行操作即可。

客户删除

删除操作与租户删除一致。

客户用户管理

客户用户创建

客户用户账号的创建与租户账号创建类似，操作步骤如下。

客户用户修改

客户用户修改与租户账号修改类似，按如下步骤操作即可。

客户用户删除

客户用户删除操作如下所示。

设备管理

本小节叙述如何在系统中进行设备的创建以及管理，同时叙述数据上传到设备的操作（MQTT协议为例）。

创建设备

设备按照下述步骤进行创建。首先在页面上点击相应按钮弹出设备创建对话框。

设备创建的第一步需要填写设备的详细信息，此处只需要填写设备名称即可，进入下一步。

设备创建第二步可以进行设备凭证信息的设置，勾选“添加凭证”后，可以选择对应的凭证类型，并手动输入或点击输入框末尾的按钮自动生成相应的令牌值。此处的凭证用于设备数据上传。

此处不设置（默认为”Access token“类型，系统自动生成令牌值），直接进入下一步。

设备创建第三步可以将设备分配给客户，供客户账号对其进行维护，此处非必选。

最后点击添加完成设备新增的操作。

设备修改

设备基础信息修改

可以按照下述步骤对设备的基础信息进行修改，包括设备名称、设备配置、标签、分配固件、分配软件、是否网关、说明等信息。

设备用户分配

设备创建时如果没有分配给用户，或者想要修改分配的用户，可以按照下述操作进行修改。

如果设备已经被分配给了用户，可以通过设备信息末尾处的图标进行取消分配，也可以通过设备详情信息中的取消分配客户按钮取消分配。

未分配客户时，可以通过分配客户按钮或设备详情信息中的分配给客户按钮，将设备分配给客户进行管理。

设备凭据管理

创建设备时，如果没有进行设备凭据的配置，或者想要对配置的凭据进行修改，可以通过设备信息末尾处的管理凭据图标重新进行配置，也可以通过设备详情页面中的管理凭据按钮。

设备删除

可以通过以下操作对设备进行删除。

设备数据上传

在默认的设备配置当中，支持基本 MQTT、HTTP 和 CoAP 传输协议，此处使用 MQTT 协议进行数据上传的配置演示。

首先按照下述操作获取设备的访问令牌。

获取令牌值后，对我们的 MQTT 客户端进行配置，配置中主要关注以下几个要点：

• 配置客户端broker为tcp://ip_address:1883；

• MQTT 客户端配置的username应该为上述步骤中复制的设备令牌；

• topic应该指定为v1/devices/me/telemetry；

按上述条件进行配置后，发送以下消息进行测试，该消息中发送了两个属性，分别为温度和湿度：

"{\"temperature\": 32, \"humidity\": 10}"

在设备详情页面查看设备数据的上报情况，查询到相应的数据且数据值正确，证明设备端到 ThingsBoard 平台端的通路正常：

仪表盘管理

仪表盘主要用于以各种图表的形式，展示设备上传的原始数据、数据趋势，以及报警信息等。

仪表盘创建

仪表盘可以通过以下步骤进行创建。

仪表盘配置

新创建的仪表盘是没有任何内容的，具体的仪表盘展示内容与布局需要租户管理员进行配置，配置完成后授权分发给指定的用户即可。

仪表盘关联设备

下述步骤将实现通过仪表盘来展示设备上传的实时数据。

在仪表盘部件编辑页面中，首先需要将要展示的设备关联到仪表盘当中，才能在部件中进行展示配置，如下操作所示。

此处我们将之前创建的设备关联到仪表盘当中，可以为设备取一个别名用于在仪表盘中展示。筛选器类型选择单个实体用于导入单个设备，类型选择设备，在右侧下拉框中选择我们要关联进来的设备名称，如下操作所示。

至此我们将创建的设备关联到了新建的仪表盘当中，接下来我们需要选取合适的展示部件用于对设备数据的展示。

仪表盘部件配置

此处我们添加一个卡片组件用于观察设备上报的实时数据，并添加一个图表组件来观察设备上报数据的趋势。

接下来进行部件展示内容的配置（在配置要展示的设备的属性时，可以选择多个）。

采用同样的方法，再添加一个图表组件。

此时两个部件已经添加完毕，点击对应的组件，按住左键拖动鼠标可以调整组件的位置。鼠标放在组件边缘时，按住鼠标左键拖动鼠标可以调整组件的大小。将组件的大小和位置调整合适后，点击右下角的对勾图标保存更改。

此时可以再次发送数据查看图标数据的展示。

若想要修改仪表盘部件的数据源，再次点击右下角图标进入编辑模式，选择要修改的部件进行配置的修改即可。

若要对部件进行删除，则在部件修改模式中，点击对应部件右上角的叉号，对部件进行删除操作，然后保存仪表盘更改内容即可。

仪表盘用户分配

配置完成的仪表盘需要分配给相应的用户，对应用户才能获得仪表盘的访问权。上述配置完成的仪表盘没有分配给任何的用户，此时使用用户账号登录系统，进入仪表盘菜单，可以看到没有可查看的仪表盘。

按下述操作，将上一节中配置的仪表盘分配给之前创建的客户。

完成分配后，再次登录对应客户下的用户账号，即可在仪表盘菜单中对该仪表盘进行查看（只有查看权限，无法进行修改）。

若想要取消仪表盘的分配，按照上述仪表盘分配的操作，在第四步选择要分配的用户是，设置为空，然后更新即可。

仪表盘修改

参照下列步骤可以对仪表盘的基本信息进行修改。

仪表盘删除

按照下述步骤可以实现对仪表盘的删除操作。

规则链库

系统提供了规则链库供开发人员自行配置消息的变换、过滤、计算与传输。

规则链创建

系统提供了一个默认的根规则链支持用户使用，此处不在根规则链上进行改动，而是将根规则链导出后重新导入，然后在新导入的规则链中进行修改和配置。

首先按照下列步骤导出根规则链，点击导出后系统将自动执行下载，导出的文件为 json 格式。

将导出的配置重新导入系统。点击导入后，系统将直接跳转到新导入的规则链的配置页面，直接点击右下角的应用更改按钮即可。重新退出到规则链库菜单即可看到新导入的规则链库配置。

规则链修改

按照下述步骤可以对规则链的基本信息进行修改。可以为上一小节中导入的规则链进行重命名。

规则链删除

按照下列操作可以对新创建的规则链进行删除操作（注：系统提供的默认根规则链不可删除）。

规则链配置

若需要对规则链进行配置，则需要按照下列操作进入规则链的配置页面。

系统提供了 6 类规则节点供开发人员进行配置，分别为筛选器、属性集、变化、动作、外部、流。若需要配置某一规则节点，则点击鼠标将对应节点拖入右侧编辑页面并进行配置，然后添加即可。

接下来对不同类中可能比较常用的、对数据进行操作的规则节点的配置进行讲解，因为之前设备的创建中应用了默认的设备配置（后续会讲解），默认设备配置中使用规则链为根链Root Rule Chain，因此下面的演示均为在 Root Rule Chain 中进行的配置。

筛选器

check fidles presence

该规则节点用于验证消息体或者消息的元数据中的某些属性是否存在，并根据验证结果对消息进行分发。该节点的配置内容有：

• 名称：必填项，表明该节点的名称；

• Message field names：消息体中需验证的属性名，该消息即设备主动发送的消息内容。此处可以配置多个，每个属性输入完后按“回车”键入；

• Metadata field names：消息元数据中需要验证的属性名，元数据为系统附带的数据，在默认配置的情况下一般有deviceType、deviceName以及ts三个元数据属性。此处可以配置多个，每个属性输入完后按“回车”键入；

• Check that all specified fields are present：选择框，勾选后，在进行上述的属性验证时，各验证条件以“与”进行连接；不勾选时，在进行上述的属性验证时，各验证条件以“或”进行连接；

• 说明：非必填项，附加说明；

根据判断结果，该规则节点的出口有true和false两种。

简单使用示例如下：

script

该规则节点允许开发人员以编程的方式实现数据的过滤，即实现自定义的过滤规则对消息进行分发。该节点的配置内容有：

• 名称：必填项，表明该节点的名称；

• function Filter：代码（通过代码自定义过滤规则），函数入参包括 msg（消息）、metadata（元数据）、msgType（上一节点推送的消息类型），返回值应为布尔值；

• 说明：非必填项，附加说明；

根据代码逻辑，该规则节点的出口有true和false两种。

简单使用示例如下：

return msg.temperature > 20;

switch

该规则节点允许开发人员以编程的方式实现数据的分组过滤，即实现自定义的分发规则对数据进行分发。该节点的配置内容有：

• 名称：必填项，表明该节点的名称；

• function Switch：代码（通过代码自定义分组规则），函数入参包括 msg（消息）、metadata（元数据）、msgType（上一节点推送的消息类型），返回值应为字符串数组，指示要分发的路径；

• 说明：非必填项，附加说明；

根据代码逻辑，该规则节点的出口由编码人员进行定义，见示例。

简单使用示例如下：

if (msg.temperature > 25) {
    return ['High temperature'];
} else if (msg.temperature < 18) {
    return ['Low temperature'];
} else {
    return ['Normal temperature'];
}

上述代码中定义了三个出口，分别为High temperature、Low temperature以及Normal temperature。因此，在连接下一个节点时，我们要按照我们定义的出口路径自定义连接，如下图所示。输入完成后按“回车”创建一个链接标签，然后点击添加即可。

属性集

calculate delta

该规则节点用于计算本条消息中的数据与上一条消息中的对应数据的差值，并根据计算结果对消息内容进行完善和分发。该节点的配置内容有：

• 名称：必填项，表明该节点的名称；

• Input value Key：必填项，要进行增量计算的属性名称；

• Output value Key：必填项，计算所得的增量值添加到消息体中的属性名称；

• Decimals：增量计算的精度；

• Use cache for latest value：选择项，使用内存存储上一数据的值，默认勾选；

• Tell Failure if delta is negative：选择项，若增量值为负数，则认为消息处理失败，默认勾选；

• Add period between messages： 选择项，在消息体中添加与上一条消息的时间差值，默认不勾选。勾选后需填写 Period value key，作为计算所得的时间差值添加到消息体中的属性名称；

• 说明：非必填项，附加说明；

根据运行结果，该规则节点的出口有Success、Failure以及Other三种：

• Success ：增量计算成功的数据出口；

• Failure：消息处理失败的数据出口，若勾选 Tell Failure if delta is negative，则计算增量为负的数据从该出口输出；

• Other：消息中缺失要执行增量计算的属性值的数据出口；

简单使用示例如下：

customer attributes

该规则节点用于将配置给用户的一些属性添加到消息的元数据当中，并根据处理结果分发数据。该节点的配置内容有：

• 名称：必填项，表明该节点的名称；

• Latest telemetry： 选择项，选择后将根据配置的密钥获取客户远程上报的最新属性值，取消勾选则查询设备所属客户的服务端属性，默认取消勾选；

• Source telemetry key：输入项，要添加到消息元数据的客户属性名称；

• Target attribute：输入项，要添加到消息元数据中的属性名，与 Source telemetry key 承兑出现，可添加多对属性；

• 说明：非必填项，附加说明；

根据运行结果，该规则节点的出口有Success、Failure两种。当未给设备配置所属的客户时，数据从Failure出口输出。

此处涉及到用户属性的设置，可以按照如下操作进行配置。

该规则节点简单的使用示例如下：

customer details

该规则节点用于将配置给用户的一些详情信息添加到消息当中，并根据处理结果分发数据。该节点的配置内容有：

• 名称：必填项，表明该节点的名称；

• Select entity details：多选项，选择要添加到消息当中的客户的详细信息（在创建客户时进行配置的信息，包括国家、城市、地址、邮箱等…），添加的信息的属性名格式为customer_具体内容名；

• Add selected details to message metadata：选择项，若勾选则将相应的信息添加到元数据当中向下游节点传递；若不勾选则将相应的信息添加到数据当中向下游节点传递。默认不勾选；

• 说明：非必填项，附加说明；

根据运行结果，该规则节点的出口有Success、Failure两种。当未给设备配置所属的客户时，数据从Failure出口输出。

简单的使用示例如下：

tenant attributes

该规则节点用于将配置给租户的一些属性添加到消息的元数据当中，并根据处理结果分发数据。该节点的配置内容与 customer attributes 规则节点的配置完全相同，此处不再赘述。

此处涉及到租户属性的设置，可以按照如下操作进行配置。

简单的使用示例如下：

tenant details

该规则节点用于将配置给租户的一些详情信息添加到消息当中，并根据处理结果分发数据。该节点的配置内容与 customer details 规则节点的配置完全相同，此处不再赘述。

简单的使用示例如下：

fetch device credentials

该节点用于将设备的密钥以及 token 类型添加到消息中向下游节点传递。节点配置内容包括：

• 名称：必填项，表明该节点的名称；

• Fetch credentials to metadata： 选择项，勾选后将设备密钥信息添加至元数据，否则添加到消息数据，默认勾选；

• 说明：非必填项，附加说明；

根据运行结果，该规则节点的出口有Success、Failure两种。

简单的使用示例如下：

变换

copy keys

该节点用于复制元数据中的键值到数据，或是将数据中的键值复制到元数据。节点配置内容包括：

• 名称：必填项，表明该节点的名称；

• Copy from：选择项，可以选择复制的方向，从数据到元数据（Data to metadata）或从元数据到数据（Metadata to data）。下列的输入框可以输入要复制的属性名称，可输入多个，输入完成后敲击回车完成一次键入；

• 说明：非必填项，附加说明；

根据运行结果，该规则节点的出口有Success、Failure两种。

简单的使用示例如下：

delete keys

该节点用于删除数据或者元数据中的键值。节点配置内容包括：

• 名称：必填项，表明该节点的名称；

• Delete from：选择项，可以选择从哪里删除数据，从数据（Data）中删除或从元数据（Metadata）中删除。下列的输入框可以输入要复制的属性名称，可输入多个，输入完成后敲击回车完成一次键入；

• 说明：非必填项，附加说明；

根据运行结果，该规则节点的出口有Success、Failure两种。

简单的使用示例如下：

rename keys

该节点用于对数据或者元数据中的属性进行重命名。节点配置内容包括：

• 名称：必填项，表明该节点的名称；

• Rename keys in：选择项，可以选择更改哪里的数据，从数据（Data）中更改或从元数据（Metadata）中更改。下面的 Key name 以及 New key name 成对出现，表示原属性名称和新属性名称；

• 说明：非必填项，附加说明；

根据运行结果，该规则节点的出口有Success、Failure两种。

简单的使用示例如下：

deduplication

该节点可用于消息去重或变换消息向下游发送的频率。节点的配置内容包括：

• 名称：必填项，表明该节点的名称；

• Interval：必填项，表示时间间隔，即每过多久向下游发送一次数据；

• Strategy：选择项，表示消息向下游发送的策略。系统提供三种策略供开发人员选择，分别为 First Message、Last Message 以及 All Messages。前两种策略分别为向下游发送最早的一条数据或发送最晚的一条数据，最后一个策略为发送所有数据的 JSON 字符串组。当选择左后一种策略时，还需要配置 Output message type 与 队列。前者为消息类型配置，后者为队列配置；

• 说明：非必填项，附加说明；

根据运行结果，该规则节点的出口有Success、Failure两种。

简单的使用示例如下：

当选择 All Messages 模式时，下游节点收到的数据格式如下所示：

[{
    "msg": {
        "temperature": 26,
        "humidity": 31
    },
    "metadata": {
        "deviceType": "default",
        "deviceName": "device-01",
        "ts": "1703490713006"
    }
}, {
    "msg": {
        "temperature": 12,
        "humidity": 16
    },
    "metadata": {
        "deviceType": "default",
        "deviceName": "device-01",
        "ts": "1703490718019"
    }
}, {
    "msg": {
        "temperature": 15,
        "humidity": 16
    },
    "metadata": {
        "deviceType": "default",
        "deviceName": "device-01",
        "ts": "1703490723041"
    }
}, {
    "msg": {
        "temperature": 13,
        "humidity": 10
    },
    "metadata": {
        "deviceType": "default",
        "deviceName": "device-01",
        "ts": "1703490728061"
    }
}, {
    "msg": {
        "temperature": 12,
        "humidity": 18
    },
    "metadata": {
        "deviceType": "default",
        "deviceName": "device-01",
        "ts": "1703490733073"
    }
}]

script

该节点允许开发人员以代码的方式对数据进行自定义变换，可以通过代码逻辑修改向下游发送的数据内容以及数据格式。节点配置内容如下：

• 名称：必填项，表明该节点的名称；

• function Transform：代码（通过代码自定义变换规则），函数入参包括 msg（消息）、metadata（元数据）、msgType（上一节点推送的消息类型），返回值应为固定格式{msg: newMsg, metadata: newMetadata, msgType: newMsgType}，其中的值为我们经过变化后的对象；

• 说明：非必填项，附加说明；

根据运行结果，该规则节点的出口有Success、Failure两种。

简单的使用示例如下：

变换逻辑代码

msg.timestamp = metadata.ts;
msg.province = '山东省';
msg.city = '济南市';
return {
    msg: msg,
    metadata: metadata,
    msgType: msgType
};

下游节点收到的数据

{
    "temperature": 21,
    "humidity": 15,
    "timestamp": "1703491991280",
    "province": "山东省",
    "city": "济南市"
}

使用示例

动作

math function

该规则节点可以实现数学计算，并将结果保存到消息或者数据库当中。该节点的可配置内容有：

• 名称：必填项，表明该节点的名称；

• Functions：数学函数，系统提供了很多常用的数学函数供用户使用（见下文表格）。此外，用户可以选择 Custom Function 来自定义函数；

• Arguments：设置函数公式中的参数与实际物理量的映射关系，此处可添加多个映射关系。Type 为映射关系类型，系统提供了 5 种映射关系类型供选择，分别为：

  • Attribute：从属性中选择，其配置中的 Key 为属性名称，Attribute scope 为属性的范围（共享属性、客户端属性、服务端属性），Default value 为缺失默认值；

  • Time series：从时序数据中选择，其配置中的 Key 为时序数据的属性名称，Default value 为缺失默认值；

  • Constant：常数，其配置中的 Constant value 为常数的值；

  • Message body：从消息正文中选择，其配置中的 Key 为消息正文中的的属性名称，Default value 为缺失默认值；

  • Message metadata：从消息元数据中选择，其配置中的 Key 为消息元数据中的属性名称，Default value 为缺失默认值；

• Mathematical Expression：当选择自定义函数时，需要配置该选项以设置函数的计算规则。公式中的参数需要使用 Arguments 当中的映射 x、y、z 等来表示。

• Result：用于配置函数计算的结果如何使用。系统提供了 4 中方式供选择，分别为：

  • Attribute：配置到属性当中，可作为属性存入数据库当中。其配置中的 Attribute scope 用于设置属性的作用域，可在共享属性和服务端属性中选择，Key 用于配置属性的名称，Number of digits after floating point 用于配置计算结果的保留小数位，Add to message body 和 Add to message metadata 为可选择项，勾选后同步将数据存入消息正文和元数据；

  • Time series：配置到时序数据当中，可作为时序数据存入数据库当中，Key 用于配置属性的名称，Number of digits after floating point 用于配置计算结果的保留小数位，Add to message body 和 Add to message metadata 为可选择项，勾选后同步将数据存入消息正文和元数据；

  • Message body：配置到消息正文当中，可作为消息内容向下游规则节点传递，Key 用于配置属性的名称，Number of digits after floating point 用于配置计算结果的保留小数位；

  • Message metadata：配置到消息元数据当中，可作为消息元数据向下游规则节点传递，Key 用于配置属性的名称，Number of digits after floating point 用于配置计算结果的保留小数位；

• 说明：非必填项，附加说明；

系统内置的函数如下表所示：

函数	参数个数	描述	参考
ADD	2	x + y
SUB	2	x - y
MULT	2	x * y
DIV	2	x / y
SIN	1	Returns 三角正弦	Math.sin
SINH	1	Returns 双曲正弦 (ex - e-x)/2	Math.sinh
COS	1	Returns 三角余弦	Math.cos
COSH	1	Returns 三角余弦(ex + e-x)/2	Math.cosh
TAN	1	Returns 三角正切	Math.tan
TANH	1	Returns 双曲正切	Math.tanh
ACOS	1	Returns 反角余弦范围内0.0到pi	Math.acos
ASIN	1	Returns 正弦弧范围内*-pi/2到pi/2*	Math.asin
ATAN	1	Returns 反正切范围内-pi/2到pi/2	Math.atan
ATAN2	2	Returns 矩形坐标	Math.atan2
EXP	1	Returns ex	Math.exp
EXPM1	1	Returns ex-1	Math.expm1
SQRT	1	Returns 正平方根	Math.sqrt
CBRT	1	Returns 多维数据集根	Math.cbrt
GET_EXP	1	Returns 无偏指数	Math.getExponent
HYPOT	2	Returns 无偏指数sqrt(x2 +y2)	Math.getExponent
LOG	1	Returns 自然对数	Math.log
LOG10	1	Returns 10对数	Math.log10
LOG1P	1	Returns 参数和1之和的自然对数	Math.log1p
CEIL	1	Returns 最小整数	Math.ceil
FLOOR	1	Returns 最大整数	Math.floor
FLOOR_DIV	2	Returns 最大商数	Math.floorDiv
FLOOR_MOD	2	Returns 底模数	Math.floorMod
ABS	1	Returns 绝对值	Math.abs
MIN	2	Returns 最小数	Math.min
MAX	2	Returns 最大数	Math.max
POW	2	Returns 幂	Math.pow
SIGNUM	1	Returns 符号函数	Math.signum
RAD	1	将以度为单位测量的角度转换为以弧度为单位的近似等效角度	Math.toRadians
DEG	1	将以弧度为单位测量的角度转换为以度为单位的近似等效角度	Math.toDegrees
CUSTOM	1-16	自定义函数例如(x - 32) / 1.8使用此函数指定复杂的数学表达式	exp4j

根据运行结果，该规则节点的出口有Success、Failure两种。

简单的使用示例如下：

create alarm && clear alarm

两个规则节点分别用于创建和清除警报。只要有数据流入创建或者清除警报的节点，则必定会创建或清除一条警报。节点中可以通过编码的方式自定义警报的详细内容。该系统中同一设备同一类型的报警信息最多可存在一条，后续报警以更新的方式呈现。当存在的报警被清除时，后续的报警信息才会新建。

create alarm 规则节点需配置的内容有：

• 名称：必填项，表明该节点的名称；

• function Details：定义警报的详细内容，函数入参包括 msg（消息）、metadata（元数据）、msgType（上一节点推送的消息类型），可以通过metadata.prevAlarmDetails访问先前的警报详细信息。返回值应为details对象，即报警的详细信息；

• Alarm type：必填项，可自定义报警的类型；

• Alarm severity：必选项，配置报警的危险程度，系统提供危险、重要、次要、警告、不确定五种程度供选择；

• 说明：非必填项，附加说明；

根据运行结果，该规则节点的出口有Created、Updated、False、Failure。新建的警报将从Created出口传递，更新的警报将从Updated出口传递。

clear alarm 规则节点需配置的内容有：

• 名称：必填项，表明该节点的名称；

• function Details：定义警报的详细内容，函数入参包括 msg（消息）、metadata（元数据）、msgType（上一节点推送的消息类型），可以通过metadata.prevAlarmDetails访问先前的警报详细信息。返回值应为details对象，即报警的详细信息；

• Alarm type：必填项，可自定义报警的类型；

• 说明：非必填项，附加说明；

根据运行结果，该规则节点的出口有Cleared、False、Failure。清除的警报将从Cleared出口传递，无所需清除的警报时将从False出口传递。

简单的使用示例如下，该实例中定义温度在 28 摄氏度及以上时触发高温警报，报警内容中记录当前温度与连续触发高温警报的消息个数；若设备上报的温度低于 29 摄氏度时，清除警报。

create alarm 规则节点代码：

var details = {temperature: msg.temperature, count: 1};

if (metadata.prevAlarmDetails) {
    var prevDetails = JSON.parse(metadata.prevAlarmDetails);
    if(prevDetails.count) {
        details.count = prevDetails.count + 1;
    }
}

return details;

clear alarm 规则节点代码：

var details = {};
if (metadata.prevAlarmDetails) {
    details = JSON.parse(metadata.prevAlarmDetails);
    //remove prevAlarmDetails from metadata
    delete metadata.prevAlarmDetails;
    //now metadata is the same as it comes IN this rule node
}


return details;

规则链配置：

delay

该规则节点用于将流入节点的数据延迟一定时间后再向下游节点发出。其配置内容有：

• 名称：必填项，表明该节点的名称；

• Use period in seconds pattern：可选项，勾选后可以使用消息正文或者元数据中的某些属性的值作为该条消息的延迟时间，默认不勾选；

• Period in seconds：必填项，用于配置延迟时间；

• Period in seconds pattern：必填项，当勾选 Use period in seconds pattern 时，用于指定以哪个属性的值为延迟时间。使用${metadataKey}获取元数据当中的数值，使用$[messageKey]获取消息正文中的数值；

• Maximum pending messages：用于指定节点队列长度，流入该节点的数据将被放入挂起队列，在经历延迟时间之后将数据向下游发出并从队列中删除；

• 说明：非必填项，附加说明；

根据队列大小，该规则节点存在Success和Failure两个出口。在队列中挂起并到达延迟时间的数据将从Success出口流出，队列满后到达节点的数据将从Failure出口流出。

简单的使用示例如下：

generator

该节点用于生成消息，一般在开发时用于测试规则链。其配置内容有：

• 名称：必填项，表明该节点的名称；

• Message count：必填项，配置生产的消息个数；

• Period in seconds：必填项，配置消息发出的时间间隔；

• 类型：非必填项，可以指定消息的发起实体；

• 队列：非必填项，可以指定消息的发出策略；

• function Generate：可以通过编码的方式定义生成的消息内容与格式。函数入参包括prevMsg（上条消息主体）、prevMetadata（上条消息元数据）、prevMsgType（上上条消息类型），函数返回值应为{ msg: msg, metadata: metadata, msgType: msgType }格式，其中的值 msg、metadata、msgType 均为对象；

• 说明：非必填项，附加说明；

根据执行情况，该规则节点存在Success和Failure两个出口。

简单的使用示例如下：

log

该节点用于将流出的消息通过编码的方式转换为字符串并记录在系统的日志文件当中。其可配置的内容包括：

• 名称：必填项，表明该节点的名称；

• function ToString：可以通过编码的方式定义日志记录的格式。函数入参包括 msg（消息主体）， metadata（消息元数据）， msgType（消息类型），函数返回值应为字符串类型；

• 说明：非必填项，附加说明；

根据执行情况，该规则节点存在Success和Failure两个出口。

外部

kafka

该节点可以将传入的消息的消息主体转发至 Kafka，其本质就是配置一个 Kafka 生产者客户端。可配置的内容包括：

• 名称：必填项，表明该节点的名称；

• Topic pattern：必填项，指定消息发送的主题，使用${metadataKey}获取元数据中对应属性的值作为 topic，使用$[messageKey]获取消息主体中对应属性的值作为 topic；

• Key pattern：非必填项，用于指定消息的 Key，相同 Key 的消息会被划入同一个分区；

• Bootstrap servers：必填项，指定 Kafka 服务的地址；

• Automatically retry times if fails：非必填项，用于指定消息发送失败时重试的次数，默认为 0；

• Produces batch size：非必填项，用于指定以字节为单位的批处理大小，默认为 16384；

• Time to buffer locally：非必填项，用于指定最大的本地缓冲窗口持续时间，默认为 0；

• Client buffer max size：非必填项，用于指定发送消息的最大缓冲区大小（以字节为单位），默认为 33554432；

• Number of acknowledgments：必填项，用于指定分区中有多少副本收到该消息时生产者就认为该消息已经成功写入。设置为 0 可以保证最大的吞吐量；acks 设置为 -1 或 all 可以保证最强的可靠性；asks 设置为 1 时消息可靠性和吞吐量之间的折中方案；

• Key serializer：必填项，默认是 org.apache.kafka.common.serialization.StringSerializer；

• Value serializer：必填项，默认是 org.apache.kafka.common.serialization.StringSerializer；

• Other properties：可以为 kafka 客户端连接提供任何其他属性，以键值对的形式进行添加，可添加多对；

• Add Message metadata key-value pairs to Kafka record headers：可选项，勾选后，消息的元数据将以键值对的形式添加到 Kafka 客户端连接的 Headers 当中；

• 说明：非必填项，附加说明；

根据转发情况，该规则节点存在Success和Failure两个出口。

简单的配置示例如下：

mqtt

该节点可以将传入消息的消息主体转发至 Mqtt 服务器。其可配置内容包括：

• 名称：必填项，表明该节点的名称；

• Topic pattern：必填项，用于配置 topic，可以是静态字符串，也可以通过${deviceType}使用消息元数据属性；

• Host：必填项，用于配置 Mqtt 代理服务器地址；

• Port：必填项，用于配置 Mqtt 代理服务器端口，默认为1883；

• Connection timeout：必填项，用于配置连接到 Mqtt 服务器的超时时间（以秒为单位），默认为 10；

• Client ID：非必填项，用于配置客户端 id。如果没有指定，将使用默认生成的 clientId；

• Add Service ID as suffix to Client ID：可选项，在配置 Client ID 后才可勾选，勾选后会将 Service ID 作为后缀添加至 Client ID；

• Clean session：可选项，可配置是否删除 session，默认勾选；

• Retained：可选项，可配置消息是否保留，默认不勾选；

• Enable SSL：可选项，用于启用/禁用安全通信，默认不勾选；

• Credentials：Mqtt 连接凭据。系统提供三种连接凭证验证方式，即 Anonymous（不验证）、Basic（用户名密码验证）、PEM（凭证文件验证）；

• 说明：非必填项，附加说明；

根据转发情况，该规则节点存在Success和Failure两个出口。

简单的配置示例如下：

rest api call

该节点可以将传入消息的消息主体转发至外部的 API 接口。其基本配置包括：

• 名称：必填项，表明该节点的名称；

• Endpoint URL pattern：必填项，配置外部 API 接口路径；

• Request method：必填项，用于配置请求方式；

• Enable proxy：可选项，用于配置代理，默认不勾选；

• Use simple client HTTP factory：可选项，使用简化 http 客户端工厂，默认不勾选；

• Message without quotes：可选项，勾选后发送的消息不使用双引号括住，默认不勾选；

• Without request body：可选项，勾选后不含请求体；

• Read timeout in millis：非必填项，用于设置读取超时时间，默认为 0 表示无限超时时间；

• Max number of parallel requests：非必填项，用于设置最大并行请求数，默认为 0 表示无限制；

• Headers：非必填项，用于设置请求头的信息，可添加多个；

• Credentials：连接凭证，系统提供三种连接凭证验证方式（同 Mqtt 规则节点设置）；

• 说明：非必填项，附加说明；

根据转发情况，该规则节点存在Success和Failure两个出口。

简单的配置示例如下：

队列

队列可配置消息的提交策略和处理策略，以保证消息处理、削峰以及系统在极端负载下正常运行。系统默认提供了 HighPriority、Main、SequentialByOriginator 三种队列供用户使用。其中，Main 队列作为默认队列，只可修改，不可删除。

队列创建

按照如下操作可以进行新队列的创建。

其中：

• 名称：配置队列的名称，添加后不可修改；

• 提交设置用于配置消息的提交策略（Strategy type），可从下列策略中进行选择：

  • 按发起者顺序处理（SEQUENTIAL_BY_ORIGINATOR）：消息在特定实体（消息发起者）内按顺序提交消息；

  • 按租户顺序处理（SEQUENTIAL_BY_TENANT）：消息在租户（消息发起者的所有者）内按顺序提交消息；

  • 顺序处理（SEQUENTIAL）：较慢的消息处理，消息按顺序提交，在确认上一个消息之前不会提交新消息；

  • 突发处理（BURST）：所有消息按到达的先后顺序提交到规则链；

  • 批量处理（BATCH）：在确认前一批消息之前，不会提交下一批消息；

• 重试处理设置用于配置消息的处理策略（Processing type），可从下列策略中进行选择：

  • 失败与超时重试（RETRY_FAILED_AND_TIMED_OUT）：重试处理所有失败和超时的消息；

  • 跳过所有失败（SKIP_ALL_FAILURES）：忽略所有故障，会导致失败的消息丢失；

  • 跳过所有失败和超时（SKIP_ALL_FAILURES_AND_TIMED_OUT）：忽略所有故障和超时，会导致失败与超时的消息丢失；

  • 全部重试（RETRY_ALL）：重试处理所有消息。如果 100 条消息中有 1 条失败，策略将重新处理全部 100 条消息；

  • 失败重试（RETRY_FAILED）：重试处理所有失败的消息。如果每 100 条消息中有 1 条失败，策略将仅重新处理 1 条消息。此外，超时的消息将不会重新处理；

  • 超时重试（RETRY_TIMED_OUT）：重试处理所有超时消息。如果每 100 条消息中有 1 条超时，策略将仅重新处理 1 条消息。此外，失败的消息将不会被重新处理；

  重试设置中的重试次数、跳过重试的失败消息百分比、重试间隔以及最大重试间隔参数可以根据需要进行设置。

• 轮询设置可以配置消费者的轮询策略：

  • 轮询间隔：用于配置没有新消息到达时两次轮询之间的间隔时间（以毫秒为单位）；

  • 分区：用于配置队列关联的分区数，用于扩展并行处理的消息数；

  • 处理超时：用于配置处理消费者返回的特定消息包时间间隔（以毫秒为单位）；

  • 每个分区消费者单独轮询消息：建议勾选；

• 说明：队列说明；

队列修改

按照如下步骤可以实现队列配置策略的修改（注：名称不可修改，仅可修改队列策略）。

队列删除

按照下列操作可以实现队列的删除（注：系统提供的默认 Main 队列不可删除）。

设备配置

设备配置可以为某一类设备设定共同的一些消息处理方式，比如规则链、消息传输队列、传输协议配置、告警规则配置等。

设备配置创建

设备配置创建过程中，需要分别设置设备配置详情、传输配置、告警规则以及设备预配置，其创建过程如下。

设备配置详情

在详情中，可以进行如下内容的配置：

• 名称：必填项，设备配置的名称；

• 默认规则链：选填项，可以指定使用哪一套规则链，若不填则使用默认的根规则链；

• 移动端仪表盘：选填项，指定被移动端应用用作设备详情的仪表板；

• 队列：选填项，可以指定消息提交和处理的策略，默认为 Main；

• Default edge rule chain：无需配置；

• 设备配置图片：选填项，可以上传设备图片；

• 说明：选填项，设备说明；

传输配置

传输配置中，可以配置设备数据上传的协议，系统提供以下几种协议：

• 默认：支持基本 MQTT、HTTP 和 CoAP 传输，无特殊需求一般选择默认即可；

• MQTT：启用高级MQTT传输设置，可进行高级配置；

• CoAP： 启用高级 CoAP 传输设置，可进行高级配置；

• LWM2M：LWM2M传输类型，可进行高级配置；

• SNMP：指定 SNMP 传输配置，可进行高级配置；

告警规则

在设备配置的告警规则中，可以对警报创建和消除的条件进行配置（与在规则引擎中进行配置效果相同，此处配置可避免编码）。

进入告警规则配置页签，点击添加告警规则，进入告警规则配置页面。

告警创建规则配置

通过“添加创建条件”按钮可创建多个。

严重程度

系统提供了五种告警的严重程度供配置人员选择，分别为危险、重要、次要、警告、不确定，根据情况选择即可。

条件

条件即需要配置告警的创建逻辑，点击添加告警规则条件按钮，按照下列步骤完成一个告警规则条件的创建。

其中：

步骤 2 进行筛选器配置时，系统提供三个键类型供选择，分别为属性、Timeseries（时序数据）、常量。选择前两者时，键名为下拉框，选择相应的属性名即可；选择常量时，键名为输入框，需要自行输入。值类型为下拉选择框，包括字符串、数字、布尔值、日期时间四种类型可选。

步骤 5 配置筛选器时，可以通过添加按钮添加多个逻辑；操作为下拉选择框，提供各种比较逻辑；值则为比较的阈值。可以通过下列操作实现动态比较阈值的配置。注意，此处需要提前创建所选择的动态源类型所填源属性（配置方法在规则链库-规则链配置-属性集-customer attributes以及tenant attributes中有介绍，设备属性配置操作相同，此处不再赘述）。

步骤 6 配置条件类型时，系统提供简单、持续时间以及重复三种类型。当选择持续时间时，需要配置持续时间的值以及时间单位，此处同样可以使用动态源进行配置；当选择重复时，需要配置重复出现的次数，此处同样可以使用动态源进行配置。

启用规则

启用规则可以设置告警创建规则启用的时间范围，系统提供始终启用、定时启用以及自定义启用三种规则，选择对应规则进行配置保存即可。

详情模板

用于配置警报的详情内容，即在规则链中 Details 函数返回的 details 对象。

移动仪表盘

用于警报详细报告。

告警清除规则配置

告警清除规则的配置与创建规则步骤完全相同，只是配置内容的差异，此处不详细展开。

设备预配置

ThingsBoard 可以根据设备生产厂商提供的设备唯一凭证实现自动配置设备。选择禁用即可。

设备配置修改

按照如下步骤可以实现对设备配置的修改操作。

设备配置删除

按照下列步骤即可实现设备配置的删除操作。

设备配置使用

本小节主要叙述如何将配置好的设备配置分配给设备进行使用，并通过仪表盘部件进行验证。

首先，按照下列操作步骤，将新创建的设备配置分配给之前创建的设备。

配置完成后，我们在仪表盘中引入一个告警展示的部件，来查看我们配置的告警规则是否已经生效，从而验证设备配置是否成功。

按照下列步骤在仪表盘中配置一个告警部件。

重新上传数据，查看告警是否正常创建和清除。

至此，关于 Thingsboard 平台的基本配置和使用方法介绍完毕，感谢您阅读本文。如果您在阅读过程中发现了任何错误或不准确的内容，请与我联系并提供反馈，我将尽快进行更正和修正。