IoT Gateway服务方法及数据类型

方法
- 核心方法（TBGatewayService）
- 实用方法（TBUtility）
  - install_package
  - convert_key_to_datapoint_key
数据类型

方法

核心方法（TBGatewayService）

网关服务类中对自定义连接器实现可能有帮助的实用方法。
/thingsboard_gateway/gateway/tb_gateway_service.py

send_to_storage

此方法允许您向ThingsBoard实例发送数据。

参数	描述
connector_name	发送数据的连接器名称。
connector_id	发送数据的连接器UUID。
data	包含设备数据的ConvertedData对象。

数据发送成功返回True，否则返回False。

send_rpc_reply

此方法允许您向ThingsBoard实例的RPC请求发送响应。

参数	默认值	描述
device	-	接收到RPC请求的设备名称。
req_id	-	RPC请求的整数标识符。
content	-	将作为RPC请求响应发送的数据字典。
success_sent	-	指示响应是否成功发送的布尔值。
wait_for_publish	-	指示网关是否应等待响应发布消息确认还是可以处理下一条消息的布尔值。
quality_of_service	0	响应消息的服务质量。
to_connector_rpc	False	指示原始请求是由连接器自身处理还是发送到设备的布尔值。

无返回值。

add_device

此方法允许您向网关添加设备，并向ThingsBoard实例发送”CONNECT”。

参数	默认值	描述
device_name	-	设备名称。
content	-	字典，应包含键”connector”和连接器实例作为值。将用于设置所创建设备的connectorName和connectorType参数。
device_type	“default”	设备类型。

设备添加成功返回True，否则返回False。

del_device

此方法允许您从网关删除设备，并向ThingsBoard实例发送”DISCONNECT”。

参数	默认值	描述
device_name	-	设备名称。

无返回值。

实用方法（TBUtility）

实用工具类中对自定义连接器实现可能有帮助的方法。 /thingsboard_gateway/tb_utility/tb_utility.py

install_package

此方法允许您在运行时从PyPi仓库安装软件包并将其加载到当前上下文中。

参数	默认值	描述
package	-	软件包名称。
version	upgrade	软件包版本。”upgrade”表示将安装最新可用版本。
force_install	False	指示是否在软件包已安装的情况下仍然安装的布尔值。

返回调用subprocess模块的check_call方法的结果。

使用示例：

from thingsboard_gateway.tb_utility.tb_utility import TBUtility
try:
    from pyserial import serial
except ImportError:
    TBUtility.install_package("pyserial")
    from pyserial import serial

convert_key_to_datapoint_key

此方法允许您将字符串键、设备的上报策略配置和键配置转换为DatapointKey。
创建ConvertedData对象需要使用DatapointKey对象。

参数	描述
key	键的最终字符串表示。
device_report_strategy	设备的ReportStrategyConfig对象。
key_config	此键的配置，可能包含键的上报策略配置。
logger	可选，当未找到键的上报策略配置时，将显示跟踪日志。

您可以在数据类型描述部分了解更多关于ReportStrategyConfig对象或ConvertedData对象的信息。

数据类型

本节包含网关中使用的对象说明。

ConvertedData

此对象用于通过send_to_storage方法将转换后的数据保存到存储中。
通常在转换器的convert方法中创建。

字段	描述
device_name	设备名称。
device_type	设备的设备配置文件名称。
telemetry	TelemetryEntry对象列表。
attributes	Attributes对象。

ConvertedData还包含服务字段，如metadata（允许使用延迟调试模式）和ts_index（充当带时间戳的遥测条目缓存）。

ConvertedData构造函数：

参数	默认值	描述
device_name	-	设备名称。
device_type	default	设备的设备配置文件名称。

ConvertedData对象创建示例：

converted_data = ConvertedData("CustomSerialDevice", "CustomSerialDeviceType")

ConvertedData方法：

add_to_telemetry

此方法允许您向ConvertedData对象中的遥测列表添加遥测条目或遥测条目列表。
此方法将分析传入的遥测数据并按时间戳在遥测列表中进行分组。

向ConvertedData对象添加遥测数据有以下几种方式： 1.通过TBUtility.convert_key_to_datapoint_key(…)方法创建的TelemetryEntry和DatapointKey对象作为遥测键。
强烈推荐，以便能够使用分层上报策略。

参数	描述
key_or_entry	遥测的DatapointKey。
value	遥测值。

使用示例：

```python
device_report_strategy = ReportStrategyConfig({"reportStrategy": {"type":"ON_RECEIVED"}})   # Create ReportStrategyConfig object for device, for demonstration.
key_config = {"key": "$[:8]", "type": "string", "fromByte": 8, "toByte": -1, "reportStrategy": {"type": "ON_CHANGE_OR_REPORT_PERIOD", "reportPeriod": "60000"}}   # Configuration for key for demonstration.

received_key = "humidity"   # Received key for telemetry. (Such as key in config may be some kind of expression, we will use string key, like it was already formatted.)
received_value = 48   # Received value for telemetry.

humidity_datapoint_key = TBUtility.convert_key_to_datapoint_key(received_key, device_report_strategy, key_config)   # Convert key to DatapointKey object.
humidity_telemetry_entry = TelemetryEntry({humidity_datapoint_key: received_value}, ts=123456789000)   # Create TelemetryEntry object with values and timestamp. For demonstration we use unreal timestamp in milliseconds.
converted_data.add_to_telemetry(humidity_datapoint_key, received_value)   # Add telemetry to the telemetry list.
```

2.使用DatapointKey对象作为遥测键。

参数	描述
telemetry_entry	TelemetryEntry对象或TelemetryEntry对象列表。

使用示例：

```python
humidity_datapoint_key = DatapointKey("humidity")   # Create DatapointKey object for telemetry key, without report strategy configuration.
telemetry_entry_with_humidity = TelemetryEntry({humidity_datapoint_key: 48})   # Create TelemetryEntry object with values, timestamp will be set to current timestamp internally.
converted_data.add_to_telemetry(telemetry_entry_with_humidity)   # Add telemetry entry to the telemetry list.
```

add_to_attributes

此方法允许您向ConvertedData对象中的Attributes对象添加属性。

向ConvertedData对象添加属性有以下几种方式： 1.通过TBUtility.convert_key_to_datapoint_key(…)方法创建的DatapointKey对象作为属性键。
强烈推荐，以便能够使用分层上报策略。

参数	描述
key_or_entry	属性的DatapointKey。
value	属性值。

使用示例：

```python
device_report_strategy = ReportStrategyConfig({"reportStrategy": {"type":"ON_RECEIVED"}})   # Create ReportStrategyConfig object for device, for demonstration.
key_config = {"key": "$[:12]", "type": "string", "fromByte": 12, "toByte": -1, "reportStrategy": {"type": "ON_CHANGE_OR_REPORT_PERIOD", "reportPeriod": "60000"}}   # Configuration for key for demonstration.

received_key = "SerialNumber"   # Received key for attribute. (Such as key in config may be some kind of expression, we will use string key, like it was already formatted.)
received_value = "24BC94AA95"   # Received value for attribute.

serial_number_datapoint_key = TBUtility.convert_key_to_datapoint_key(received_key, device_report_strategy, key_config)   # Convert key to DatapointKey object.
converted_data.add_to_attributes(serial_number_datapoint_key, received_value)   # Add attribute to the attributes list.
``` 2.使用[DatapointKey](#datapointkey)对象作为属性键。

参数	描述
key_or_entry	属性的DatapointKey。
value	属性值。

使用示例：

```python
serial_number_datapoint_key = DatapointKey("SerialNumber")   # Create DatapointKey object for attribute key, without report strategy configuration.
converted_data.add_to_attributes(serial_number_datapoint_key, "24BC94AA95")   # Add attribute to the attributes list.
```   

3.使用键/值对字典作为属性。

参数	描述
key_or_entry	属性的键/值对字典。

使用示例：

```python
attributes = {"SerialNumber": "24BC94AA95"}   # Create dictionary with key/value pair for attribute.
converted_data.add_to_attributes(attributes)   # Add attribute to the attributes list.
```

4.使用键/值对字典列表作为属性。

参数	描述
key_or_entry	属性的键/值对字典列表。

使用示例：

```python
attributes = [{"SerialNumber": "24BC94AA95"}, {"FirmwareVersion": "1.0.0"}]   # Create list of dictionaries with key/value pair for attributes.
converted_data.add_to_attributes(attributes)   # Add attributes to the attributes list.
```

5.使用字符串键和值作为属性。

参数	描述
key_or_entry	属性的字符串键。
value	属性值。

使用示例：

```python
converted_data.add_to_attributes("SerialNumber", "24BC94AA95")   # Add attribute to the attributes list.
```

ConvertedData示例：

在下面的示例中，我们将演示如何创建ConvertedData对象并向其添加遥测和属性。
我们将使用TBUtility.convert_key_to_datapoint_key(…)方法作为遥测和属性键。
设备的主上报策略为”ON_RECEIVED”，但我们将为每个遥测和属性键使用不同的上报策略。

# Preparations for demonstration.
connector_name = "CustomSerialConnector"
connector_id = UUID("10101010-1010-1010-1010-101010101010")
# ...
device_report_strategy = ReportStrategyConfig({"reportStrategy": {"type":"ON_RECEIVED"}})

# Configuration for keys for demonstration.
telemetry_key_config = {"key": "$[:8]", "type": "string", "fromByte": 8, "toByte": 18, "reportStrategy": {"type": "ON_CHANGE_OR_REPORT_PERIOD", "reportPeriod": "60000"}}
attr_key_config = {"key": "$[18:30]", "type": "string", "fromByte": 30, "toByte": -1, "reportStrategy": {"type": "ON_CHANGE"}}

# Received data for demonstration.
device_name = "CustomSerialDevice"
device_type = "CustomSerialDeviceType"
received_telemetry_key = "humidity"
received_telemetry_value = 48
received_key_attr = "SerialNumber"
received_value_attr = "24BC94AA95"

converted_data = ConvertedData(device_name, device_type)   # Create ConvertedData object with device name and device type.

# Convert keys to DatapointKey objects.
telemetry_datapoint_key = TBUtility.convert_key_to_datapoint_key(received_telemetry_key, device_report_strategy, telemetry_key_config)
attribute_datapoint_key = TBUtility.convert_key_to_datapoint_key(received_key_attr, device_report_strategy, attr_key_config)

# Add telemetry to the telemetry list.
converted_data.add_to_telemetry(telemetry_datapoint_key, received_telemetry_value)

# Add attribute to the attributes.
converted_data.add_to_attributes(attribute_datapoint_key, received_value_attr)

# ...

# Send data to the ThingsBoard instance. (gateway is an instance of TBGatewayService, provided to connector on initialization)
gateway.send_to_storage(connector_name, connector_id, converted_data)

上述示例的结果是一个包含遥测和属性的ConvertedData对象。
收集在遥测和属性中的数据将根据上报策略配置发送到ThingsBoard实例。
在此示例中，遥测数据将在变化时或每60秒发送到ThingsBoard实例，而属性仅在变化时发送。

Attributes

这是ConvertedData对象的内部对象，包含设备的属性。无需直接创建Attributes对象，当您向ConvertedData对象添加属性时，它会自动创建。

字段	描述
values	属性的DatapointKey/值对字典。

TelemetryEntry

此对象用于收集设备的遥测数据，包含时间戳和相关键/值。

字段	描述
values	遥测条目的键/值对字典。
ts	可选，遥测条目的时间戳。如果未提供ts，将设置为当前时间戳。

TelemetryEntry对象创建示例： 1.通过TBUtility.convert_key_to_datapoint_key(…)方法创建的DatapointKey对象作为遥测键。 强烈推荐，以便能够使用分层上报策略。

```python
device_report_strategy = ReportStrategyConfig({"reportStrategy": {"type":"ON_RECEIVED"}})   # Create ReportStrategyConfig object for device, for demonstration.
key_config = {"key": "$[:8]", "type": "string", "fromByte": 8, "toByte": -1, "reportStrategy": {"type": "ON_CHANGE_OR_REPORT_PERIOD", "reportPeriod": "60000"}}   # Configuration for key for demonstration.

received_key = "humidity"   # Received key for telemetry. (Such as key in config may be some kind of expression, we will use string key, like it was already formatted.)
received_value = 48   # Received value for telemetry.

humidity_datapoint_key = TBUtility.convert_key_to_datapoint_key(received_key, device_report_strategy, key_config)   # Convert key to DatapointKey object.
humidity_telemetry_entry = TelemetryEntry({humidity_datapoint_key: received_value}, ts=123456789000)   # Create TelemetryEntry object with values and timestamp. For demonstration we use unreal timestamp in milliseconds.
```

2.使用DatapointKey对象作为遥测键。

```python
humidity_datapoint_key = DatapointKey("humidity")   # Create DatapointKey object for telemetry key without report strategy configuration.
humidity_telemetry_entry = TelemetryEntry({humidity_datapoint_key: 48}, ts=123456789000)   # Create TelemetryEntry object with values and timestamp. For demonstration we use unreal timestamp in milliseconds.
```

3.使用字符串键和值作为遥测键。

```python
humidity_telemetry_entry = TelemetryEntry({"humidity": 48})   # Create TelemetryEntry object with values and current timestamp.
```

DatapointKey

此对象用于表示带有上报策略配置的遥测或属性键。

字段	描述
key	遥测或属性的键。
report_strategy	键的ReportStrategyConfig对象。

DatapointKey对象创建示例： 1.使用TBUtility.convert_key_to_datapoint_key(…)方法作为遥测键。它将使用key_config或device_report_strategy中的上报配置。 强烈推荐，以便能够使用分层上报策略。

```python
device_report_strategy = ReportStrategyConfig({"reportStrategy": {"type":"ON_RECEIVED"}})   # Create ReportStrategyConfig object for device, for demonstration.
key_config = {"key": "$[:8]", "type": "string", "fromByte": 8, "toByte": -1, "reportStrategy": {"type": "ON_CHANGE_OR_REPORT_PERIOD", "reportPeriod": "60000"}}   # Configuration for key for demonstration.

received_key = "humidity"   # Received key for telemetry. (Such as key in config may be some kind of expression, we will use string key, like it was already formatted.)

humidity_datapoint_key = TBUtility.convert_key_to_datapoint_key(received_key, device_report_strategy, key_config)   # Convert key to DatapointKey object.
```

2.使用ReportStrategyConfig对象作为遥测键。

```python
key_report_strategy = ReportStrategyConfig({"reportStrategy": {"type":"ON_RECEIVED"}})   # Create ReportStrategyConfig object for key, for demonstration.
humidity_datapoint_key = DatapointKey("humidity", key_report_strategy)   # Create DatapointKey object for telemetry key with report strategy configuration.
```

3.使用字符串键作为遥测键（不带上报策略）。

```python
humidity_datapoint_key = DatapointKey("humidity")   # Create DatapointKey object for telemetry key without report strategy configuration.
```

ReportStrategyConfig

此对象是上报策略配置的表示。
它用于在不同层级上设置遥测或属性键的上报策略。
上报策略配置有以下层级：

网关层级 -网关中所有设备的上报策略。（在全局配置中设置）
连接器层级 -连接器中所有设备的上报策略。（在连接器配置中设置）
设备层级 -设备中所有键的上报策略。（在设备配置中设置）
键层级 -键的上报策略。（在键配置中设置）

键层级覆盖设备层级，设备层级覆盖连接器层级，连接器层级覆盖网关层级。

字段	描述
config	可能包含上报策略配置的配置对象。（reportStrategy）
default_report_strategy_config	可选，包含默认上报策略配置的字典。

如果配置中未设置reportStrategy，将使用默认上报策略。

ReportStrategyConfig对象创建示例： 1.使用包含上报策略配置的字典。

```python
report_strategy_config = ReportStrategyConfig({"reportStrategy": {"type":"ON_RECEIVED"}})
``` 2.使用包含上报策略配置和默认上报策略配置的字典。

```python
default_report_strategy_config = {"reportStrategy": {"type":"ON_CHANGE"}}
report_strategy_config = ReportStrategyConfig({"reportStrategy": {"type":"ON_RECEIVED"}}, default_report_strategy_config)
```

连接器接口

此对象用于表示连接器的接口。
自定义连接器类应继承此对象。
/thingsboard_gateway/connectors/connector.py

方法	描述
__init__	连接器的构造函数。网关传递以下参数：gateway、config、connector_type
open	用于启动连接器的方法。
close	用于停止连接器的方法。
get_id	获取连接器ID的方法。连接器ID存储在传递给构造函数的config中，键为id
get_name	获取连接器名称的方法。连接器名称存储在传递给构造函数的config中，键为name
get_type	获取连接器类型的方法。预期获取传递给构造函数的连接器类型。
get_config	获取连接器配置的方法。预期返回传递给构造函数的连接器配置。
is_connected	检查连接器是否已连接的方法。预期返回布尔值。
is_stopped	检查连接器是否已停止的方法。预期返回布尔值。
on_attributes_update	处理来自平台实例的属性更新的方法。
server_side_rpc_handler	处理来自平台实例的RPC请求的方法。

转换器接口

此对象用于表示转换器的接口。自定义转换器类应继承此对象。 /thingsboard_gateway/connectors/converter.py

方法	描述
__init__	转换器的构造函数。取决于连接器的实现，通常传递：config、logger
convert	将数据从设备格式转换为平台格式或反之亦然的方法。

转换器接口方法

转换器方法的实现取决于其类型- 上行或下行。

上行转换器convert方法

此方法用于将数据从设备格式转换为ThingsBoard实例格式。
建议返回ConvertedData对象（取决于实现，但网关服务的send_to_storage方法期望接收ConvertedData对象）。

下行转换器convert方法

此方法用于将数据从ThingsBoard实例格式转换为设备格式。
传入数据是一个键/值对字典，表示应发送到设备的数据。
此类型的转换器通常用于将平台实例的RPC或属性更新转换为设备格式。
返回值取决于转换器的实现。