终止支持通知：2026 年 10 月 7 日， Amazon 将停止对的支持。 Amazon IoT Greengrass Version 1 2026 年 10 月 7 日之后，您将无法再访问这些 Amazon IoT Greengrass V1 资源。如需了解更多信息，请访问[迁移自 Amazon IoT Greengrass Version 1](https://docs.amazonaws.cn/greengrass/v2/developerguide/migrate-from-v1.html)。 本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 串行流连接器 **警告** 此连接器已进入*生命周期延长阶段*， Amazon IoT Greengrass 不会发布更新来提供功能、现有功能增强、安全补丁或错误修复。有关更多信息，请参阅 [Amazon IoT Greengrass Version 1 维护政策](maintenance-policy.md)。 串行流[连接器](connectors.md)对 Amazon IoT Greengrass 核心设备上的串行端口进行读取和写入。 此连接器支持两种操作模式： + **Read-On-Demand**。 接收有关 MQTT 主题的读取和写入请求，并发布读取操作的响应或写入操作的状态。 + **Polling-Read**。 定期从串行端口读取。此模式还支持 Read-On-Demand 请求。 **注意** 读取请求的限制为最多 63994 字节的读取长度。写入请求的限制为最多 128000 字节的数据长度。 此连接器具有以下版本。 | 版本 | 进行筛选 | | --- | --- | | 3 | `arn:aws:greengrass:{{region}}::/connectors/SerialStream/versions/3` | | 2 | `arn:aws:greengrass:{{region}}::/connectors/SerialStream/versions/2` | | 1 | `arn:aws:greengrass:{{region}}::/connectors/SerialStream/versions/1` | 有关版本更改的信息，请参阅[更改日志](#serial-stream-connector-changelog)。 ## 要求 此连接器具有以下要求： ------ #### [ Version 3 ] + Amazon IoT Greengrass 核心软件 v1.9.3 或更高版本。 + [Python](https://www.python.org/) 版本 3.7 或 3.8 已安装在核心设备上，并已添加到 PATH 环境变量中。 **注意** 要使用 Python 3.8，请运行以下命令来创建从默认 Python 3.7 安装文件夹到已安装的 Python 3.8 二进制文件的符号链接。 ``` sudo ln -s {{path-to-python-3.8}}/python3.8 /usr/bin/python3.7 ``` 这会将设备配置为满足 Amazon IoT Greengrass的 Python 要求。 + Greengrass 组中一个指向目标串行端口的[本地设备资源](access-local-resources.md)。 **注意** 建议先设置串行端口并验证可读取和写入此串行端口，然后部署此连接器。 ------ #### [ Versions 1 - 2 ] + Amazon IoT Greengrass 核心软件 v1.7 或更高版本。 + [Python](https://www.python.org/) 版本 2.7 已安装在核心设备上，并已添加到 PATH 环境变量中。 + Greengrass 组中一个指向目标串行端口的[本地设备资源](access-local-resources.md)。 **注意** 建议先设置串行端口并验证可读取和写入此串行端口，然后部署此连接器。 ------ ## 连接器参数 该连接器提供以下参数： `BaudRate` 串行连接的波特率。 Amazon IoT 控制台中的显示名称：**波特率** 必需：`true` 类型：`string` 有效值：`110, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 56000, 57600, 115200, 230400` 有效模式：`^110$|^300$|^600$|^1200$|^2400$|^4800$|^9600$|^14400$|^19200$|^28800$|^38400$|^56000$|^57600$|^115200$|^230400$` `Timeout` 读取操作的超时（以秒为单位）。 Amazon IoT 控制台中的显示名称：**超时** 必需：`true` 类型：`string` 有效值：`1 - 59` 有效模式：`^([1-9]|[1-5][0-9])$` `SerialPort` 设备上的物理串行端口的绝对路径。这是为本地设备资源指定的源路径。 Amazon IoT 控制台中的显示名称：**串行端口** 必需：`true` 类型：`string` 有效模式：`[/a-zA-Z0-9_-]+` `SerialPort-ResourceId` 表示物理串行端口的本地设备资源的 ID。 连接器被授予对该资源的读写访问权限。 Amazon IoT 控制台中的显示名称：**串行端口资源** 必需：`true` 类型：`string` 有效模式：`[a-zA-Z0-9_-]+` `PollingRead` 设置读取模式： Polling-Read 或 Read-On-Demand。 + 对于 Polling-Read 模式，请指定`true`。在该模式下，`PollingInterval`、`PollingReadType` 和 `PollingReadLength` 属性是必需属性。 + 对于 Read-On-Demand 模式，请指定`false`。在该模式下，将在读取请求中指定类型和长度值。 Amazon IoT 控制台中的显示名称：**读取模式** 必需：`true` 类型：`string` 有效值：`true, false` 有效模式：`^([Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee])$` `PollingReadLength` 要在每个轮询读取操作中读取的数据长度（字节）。这仅在使用 Polling-Read 模式时适用。 Amazon IoT 控制台中的显示名称：**轮询读取时长** 必需：`false`。当 `PollingRead` 为 `true` 时，该属性是必需属性。 类型：`string` 有效模式：`^(|[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-2][0-9]{3}|63[0-8][0-9]{2}|639[0-8][0-9]|6399[0-4])$` `PollingReadInterval` 轮询读取的时间间隔（以秒为单位）。这仅在使用 Polling-Read 模式时适用。 Amazon IoT 控制台中的显示名称：**轮询读取间隔** 必需：`false`。当 `PollingRead` 为 `true` 时，该属性是必需属性。 类型：`string` 有效值：1 - 999 有效模式：`^(|[1-9]|[1-9][0-9]|[1-9][0-9][0-9])$` `PollingReadType` 轮询线程读取的数据类型。这仅在使用 Polling-Read 模式时适用。 Amazon IoT 控制台中的显示名称：**轮询读取类型** 必需：`false`。当 `PollingRead` 为 `true` 时，该属性是必需属性。 类型：`string` 有效值：`ascii, hex` 有效模式：`^(|[Aa][Ss][Cc][Ii][Ii]|[Hh][Ee][Xx])$` `RtsCts` 指示是否启用 RTS/CTS 流量控制。默认值为 `false`。有关更多信息，请参阅 [RTS、CTS 和 RTR](https://en.wikipedia.org/wiki/RS-232#RTS,_CTS,_and_RTR)。 Amazon IoT 控制台中的显示名称：**RTS/CTS 流量控制** 必需：`false` 类型：`string` 有效值：`true, false` 有效模式：`^(|[Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee])$` `XonXoff` 指示是否启用软件流控制。默认值为 `false`。有关更多信息，请参阅[软件流控制](https://en.wikipedia.org/wiki/Software_flow_control)。 Amazon IoT 控制台中的显示名称：**软件流量控制** 必需：`false` 类型：`string` 有效值：`true, false` 有效模式：`^(|[Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee])$` `Parity` 串行端口的奇偶校验。默认值为 `N`。有关更多信息，请参阅[奇偶校验](https://en.wikipedia.org/wiki/Serial_port#Parity)。 Amazon IoT 控制台中的显示名称：**串行端口奇偶校验** 必需：`false` 类型：`string` 有效值：`N, E, O, S, M` 有效模式：`^(|[NEOSMneosm])$` ### 创建连接器示例 (Amazon CLI) 以下 CLI 命令创建一个 `ConnectorDefinition`，其初始版本包含串行流连接器。它将连接器配置为 Polling-Read 模式。 ``` aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MySerialStreamConnector", "ConnectorArn": "arn:aws:greengrass:{{region}}::/connectors/SerialStream/versions/3", "Parameters": { "BaudRate" : "9600", "Timeout" : "25", "SerialPort" : "/dev/serial1", "SerialPort-ResourceId" : "my-serial-port-resource", "PollingRead" : "true", "PollingReadLength" : "30", "PollingReadInterval" : "30", "PollingReadType" : "hex" } } ] }' ``` 在 Amazon IoT Greengrass 控制台中，您可以从群组的 “连接器” 页面添加**连接器**。有关更多信息，请参阅 [Greengrass 连接器入门（控制台）](connectors-console.md)。 ## 输入数据 此连接器接受关于两个 MQTT 主题的串行端口读取或写入请求。输入消息必须采用 JSON 格式。 + 读取请求位于`serial/+/read/#` 主题上。 + 写入请求位于 `serial/+/write/#` 主题上。 要发布到这些主题，请将 `+` 通配符替换为核心事物名称，将 `#` 通配符替换为串行端口的路径。例如： ``` serial/{{core-thing-name}}/read/dev/{{serial-port}} ``` **主题筛选条件**：`serial/+/read/#` 使用此主题向串行引脚发送按需读取请求。读取请求的限制为最多 63994 字节的读取长度。 **消息属性** `readLength` 要从串行端口读取的数据长度。 必需：`true` 类型：`string` 有效模式：`^[1-9][0-9]*$` `type` 要读取的数据的类型。 必需：`true` 类型：`string` 有效值：`ascii, hex` 有效模式：`(?i)^(ascii|hex)$` `id` 请求的任意 ID。此属性用于将输入请求映射到输出响应。 必需：`false` 类型：`string` 有效模式：`.+` **示例输入** ``` { "readLength": "30", "type": "ascii", "id": "abc123" } ``` **主题筛选条件**：`serial/+/write/#` 使用此主题向串行引脚发送写入请求。写入请求的限制为最多 128000 字节的数据长度。 **消息属性** `data` 要写入到该串行端口的字符串。 必需：`true` 类型：`string` 有效模式：`^[1-9][0-9]*$` `type` 要读取的数据的类型。 必需：`true` 类型：`string` 有效值：`ascii, hex` 有效模式：`^(ascii|hex|ASCII|HEX)$` `id` 请求的任意 ID。此属性用于将输入请求映射到输出响应。 必需：`false` 类型：`string` 有效模式：`.+` **示例输入：ASCII 请求** ``` { "data": "{{random serial data}}", "type": "ascii", "id": "abc123" } ``` **示例输入：十六进制请求** ``` { "data": "{{base64 encoded data}}", "type": "hex", "id": "abc123" } ``` ## 输出数据 连接器发布关于两个主题的输出数据： + 来自连接器的关于 `serial/+/status/#` 主题的状态信息。 + 来自读取请求的响应（关于 `serial/+/read_response/#` 主题）。 当发布到此主题时，连接器会将 `+` 通配符替换为核心事物名称，并将 `#` 通配符替换为串行端口的路径。例如： ``` serial/{{core-thing-name}}/status/dev/{{serial-port}} ``` **主题筛选条件**：`serial/+/status/#` 使用此主题侦听读取和写入请求的状态。如果请求包含 `id` 属性，则该属性将在响应中返回。 **示例输出：成功** ``` { "response": { "status": "success" }, "id": "abc123" } ``` **示例输出：失败** 失败响应包含一个 `error_message` 属性，用于描述在执行读取或写入操作时遇到的错误或超时。 ``` { "response": { "status": "fail", "error_message": "Could not write to port" }, "id": "abc123" } ``` **主题筛选条件**：`serial/+/read_response/#` 使用此主题接收来自读取操作的响应数据。如果类型为 `hex`，则响应数据经过 Base64 编码。 **示例输出** ``` { "data": "{{output of serial read operation}}" "id": "abc123" } ``` ## 用法示例 使用以下概括步骤设置可用于尝试连接器的示例 Python 3.7 Lambda 函数。 **注意** 如果你使用其他 Python 运行时，你可以创建从 Py Python3.x thon 3.7 的符号链接。 [连接器入门（控制台）](connectors-console.md) 和 [连接器入门 (CLI)](connectors-cli.md) 主题包含详细步骤，说明如何配置和部署示例 Twilio 通知连接器。 1. 确保满足连接器的[要求](#serial-stream-connector-req)。 1. 创建并发布将输入数据发送到连接器的 Lambda 函数。 将[示例代码](#serial-stream-connector-usage-example)保存为 PY 文件。下载并解压[适用于 Python 的Amazon IoT Greengrass Core 软件开发工具包](lambda-functions.md#lambda-sdks-core)。然后，创建一个 zip 包，其中在根级别包含 PY 文件和 `greengrasssdk` 文件夹。此 zip 包是您上传到 Amazon Lambda的部署包。 创建 Python 3.7 Lambda 函数后，请发布函数版本并创建别名。 1. 配置 Greengrass 组。 1. 通过别名来添加 Lambda 函数（推荐）。将 Lambda 生命周期配置为长时间生存（或在 CLI 中设置为 `"Pinned": true`）。 1. 添加所需的本地设备资源并授予 read/write 对 Lambda 函数的访问权限。 1. 将连接器添加到组并配置其[参数](#serial-stream-connector-param)。 1. 向组添加允许连接器接收[输入数据](#serial-stream-connector-data-input)并针对支持的主题筛选条件发送[输出数据](#serial-stream-connector-data-output)的订阅。 + 将 Lambda 函数设置为源，将连接器设置为目标，并使用支持的输入主题筛选条件。 + 将连接器设置为源，将 Amazon IoT Core 设置为目标，并使用支持的输出主题筛选条件。您可以使用此订阅在 Amazon IoT 控制台中查看状态消息。 1. 部署组。 1. 在 Amazon IoT 控制台的 “**测试**” 页面上，订阅输出数据主题以查看来自连接器的状态消息。示例 Lambda 函数是长时间生存的，并且在部署组后立即开始发送消息。 完成测试后，您可以将 Lambda 生命周期设置为按需（或在 CLI 中设置为 `"Pinned": false`）并部署组。这会阻止函数发送消息。 ### 示例 以下示例 Lambda 函数向连接器发送一条输入消息。 ``` import greengrasssdk import json TOPIC_REQUEST = 'serial/CORE_THING_NAME/write/dev/serial1' # Creating a greengrass core sdk client iot_client = greengrasssdk.client('iot-data') def create_serial_stream_request(): request = { "data": "TEST", "type": "ascii", "id": "abc123" } return request def publish_basic_request(): iot_client.publish(payload=json.dumps(create_serial_stream_request()), topic=TOPIC_REQUEST) publish_basic_request() def lambda_handler(event, context): return ``` ## 许可证 串行流连接器包括以下第三方 software/licensing： + [pyserial](https://github.com/pyserial/pyserial)/BSD 该连接器在 [Greengrass Core 软件许可协议](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)下发布。 ## 更改日志 下表介绍每个版本连接器的更改。 | 版本 | 更改 | | --- | --- | | 3 | 已将 Lambda 运行时升级到 Python 3.7，这会更改运行时要求。 | | 2 | 更新了连接器 ARN 以获得支持。 Amazon Web Services 区域 | | 1 | 初始版本。 | Greengrass 组在一个时间上只能包含一个版本的连接器。有关升级连接器版本的信息，请参阅[升级连接器版本](connectors.md#upgrade-connector-versions)。 ## 另请参阅 + [使用 Greengrass 连接器与服务和协议集成](connectors.md) + [Greengrass 连接器入门（控制台）](connectors-console.md) + [Greengrass 连接器入门 (CLI)](connectors-cli.md)