Amazon IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the Amazon IoT Greengrass V1 maintenance policy. After this date, Amazon IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on Amazon IoT Greengrass V1 won't be disrupted and will continue to operate and to connect to the cloud. We strongly recommend that you migrate to Amazon IoT Greengrass Version 2, which adds significant new features and support for additional platforms.
Serial Stream connector
Warning
This connector has moved into the extended life phase, and Amazon IoT Greengrass won't release updates that provide features, enhancements to existing features, security patches, or bug fixes. For more information, see Amazon IoT Greengrass Version 1 maintenance policy.
The Serial Stream connector reads and writes to a serial port on an Amazon IoT Greengrass core device.
This connector supports two modes of operation:
Read-On-Demand. Receives read and write requests on MQTT topics and publishes the response of the read operation or the status of the write operation.
Polling-Read. Reads from the serial port at regular intervals. This mode also supports Read-On-Demand requests.
Note
Read requests are limited to a maximum read length of 63994 bytes. Write requests are limited to a maximum data length of 128000 bytes.
This connector has the following versions.
Version |
ARN |
---|---|
3 |
|
2 |
|
1 |
|
For information about version changes, see the Changelog.
Requirements
This connector has the following requirements:
Connector Parameters
This connector provides the following parameters:
BaudRate
-
The baud rate of the serial connection.
Display name in the Amazon IoT console: Baud rate
Required:
true
Type:
string
Valid values:
110, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 56000, 57600, 115200, 230400
Valid pattern:
^110$|^300$|^600$|^1200$|^2400$|^4800$|^9600$|^14400$|^19200$|^28800$|^38400$|^56000$|^57600$|^115200$|^230400$
Timeout
-
The timeout (in seconds) for a read operation.
Display name in the Amazon IoT console: Timeout
Required:
true
Type:
string
Valid values:
1 - 59
Valid pattern:
^([1-9]|[1-5][0-9])$
SerialPort
-
The absolute path to the physical serial port on the device. This is the source path that's specified for the local device resource.
Display name in the Amazon IoT console: Serial port
Required:
true
Type:
string
Valid pattern:
[/a-zA-Z0-9_-]+
SerialPort-ResourceId
-
The ID of the local device resource that represents the physical serial port.
Note
This connector is granted read-write access to the resource.
Display name in the Amazon IoT console: Serial port resource
Required:
true
Type:
string
Valid pattern:
[a-zA-Z0-9_-]+
PollingRead
-
Sets the read mode: Polling-Read or Read-On-Demand.
For Polling-Read mode, specify
true
. In this mode, thePollingInterval
,PollingReadType
, andPollingReadLength
properties are required.For Read-On-Demand mode, specify
false
. In this mode, the type and length values are specified in the read request.
Display name in the Amazon IoT console: Read mode
Required:
true
Type:
string
Valid values:
true, false
Valid pattern:
^([Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee])$
PollingReadLength
-
The length of data (in bytes) to read in each polling read operation. This applies only when using Polling-Read mode.
Display name in the Amazon IoT console: Polling read length
Required:
false
. This property is required whenPollingRead
istrue
.Type:
string
Valid pattern:
^(|[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
-
The interval (in seconds) at which the polling read takes place. This applies only when using Polling-Read mode.
Display name in the Amazon IoT console: Polling read interval
Required:
false
. This property is required whenPollingRead
istrue
.Type:
string
Valid values: 1 - 999
Valid pattern:
^(|[1-9]|[1-9][0-9]|[1-9][0-9][0-9])$
PollingReadType
-
The type of data that the polling thread reads. This applies only when using Polling-Read mode.
Display name in the Amazon IoT console: Polling read type
Required:
false
. This property is required whenPollingRead
istrue
.Type:
string
Valid values:
ascii, hex
Valid pattern:
^(|[Aa][Ss][Cc][Ii][Ii]|[Hh][Ee][Xx])$
RtsCts
-
Indicates whether to enable the RTS/CTS flow control. The default value is
false
. For more information, see RTS, CTS, and RTR. Display name in the Amazon IoT console: RTS/CTS flow control
Required:
false
Type:
string
Valid values:
true, false
Valid pattern:
^(|[Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee])$
XonXoff
-
Indicates whether to enable the software flow control. The default value is
false
. For more information, see Software flow control. Display name in the Amazon IoT console: Software flow control
Required:
false
Type:
string
Valid values:
true, false
Valid pattern:
^(|[Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee])$
Parity
-
The parity of the serial port. The default value is
N
. For more information, see Parity. Display name in the Amazon IoT console: Serial port parity
Required:
false
Type:
string
Valid values:
N, E, O, S, M
Valid pattern:
^(|[NEOSMneosm])$
Create Connector Example (Amazon CLI)
The following CLI command creates a ConnectorDefinition
with an initial version that contains the Serial Stream connector.
It configures the connector for Polling-Read mode.
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MySerialStreamConnector", "ConnectorArn": "arn:aws-cn: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" } } ] }'
In the Amazon IoT Greengrass console, you can add a connector from the group's Connectors page. For more information, see Getting started with Greengrass connectors (console).
Input data
This connector accepts read or write requests for serial ports on two MQTT topics. Input messages must be in JSON format.
-
Read requests on the
serial/+/read/#
topic. -
Write requests on the
serial/+/write/#
topic.
To publish to these topics, replace the +
wildcard with the core thing name and #
wildcard with
the path to the serial port. For example:
serial/
core-thing-name
/read/dev/serial-port
- Topic filter:
serial/+/read/#
-
Use this topic to send on-demand read requests to a serial pin. Read requests are limited to a maximum read length of 63994 bytes.
- Message properties
-
readLength
-
The length of data to read from the serial port.
Required:
true
Type:
string
Valid pattern:
^[1-9][0-9]*$
type
-
The type of data to read.
Required:
true
Type:
string
Valid values:
ascii, hex
Valid pattern:
(?i)^(ascii|hex)$
id
-
An arbitrary ID for the request. This property is used to map an input request to an output response.
Required:
false
Type:
string
Valid pattern:
.+
- Example input
-
{ "readLength": "30", "type": "ascii", "id": "abc123" }
- Topic filter:
serial/+/write/#
-
Use this topic to send write requests to a serial pin. Write requests are limited to a maximum data length of 128000 bytes.
- Message properties
-
data
-
The string to write to the serial port.
Required:
true
Type:
string
Valid pattern:
^[1-9][0-9]*$
type
-
The type of data to read.
Required:
true
Type:
string
Valid values:
ascii, hex
Valid pattern:
^(ascii|hex|ASCII|HEX)$
id
-
An arbitrary ID for the request. This property is used to map an input request to an output response.
Required:
false
Type:
string
Valid pattern:
.+
- Example input: ASCII request
-
{ "data": "
random serial data
", "type": "ascii", "id": "abc123" } - Example input: hex request
-
{ "data": "
base64 encoded data
", "type": "hex", "id": "abc123" }
Output data
The connector publishes output data on two topics:
-
Status information from the connector on the
serial/+/status/#
topic. -
Responses from read requests on the
serial/+/read_response/#
topic.
When publishing to this topic, the connector replaces the +
wildcard with the core thing name and #
wildcard with the path to the serial port. For example:
serial/
core-thing-name
/status/dev/serial-port
- Topic filter:
serial/+/status/#
-
Use this topic to listen for the status of read and write requests. If an
id
property is included it the request, it's returned in the response.- Example output: Success
-
{ "response": { "status": "success" }, "id": "abc123" }
- Example output: Failure
-
A failure response includes an
error_message
property that describes the error or timeout encountered while performing the read or write operation.{ "response": { "status": "fail", "error_message": "Could not write to port" }, "id": "abc123" }
- Topic filter:
serial/+/read_response/#
-
Use this topic to receive response data from a read operation. The response data is Base64 encoded if the type is
hex
.- Example output
-
{ "data": "
output of serial read operation
" "id": "abc123" }
Usage Example
Use the following high-level steps to set up an example Python 3.7 Lambda function that you can use to try out the connector.
Note
-
If you use other Python runtimes, you can create a symlink from Python3.x to Python 3.7.
-
The Get started with connectors (console) and Get started with connectors (CLI) topics contain detailed steps that show you how to configure and deploy an example Twilio Notifications connector.
Make sure you meet the requirements for the connector.
-
Create and publish a Lambda function that sends input data to the connector.
Save the example code as a PY file. Download and unzip the Amazon IoT Greengrass Core SDK for Python. Then, create a zip package that contains the PY file and the
greengrasssdk
folder at the root level. This zip package is the deployment package that you upload to Amazon Lambda.After you create the Python 3.7 Lambda function, publish a function version and create an alias.
-
Configure your Greengrass group.
-
Add the Lambda function by its alias (recommended). Configure the Lambda lifecycle as long-lived (or
"Pinned": true
in the CLI). -
Add the required local device resource and grant read/write access to the Lambda function.
-
Add the connector to your group and configure its parameters.
-
Add subscriptions to the group that allow the connector to receive input data and send output data on supported topic filters.
Set the Lambda function as the source, the connector as the target, and use a supported input topic filter.
Set the connector as the source, Amazon IoT Core as the target, and use a supported output topic filter. You use this subscription to view status messages in the Amazon IoT console.
-
-
Deploy the group.
-
In the Amazon IoT console, on the Test page, subscribe to the output data topic to view status messages from the connector. The example Lambda function is long-lived and starts sending messages immediately after the group is deployed.
When you're finished testing, you can set the Lambda lifecycle to on-demand (or
"Pinned": false
in the CLI) and deploy the group. This stops the function from sending messages.
Example
The following example Lambda function sends an input message to the connector.
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
Licenses
The Serial Stream connector includes the following third-party software/licensing:
pyserial
/BSD
This connector is released under the
Greengrass Core Software License Agreement
Changelog
The following table describes the changes in each version of the connector.
Version |
Changes |
---|---|
3 |
Upgraded the Lambda runtime to Python 3.7, which changes the runtime requirement. |
2 |
Updated connector ARN for Amazon Web Services Region support. |
1 |
Initial release. |
A Greengrass group can contain only one version of the connector at a time. For information about upgrading a connector version, see Upgrading connector versions.