Devices and jobs - Amazon IoT Core
Programming devices to work with jobs
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Devices and jobs

Devices can communicate with Amazon IoT Jobs using MQTT, HTTP Signature Version 4, or HTTP TLS. To determine the endpoint to use when your device communicates with Amazon IoT Jobs, run the DescribeEndpoint command. For example, if you run this command:

aws iot describe-endpoint --endpoint-type iot:Data-ATS

you get a result similar to the following:

{
    "endpointAddress": "a1b2c3d4e5f6g7-ats.iot.us-west-2.amazonaws.com"
}

Devices can communicate with Amazon IoT Jobs using MQTT protocol. Devices subscribe to MQTT topics to be notified of new jobs and to receive responses from the Amazon IoT Jobs service. Devices publish on MQTT topics to query or update the state of a job launch. Each device has its own general MQTT topic. For more information about publishing and subscribing to MQTT topics, see Device communication protocols.

With this method of communication, your device uses its device-specific certificate and private key to authenticate with Amazon IoT Jobs.

Your devices can subscribe to the following topics. thing-name is the name of the thing associated with the device.

  • $aws/things/thing-name/jobs/notify

    Subscribe to this topic to notify you when a job launch is added or removed from the list of pending job launches.

  • $aws/things/thing-name/jobs/notify-next

    Subscribe to this topic to notify you when the next pending job execution has changed.

  • $aws/things/thing-name/jobs/request-name/accepted

    The Amazon IoT Jobs service publishes success and failure messages on an MQTT topic. The topic is formed by appending accepted or rejected to the topic used to make the request. Here, request-name is the name of a request such as Get and the topic can be: $aws/things/myThing/jobs/get. Amazon IoT Jobs then publishes success messages on the $aws/things/myThing/jobs/get/accepted topic.

  • $aws/things/thing-name/jobs/request-name/rejected

    Here, request-name is the name of a request such as Get. If the request failed, Amazon IoT Jobs publishes failure messages on the $aws/things/myThing/jobs/get/rejected topic.

You can also use the following HTTPS API operations:

Devices can communicate with Amazon IoT Jobs using HTTP Signature Version 4 on port 443. This is the method used by the Amazon SDKs and CLI. For more information about those tools, see Amazon CLI Command Reference: iot-jobs-data or Amazon SDKs and Tools and refer to the IotJobsDataPlane section for your preferred language.

With this method of communication, your device uses IAM credentials to authenticate with Amazon IoT Jobs.

The following commands are available using this method:

  • DescribeJobExecution

    aws iot-jobs-data describe-job-execution ...

  • GetPendingJobExecutions

    aws iot-jobs-data get-pending-job-executions ...

  • StartNextPendingJobExecution

    aws iot-jobs-data start-next-pending-job-execution ...

  • UpdateJobExecution

    aws iot-jobs-data update-job-execution ...

Devices can communicate with Amazon IoT Jobs using HTTP TLS on port 8443 using a third-party software client that supports this protocol.

With this method, your device uses X.509 certificate-based authentication (for example, its device-specific certificate and private key).

The following commands are available using this method:

  • DescribeJobExecution

  • GetPendingJobExecutions

  • StartNextPendingJobExecution

  • UpdateJobExecution

Programming devices to work with jobs

The examples in this section use MQTT to illustrate how a device works with the Amazon IoT Jobs service. Or, you could use the corresponding API or CLI commands. For these examples, we assume a device called MyThing that subscribes to the following MQTT topics:

  • $aws/things/MyThing/jobs/notify (or $aws/things/MyThing/jobs/notify-next)

  • $aws/things/MyThing/jobs/get/accepted

  • $aws/things/MyThing/jobs/get/rejected

  • $aws/things/MyThing/jobs/jobId/get/accepted

  • $aws/things/MyThing/jobs/jobId/get/rejected

If you're using code signing for Amazon IoT, your device code must verify the signature of your code file. The signature is in the job document in the codesign property. For more information about verifying a code file signature, see Device Agent Sample.

Topics