AWS jobs

The Amazon Web Services (AWS) jobs library provides functions for working with the AWS IoT jobs service.

You can use the library to report the status of AWS IoT jobs and to subscribe to job topics.

The module also contains the following elements:

  • String templates that can be used for generating MQTT topics

  • Defines for lengths of topics, status, and job IDs

  • Defines for subscribe message IDs

This library assumes that all strings can be formatted in UTF-8.

Configuration

Configure the following parameters when using this library:

API documentation

Header file: include/net/aws_jobs.h
Source files: subsys/net/lib/aws_jobs/
group aws_jobs

Library for interacting with AWS Jobs.

MQTT message IDs used for identifying subscribe message ACKs

SUBSCRIBE_ID_BASE
SUBSCRIBE_NOTIFY
SUBSCRIBE_NOTIFY_NEXT
SUBSCRIBE_GET
SUBSCRIBE_JOB_ID_GET
SUBSCRIBE_JOB_ID_UPDATE
SUBSCRIBE_EXPECTED

Defines

AWS

The max JOB_ID_LEN according to AWS docs https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html.

AWS_LEN
AWS_JOBS_JOB_ID_MAX_LEN
AWS_JOBS_TOPIC_STATIC_LEN
AWS_JOBS_TOPIC_MAX_LEN

Enums

enum execution_status

Job Execution Status.

Values:

enumerator AWS_JOBS_QUEUED
enumerator AWS_JOBS_IN_PROGRESS
enumerator AWS_JOBS_SUCCEEDED
enumerator AWS_JOBS_FAILED
enumerator AWS_JOBS_TIMED_OUT
enumerator AWS_JOBS_REJECTED
enumerator AWS_JOBS_REMOVED
enumerator AWS_JOBS_CANCELED

Functions

int aws_jobs_create_topic_notify_next(struct mqtt_client *const client, uint8_t *topic_buf)

Construct the notify-next topic for receiving AWS IoT jobs.

Parameters:

  • client – [in] Connected MQTT client instance.

  • topic_buf – [out] Buffer to store the topic in.

Return values:

  • 0 – If successful.

  • -EINVAL – If the provided input parameter is not valid.

  • -ENOMEM – If cannot fit in the buffer, which is assumed to be AWS_JOBS_TOPIC_MAX_LEN in size.

int aws_jobs_subscribe_topic_notify_next(struct mqtt_client *const client, uint8_t *topic_buf)

Construct the notify-next topic and subscribe to it for receiving AWS IoT jobs.

Parameters:

  • client – [in] Connected MQTT client instance.

  • topic_buf – [out] Buffer to store the topic in.

Return values:

  • 0 – If successful, otherwise the return code of mqtt_subscribe or snprintf.

  • -EINVAL – If the provided input parameter is not valid.

int aws_jobs_unsubscribe_topic_notify_next(struct mqtt_client *const client, uint8_t *topic_buf)

Construct the notify-next topic and unsubscribe from it to stop receiving AWS IoT jobs.

Parameters:

  • client – [in] Connected MQTT client instance.

  • topic_buf – [out] Buffer to store the topic in.

Return values:

  • 0 – If successful, otherwise the return code of mqtt_unsubscribe or snprintf.

  • -EINVAL – If the provided input parameter is not valid.

int aws_jobs_create_topic_notify(struct mqtt_client *const client, uint8_t *topic_buf)

Construct the notify topic for receiving AWS IoT jobs.

Parameters:

  • client – [in] Connected MQTT client instance.

  • topic_buf – [out] Buffer to store the topic in.

Return values:

  • 0 – If successful.

  • -EINVAL – If the provided input parameter is not valid.

  • -ENOMEM – If cannot fit in the buffer, which is assumed to be AWS_JOBS_TOPIC_MAX_LEN in size.

int aws_jobs_subscribe_topic_notify(struct mqtt_client *const client, uint8_t *topic_buf)

Construct the notify topic and subscribe to it for receiving AWS IoT jobs lists.

Parameters:

  • client – [in] Connected MQTT client instance.

  • topic_buf – [out] Buffer to store the topic in.

Return values:

  • 0 – If successful, otherwise the return code of mqtt_subscribe or snprintf.

  • -EINVAL – If the provided input parameter is not valid.

int aws_jobs_unsubscribe_topic_notify(struct mqtt_client *const client, uint8_t *topic_buf)

Construct the notify topic and unsubscribe to stop receiving AWS IoT jobs lists.

Parameters:

  • client – [in] Connected MQTT client instance.

  • topic_buf – [out] Buffer to store the topic in.

Return values:

  • 0 – If successful, otherwise the return code of mqtt_unsubscribe or snprintf.

  • -EINVAL – If the provided input parameter is not valid.

int aws_jobs_create_topic_get(struct mqtt_client *const client, const uint8_t *job_id, uint8_t *topic_buf)

Construct the get topic for a job ID.

Parameters:

  • client – [in] Connected MQTT client instance.

  • job_id – [in] Job ID of the currently accepted job.

  • topic_buf – [out] Buffer to store the topic in.

Return values:

  • 0 – If successful.

  • -EINVAL – If the provided input parameter is not valid.

  • -ENOMEM – If cannot fit in the buffer, which is assumed to be AWS_JOBS_TOPIC_MAX_LEN in size.

int aws_jobs_subscribe_topic_get(struct mqtt_client *const client, const uint8_t *job_id, uint8_t *topic_buf)

Construct the get topic for a job ID and subscribe to it for both accepted and rejected.

Parameters:

  • client – [in] Connected MQTT client instance.

  • job_id – [in] Job ID of the currently accepted job.

  • topic_buf – [out] Buffer to store the topic in.

Return values:

  • 0 – If successful, otherwise the return code of mqtt_subscribe or snprintf.

  • -EINVAL – If the provided input parameter is not valid.

int aws_jobs_unsubscribe_topic_get(struct mqtt_client *const client, const uint8_t *job_id, uint8_t *topic_buf)

Construct the get topic for a job ID and unsubscribe from it for both accepted and rejected.

Parameters:

  • client – [in] Connected MQTT client instance.

  • job_id – [in] Job ID of the currently accepted job.

  • topic_buf – [out] Buffer to store the topic in.

Return values:

  • 0 – If successful, otherwise the return code of mqtt_unsubscribe or snprintf.

  • -EINVAL – If the provided input parameters are not valid.

int aws_jobs_subscribe_topic_update(struct mqtt_client *const client, const uint8_t *job_id, uint8_t *topic_buf)

Construct the update topic for a job ID and subscribe to rejected and accepted to receive feedback when submitting a job execution update.

Parameters:

  • client – [in] Connected MQTT client instance.

  • job_id – [in] Job ID of the currently accepted job.

  • topic_buf – [out] Buffer to store the topic in.

Return values:

  • 0 – If successful, otherwise the return code of mqtt_subscribe or snprintf.

  • -EINVAL – If the provided input parameters are not valid.

int aws_jobs_unsubscribe_topic_update(struct mqtt_client *const client, const uint8_t *job_id, uint8_t *topic_buf)

Construct the update topic for a job ID and unsubscribe from rejected and accepted to stop receiving feedback from the job execution.

Parameters:

  • client – [in] Connected MQTT client instance.

  • job_id – [in] Job ID of the currently accepted job.

  • topic_buf – [out] Buffer to store the topic in.

Return values:

  • 0 – If successful, otherwise the return code of mqtt_unsubscribe or snprintf.

  • -EINVAL – If the provided input parameters are not valid.

int aws_jobs_update_job_execution(struct mqtt_client *const client, const uint8_t *job_id, enum execution_status status, const uint8_t *status_details, int expected_version, const uint8_t *client_token, uint8_t *topic_buf)

AWS Jobs update job execution status function.

This implements the minimal requirements for running an AWS job. Only updating status and status details is supported.

Parameters:

  • client – [in] Initialized and connected MQTT Client instance.

  • job_id – [in] The ID of the job which you are updating.

  • status – [in] The job execution status.

  • status_details – [in] JSON object in string format containing additional information. Max 10 fields. Can be NULL.

  • expected_version – [in] The expected job document version. Must be incremented by 1 for every update.

  • client_token – [in] This can be an arbitrary value and will be reflected in the response to the update.

  • topic_buf – [out] Buffer to store the topic in.

Return values:

  • 0 – If the update is published successfully, otherwise return mqtt_publish error code or the error code of snprintf.

  • -EINVAL – If the provided input parameters are not valid.

int aws_jobs_get_job_execution(struct mqtt_client *const client, const char *job_id, uint8_t *topic_buf)

AWS Jobs get job execution.

This implements fetching a job from the queue in AWS.

Parameters:

  • client – [in] Initialized and connected MQTT Client instance.

  • job_id – [in] The ID of the job you are fetching use “$next” for fetching the next IN_PROGRESS. or QUEUED job. It will fetch the first created job if multiple exsists.

  • topic_buf – [out] Buffer to store the topic in.

Return values:

0 – If the update is published successfully, otherwise return mqtt_publish error code or the error code of snprintf.

bool aws_jobs_cmp(const char *sub, const char *pub, size_t pub_len, const uint8_t *suffix)

Compare topics.

Check if topics match

Parameters:

  • sub – [in] Topic subscribed to

  • pub – [in] Published topic

  • pub_len – [in] Length of published topic

  • suffix – [in] Suffix to match. Cannot be NULL. Must be empty string for sub topics not ending with ‘#’.

Returns:

true if topics with given suffix match, false otherwise.