thinger/ttn-stack-plugin

The Things Stack

The Things Network是一个LoRaWAN网络解决方案，可简化大型IoT应用在全球协作物联网网络上的部署。Thinger.io为The Things Stack用户提供了增强集成能力，通过易于配置的工具实现设备数据的存储、分析和展示。该插件支持接收The Things Stack Webhook消息，并提供以下特色功能：

• 上行数据载荷处理
• 下行数据载荷处理
• 自动设备和数据桶配置

插件功能

• 支持The Things Stack应用中新设备的自动设备和数据桶配置，无需额外配置即可在Thinger.io中使用The Things Stack数据。
• 基于The Things Stack信息存储设备元数据，如设备位置、信号质量、硬件序列号等。
• 自动将设备数据存储到数据桶，便于从控制台直接使用。
• 支持通过Node.js定义自定义上行回调，处理The Things Stack集成提供的payload_raw或payload_fields。
• 支持通过Node.js定义自定义下行回调，可将用户友好的JSON格式下行数据转换为The Things Stack网络所需的payload_raw或payload_fields。

The Things Stack核心概念

为更好理解后续内容，以下介绍The Things Stack的基本概念：

• 设备（Device）：具有LoRa接口的硬件设备。
• 网关（Gateway）：同时具备LoRa和互联网连接的硬件设备，接收多个设备的LoRa消息并通过互联网推送到The Things Stack网络。
• 上行（Uplink）：设备向The Things Stack网络发送消息的数据流。
• 下行（Downlink）：The Things Stack网络向设备发送消息的数据流。
• 应用（Application）：定义同一类型设备组的概念，通常这些设备在上下行中发送相同类型的数据。
• 集成（Integration）：将设备数据推送到The Things Stack网络外部的方式，如发送消息到Thinger.io等其他平台。

插件配置

本节介绍配置The Things Stack插件的不同界面。

集成The Things Stack应用

集成的第一步是创建新的插件配置。可为The Things Stack中部署的每个应用创建多个具有自定义行为的配置文件。创建新应用配置文件只需输入应用ID并点击绿色的“添加应用”按钮。注意，ID必须与The Things Stack应用中定义的标识符完全一致。

“应用ID（Application Id）”下拉菜单用于选择和配置特定的应用配置文件，若选择“default”配置文件，则该配置将应用于所有与插件集成的应用。

!!! warning

创建应用时，应用标识符必须与The Things Stack中定义的完全相同。

上行设置

如上图所示，可通过以下参数配置插件行为：

• 自动配置资源（Auto provision resources）：启用或禁用接收未创建设备的消息时自动配置资源。
• 设备连接超时（Device Connection Timeout）：创建新设备时，设置设备连接超时时间（分钟），超过固定时间未接收消息，平台将设备视为已断开连接。
• 设备标识符前缀（Device Identifier Prefix）：创建新设备时，使用自定义前缀+原始设备ID命名设备。
• 数据桶标识符前缀（Bucket Identifier Prefix）：创建与设备关联的新数据桶时，使用自定义前缀+原始设备ID命名数据桶。
• 分配资产类型（Assign Asset Type）：将自动配置的设备和数据桶关联到指定的资产类型。
• 分配资产组（Assign Asset Group）：将自动配置的设备和数据桶关联到指定的资产组。
• 更新设备位置（Update device location）：使用网关信息中提供的位置更新当前设备位置。
• 初始化下行数据（Initialize Downlink Data）：创建新设备时，初始化自定义下行数据，可在后续下行请求中修改和处理。

下行设置

可在Thinger.io中配置The Things Stack下行流程，选择部分参数的行为，如下所示：

• 确认下行（Confirmed Downlink）：启用时，下行消息必须由设备确认。
• 推入下行队列（Push To Downlink Queue）：启用时，下行消息将被推入队列而非替换先前消息。
• 下行优先级（Downlink Priority）：指定下行消息的优先级。

载荷处理

此选项卡用于配置载荷数据处理，将The Things Stack Webhook接收的二进制载荷转换为用户友好的变量，或将下行JSON转换为将传输到The Things Stack的二进制缓冲区。

界面提供Node.js脚本代码编辑器，可定义编码/解码流程，并提供测试工具验证“上行”和“下行”流程的行为。

以下部分提供配置上行和下行方法的额外信息。

=== "上行"

上行方法在网关通过The Things Stack网络发送新消息后调用。根据The Things Stack应用中的配置，此函数将接收不同输入：

* **Base64字符串**：若The Things Stack应用为载荷定义了“自定义Javascript格式化器（Custom Javascript Formatter）”但未提供解码器函数，此方法将接收Base64编码的原始载荷。此时需编写函数将Base64数据转换为JSON对象。
* **Cayene LPP生成的JSON对象**：若The Things Stack应用定义了“Cayene LPP”载荷格式化器，The Things Stack会自动将二进制数据转换为平台可直接使用的JSON对象。此时无需定义自定义上行方法，除非需要进行额外处理（如合并计算字段）。
* **自定义解码器生成的JSON对象**：若The Things Stack应用为载荷定义了“自定义Javascript格式化器”并提供了解码器函数，此函数将接收The Things Stack函数的输出。此时在插件中创建自定义上行方法是冗余的，可选择在The Things Stack或插件中创建函数。

此方法的输出必须是包含平台所需信息的JSON对象。以下是将Base64数据转换为包含“temperature”（温度）和“humidity”（湿度）的JSON对象的上行方法示例：

```javascript
/* 将Base64载荷转换为Thinger.io可使用的JSON对象 */
module.exports.uplink = function(payload){
    const buffer = Buffer.from(payload, 'base64');
    let processed = {};
    processed.temperature = buffer.readInt16LE(0)/100.0;
    processed.humidity = buffer.readInt16LE(2)/100.0;
    return processed;
};
```

!!! info

    上行方法必须始终返回JSON对象。

=== "下行"

下行方法在插件向The Things Stack发起下行请求前调用。要向The Things Stack发起下行请求，插件必须接收HTTP POST调用，指示Thinger.io设备标识符，并自动向所需的The Things Stack端点及其特定协议发起请求。有关更多详细信息，请查看后续部分。

根据插件通过REST API的调用方式，此函数将接收不同输入：

* **JSON对象**：若对定义了“downlink”属性的Thinger.io设备进行下行调用（若插件配置了“初始化下行数据”，该属性会自动初始化），此方法将接收该属性的JSON内容。通常包含用户友好的设备配置，需编码为Base64二进制。
* **JSON对象**：若插件下行请求在POST调用中包含JSON载荷，此函数将接收该载荷而非设备“downlink”属性中的内容。

此方法的输出应为以下之一：

* **Base64字符串**：若The Things Stack应用未定义转换器，需返回可直接发送到The Things Stack网络的二进制信息。
* **JSON对象**：若The Things Stack应用为载荷提供转换器，此方法可返回JSON对象，该对象将在转换器方法中可用。此时在插件中创建自定义下行方法是冗余的，可选择在The Things Stack或插件中创建函数。或者，若需自定义f_port，可通过输入消息`{ "f_port": 1, "payload": "<要发送到下行的期望载荷>" }`指定下行使用的专用“f_port”。

将JSON设备配置转换为The Things Stack所需Base64的下行方法示例：

```javascript
/* 将包含设备配置的JSON对象转换为The Things Stack期望的Base64字符串 */
module.exports.downlink = function(payload){
    let bytes = [];
    bytes[0] = payload.enabled ? 1 : 0;
    bytes[1] = payload.frequency;
    bytes[2] = payload.threshold;
    return Buffer.from(bytes).toString('base64');
};
```

!!! info

    若The Things Stack应用未定义转换器，下行方法应返回Base64字符串。

The Things Stack控制台配置

上行配置

插件配置界面的最后一个选项卡为“Webhook设置”，旨在帮助开发人员完成The Things Stack控制台中的集成，提供设置Webhook配置文件所需的所有信息。

!!! info

注意，REST API未定义应用ID，插件软件将检查此参数以根据配置管理载荷。

在The Things Stack Web控制台中创建新Webhook集成，请按照以下步骤操作：

1. 选择要集成的应用。
2. 在主菜单中打开“集成（Integrations）”部分，点击“Webhooks”选项，将显示Webhooks列表。

3. 点击界面右上角的蓝色“+添加Webhook（+Add webhook）”按钮，可选择不同的Webhook集成模板。选择Thinger.io模板。然后，只需使用Thinger.io“Webhook设置”选项卡提供的信息填写表单，并选择JSON Webhook格式即可配置Webhook。

!!! info

注意，Authorization头必须使用包含“Bearer”命令的访问令牌进行设置。

下行配置

作为Webhook模板的一部分，下载API密钥会自动创建，无需进一步配置。

执行下行流程

Thinger.io的The Things Stack插件已准备好自动管理向The Things Stack服务器发送下行消息，该系统从设备下行属性（设备配置期间自动生成）中获取数据，并将其作为对系统下一个HTTP请求的响应插入。通过这种方式，只需通过仪表板小部件、Node-RED或直接API集成修改此属性的值，即可创建设备配置和控制流程。

创建新下行流程请确保遵循以下步骤：

1. 在Thinger.io配置插件的下行设置
2. 如需，使用插件的“下行载荷处理”编写编码脚本
3. 修改属性值以启动下行流程执行

之后，插件将执行载荷处理，并在The Things Stack API对服务器的下一个请求中发送响应。可通过访问插件日志（插件>插件配置文件>日志）跟踪此通信。

监控数据

在Thinger.io中有多种方式查看设备发送的数据。

只要设备通过The Things Stack发送上行消息，原始数据就会在The Things Stack插件配置或自动配置的Thinger.io数据桶中可用，无需额外配置。

不过，建议在Thinger.io中创建仪表板（Dashboard），以更全面地查看数据。