{"id":13725471,"url":"https://github.com/aws/aws-iot-device-sdk-python","last_synced_at":"2025-04-10T02:13:52.755Z","repository":{"id":9176965,"uuid":"60723336","full_name":"aws/aws-iot-device-sdk-python","owner":"aws","description":"SDK for connecting to AWS IoT from a device using Python. ","archived":false,"fork":false,"pushed_at":"2024-11-26T20:02:49.000Z","size":332,"stargazers_count":686,"open_issues_count":1,"forks_count":423,"subscribers_count":58,"default_branch":"master","last_synced_at":"2025-04-10T02:13:47.283Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-06-08T19:06:12.000Z","updated_at":"2025-03-25T08:47:51.000Z","dependencies_parsed_at":"2024-04-22T09:02:27.827Z","dependency_job_id":"8b041f55-9a86-4397-b133-36613db98775","html_url":"https://github.com/aws/aws-iot-device-sdk-python","commit_stats":{"total_commits":103,"total_committers":18,"mean_commits":5.722222222222222,"dds":"0.49514563106796117","last_synced_commit":"567e3dbd0e027e990e4ecfc423b98629e13d37f3"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-iot-device-sdk-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-iot-device-sdk-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-iot-device-sdk-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-iot-device-sdk-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws","download_url":"https://codeload.github.com/aws/aws-iot-device-sdk-python/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248142902,"owners_count":21054671,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T01:02:24.387Z","updated_at":"2025-04-10T02:13:52.727Z","avatar_url":"https://github.com/aws.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"New Version Available\t\n=============================\nA new AWS IoT Device SDK is [now available](https://github.com/awslabs/aws-iot-device-sdk-python-v2). It is a complete rework, built to improve reliability, performance, and security. We invite your feedback!\t\n\nThis SDK will no longer receive feature updates, but will receive security updates.\t\n\nAWS IoT Device SDK for Python\n=============================\n\nThe AWS IoT Device SDK for Python allows developers to write Python\nscript to use their devices to access the AWS IoT platform through `MQTT or\nMQTT over the  WebSocket\nprotocol \u003chttp://docs.aws.amazon.com/iot/latest/developerguide/protocols.html\u003e`__.\nBy connecting their devices to AWS IoT, users can securely work with\nthe message broker, rules, and the device shadow (sometimes referred to as a thing shadow) provided by AWS IoT and\nwith other AWS services like AWS Lambda, Amazon Kinesis, Amazon S3, and more.\n\n-  Overview_\n-  Installation_\n-  `Use the SDK`_\n-  `Key Features`_\n-  Examples_\n-  `API Documentation`_\n-  License_\n-  Support_\n\n--------------\n\n.. _Overview:\n\nOverview\n~~~~~~~~\n\nThis document provides instructions for installing and configuring\nthe AWS IoT Device SDK for Python. It includes examples demonstrating the\nuse of the SDK APIs.\n\nMQTT Connections\n________________\n\nThe SDK is built on top of a modified `Paho MQTT Python client\nlibrary \u003chttps://eclipse.org/paho/clients/python/\u003e`__. Developers can choose from two\ntypes of connections to connect to AWS\nIoT:\n\n-  MQTT (over TLS 1.2) with X.509 certificate-based mutual\n   authentication.\n-  MQTT over the WebSocket protocol with AWS Signature Version 4 authentication.\n-  MQTT (over TLS 1.2) with X.509 certificate-based mutual authentication with TLS ALPN extension.\n\nFor MQTT over TLS (port 8883 and port 443), a valid certificate and a private key are\nrequired for authentication. For MQTT over the WebSocket protocol (port 443),\na valid AWS Identity and Access Management (IAM) access key ID and secret access key pair are required for\nauthentication.\n\nDevice Shadow\n_____________\n\nA device shadow, or thing shadow, is a JSON document that is used to\nstore and retrieve current state information for a thing (device, app,\nand so on). A shadow can be created and maintained for each thing or device so that its state can be get and set\nregardless of whether the thing or device is connected to the Internet. The\nSDK implements the protocol for applications to retrieve, update, and\ndelete shadow documents. The SDK allows operations on shadow documents\nof single or multiple shadow instances in one MQTT connection. The SDK\nalso allows the use of the same connection for shadow operations and non-shadow, simple MQTT operations.\n\n.. _Installation:\n\nInstallation\n~~~~~~~~~~~~\n\nRequirements\n____________________\n\n-  Python3.8+.  The SDK has worked for older Python versions in the past, but they are no longer formally supported.  Over time, expect the minimum Python version to loosely track the minimum non-end-of-life version.\nInstall from pip\n________________\n\n\n.. code-block:: sh\n\n    pip install AWSIoTPythonSDK\n\nBuild from source\n_________________\n\n\n.. code-block:: sh\n\n    git clone https://github.com/aws/aws-iot-device-sdk-python.git\n    cd aws-iot-device-sdk-python\n    python setup.py install\n\nDownload the zip file\n_____________________\n\n\nThe SDK zip file is available `here \u003chttps://s3.amazonaws.com/aws-iot-device-sdk-python/aws-iot-device-sdk-python-latest.zip\u003e`__. Unzip the package and install the SDK like this:\n\n.. code-block:: python\n\n    python setup.py install\n\n.. _Use_the_SDK:\n\nUse the SDK\n~~~~~~~~~~~\n\nCollection of Metrics\n_____________________\n\nBeginning with Release v1.3.0 of the SDK, AWS collects usage metrics indicating which language and version of the SDK\nis being used. This feature is enabled by default and allows us to prioritize our resources towards addressing issues\nfaster in SDKs that see the most and is an important data point. However, we do understand that not all customers would\nwant to report this data. In that case, the sending of usage metrics can be easily disabled by the user using the\ncorresponding API:\n\n.. code-block:: python\n\n    # AWS IoT MQTT Client\n    AWSIoTPythonSDK.MQTTLib.AWSIoTMQTTClient.enableMetricsCollection()\n    AWSIoTPythonSDK.MQTTLib.AWSIoTMQTTClient.disableMetricsCollection()\n    # AWS IoT MQTT Shadow Client\n    AWSIoTPythonSDK.MQTTLib.AWSIoTMQTTShadowClient.enableMetricsCollection()\n    AWSIoTPythonSDK.MQTTLib.AWSIoTMQTTShadowClient.disableMetricsCollection()\n\nCredentials\n___________\n\nThe SDK supports two types of credentials that correspond to the two connection \ntypes:\n\n-  X.509 certificate\n\n   For the certificate-based mutual authentication connection\n   type.\n   Download the `AWS IoT root\n   CA \u003chttps://docs.aws.amazon.com/iot/latest/developerguide/managing-device-certs.html#server-authentication\u003e`__.\n   Use the AWS IoT console to create and download the certificate and private key. You must specify the location of these files \n   when you initialize the client.\n\n-  IAM credentials\n\n   For the Websocket with Signature Version 4 authentication type. You will need IAM credentials: an access key ID, a secret access\n   key, and an optional session token. You must  also\n   download the `AWS IoT root\n   CA \u003chttps://docs.aws.amazon.com/iot/latest/developerguide/managing-device-certs.html#server-authentication\u003e`__.\n   You can specify the IAM credentials by:\n\n   -  Passing method parameters\n\n      The SDK will first call the following method to check if there is any input for a custom IAM\n      credentials configuration:\n\n      .. code-block:: python\n\n          # AWS IoT MQTT Client\n          AWSIoTPythonSDK.MQTTLib.AWSIoTMQTTClient.configureIAMCredentials(obtainedAccessKeyID, obtainedSecretAccessKey, obtainedSessionToken)        \n          # AWS IoT MQTT Shadow Client\n          AWSIoTPythonSDK.MQTTLib.AWSIoTMQTTShadowClient.configureIAMCredentials(obtainedAccessKeyID, obtainedSecretAccessKey, obtainedSessionToken)\n\n      Note: We do not recommend hard-coding credentials in a custom script. You can use `Amazon Cognito Identity\n      \u003chttps://aws.amazon.com/cognito/\u003e`__ or another credential\n      provider.\n\n   -  Exporting environment variables\n\n      If there is no custom configuration through method calls, the SDK\n      will then check these environment variables for credentials:\n\n      ``AWS_ACCESS_KEY_ID``\n\n      The access key for your AWS account.\n\n      ``AWS_SECRET_ACCESS_KEY``\n\n      The secret key for your AWS account.\n\n      ``AWS_SESSION_TOKEN``\n      \n      The session key for your AWS account. This is required only when\n      you are using temporary credentials. For more information, see\n      `here \u003chttp://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html\u003e`__.\n\n      You can set your IAM credentials as environment variables by\n      using the preconfigured names. For Unix systems, you can do the\n      following:\n\n      .. code-block:: sh\n\n          export AWS_ACCESS_KEY_ID=\u003cyour aws access key id string\u003e\n          export AWS_SECRET_ACCESS_KEY=\u003cyour aws secret access key string\u003e\n          export AWS_SESSION_TOKEN=\u003cyour aws session token string\u003e\n\n      For Windows, open ``Control Panel`` and choose ``System``. In\n      ``Advanced system settings`` choose ``Environment Variables`` and\n      then configure the required environment variables.\n\n   -  Configuring shared credentials file\n\n      If there are no such environment variables specified, the SDK\n      will check the **default** section for a shared\n      credentials file (in Unix, ``~/.aws/credentials`` and in Windows, ``%UserProfile%\\.aws\\credentials``) as follows:\n\n      .. code-block:: sh\n\n          [default]\n          aws_access_key_id=foo\n          aws_secret_access_key=bar\n          aws_session_token=baz\n\n      You can use the AWS CLI to configure the shared credentials file \u003chttp://aws.amazon.com/cli/\u003e`__:\n\n      .. code-block:: sh\n\n          aws configure\n\nAWSIoTMQTTClient\n________________\n\nThis is the client class used for plain MQTT communication with AWS IoT.\nYou can initialize and configure the client like this:\n\n.. code-block:: python\n\n    # Import SDK packages\n    from AWSIoTPythonSDK.MQTTLib import AWSIoTMQTTClient\n\n    # For certificate based connection\n    myMQTTClient = AWSIoTMQTTClient(\"myClientID\")\n    # For Websocket connection\n    # myMQTTClient = AWSIoTMQTTClient(\"myClientID\", useWebsocket=True)\n    # Configurations\n    # For TLS mutual authentication\n    myMQTTClient.configureEndpoint(\"YOUR.ENDPOINT\", 8883)\n    # For Websocket\n    # myMQTTClient.configureEndpoint(\"YOUR.ENDPOINT\", 443)\n    # For TLS mutual authentication with TLS ALPN extension\n    # myMQTTClient.configureEndpoint(\"YOUR.ENDPOINT\", 443)\n    myMQTTClient.configureCredentials(\"YOUR/ROOT/CA/PATH\", \"PRIVATE/KEY/PATH\", \"CERTIFICATE/PATH\")\n    # For Websocket, we only need to configure the root CA\n    # myMQTTClient.configureCredentials(\"YOUR/ROOT/CA/PATH\")\n    myMQTTClient.configureOfflinePublishQueueing(-1)  # Infinite offline Publish queueing\n    myMQTTClient.configureDrainingFrequency(2)  # Draining: 2 Hz\n    myMQTTClient.configureConnectDisconnectTimeout(10)  # 10 sec\n    myMQTTClient.configureMQTTOperationTimeout(5)  # 5 sec\n    ...\n\nFor basic MQTT operations, your script will look like this:\n\n.. code-block:: python\n\n    ...\n    myMQTTClient.connect()\n    myMQTTClient.publish(\"myTopic\", \"myPayload\", 0)\n    myMQTTClient.subscribe(\"myTopic\", 1, customCallback)\n    myMQTTClient.unsubscribe(\"myTopic\")\n    myMQTTClient.disconnect()\n    ...\n\nAWSIoTShadowClient\n__________________\n\nThis is the client class used for device shadow operations with AWS IoT.\nYou can initialize and configure the client like this:\n\n.. code-block:: python\n\n    from AWSIoTPythonSDK.MQTTLib import AWSIoTMQTTShadowClient\n\n    # For certificate based connection\n    myShadowClient = AWSIoTMQTTShadowClient(\"myClientID\")\n    # For Websocket connection\n    # myMQTTClient = AWSIoTMQTTClient(\"myClientID\", useWebsocket=True)\n    # Configurations\n    # For TLS mutual authentication\n    myShadowClient.configureEndpoint(\"YOUR.ENDPOINT\", 8883)\n    # For Websocket\n    # myShadowClient.configureEndpoint(\"YOUR.ENDPOINT\", 443)\n    # For TLS mutual authentication with TLS ALPN extension\n    # myShadowClient.configureEndpoint(\"YOUR.ENDPOINT\", 443)\n    myShadowClient.configureCredentials(\"YOUR/ROOT/CA/PATH\", \"PRIVATE/KEY/PATH\", \"CERTIFICATE/PATH\")\n    # For Websocket, we only need to configure the root CA\n    # myShadowClient.configureCredentials(\"YOUR/ROOT/CA/PATH\")\n    myShadowClient.configureConnectDisconnectTimeout(10)  # 10 sec\n    myShadowClient.configureMQTTOperationTimeout(5)  # 5 sec\n    ...\n\nFor shadow operations, your script will look like this:\n\n.. code-block:: python\n\n    ...\n    myShadowClient.connect()\n    # Create a device shadow instance using persistent subscription\n    myDeviceShadow = myShadowClient.createShadowHandlerWithName(\"Bot\", True)\n    # Shadow operations\n    myDeviceShadow.shadowGet(customCallback, 5)\n    myDeviceShadow.shadowUpdate(myJSONPayload, customCallback, 5)\n    myDeviceShadow.shadowDelete(customCallback, 5)\n    myDeviceShadow.shadowRegisterDeltaCallback(customCallback)\n    myDeviceShadow.shadowUnregisterDeltaCallback()\n    ...\n\nYou can also retrieve the MQTTClient(MQTT connection) to perform plain\nMQTT operations along with shadow operations:\n\n.. code-block:: python\n\n    myMQTTClient = myShadowClient.getMQTTConnection()\n    myMQTTClient.publish(\"plainMQTTTopic\", \"Payload\", 1)\n\nAWSIoTMQTTThingJobsClient\n__________________\n\nThis is the client class used for jobs operations with AWS IoT. See docs here:\nhttps://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html\nYou can initialize and configure the client like this:\n\n.. code-block:: python\n\n    from AWSIoTPythonSDK.MQTTLib import AWSIoTMQTTThingJobsClient\n\n    # For certificate based connection\n    myJobsClient = AWSIoTMQTTThingJobsClient(\"myClientID\", \"myThingName\")\n    # For Websocket connection\n    # myJobsClient = AWSIoTMQTTThingJobsClient(\"myClientID\", \"myThingName\", useWebsocket=True)\n    # Configurations\n    # For TLS mutual authentication\n    myJobsClient.configureEndpoint(\"YOUR.ENDPOINT\", 8883)\n    # For Websocket\n    # myJobsClient.configureEndpoint(\"YOUR.ENDPOINT\", 443)\n    myJobsClient.configureCredentials(\"YOUR/ROOT/CA/PATH\", \"PRIVATE/KEY/PATH\", \"CERTIFICATE/PATH\")\n    # For Websocket, we only need to configure the root CA\n    # myJobsClient.configureCredentials(\"YOUR/ROOT/CA/PATH\")\n    myJobsClient.configureConnectDisconnectTimeout(10)  # 10 sec\n    myJobsClient.configureMQTTOperationTimeout(5)  # 5 sec\n    ...\n\nFor job operations, your script will look like this:\n\n.. code-block:: python\n\n    ...\n    myJobsClient.connect()\n    # Create a subsciption for $notify-next topic\n    myJobsClient.createJobSubscription(notifyNextCallback, jobExecutionTopicType.JOB_NOTIFY_NEXT_TOPIC)\n    # Create a subscription for update-job-execution accepted response topic\n    myJobsClient.createJobSubscription(updateSuccessfulCallback, jobExecutionTopicType.JOB_UPDATE_TOPIC, jobExecutionTopicReplyType.JOB_ACCEPTED_REPLY_TYPE, '+')\n    # Send a message to start the next pending job (if any)\n    myJobsClient.sendJobsStartNext(statusDetailsDict)\n    # Send a message to update a successfully completed job\n    myJobsClient.sendJobsUpdate(jobId, jobExecutionStatus.JOB_EXECUTION_SUCCEEDED, statusDetailsDict)\n    ...\n\nYou can also retrieve the MQTTClient(MQTT connection) to perform plain\nMQTT operations along with shadow operations:\n\n.. code-block:: python\n\n    myMQTTClient = myJobsClient.getMQTTConnection()\n    myMQTTClient.publish(\"plainMQTTTopic\", \"Payload\", 1)\n\nDiscoveryInfoProvider\n_____________________\n\nThis is the client class for device discovery process with AWS IoT Greengrass.\nYou can initialize and configure the client like this:\n\n.. code-block:: python\n\n    from AWSIoTPythonSDK.core.greengrass.discovery.providers import DiscoveryInfoProvider\n\n    discoveryInfoProvider = DiscoveryInfoProvider()\n    discoveryInfoProvider.configureEndpoint(\"YOUR.IOT.ENDPOINT\")\n    discoveryInfoProvider.configureCredentials(\"YOUR/ROOT/CA/PATH\", \"CERTIFICATE/PATH\", \"PRIVATE/KEY/PATH\")\n    discoveryInfoProvider.configureTimeout(10)  # 10 sec\n\nTo perform the discovery process for a Greengrass Aware Device (GGAD) that belongs to a deployed group, your script\nshould look like this:\n\n.. code-block:: python\n\n    discoveryInfo = discoveryInfoProvider.discover(\"myGGADThingName\")\n    # I know nothing about the group/core I want to connect to. I want to iterate through all cores and find out.\n    coreList = discoveryInfo.getAllCores()\n    groupIdCAList = discoveryInfo.getAllCas()  # list([(groupId, ca), ...])\n    # I know nothing about the group/core I want to connect to. I want to iterate through all groups and find out.\n    groupList = discoveryInfo.getAllGroups()\n    # I know exactly which group, which core and which connectivity info I need to connect.\n    connectivityInfo = discoveryInfo.toObjectAtGroupLevel()[\"YOUR_GROUP_ID\"]\n                                    .getCoreConnectivityInfo(\"YOUR_CORE_THING_ARN\")\n                                    .getConnectivityInfo(\"YOUR_CONNECTIVITY_ID\")\n    # Connecting logic follows...\n    ...\n\nFor more information about discovery information access at group/core/connectivity info set level, please refer to the\nAPI documentation for ``AWSIoTPythonSDK.core.greengrass.discovery.models``,\n`Greengrass Discovery documentation \u003chttp://docs.aws.amazon.com/greengrass/latest/developerguide/gg-discover-api.html\u003e`__\nor `Greengrass overall documentation \u003chttp://docs.aws.amazon.com/greengrass/latest/developerguide/what-is-gg.html\u003e`__.\n\n\nSynchronous APIs and Asynchronous APIs\n______________________________________\n\nBeginning with Release v1.2.0, SDK provides asynchronous APIs and enforces synchronous API behaviors for MQTT operations,\nwhich includes:\n- connect/connectAsync\n- disconnect/disconnectAsync\n- publish/publishAsync\n- subscribe/subscribeAsync\n- unsubscribe/unsubscribeAsync\n\n- Asynchronous APIs\nAsynchronous APIs translate the invocation into MQTT packet and forward it to the underneath connection to be sent out.\nThey return immediately once packets are out for delivery, regardless of whether the corresponding ACKs, if any, have\nbeen received. Users can specify their own callbacks for ACK/message (server side PUBLISH) processing for each\nindividual request. These callbacks will be sequentially dispatched and invoked upon the arrival of ACK/message (server\nside PUBLISH) packets.\n\n- Synchronous APIs\nSynchronous API behaviors are enforced by registering blocking ACK callbacks on top of the asynchronous APIs.\nSynchronous APIs wait on their corresponding ACK packets, if there is any, before the invocation returns. For example,\na synchronous QoS1 publish call will wait until it gets its PUBACK back. A synchronous subscribe call will wait until\nit gets its SUBACK back. Users can configure operation time out for synchronous APIs to stop the waiting.\n\nSince callbacks are sequentially dispatched and invoked, calling synchronous APIs within callbacks will deadlock the\nuser application. If users are inclined to utilize the asynchronous mode and perform MQTT operations\nwithin callbacks, asynchronous APIs should be used. For more details, please check out the provided samples at\n``samples/basicPubSub/basicPubSub_APICallInCallback.py``\n\n.. _Key_Features:\n\nKey Features\n~~~~~~~~~~~~\n\nProgressive Reconnect Back Off\n______________________________\n\nWhen a non-client-side disconnect occurs, the SDK will reconnect automatically. The following APIs are provided for configuration:\n\n.. code-block:: python\n\n    # AWS IoT MQTT Client\n    AWSIoTPythonSDK.MQTTLib.AWSIoTMQTTClient.configureAutoReconnectBackoffTime(baseReconnectQuietTimeSecond, maxReconnectQuietTimeSecond, stableConnectionTimeSecond)\n    # AWS IoT MQTT Shadow Client\n    AWSIoTPythonSDK.MQTTLib.AWSIoTMQTTShadowClient.configureAutoReconnectBackoffTime(baseReconnectQuietTimeSecond, maxReconnectQuietTimeSecond, stableConnectionTimeSecond)\n\nThe auto-reconnect occurs with a progressive backoff, which follows this\nmechanism for reconnect backoff time calculation:\n\n    t\\ :sup:`current` = min(2\\ :sup:`n` t\\ :sup:`base`, t\\ :sup:`max`)\n\nwhere t\\ :sup:`current` is the current reconnect backoff time, t\\ :sup:`base` is the base\nreconnect backoff time, t\\ :sup:`max` is the maximum reconnect backoff time.\n\nThe reconnect backoff time will be doubled on disconnect and reconnect\nattempt until it reaches the preconfigured maximum reconnect backoff\ntime. After the connection is stable for over the\n``stableConnectionTime``, the reconnect backoff time will be reset to\nthe ``baseReconnectQuietTime``.\n\nIf no ``configureAutoReconnectBackoffTime`` is called, the following\ndefault configuration for backoff timing will be performed on initialization:\n\n.. code-block:: python\n\n    baseReconnectQuietTimeSecond = 1\n    maxReconnectQuietTimeSecond = 32\n    stableConnectionTimeSecond = 20\n\nOffline Requests Queueing with Draining\n_______________________________________\n\nIf the client is temporarily offline and disconnected due to \nnetwork failure, publish/subscribe/unsubscribe requests will be added to an internal\nqueue until the number of queued-up requests reaches the size limit\nof the queue. This functionality is for plain MQTT operations. Shadow\nclient contains time-sensitive data and is therefore not supported.\n\nThe following API is provided for configuration:\n\n.. code-block:: python\n\n    AWSIoTPythonSDK.MQTTLib.AWSIoTMQTTClient.configureOfflinePublishQueueing(queueSize, dropBehavior)\n\nAfter the queue is full, offline publish/subscribe/unsubscribe requests will be discarded or\nreplaced according to the configuration of the drop behavior:\n\n.. code-block:: python\n\n    # Drop the oldest request in the queue\n    AWSIoTPythonSDK.MQTTLib.DROP_OLDEST = 0\n    # Drop the newest request in the queue\n    AWSIoTPythonSDK.MQTTLib.DROP_NEWEST = 1\n\nLet's say we configure the size of offlinePublishQueue to 5 and we\nhave 7 incoming offline publish requests.\n\nIn a ``DROP_OLDEST`` configuration:\n\n.. code-block:: python\n\n    myClient.configureOfflinePublishQueueing(5, AWSIoTPythonSDK.MQTTLib.DROP_OLDEST);\n\nThe internal queue should be like this when the queue is just full:\n\n.. code-block:: sh\n\n    HEAD ['pub_req1', 'pub_req2', 'pub_req3', 'pub_req4', 'pub_req5']\n\nWhen the 6th and the 7th publish requests are made offline, the internal\nqueue will be like this:\n\n.. code-block:: sh\n\n    HEAD ['pub_req3', 'pub_req4', 'pub_req5', 'pub_req6', 'pub_req7']\n\nBecause the queue is already full, the oldest requests ``pub_req1`` and\n``pub_req2`` are discarded.\n\nIn a ``DROP_NEWEST`` configuration:\n\n.. code-block:: python\n\n    myClient.configureOfflinePublishQueueing(5, AWSIoTPythonSDK.MQTTLib.DROP_NEWEST);\n\nThe internal queue should be like this when the queue is just full:\n\n.. code-block:: sh\n\n    HEAD ['pub_req1', 'pub_req2', 'pub_req3', 'pub_req4', 'pub_req5']\n\nWhen the 6th and the 7th publish requests are made offline, the internal\nqueue will be like this:\n\n.. code-block:: sh\n\n    HEAD ['pub_req1', 'pub_req2', 'pub_req3', 'pub_req4', 'pub_req5']\n\nBecause the queue is already full, the newest requests ``pub_req6`` and\n``pub_req7`` are discarded.\n\nWhen the client is back online, connected, and resubscribed to all topics\nit has previously subscribed to, the draining starts. All requests\nin the offline request queue will be resent at the configured draining\nrate:\n\n.. code-block:: python\n\n    AWSIoTPythonSDK.MQTTLib.AWSIoTMQTTClient.configureDrainingFrequency(frequencyInHz)\n\nIf no ``configOfflinePublishQueue`` or ``configureDrainingFrequency`` is\ncalled, the following default configuration for offline request queueing\nand draining will be performed on the initialization:\n\n.. code-block:: python\n\n    offlinePublishQueueSize = 20\n    dropBehavior = DROP_NEWEST\n    drainingFrequency = 2Hz\n\nBefore the draining process is complete, any new publish/subscribe/unsubscribe request\nwithin this time period will be added to the queue. Therefore, the draining rate\nshould be higher than the normal request rate to avoid an endless\ndraining process after reconnect.\n\nThe disconnect event is detected based on PINGRESP MQTT\npacket loss. Offline request queueing will not be triggered until the\ndisconnect event is detected. Configuring a shorter keep-alive\ninterval allows the client to detect disconnects more quickly. Any QoS0\npublish, subscribe and unsubscribe requests issued after the network failure and before the\ndetection of the PINGRESP loss will be lost.\n\nPersistent/Non-Persistent Subscription\n______________________________________\n\nDevice shadow operations are built on top of the publish/subscribe model\nfor the MQTT protocol, which provides an asynchronous request/response workflow. Shadow operations (Get, Update, Delete) are\nsent as requests to AWS IoT. The registered callback will \nbe executed after a response is returned. In order to receive\nresponses, the client must subscribe to the corresponding shadow\nresponse topics. After the responses are received, the client might want\nto unsubscribe from these response topics to avoid getting unrelated\nresponses for charges for other requests not issued by this client.\n\nThe SDK provides a persistent/non-persistent subscription selection on\nthe initialization of a device shadow. Developers can choose the type of subscription workflow they want to follow.\n\nFor a non-persistent subscription, you will need to create a device\nshadow like this:\n\n.. code-block:: python\n\n    nonPersistentSubShadow = myShadowClient.createShadowHandlerWithName(\"NonPersistentSubShadow\", False)\n\nIn this case, the request to subscribe to accepted/rejected topics will be\nsent on each shadow operation. After a response is returned,\naccepted/rejected topics will be unsubscribed to avoid getting unrelated\nresponses.\n\nFor a persistent subscription, you will need to create a device shadow\nlike this:\n\n.. code-block:: python\n\n    persistentSubShadow = myShadowClient.createShadowHandlerWithName(\"PersistentSubShadow\", True)\n\nIn this case, the request to subscribe to the corresponding\naccepted/rejected topics will be sent on the first shadow operation. For\nexample, on the first call of shadowGet API, the following topics will\nbe subscribed to on the first Get request:\n\n.. code-block:: sh\n\n    $aws/things/PersistentSubShadow/shadow/get/accepted\n    $aws/things/PersistentSubShadow/shadow/get/rejected\n\nBecause it is a persistent subscription, no unsubscribe requests will be\nsent when a response is returned. The SDK client is always listening on\naccepted/rejected topics.\n\nIn all SDK examples, PersistentSubscription is used in consideration of its better performance.\n\nSSL Ciphers Setup\n______________________________________\nIf custom SSL Ciphers are required for the client, they can be set when configuring the client before\nstarting the connection.\n\nTo setup specific SSL Ciphers:\n\n.. code-block:: python\n\n    myAWSIoTMQTTClient.configureCredentials(rootCAPath, privateKeyPath, certificatePath, Ciphers=\"AES128-SHA256\")\n\n\n.. _Examples:\n\nExamples\n~~~~~~~~\n\nBasicPubSub\n___________\n\nThis example demonstrates a simple MQTT publish/subscribe using AWS\nIoT. It first subscribes to a topic and registers a callback to print\nnew messages and then publishes to the same topic in a loop.\nNew messages are printed upon receipt, indicating\nthe callback function has been called.\n\nInstructions\n************\n\nRun the example like this:\n\n.. code-block:: python\n\n    # Certificate based mutual authentication\n    python basicPubSub.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e\n    # MQTT over WebSocket\n    python basicPubSub.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -w\n    # Customize client id and topic\n    python basicPubSub.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e -id \u003cclientId\u003e -t \u003ctopic\u003e\n    # Customize the message\n    python basicPubSub.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e -id \u003cclientId\u003e -t \u003ctopic\u003e -M \u003cmessage\u003e\n    # Customize the port number\n    python basicPubSub.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e -p \u003cportNumber\u003e\n    # change the run mode to subscribe or publish only (see python basicPubSub.py -h for the available options)\n    python basicPubSub.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e -m \u003cmode\u003e\n\nSource\n******\n\nThe example is available in ``samples/basicPubSub/``.\n\nBasicPubSub with Amazon Cognito Session Token\n_____________________________________________\n\nThis example demonstrates a simple MQTT publish/subscribe using an Amazon Cognito\nIdentity session token. It uses the AWS IoT Device SDK for\nPython and the AWS SDK for Python (boto3). It first makes a request to\nAmazon Cognito to retrieve the access ID, the access key, and the session token for temporary\nauthentication. It then uses these credentials to connect to AWS\nIoT and communicate data/messages using MQTT over Websocket, just like\nthe BasicPubSub example.\n\nInstructions\n************\n\nTo run the example, you will need your **Amazon Cognito identity pool ID** and allow **unauthenticated\nidentities** to connect. Make sure that the policy attached to the\nunauthenticated role has permissions to access the required AWS IoT\nAPIs. For more information about Amazon Cognito, see\n`here \u003chttps://console.aws.amazon.com/cognito/\u003e`__.\n\nRun the example like this:\n\n.. code-block:: python\n\n    python basicPubSub_CognitoSTS.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -C \u003cCognitoIdentityPoolID\u003e\n    # Customize client id and topic\n    python basicPubsub_CognitoSTS.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -C \u003cCognitoIdentityPoolID\u003e -id \u003cclientId\u003e -t \u003ctopic\u003e\n\nSource\n******\n\nThe example is available in ``samples/basicPubSub/``.\n\nBasicPubSub Asynchronous version\n________________________________\n\nThis example demonstrates a simple MQTT publish/subscribe with asynchronous APIs using AWS IoT.\nIt first registers general notification callbacks for CONNACK reception, disconnect reception and message arrival.\nIt then registers ACK callbacks for subscribe and publish requests to print out received ack packet ids.\nIt subscribes to a topic with no specific callback and then publishes to the same topic in a loop.\nNew messages are printed upon reception by the general message arrival callback, indicating\nthe callback function has been called.\nNew ack packet ids are printed upon reception of PUBACK and SUBACK through ACK callbacks registered with asynchronous\nAPI calls, indicating that the the client received ACKs for the corresponding asynchronous API calls.\n\nInstructions\n************\n\nRun the example like this:\n\n.. code-block:: python\n\n    # Certificate based mutual authentication\n    python basicPubSubAsync.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e\n    # MQTT over WebSocket\n    python basicPubSubAsync.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -w\n    # Customize client id and topic\n    python basicPubSubAsync.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e -id \u003cclientId\u003e -t \u003ctopic\u003e\n    # Customize the port number\n    python basicPubSubAsync.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e -p \u003cportNumber\u003e\n\nSource\n******\n\nThe example is available in ``samples/basicPubSub/``.\n\nBasicPubSub with API invocation in callback\n___________\n\nThis example demonstrates the usage of asynchronous APIs within callbacks. It first connects to AWS IoT and subscribes\nto 2 topics with the corresponding message callbacks registered. One message callback contains client asynchronous API\ninvocation that republishes the received message from \u003ctopic\u003e to  \u003ctopic\u003e/republish. The other message callback simply\nprints out the received message. It then publishes messages to \u003ctopic\u003e in an infinite loop. For every message received\nfrom \u003ctopic\u003e, it will be republished to \u003ctopic\u003e/republish and be printed out as configured in the simple print-out\nmessage callback.\nNew ack packet ids are printed upon reception of PUBACK and SUBACK through ACK callbacks registered with asynchronous\nAPI calls, indicating that the the client received ACKs for the corresponding asynchronous API calls.\n\nInstructions\n************\n\nRun the example like this:\n\n.. code-block:: python\n\n    # Certificate based mutual authentication\n    python basicPubSub_APICallInCallback.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e\n    # MQTT over WebSocket\n    python basicPubSub_APICallInCallback.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -w\n    # Customize client id and topic\n    python basicPubSub_APICallInCallback.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e -id \u003cclientId\u003e -t \u003ctopic\u003e\n    # Customize the port number\n    python basicPubSub_APICallInCallback.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e -p \u003cportNumber\u003e\n\nSource\n******\n\nThe example is available in ``samples/basicPubSub/``.\n\nBasicShadow\n___________\n\nThis example demonstrates the use of basic shadow operations\n(update/delta). It has two scripts, ``basicShadowUpdater.py`` and\n``basicShadowDeltaListener.py``. The example shows how an shadow update\nrequest triggers delta events.\n\n``basicShadowUpdater.py`` performs a shadow update in a loop to\ncontinuously modify the desired state of the shadow by changing the\nvalue of the integer attribute.\n\n``basicShadowDeltaListener.py`` subscribes to the delta topic\nof the same shadow and receives delta messages when there is a\ndifference between the desired and reported states.\n\nBecause only the desired state is being updated by basicShadowUpdater, a\nseries of delta messages that correspond to the shadow update requests should be received in basicShadowDeltaListener.\n\nInstructions\n************\n\nRun the example like this:\n\nFirst, start the basicShadowDeltaListener:\n\n.. code-block:: python\n\n    # Certificate-based mutual authentication\n    python basicShadowDeltaListener.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e\n    # MQTT over WebSocket\n    python basicShadowDeltaListener.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -w\n    # Customize the port number\n    python basicShadowDeltaListener.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e -p \u003cportNumber\u003e\n\n\nThen, start the basicShadowUpdater:\n\n.. code-block:: python\n\n    # Certificate-based mutual authentication\n    python basicShadowUpdater.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e\n    # MQTT over WebSocket\n    python basicShadowUpdater.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -w\n    # Customize the port number\n    python basicShadowUpdater.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e -p \u003cportNumber\u003e\n\n\nAfter the basicShadowUpdater starts sending shadow update requests, you\nshould be able to see corresponding delta messages in the\nbasicShadowDeltaListener output.\n\nSource\n******\n\nThe example is available in ``samples/basicShadow/``.\n\nThingShadowEcho\n_______________\n\nThis example demonstrates how a device communicates with AWS IoT,\nsyncing data into the device shadow in the cloud and receiving commands\nfrom another app. Whenever there is a new command from the app side to\nchange the desired state of the device, the device receives this\nrequest and applies the change by publishing it as the reported state. By\nregistering a delta callback function, users will be able to see this\nincoming message and notice the syncing of the state.\n\nInstructions\n************\n\nRun the example like this:\n\n.. code-block:: python\n\n    # Certificate based mutual authentication\n    python ThingShadowEcho.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e\n    # MQTT over WebSocket\n    python ThingShadowEcho.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -w\n    # Customize client Id and thing name\n    python ThingShadowEcho.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e -id \u003cclientId\u003e -n \u003cthingName\u003e\n    # Customize the port number\n    python ThingShadowEcho.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e -p \u003cportNumber\u003e\n\nNow use the `AWS IoT console \u003chttps://console.aws.amazon.com/iot/\u003e`__ or other MQTT\nclient to update the shadow desired state only. You should be able to see the reported state is updated to match\nthe changes you just made in desired state.\n\nSource\n******\n\nThe example is available in ``samples/ThingShadowEcho/``.\n\nJobsSample\n__________\n\nThis example demonstrates how a device communicates with AWS IoT while\nalso taking advantage of AWS IoT Jobs functionality. It shows how to\nsubscribe to Jobs topics in order to recieve Job documents on your\ndevice. It also shows how to process those Jobs so that you can see in\nthe `AWS IoT console \u003chttps://console.aws.amazon.com/iot/\u003e`__ which of your devices have received and processed\nwhich Jobs. See the AWS IoT Device Management documentation `here \u003chttps://aws.amazon.com/documentation/iot-device-management/\u003e`__\nfor more information on creating and deploying Jobs to your fleet of\ndevices to facilitate management tasks such deploying software updates\nand running diagnostics.\n\nInstructions\n************\n\nFirst use the `AWS IoT console \u003chttps://console.aws.amazon.com/iot/\u003e`__ to create and deploy Jobs to your fleet of devices.\n\nThen run the example like this:\n\n.. code-block:: python\n\n    # Certificate based mutual authentication\n    python jobsSample.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e -n \u003cthingName\u003e\n    # MQTT over WebSocket\n    python jobsSample.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -w -n \u003cthingName\u003e\n    # Customize client Id and thing name\n    python jobsSample.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e -id \u003cclientId\u003e -n \u003cthingName\u003e\n    # Customize the port number\n    python jobsSample.py -e \u003cendpoint\u003e -r \u003crootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e -n \u003cthingName\u003e -p \u003cportNumber\u003e\n\nSource\n******\n\nThe example is available in ``samples/jobs/``.\n\nBasicDiscovery\n______________\n\nThis example demonstrates how to perform a discovery process from a Greengrass Aware Device (GGAD) to obtain the required\nconnectivity/identity information to connect to the Greengrass Core (GGC) deployed within the same group. It uses the\ndiscovery information provider to invoke discover call for a certain GGAD with its thing name. After it gets back a\nsuccess response, it picks up the first GGC and the first set of identity information (CA) for the first group, persists \\\nit locally and iterates through all connectivity info sets for this GGC to establish a MQTT connection to the designated\nGGC. It then publishes messages to the topic, which, on the GGC side, is configured to route the messages back to the\nsame GGAD. Therefore, it receives the published messages and invokes the corresponding message callbacks.\n\nNote that in order to get the sample up and running correctly, you need:\n\n1. Have a successfully deployed Greengrass group.\n\n2. Use the certificate and private key that have been deployed with the group for the GGAD to perform discovery process.\n\n3. The subscription records for that deployed group should contain a route that routes messages from the targeted GGAD to itself via a dedicated MQTT topic.\n\n4. The deployed GGAD thing name, the deployed GGAD certificate/private key and the dedicated MQTT topic should be used as the inputs for this sample.\n\n\nRun the sample like this:\n\n.. code-block:: python\n\n    python basicDiscovery.py -e \u003cendpoint\u003e -r \u003cIoTRootCAFilePath\u003e -c \u003ccertFilePath\u003e -k \u003cprivateKeyFilePath\u003e -n \u003cGGADThingName\u003e -t \u003cRoutingTopic\u003e\n\nIf the group, GGC, GGAD and group subscription/routes are set up correctly, you should be able to see the sample running\non your GGAD, receiving messages that get published to GGC by itself.\n\n.. _API_Documentation:\n\nAPI Documentation\n~~~~~~~~~~~~~~~~~\n\nYou can find the API documentation for the SDK `here \u003chttps://s3.amazonaws.com/aws-iot-device-sdk-python-docs/index.html\u003e`__.\n\n.. _License:\n\nLicense\n~~~~~~~\n\nThis SDK is distributed under the `Apache License, Version\n2.0 \u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e`__, see LICENSE.txt\nand NOTICE.txt for more information.\n\n.. _Support:\n\nSupport\n~~~~~~~\n\nIf you have technical questions about the AWS IoT Device SDK, use the `AWS\nIoT Forum \u003chttps://forums.aws.amazon.com/forum.jspa?forumID=210\u003e`__.\nFor any other questions about AWS IoT, contact `AWS\nSupport \u003chttps://aws.amazon.com/contact-us\u003e`__.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Faws-iot-device-sdk-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws%2Faws-iot-device-sdk-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Faws-iot-device-sdk-python/lists"}