支援終止通知：2026 年 10 月 7 日 AWS 將停止 的支援 AWS IoT Greengrass Version 1。2026 年 10 月 7 日之後，您將無法再存取 AWS IoT Greengrass V1 資源。如需詳細資訊，請造訪[從 遷移 AWS IoT Greengrass Version 1](https://docs.aws.amazon.com/greengrass/v2/developerguide/migrate-from-v1.html)。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 序列串流連接器 **警告** 此連接器已進入*延長生命週期階段*，且 AWS IoT Greengrass 不會發行提供現有功能、增強功能、安全修補程式或錯誤修正的更新。如需詳細資訊，請參閱[AWS IoT Greengrass Version 1 維護政策](maintenance-policy.md)。 序列串流[連接器](connectors.md)會讀取和寫入 AWS IoT Greengrass 核心裝置上的序列連接埠。 此連接器支援兩種操作模式： + **隨需讀取**。接收 MQTT 主題上的讀取和寫入請求，並發佈讀取操作的回應，或寫入操作的狀態。 + **輪詢讀取**。定期從序列埠讀取。這個模式還支援隨需讀取請求。 **注意** 讀取請求的最大讀取長度限制為 63994 位元組。寫入請求的最大資料長度限制為 128000 位元組。 此連接器具有下列版本。 | 版本 | ARN | | --- | --- | | 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` | 如需版本變更的詳細資訊，請參閱 [Changelog](#serial-stream-connector-changelog)。 ## 要求 此連接器有下列要求： ------ #### [ Version 3 ] + AWS IoT Greengrass 核心軟體 v1.9.3 或更新版本。 + 安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 3.7 或 3.8 版。 **注意** 若要使用 Python 3.8，請執行下列命令，以建立從預設 Python 3.7 安裝資料夾到已安裝 Python 3.8 二進位檔的符號連結。 ``` sudo ln -s path-to-python-3.8/python3.8 /usr/bin/python3.7 ``` 這會設定您的裝置以符合 AWS IoT Greengrass的 Python 需求。 + Greengrass 群組中的[本機裝置資源](access-local-resources.md)，指向目標序列連接埠。 **注意** 在您部署此連接器之前，建議您設定序列埠並驗證是否可對該序列埠進行讀取和寫入。 ------ #### [ Versions 1 - 2 ] + AWS IoT Greengrass 核心軟體 v1.7 或更新版本。 + 安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 2.7 版。 + Greengrass 群組中的[本機裝置資源](access-local-resources.md)，指向目標序列連接埠。 **注意** 在您部署此連接器之前，建議您設定序列埠並驗證是否可對該序列埠進行讀取和寫入。 ------ ## 連接器參數 此連接器提供下列參數： `BaudRate` 序列連線的傳輸速率。 AWS 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` 讀取操作的逾時 (以秒為單位)。 AWS IoT 主控台中的顯示名稱：**逾時** 必要：`true` 類型：`string` 有效值：`1 - 59` 有效模式： `^([1-9]|[1-5][0-9])$` `SerialPort` 裝置上實體序列埠的絕對路徑。這是指定給本機裝置資源的來源路徑。 AWS IoT 主控台中的顯示名稱：**序列連接埠** 必要：`true` 類型：`string` 有效模式： `[/a-zA-Z0-9_-]+` `SerialPort-ResourceId` 代表實體序列埠的本機裝置資源 ID。 此連接器已授予資源的讀寫存取權。 AWS IoT 主控台中的顯示名稱：**序列連接埠資源** 必要：`true` 類型：`string` 有效模式： `[a-zA-Z0-9_-]+` `PollingRead` 設定讀取模式：輪詢讀取或隨需讀取。 + 對於輪詢讀取模式，指定 `true`。在此模式中，需要 `PollingInterval`、`PollingReadType` 和 `PollingReadLength` 屬性。 + 對於隨需讀取模式，指定 `false`。在這個模式下，類型和長度值是在讀取請求中指定。 在 AWS IoT 主控台中顯示名稱：**讀取模式** 必要：`true` 類型：`string` 有效值：`true, false` 有效模式： `^([Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee])$` `PollingReadLength` 在每個輪詢讀取操作中讀取的資料長度 (以位元組為單位)。這只適用於使用輪詢讀取模式時。 在 AWS 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` 輪詢讀取的間隔 (以秒為單位)。這只適用於使用輪詢讀取模式時。 在 AWS IoT 主控台中顯示名稱：**輪詢讀取間隔** 必要：`false`。當 `PollingRead` 為 `true` 時，此為必要屬性。 類型：`string` 有效值：1 - 999 有效模式： `^(|[1-9]|[1-9][0-9]|[1-9][0-9][0-9])$` `PollingReadType` 輪詢執行緒讀取的資料類型。這只適用於使用輪詢讀取模式時。 在 AWS 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)。 AWS 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)。 AWS IoT 主控台中的顯示名稱：**軟體流程控制** 必要：`false` 類型：`string` 有效值：`true, false` 有效模式： `^(|[Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee])$` `Parity` 序列埠的同位。預設值為 `N`。如需詳細資訊，請參閱[同位](https://en.wikipedia.org/wiki/Serial_port#Parity)。 AWS IoT 主控台中的顯示名稱：**序列連接埠同位** 必要：`false` 類型：`string` 有效值：`N, E, O, S, M` 有效模式： `^(|[NEOSMneosm])$` ### 建立範例連接器 (AWS CLI) 下列 CLI 命令`ConnectorDefinition`會使用包含序列串流連接器的初始版本來建立 。它將連接器設定為輪詢讀取模式。 ``` 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" } } ] }' ``` 在 AWS 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 執行期，則可以建立從 Python3.x 到 Python 3.7 的符號連結。 [連接器入門 (主控台)](connectors-console.md) 和 [連接器入門 (CLI)](connectors-cli.md) 主題包含詳細步驟，說明如何設定和部署範例 Twilio 通知連接器。 1. 確定您符合連接器的[要求](#serial-stream-connector-req)。 1. 建立並發佈 Lambda 函數，將輸入資料傳送至連接器。 將[範例程式碼](#serial-stream-connector-usage-example)儲存為 PY 檔案。下載並解壓縮[AWS IoT Greengrass 適用於 Python 的 Core SDK](lambda-functions.md#lambda-sdks-core)。然後，建立在根層級包含 PY 檔案和 `greengrasssdk` 資料夾的 zip 套件。此 zip 套件是您上傳至 的部署套件 AWS Lambda。 建立 Python 3.7 Lambda 函數後，發佈函數版本並建立別名。 1. 設定 Greengrass 群組。 1. 依別名新增 Lambda 函數 （建議）。將 Lambda 生命週期設定為長期 （或在 CLI `"Pinned": true`中）。 1. 新增必要的本機裝置資源，並授予 Lambda 函數的讀取/寫入存取權。 1. 將連接器新增至群組並設定其[參數](#serial-stream-connector-param)。 1. 將訂閱新增至群組，允許連接器在支援主題篩選條件上接收[輸入資料](#serial-stream-connector-data-input)並傳送[輸出資料](#serial-stream-connector-data-output)。 + 將 Lambda 函數設定為來源，將連接器設定為目標，並使用支援的輸入主題篩選條件。 + 將連接器設為來源、將 AWS IoT Core 設為目標，並使用支援的輸出主題篩選條件。您可以使用此訂閱在 AWS IoT 主控台中檢視狀態訊息。 1. 部署群組。 1. 在 AWS 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 ``` ## 授權 序列串流連接器包含下列第三方軟體/授權： + [pyserial](https://github.com/pyserial/pyserial)/BSD 此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。 ## 變更記錄 下表說明每個版本的連接器的變更。 | 版本 | 變更 | | --- | --- | | 3 | 將 Lambda 執行時間升級至 Python 3.7，這會變更執行時間需求。 | | 2 | 更新連接器 ARN 以進行 AWS 區域 支援。 | | 1 | 初始版本。 | Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。 ## 另請參閱 + [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md) + [Greengrass 連接器入門 (主控台)](connectors-console.md) + [Greengrass 連接器入門 (CLI)](connectors-cli.md)