Package: awsgreengrasspubsubsdk
AWS IoT Greengrass PubSub SDK for PythonThis document provides information about the AWS IoT Greengrass PubSub SDK for Python.If you have any issues or feature requests, please file an issue or pull request.Note:This is a library based implementation and replacement for the AWS IoT Greengrass PubSub Framework previoulsy hosted in this repository.OverviewThe AWS IoT Greengrass PubSub SDK for Python provides an IoT PubSub application architecture delivered as a Python library to simplify and accelerate development of distributed IoT applications built on AWS IoT Greengrass Components. The SDK abstracts the AWS IoT Greengrass IPC and MQTT PubSub functionality and uses a data driven message format to route PubSub messages to user defined call-backs. This provides a Low/No-Code PubSub messaging service without the common design dependencies of distributed IoT applications.For more details see the AWS IoT Greengrass PubSub SDK:Developer GuideAPI DocsSamplesDetailed Deployment WorkshopGetting StartedThe easiest way to get started is to build and deploy the AWS IoT Greengrass PubSub SDK component template described in theSamplesdirectory.For new users just starting out with AWS IoT Greengrass or those that want to see a more detailed example of using the SDK to deploy multiple components that we recommend running through the workshopBuild a Distributed IoT Application with the AWS IoT Greengrass PubSub SDKwhere you build a Smart Factory IoT application using the AWS IoT Greengrass PubSub SDK.InstallationMinimum RequirementsPython 3.6+Install via an AWS IoT Greengrass Custom Component RecipeTo configure the AWS IoT Greengrass PubSub SDK to deploy with an AWS IoT Greengrass Component, update the recipe Lifecycle / Install event as per below:"Lifecycle": {
  "Install" : {
    "Timeout" : 300,
    "Script" : "python3 -m pip install awsgreengrasspubsubsdk"
  },
  .....A full example of this is given in theGreengrass component recipe exampleInstalling ManuallyThe AWS IoT Greengrass PubSub SDK provides functionality within an AWS IoT Greengrass component. It only has context within that framework and so for production solutions, its preferred to deploy the SDK with the component as described in the previous example. Manual installation examples given below are intended for development machines.Note: If installing manually, do so as the user that will own the Greengrass component process (i.e: gcc_user by default).Install from PyPIpython3 -m pip install awsgreengrasspubsubsdkInstall from sourcegit clone https://github.com/awslabs/aws-greengrass-labs-iot-pubsub-sdk-for-python.git
python3 -m pip install ./aws-greengrass-pubsub-sdk-for-pythonUsage and Code ExamplesOnce the AWS IoT Greengrass PubSub SDK is deployed with an AWS IoT Greengrass Component, you can route messages to your application logic via user defined Message Handlers that you register with the SDKA production ready AWS IoT Greengrass component template and more detailed examples are provided in theSamplesdirectory.The SDK defines the following required message format (with more details provided in theDeveloper Guide{
  "sdk_version": "0.1.4",
  "message_id": "20220403170948930231",
  "status": 200,
  "route": "MyPubSubMessageHandler.pubsub_message_route_target",
  "message": {
    "my-message-param01": "param01",
    "my-message-param02": "param02"
  }
}The SDK will route received PubSub messages to a user defined message handler class and method as provided in the messageroutevalue. The message route value is aClass.Methodnamespace representation of the desired message route target.Using this approach, the AWS IoT Greengrass PubSub SDK routes PubSub messages to your application logic in easily defined message callbacks.Initialising the SDK and Message Handler ClassesAdd a method that will be the route of last resort for received PubSub messages and the expected message parameters.def default_message_handler(self, protocol, topic, message_id, status, route, message):
   
   # Process messages without a registered handler router target
   log.error('Received message to unknown route / message handler: {} - message: {}'.format(route, message)))Initialise the AWS IoT Greengrass PubSub SDK Client# Import the AWS IoT Greengrass PubSub SDK
from awsgreengrasspubsubsdk.pubsub_client import AwsGreengrassPubSubSdkClient

# Declare the PubSub Base topic, this is used to build the default Ingress and Egress PubSub topics.
pubsub_base_topic = 'com.my_greengrass.application'

# Initilise the AwsGreengrassPubSubSdkClient with the pubsub_base_topic and default_message_handler
pubsub_client = AwsGreengrassPubSubSdkClient(pubsub_base_topic, default_message_handler )Create one or more user defined message handler class/es with named functions to route PubSub messages with the expected parameters. This method allows easy separation of message processing functionality within your application.class MyPubSubMessageHandler():

    def pubsub_message_route_target(self, protocol, topic, message_id, status, route, message):
        
        # Process messages with route = 'MyPubSubMessageHandler.pubsub_message_route_target'
        log.info('MyPubSubMessageHandler.pubsub_message_route_target received message: {}'.format(message))Register the message handler class/es with the PubSub SDK Client with theregister_message_handlercall.my_pubsub_message_handler = MyPubSubMessageHandler()
pubsub_client.register_message_handler(my_pubsub_message_handler)Activate the IPC and / or MQTT Protocols in the SDK:# Activate IPC Protocol
pubsub_client.activate_ipc_pubsub()

# Acticate MQTT Protocol
pubsub_client.activate_mqtt_pubsub()Complete!On completion of the above and once successfully deployed, your AWS IoT Greengrass component will listen on the default Ingress topic(base-pubsub-topic/THING_NAME/ingress)and any other user defined topics. The SDK will begin routing PubSub messages to your registered Message Handler classes as per the messageroutevalue. As describe above, any message received on the SDK subscribed topic with valueroute = MyPubSubMessageHandler.pubsub_message_route_targetwill be automatically forwarded to the method provided in the example.Note:If the route value does not match any route target methods, the message will be forwarded to the default_message_handler class.Subscribing to Custom TopicsThe SDK provides a programmatic means of subscribing to user defined topics. You can subscribe to any topic that is permitted by the access policy provided in the component recipe.my_topic = 'my/interesting/topic'

# Subscribe to topic on IPC
pubsub_client.subscribe_to_topic('ipc', topic)

# Subscribe to topic on MQTT
pubsub_client.subscribe_to_topic('mqtt', topic)

# Subscribe to topic on IPC and MQTT
pubsub_client.subscribe_to_topic('ipc_mqtt', topic)If the protocol (IPC or MQTT) is activated, the SDK will subscribe to the topic and begin routig messages immediatly. If not, the subscription request will be stored and actioned when the selected protocol is activated.Publishing Message to PubSubThe SDK provides a message formatter class to ensure consistent messages. See themessage_formatterAPI Docs for more detail.# Initialise the PubSubMessageFormatter
from awsgreengrasspubsubsdk.message_formatter import PubSubMessageFormatter
message_formatter = PubSubMessageFormatter()

# Use the message formatter to create a well-formatted PubSub SDK response message
receive_route = 'MyPubSubMessageHandler.pubsub_message_response'
my_message = {
    "my-message-param01": "param01",
    "my-message-param02": "param02"
}
# Defaults will be applied for parameteres not provided here. See API Docs.
sdk_format_msg = message_formatter.get_message(route=receive_route, message=my_message)

## Publish the message to IPC and MQTT. 
pubsub_client.publish_message('ipc_mqtt', sdk_format_msg)Installation IssuesThe AWS IoT Greengrass PubSub SDK (awsgreengrasspubsubsdk) installsawsiotsdkas a dependancy with the following listedInstallation issues.If running the AWS IoT Greengrass component with root privileges, you will need to install in a python virtual environment by replacing the component recipe install policy with the below:"Install" : {
          "Timeout" : 300,
          "Script" : "python3 -m venv pubsubsdk; . pubsubsdk/bin/activate; pip3 install --upgrade pip; python3 -m pip install awsgreengrasspubsubsdk"
        }SamplesA complete production ready AWS IoT Greengrass component template is provided in theSamplesdirectory.Getting HelpThe best way to interact with our team is through GitHub. You canopen an issuefor guidance, bug reports, or feature requests.Please make sure to check out our resources before opening an issue:Developer GuideAPI DocsAWS IoT Greengrass PubSub SDK Deployment WorkshopAWS IoT Greengrass V2 Developer GuideAWS IoT Core DocumentationAWS Dev BlogGiving Feedback and ContributionsWe need your help in making this SDK great. Please participate in the community and contribute to this effort by submitting issues, participating in discussion forums and submitting pull requests through the following channels.Contributions GuidelinesSubmitIssues, Feature Requests or BugsAWS IoT Core ResourcesAWS IoT Core DocumentationAWS IoT Developer Guide(source)AWS Dev BlogSecuritySeeCONTRIBUTINGfor more information.LicenseThis library is licensed under the MIT-0 License. See the LICENSE file.