or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

device-shadow.mdfleet-provisioning.mdgreengrass-discovery.mdgreengrass-ipc.mdindex.mdiot-jobs.mdmqtt-connections.md
tile.json

tessl/pypi-awsiotsdk

AWS IoT SDK based on the AWS Common Runtime for connecting IoT devices to AWS IoT Core services

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/awsiotsdk@1.24.x

To install, run

npx @tessl/cli install tessl/pypi-awsiotsdk@1.24.0

index.mddocs/

AWS IoT Device SDK Python v2

A comprehensive Python SDK for connecting IoT devices to AWS IoT Core services. Built on the AWS Common Runtime, it provides high-performance MQTT client implementations (both MQTT3 and MQTT5), device shadow management, job execution capabilities, fleet provisioning, and Greengrass discovery functionality with certificate-based authentication, WebSocket connections, and automatic reconnection support.

Package Information

  • Package Name: awsiotsdk
  • Language: Python
  • Installation: pip install awsiotsdk
  • Documentation: https://aws.github.io/aws-iot-device-sdk-python-v2/
  • Repository: https://github.com/aws/aws-iot-device-sdk-python-v2

Core Imports

Basic import for core SDK functionality:

import awsiot

Import specific modules for different capabilities:

# MQTT connection builders
from awsiot import mqtt_connection_builder, mqtt5_client_builder

# Service clients
from awsiot import iotjobs, iotshadow, iotidentity, greengrass_discovery

# Greengrass Core IPC
from awsiot.greengrasscoreipc import connect

# Event Stream RPC (used by Greengrass)
from awsiot import eventstreamrpc

Basic Usage

MQTT Connection with mTLS

from awsiot import mqtt_connection_builder
import json

# Create MQTT connection using mTLS certificates
mqtt_connection = mqtt_connection_builder.mtls_from_path(
    endpoint="your-iot-endpoint.iot.us-east-1.amazonaws.com",
    cert_filepath="path/to/certificate.pem.crt",
    pri_key_filepath="path/to/private.pem.key",
    client_id="my-device-123",
    clean_session=False,
    keep_alive_secs=30
)

# Connect to AWS IoT Core
connection_future = mqtt_connection.connect()
connection_future.result()
print("Connected to AWS IoT Core!")

# Publish a message
message = {"temperature": 23.5, "humidity": 60.2}
mqtt_connection.publish(
    topic="device/data",
    payload=json.dumps(message),
    qos=mqtt.QoS.AT_LEAST_ONCE
)

# Disconnect
disconnect_future = mqtt_connection.disconnect()
disconnect_future.result()

Device Shadow Operations

from awsiot import mqtt_connection_builder, iotshadow

# Create connection (using previous connection setup)
mqtt_connection = mqtt_connection_builder.mtls_from_path(
    endpoint="your-iot-endpoint.iot.us-east-1.amazonaws.com",
    cert_filepath="path/to/certificate.pem.crt", 
    pri_key_filepath="path/to/private.pem.key",
    client_id="my-device-123"
)

# Create shadow client
shadow_client = iotshadow.IotShadowClient(mqtt_connection)

# Update device shadow
update_request = iotshadow.UpdateShadowRequest(
    thing_name="MyDevice",
    state=iotshadow.ShadowState(
        desired={"temperature": 22.0, "fan_speed": "medium"}
    )
)

future = shadow_client.publish_update_shadow(update_request, mqtt.QoS.AT_LEAST_ONCE)
future.result()

Architecture

The AWS IoT Device SDK Python v2 is built on several key architectural components:

  • Connection Layer: Multiple connection builders supporting mTLS, WebSockets, custom authorizers, and PKCS#11/PKCS#12 for different authentication methods
  • Service Clients: High-level clients for IoT Jobs, Device Shadow, Fleet Provisioning, and Greengrass discovery with both V1 (callback-based) and V2 (Future-based) APIs
  • MQTT Protocol Support: Native support for both MQTT3 and MQTT5 protocols with extensive configuration options
  • Greengrass Integration: Complete IPC client for Greengrass Core communication enabling edge computing scenarios
  • Error Handling: Comprehensive exception hierarchy with structured error responses and deserialization failure handling
  • Cross-Platform: Platform-specific implementations for Windows certificate stores, macOS Keychain, and Unix PKCS#11

Capabilities

MQTT Connection Management

MQTT3 and MQTT5 connection builders supporting multiple authentication methods including mTLS certificates, WebSocket connections with AWS signing, custom authorizers, and platform-specific certificate stores.

# MQTT3 Connection Builders
def mtls_from_path(cert_filepath, pri_key_filepath, **kwargs): ...
def mtls_from_bytes(cert_bytes, pri_key_bytes, **kwargs): ...
def mtls_with_pkcs11(**kwargs): ...  # Unix only
def mtls_with_pkcs12(pkcs12_filepath, pkcs12_password, **kwargs): ...  # macOS only
def mtls_with_windows_cert_store_path(cert_store_path, **kwargs): ...  # Windows only
def websockets_with_default_aws_signing(region, credentials_provider, **kwargs): ...
def websockets_with_custom_authorizer(region, **kwargs): ...
def direct_with_custom_authorizer(**kwargs): ...

# MQTT5 Client Builders  
def mtls_from_path(cert_filepath, pri_key_filepath, **kwargs): ...
def mtls_from_bytes(cert_bytes, pri_key_bytes, **kwargs): ...
def mtls_with_pkcs11(**kwargs): ...  # Unix only
def mtls_with_pkcs12(pkcs12_filepath, pkcs12_password, **kwargs): ...  # macOS only
def mtls_with_windows_cert_store_path(cert_store_path, **kwargs): ...  # Windows only
def websockets_with_default_aws_signing(region, credentials_provider, **kwargs): ...
def websockets_with_custom_authorizer(region, **kwargs): ...
def direct_with_custom_authorizer(**kwargs): ...

MQTT Connection Management

Device Shadow Operations

Complete device shadow functionality including get, update, delete operations for both classic and named shadows, with support for shadow delta events and real-time shadow document updates.

class IotShadowClient:
    def publish_get_shadow(self, request, qos): ...
    def publish_update_shadow(self, request, qos): ...
    def publish_delete_shadow(self, request, qos): ...
    def subscribe_to_shadow_delta_events(self, request, qos, callback): ...

class IotShadowClientV2:
    def get_shadow(self, request): ...
    def update_shadow(self, request): ...
    def delete_shadow(self, request): ...

Device Shadow Operations

IoT Jobs Management

Job execution capabilities for device management including job discovery, execution updates, status reporting, and real-time job notifications with support for both pending and in-progress job handling.

class IotJobsClient:
    def publish_get_pending_job_executions(self, request, qos): ...
    def publish_start_next_pending_job_execution(self, request, qos): ...
    def publish_update_job_execution(self, request, qos): ...
    def subscribe_to_job_executions_changed_events(self, request, qos, callback): ...

class IotJobsClientV2:
    def get_pending_job_executions(self, request): ...
    def start_next_pending_job_execution(self, request): ...
    def update_job_execution(self, request): ...

IoT Jobs Management

Fleet Provisioning

Device certificate provisioning and thing registration including certificate creation from CSR, keys and certificate generation, and device thing registration for automated fleet provisioning workflows.

class IotIdentityClient:
    def publish_create_certificate_from_csr(self, request, qos): ...
    def publish_create_keys_and_certificate(self, request, qos): ...
    def publish_register_thing(self, request, qos): ...

class IotIdentityClientV2:
    def create_certificate_from_csr(self, request): ...
    def create_keys_and_certificate(self, request): ...
    def register_thing(self, request): ...

Fleet Provisioning

Greengrass Discovery

Greengrass Core discovery functionality for edge computing scenarios including connectivity information retrieval and core device discovery for local communication setup.

class DiscoveryClient:
    def __init__(self, bootstrap, socket_options, tls_context, region, gg_server_name, proxy_options): ...
    def discover(self, thing_name): ...

Greengrass Discovery

Greengrass Core IPC

Complete Greengrass Core Inter-Process Communication client providing access to all Greengrass Core services including component management, configuration, local deployment, pub/sub messaging, and secrets management.

def connect(**kwargs): ...

class GreengrassCoreIPCClient:
    def new_get_component_details(self): ...
    def new_list_components(self): ...  
    def new_publish_to_topic(self): ...
    def new_subscribe_to_topic(self): ...
    def new_get_thing_shadow(self): ...
    def new_update_thing_shadow(self): ...

Greengrass Core IPC

Event Stream RPC

Low-level event-stream RPC protocol implementation used by Greengrass Core IPC and other AWS IoT services, providing connection management, operation handling, and streaming capabilities for bidirectional communication.

class Connection:
    def connect(self, connection_lifecycle_handler): ...
    def close(self): ...
    def new_stream(self, operation_name, payload, stream_response_handler): ...

class Client:
    def __init__(self, connection, shape_index): ...
    def new_operation(self, operation_name): ...
    def close(self): ...

# Error classes
class ConnectionClosedError(RuntimeError): ...
class StreamClosedError(RuntimeError): ...  
class EventStreamError(RuntimeError): ...
class EventStreamOperationError(RuntimeError): ...

Error Handling

The SDK provides comprehensive error handling through structured exception types:

class V2ServiceException(Exception):
    """Wrapper exception for V2 service client failures"""
    def __init__(self, message: str, inner_error: Exception, modeled_error: Any): ...

class V2DeserializationFailure(Exception):
    """Exception for MQTT message deserialization failures"""  
    def __init__(self, message: str, inner_error: Exception, payload: bytes): ...

Common error patterns include network failures, authentication errors, malformed requests, and service-specific errors that are propagated through the Future-based APIs with detailed error information.

Types

Core Base Classes

class MqttServiceClient:
    """Base class for AWS MQTT service clients"""
    def __init__(self, mqtt_connection): ...
    def unsubscribe(self, topic: str): ...

class ModeledClass:
    """Base for input/output classes generated from AWS service model"""
    def __repr__(self): ...

@dataclass
class ServiceStreamOptions:
    """Configuration options for MQTT-based service streaming operations"""
    incoming_event_listener: Callable
    subscription_status_listener: Optional[Callable] = None
    deserialization_failure_listener: Optional[Callable] = None