AWS IoT Device SDK for Python v2

The SDK provides specialized modules for different AWS IoT capabilities. Key functional areas include:

• MQTT Connection & Clients: Use mqtt_connection_builder and mqtt5_client_builder to establish connectivity.
• IoT Shadow: Manage device shadows via iotshadow.
• IoT Jobs: Handle device jobs via iotjobs.
• Greengrass Integration: Use greengrasscoreipc and greengrass_discovery for AWS IoT Greengrass environments.
• EventStreamRPC: Support for EventStream RPC protocols.
• IoT Identity: Manage device identities via iotidentity.

The MQTT5 client emits several events related to state and network status:

• AttemptingConnect: Emitted when the client begins a connection attempt.
• ConnectionSuccess: Emitted after receiving a CONNACK packet. Includes NegotiatedSettings (final session settings).
• ConnectionFailure: Emitted if a connection fails between DNS resolution and CONNACK receipt. May include error codes or the CONNACK packet if a failing reason code was sent.
• Disconnect: Emitted when the network connection is shut down (local action, event, or remote reset). Only emitted after a ConnectionSuccess. Includes an error code and potentially the server-sent DISCONNECT packet.
• Stopped: Emitted once the client has shut down all network connections and entered an idle state (after stop() is called).

When interacting with the AWS IoT Jobs service, the SDK uses two primary MQTT-based streaming operations to notify devices of changes:

• create_job_executions_changed_stream (JobExecutionsChanged event): Emitted every time the set of queued or in-progress job executions for the device changes. If you create $N$ jobs, you will receive $N$ of these events.
• create_next_job_execution_changed_stream (NextJobExecutionChanged event): Emitted only when the specific job that is next in line to be executed changes. This typically happens when a job is completed or when a new job is queued that becomes the new 'next' job.

Developers should open both streams to maintain an accurate local state of pending work.

The Fleet Provisioning service (also known as Identity Service) allows devices to securely receive certificates and private keys upon their first connection. The v2 SDK provides a client for this service that follows the same subscription-then-publish pattern as the Jobs and Shadow services.

1. Subscribe to the required Fleet Provisioning topics to receive data and feedback.
2. Use the service client APIs to interact with the server (e.g., updating status or requesting data).

To build a robust, persistent job executor on an IoT device, follow this architectural pattern:

1. Initialization: On startup, create and open streaming operations for both JobExecutionsChanged and NextJobExecutionChanged events.
2. State Synchronization: On startup, call get_pending_job_executions to fetch and cache the current set of incomplete jobs.
3. Reactive Updates: Keep the local cache up to date by reacting to the JobExecutionsChanged and NextJobExecutionChanged MQTT events.
4. Execution Loop: While there are incomplete jobs in the cache, execute them (e.g., one-at-a-time). If the cache is empty, wait for a new event to trigger the next execution.

The v2 SDK Jobs service client (iotjobs.IotJobsClient) follows the same subscription-based pattern as the Device Shadow service. You must subscribe to necessary topics (like NextJobExecutionChangedSubscriptionRequest) before the client can effectively interact with the server to receive or update job statuses.

# Initialize Jobs client
mqtt5_client.start()
jobs_client = iotjobs.IotJobsClient(mqtt5_client)

# Subscribe to necessary topics
changed_subscription_request = iotjobs.NextJobExecutionChangedSubscriptionRequest(
    thing_name="<thing name>"
)

def on_next_job_execution_changed(event):
    return

The Shadow service provides two primary streaming operations to react to changes without manual polling or complex JSON diffing:

• create_shadow_updated_stream: Emits ShadowUpdatedEvent whenever any part of the shadow (metadata, state, or version) changes. This is useful for general monitoring.
• create_shadow_delta_updated_stream: Emits ShadowDeltaUpdatedEvent specifically when properties become out-of-sync between the desired and reported states. This allows a device to focus only on the specific properties that require action.