thinger/sigfox-plugin

Sigfox

此插件是用于优化使用Sigfox HTTP回调功能的接口，提供轻松将这些设备与Thinger.io平台集成的功能，例如自动设备和存储配置以及上行和下行云处理。

插件特性

• 对每个包含在同一Sigfox“设备类型”中的新设备，自动配置设备和数据桶。
• 存储Sigfox设备元数据：设备位置、信号质量、硬件序列号等。
• 自动将设备数据存储在数据桶中，以便从控制台轻松使用。
• 支持NodeJS自定义上行数据处理，适用于payload_raw或payload_fields。
• 支持在NodeJS中定义自定义下行回调，可将用户友好格式（JSON）的下行数据转换为Sigfox网络所需的payload_raw或payload_fields。

Sigfox概念

为更好地理解以下部分，此处介绍一些基本的Sigfox概念：

• 设备：具有官方Sigfox接口的硬件设备。
• 网关：Sigfox基础设施硬件接口，主要接收多个边缘设备的消息并通过IP通信推送到Sigfox服务器。这些网关为Sigfox公司专有。
• 上行：设备向Sigfox云发送消息的数据流，包括单向上行（仅设备到Sigfox网络的数据通信）和双向上行（允许Sigfox系统向设备发送下行消息）。
• 下行：Sigfox云向设备发送消息的数据流。
• 设备类型：定义同一类型设备组的概念，通常上行和下行发送相同类型的数据。

!!! info

了解如何配置Sigfox回调以将数据发送到Thinger.io平台，请参见https://docs.thinger.io/lpwan/sigfox#creating-sigfox-callback

插件配置

本节介绍可用于配置Sigfox插件的不同界面。

应用程序

通过此插件集成的每个Sigfox“设备类型”，都应在Thinger.io插件中定义一个新配置文件，其标识符与Sigfox平台中定义的相同。请注意，以此方式定义的每个Sigfox设备类型都允许自定义该类设备的插件行为。

可根据需要创建任意数量的设备类型配置文件。要配置新配置文件，只需从设备类型下拉列表中选择ID，然后导航到其他插件部分。

!!! warning

设备类型的标识符必须与Sigfox云中定义的完全相同。

回调配置

上行行为允许配置插件在收到来自Sigfox的新信息时的反应方式。

可配置的参数如下：

• 自动配置资源：启用或禁用在收到同一Sigfox“设备类型”中未创建设备的消息时自动配置资源。
• 设备连接超时：创建新设备时，设置设备连接超时（分钟），以便平台在固定时间未收到消息后将设备视为已断开连接。
• 设备标识符前缀：创建新设备时，使用自定义前缀+原始设备ID命名。
• 数据桶标识符前缀：创建与设备关联的新数据桶时，使用自定义前缀+原始设备ID命名。
• 更新设备位置：使用网关信息中提供的位置更新当前设备位置。
• 初始化下行数据：创建新设备时，初始化自定义下行数据，可在后续下行请求中修改和处理。

载荷处理

本节可配置载荷处理器，用于转换Sigfox上行消息中的原始数据，或Thinger.io平台发送到Sigfox云的下行消息中的载荷。

界面提供NodeJS代码编辑器，可定义uplink（上行）和downlink（下行）处理器。还可通过提供uplink和downlink的示例输入数据来测试代码。

以下是上行和下行方法的详细说明。

=== "上行"

当设备通过网络发送新消息时，将调用上行方法。根据Sigfox网络中的配置，此函数可接收两种不同的输入：

* **Base64字符串**：如果Sigfox设备类型定义了自定义载荷格式，此方法将接收base64编码的原始载荷。此时，需要编写函数将此base64数据转换为JSON对象。
* **JSON对象**：此方法的输出必须始终是包含平台所需信息的JSON对象。以下是将base64数据转换为包含从二进制数据解析的`temperature`（温度）和`humidity`（湿度）的JSON对象的上行方法示例。

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

!!! info

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

=== "下行"

仅当Sigfox设备向Sigfox云上送双向消息时，才会调用下行方法。此时，Thinger.io服务器将响应包含十六进制编码的自定义下行载荷的回调消息。有关更多详细信息，请参见以下部分。

此函数接收的输入取决于通过REST API调用插件的方式：

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

此方法的输出将是发送到Sigfox网络的**Base64字符串**格式的二进制信息。

!!! warning

    处理下行载荷时，“初始化下行数据”参数必须初始化为任意数据，否则下行载荷处理将失败。

以下是将JSON设备配置转换为Sigfox所需base64的下行方法示例：

```javascript
/* 将包含设备配置的JSON对象转换为Sigfox云所需的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('hex');
};
```

!!! info

使用界面测试器可检查代码是否正确处理载荷。

Sigfox云配置

在Thinger.io插件准备好接收数据后，下一步是配置Sigfox后端以推送消息。此过程可通过插件设置菜单的“Sigfox集成”部分简化，该部分自动生成HTTP查询和授权令牌，需将其包含在Sigfox回调管理器中：

请注意，Sigfox云提供三种不同的API，具体取决于要创建的交互类型，Thinger.io平台支持所有这些API：上行、高级数据和下行回调类型。每个回调配置可针对单个设备或属于同一设备类型的所有设备创建。

创建新回调时需配置以下参数：

• 回调类型：定义回调行为。
• 自定义载荷配置：（可选）定义设备消息的解码方式。
• URL模式：填写自动生成的Thinger.io URL模式。
• HTTP方法：上行使用POST，下行使用GET。
• 授权头：必须包含自动生成的授权信息，以允许Sigfox云向Thinger.io发送数据。
• 正文：具有指定内容类型的可配置消息载荷。

基本上行集成

此回调配置是最常见的，仅以单向方式将设备数据发送到Thinger.io，用于存储、聚合和显示。

带计算位置的上行（高级数据）

此回调配置允许检索其他信息，例如地理位置以及从接收消息的不同基站提取的基础设施元数据。但使用此回调需要约30秒的延迟。

上行和下行

最后，选择DATA/BIDIR回调，可将上行消息发送到Thinger.io平台，并等待下行消息发送到设备，以进行配置或远程控制。下行消息载荷的配置可在Thinger.io平台的Sigfox插件回调配置部分完成，或在设备仪表板中修改各个设备的下行属性：

!!! tip

必须在回调载荷中发送设备信息。其他可选值包括从Sigfox提取的信号或位置信息。

```json
{
    "device" : "{device}",
    "snr" : {snr},
    "rssi" : {rssi},
    "station": "{station}",
    "latitude": {lat},
    "longitude": {lng},
    "temperature" : {customData#temp},
    "humidity" : {customData#hum}
}
```

使用平台功能与Sigfox设备

恭喜！现在您可以将所有Sigfox设备的数据检索到Thinger.io平台，并利用其所有管理、分析和展示功能，以简单方式创建出色的IoT项目。以下是Thinger.io针对Sigfox设备的一些基本功能：

检查设备状态

由于这些设备并非实时连接到平台，长期监控其运行状态（尤其是在大型设备网络中）较为困难。但通过插件回调配置菜单中的“设备连接超时”功能，可设置超时时间，通过设备仪表板中的“设备状态”了解设备是否在规定时间内发送数据，或是否因故障停止工作。

还可从设备列表中检查大量设备的状态，但请注意，此页面不显示实时数据，需刷新以获取当前状态。

在可扩展数据桶中存储数据

Thinger.io最常用的功能之一是数据桶，可轻松存储大量数据。通过此新插件与Sigfox的集成，可在载荷处理后存储数据，而非原始或受限格式。

数据存储在数据桶后，可通过下载CSV格式的数据点、创建小部件在可自定义仪表板中展示数据，并轻松与同事或客户共享。

通过端点将数据发送到第三方

Thinger.io是一个大型技术和平台生态系统的一部分，可帮助您从数据中获取最大价值。因此，我们提供了端点工具，允许将任何设备的数据转发到第三方平台，并使用其他互联网服务（如发送电子邮件、***消息、将数据转储到Google表格等几乎所有互联网服务）。

与其他插件结合

在Thinger.io，我们持续扩展平台与技术的集成能力，以最简单的方式创建更高级的IoT项目。我们提供其他插件（如NodeRED），可通过几乎无限的方式处理IoT数据，例如创建数据警报、地理围栏、报告等。

插件开发细节

上行数据流

本节描述上行数据流的工作方式，从Sigfox网络中的源头到Thinger.io中的最终目的地。

以下小节描述图中所示元素。

Sigfox上行回调

当Sigfox收到任何设备的消息时，会自动检查其配置的集成，以转发收到的信息。此插件通过HTTP集成，因此Sigfox网络会在收到新消息时向Thinger.io插件发出HTTP请求。

Sigfox插件

Thinger.io插件以JSON格式接收来自Sigfox网络的数据。回调包含多个信息字段，例如app_id、dev_id、downlink_url、metadata，或LoRa设备发送的实际载荷信息（payload_fields或payload_raw字段，取决于Sigfox应用中配置的载荷格式）。

以下是插件收到的原始信息示例：

javascript
{
    "temperature" : {customData#temp},
    "humidity" : {customData#hum},
    "data" : {data}
}

插件收到此信息后，会进行处理以在Thinger.io中执行以下操作：

1. 如果设备在平台上不存在，基于dev_id字段自动配置新设备及其关联的数据桶。
2. 调用设备回调，将处理后的数据推送到其关联的数据桶，也可执行其他操作（如下转发数据到其他端点）。

上行处理器

此插件允许配置自定义代码处理传入数据。Sigfox设备发送的信息通常编码为小型二进制载荷，为最小化传输时间，不能直接用于展示（不应包含标签、JSON、ASCII文本等）。因此，需要在云端的某个环节处理设备发送的数据。

如有必要，此插件还允许创建自定义解码器。使用Thinger.io载荷处理的优势（如需要）在于，它使用NodeJS运行时而非纯JavaScript，因此可使用Buffer等NodeJS模块，简化处理函数的编写。

在内部，载荷处理器在插件中配置后会预编译，并使用从Sigfox接收的载荷数据执行。此函数的输出（如果执行）随后传输到下一步，即设备回调。

设备回调

此插件的最后一步是调用Thinger.io中的设备回调。该插件将新的Sigfox设备自动配置为HTTP设备。Thinger.io中的HTTP设备是可通过REST API方法推送数据的通用设备。Thinger.io负责接收输入数据并执行不同的可配置操作，例如将设备状态更改为已连接/已断开连接；将提供的数据写入配置的数据桶；通过端点将此信息发送到其他服务；将提供的信息存储为设备属性；或从设备属性返回数据。

在这种情况下，插件通过REST接口与平台交互，推送从Sigfox接收并经自定义上行方法处理的数据。默认情况下，插件初始化HTTP设备以写入自动创建的关联数据桶。因此，Sigfox设备发送的每条消息最终都会写入特定的数据桶。如下图所示：

完成设备回调后，设备将显示为已连接状态，并在配置的情况下显示其位置。

供应商