0
# AWS IoT Python SDK
1

2
A comprehensive Python SDK for connecting devices to AWS IoT platform through MQTT and MQTT over WebSocket protocols. Enables developers to build IoT applications that can securely communicate with AWS IoT services, manage device shadows (digital representations of device state), handle AWS IoT Jobs for device management, and integrate with AWS Greengrass for edge computing scenarios.
3

4
## Package Information
5

6
- **Package Name**: AWSIoTPythonSDK
7
- **Language**: Python
8
- **Installation**: `pip install AWSIoTPythonSDK`
9

10
## Core Imports
11

12
```python
13
import AWSIoTPythonSDK.MQTTLib as AWSIoTPyMQTT
14
```
15

16
For Greengrass discovery:
17

18
```python
19
from AWSIoTPythonSDK.core.greengrass.discovery.providers import DiscoveryInfoProvider
20
```
21

22
For exception handling:
23

24
```python
25
from AWSIoTPythonSDK.exception.AWSIoTExceptions import connectTimeoutException
26
from AWSIoTPythonSDK.exception.operationTimeoutException import operationTimeoutException
27
from AWSIoTPythonSDK.exception.operationError import operationError
28
```
29

30
For IoT Jobs:
31

32
```python
33
from AWSIoTPythonSDK.core.jobs.thingJobManager import jobExecutionTopicType
34
from AWSIoTPythonSDK.core.jobs.thingJobManager import jobExecutionTopicReplyType
35
from AWSIoTPythonSDK.core.jobs.thingJobManager import jobExecutionStatus
36
```
37

38
For Device Shadow operations:
39

40
```python
41
from AWSIoTPythonSDK.core.shadow.deviceShadow import deviceShadow
42
```
43

44
## Basic Usage
45

46
### TLS Mutual Authentication
47

48
```python
49
import AWSIoTPythonSDK.MQTTLib as AWSIoTPyMQTT
50

51
# Create MQTT client
52
myAWSIoTMQTTClient = AWSIoTPyMQTT.AWSIoTMQTTClient("myClientID")
53

54
# Configure endpoint and credentials  
55
myAWSIoTMQTTClient.configureEndpoint("your-endpoint.iot.region.amazonaws.com", 8883)
56
myAWSIoTMQTTClient.configureCredentials("rootCA.crt", "private.key", "certificate.crt")
57

58
# Configure auto-reconnect
59
myAWSIoTMQTTClient.configureAutoReconnectBackoffTime(1, 32, 20)
60

61
# Connect and publish
62
myAWSIoTMQTTClient.connect()
63
myAWSIoTMQTTClient.publish("myTopic", "Hello from AWS IoT device", 0)
64
myAWSIoTMQTTClient.disconnect()
65
```
66

67
### WebSocket with SigV4
68

69
```python
70
import AWSIoTPythonSDK.MQTTLib as AWSIoTPyMQTT
71

72
# Create WebSocket client
73
myAWSIoTMQTTClient = AWSIoTPyMQTT.AWSIoTMQTTClient("myClientID", useWebsocket=True)
74

75
# Configure endpoint and IAM credentials
76
myAWSIoTMQTTClient.configureEndpoint("your-endpoint.iot.region.amazonaws.com", 443)
77
myAWSIoTMQTTClient.configureIAMCredentials("accessKeyID", "secretAccessKey", "sessionToken")
78

79
# Connect and subscribe
80
myAWSIoTMQTTClient.connect()
81
myAWSIoTMQTTClient.subscribe("myTopic/sub", 1, customCallback)
82
```
83

84
## Architecture
85

86
The SDK is built around three main client types that share a common configuration pattern:
87

88
- **AWSIoTMQTTClient**: Core MQTT client providing direct publish/subscribe operations
89
- **AWSIoTMQTTShadowClient**: Specialized client for device shadow operations with persistent subscriptions
90
- **AWSIoTMQTTThingJobsClient**: Specialized client for AWS IoT Jobs management and execution
91

92
All clients support both TLS mutual authentication and WebSocket SigV4 authentication, with automatic reconnection, progressive backoff, and offline request queueing capabilities.
93

94
## Capabilities
95

96
### Core MQTT Operations
97

98
Basic MQTT connectivity including connection management, publish/subscribe operations, and advanced features like auto-reconnect, offline queueing, and custom authentication methods.
99

100
```python { .api }
101
class AWSIoTMQTTClient:
102
    def __init__(self, clientID: str, protocolType: int = 4, useWebsocket: bool = False, cleanSession: bool = True): ...
103
    def configureEndpoint(self, hostName: str, portNumber: int): ...
104
    def configureCredentials(self, CAFilePath: str, KeyPath: str = "", CertificatePath: str = "", Ciphers: str = None): ...
105
    def connect(self, keepAliveIntervalSecond: int = 600) -> bool: ...
106
    def publish(self, topic: str, payload: str, QoS: int) -> bool: ...
107
    def subscribe(self, topic: str, QoS: int, callback: callable) -> bool: ...
108
```
109

110
[Core MQTT Operations](./mqtt-client.md)
111

112
### Device Shadow Management
113

114
Device shadow operations for synchronizing device state between physical devices and the cloud, including shadow retrieval, updates, deletion, and delta notifications for state changes.
115

116
```python { .api }
117
class AWSIoTMQTTShadowClient:
118
    def __init__(self, clientID: str, protocolType: int = 4, useWebsocket: bool = False, cleanSession: bool = True, awsIoTMQTTClient = None): ...
119
    def createShadowHandlerWithName(self, shadowName: str, isPersistentSubscribe: bool) -> 'deviceShadow': ...
120

121
class deviceShadow:
122
    def shadowGet(self, callback: callable, timeout: int) -> str: ...
123
    def shadowUpdate(self, JSONPayload: str, callback: callable, timeout: int) -> str: ...
124
    def shadowDelete(self, callback: callable, timeout: int) -> str: ...
125
```
126

127
[Device Shadow Management](./device-shadows.md)
128

129
### AWS IoT Jobs
130

131
Job execution management for device fleet management, including job subscription, execution state management, progress reporting, and job lifecycle operations.
132

133
```python { .api }
134
class AWSIoTMQTTThingJobsClient:
135
    def __init__(self, clientID: str, thingName: str, QoS: int = 0, protocolType: int = 4, useWebsocket: bool = False, cleanSession: bool = True, awsIoTMQTTClient = None): ...
136
    def sendJobsStartNext(self, statusDetails: dict = None, stepTimeoutInMinutes: int = None) -> bool: ...
137
    def sendJobsUpdate(self, jobId: str, status: int, statusDetails: dict = None, expectedVersion: int = 0, executionNumber: int = 0, includeJobExecutionState: bool = False, includeJobDocument: bool = False, stepTimeoutInMinutes: int = None) -> bool: ...
138
    def createJobSubscription(self, callback: callable, jobExecutionType = None, jobReplyType = None, jobId: str = None) -> bool: ...
139
```
140

141
[AWS IoT Jobs](./iot-jobs.md)
142

143
### Greengrass Discovery
144

145
Discovery service for finding and connecting to AWS Greengrass Core devices in local networks, including connectivity information retrieval and CA certificate management.
146

147
```python { .api }
148
class DiscoveryInfoProvider:
149
    def __init__(self, caPath: str = "", certPath: str = "", keyPath: str = "", host: str = "", port: int = 8443, timeoutSec: int = 120): ...
150
    def configureEndpoint(self, host: str, port: int = 8443): ...
151
    def configureCredentials(self, caPath: str, certPath: str, keyPath: str): ...
152
    def discover(self, thingName: str) -> 'DiscoveryInfo': ...
153
```
154

155
[Greengrass Discovery](./greengrass-discovery.md)
156

157
### Exception Handling
158

159
Comprehensive exception classes for timeout conditions, operation errors, connection failures, and Greengrass discovery issues, enabling robust error handling in IoT applications.
160

161
```python { .api }
162
# Timeout exceptions
163
class connectTimeoutException(Exception): ...
164
class publishTimeoutException(Exception): ...
165
class subscribeTimeoutException(Exception): ...
166

167
# Operation errors  
168
class connectError(Exception): ...
169
class publishError(Exception): ...
170
class subscribeError(Exception): ...
171

172
# Discovery errors
173
class DiscoveryTimeoutException(Exception): ...
174
class DiscoveryUnauthorizedException(Exception): ...
175
```
176

177
[Exception Handling](./exception-handling.md)
178

179
## Constants and Enums
180

181
The SDK provides various constants and enumerations for configuration and operation:
182

183
```python { .api }
184
# SDK version information
185
import AWSIoTPythonSDK
186
__version__ = "1.5.4"  # Available as AWSIoTPythonSDK.__version__
187

188
# MQTT Protocol versions
189
MQTTv3_1 = 3
190
MQTTv3_1_1 = 4
191

192
# Queue drop behavior
193
DROP_OLDEST = 0
194
DROP_NEWEST = 1
195

196
# Job execution status values
197
class jobExecutionStatus:
198
    JOB_EXECUTION_STATUS_NOT_SET = (0, None)
199
    JOB_EXECUTION_QUEUED = (1, 'QUEUED')
200
    JOB_EXECUTION_IN_PROGRESS = (2, 'IN_PROGRESS')
201
    JOB_EXECUTION_FAILED = (3, 'FAILED')
202
    JOB_EXECUTION_SUCCEEDED = (4, 'SUCCEEDED')
203
    JOB_EXECUTION_CANCELED = (5, 'CANCELED')
204
    JOB_EXECUTION_REJECTED = (6, 'REJECTED')
205
    JOB_EXECUTION_UNKNOWN_STATUS = (99, None)
206
```