AWS IoT Device SDK для встраиваемого C

Этот тег 3.1.2 содержит версию 3 AWS IoT Device SDK для встраиваемого C. Новых функций в этом теге добавлено не будет; будут вноситься только исправления ошибок с минимальным тестированием.

Обзор

AWS IoT Device SDK для встраиваемого C представляет собой набор исходных файлов на языке C, который можно использовать в встраиваемых приложениях для безопасной связи с платформой AWS IoT. Он включает клиенты транспорта MQTT, реализации TLS и примеры их использования. Также он поддерживает специфичные для AWS IoT возможности, такие как Thing Shadow. SDK распространяется в виде исходного кода и предназначен для сборки вместе с кодом приложения, другими библиотеками и ОС реального времени. Для получения дополнительной информации о портировании Device SDK для встраиваемого C на дополнительные платформы обратитесь к PortingGuide.

Возможности

Device SDK упрощает доступ к функциям публикации и подписки AWS IoT брокера через MQTT и предоставляет API для взаимодействия с Thing Shadow. SDK протестирован для работы с платформой AWS IoT, чтобы обеспечить наилучшую совместимость устройства с платформой AWS IoT.### Подключение MQTT SDK предоставляет возможность создания и поддержания взаимно аутентифицированного соединения TLS, по которому работает MQTT. Это соединение используется для дальнейших операций публикации и позволяет подписываться на темы MQTT, вызывая конфигурируемую функцию обратного вызова при получении данных сообщений.### Thing Shadow SDK реализует специальный протокол для Thing Shadow для получения, обновления и удаления Thing Shadow, следуя протоколу, чтобы гарантировать правильную версионность и поддержку токенов клиентов. Он абстрагирует необходимые подписки MQTT тем посредством автоматического подписывания и отписывания от зарезервированных тем по мере необходимости для каждого вызова API. Входящие запросы изменения состояния автоматически сигнализируются через конфигурируемую функцию обратного вызова.

Задачи

SDK предоставляет возможности для упрощенного использования службы задач AWS. Сервис задач может использоваться для управления устройствами, такими как обновление файлов программ, поворот сертификатов устройства или выполнение других задач обслуживания, таких как восстановление настроек устройства или перезапуск устройств.

Цели дизайна этого SDK

Встроенный C SDK был специально создан для устройств с ограниченными ресурсами (работающих на микроконтроллерах и реальной-time операционной системе (RTOS)).

Основные аспекты включают:

• Гибкость при выборе и использовании функциональности (уменьшение размера памяти)
• Только статическая память (нет вызова malloc)
• Настройка использования ресурсов (JSON токены, MQTT подписчики обработчиков и т.д.)
• Может быть перенесен на другую систему реального времени (RTOS), использует обертки для функций специфичных для ОСДля получения более подробной информации о структуре SDK обратитесь туда

Сбор данных метрик

Начиная с версии SDK v2.2.0, Amazon Web Services собирает данные о метриках использования, указывающие, какой язык и версию SDK используются. Это позволяет нам направлять наши ресурсы на решение проблем быстрее в тех SDK, которые используются чаще всего, что является важным показателем. Однако мы понимаем, что не все клиенты хотят отчитываться по этим данным по умолчанию. В этом случае отправка данных метрик может быть легко отключена пользователем путём установки флага DISABLE_METRICS в значение true в файле конфигурации aws_iot_config.h для каждого приложения.

Как начать?

Убедитесь, что вы знакомы с платформой AWS IoT и создали необходимые сертификаты и политики. Для получения более подробной информации о платформе AWS IoT посетите руководство разработчика AWS IoT.

Чтобы быстро приступить к работе с платформой AWS IoT, мы адаптировали SDK для операционных систем типа POSIX, таких как Ubuntu, OS X и RHEL. SDK настроен для библиотеки mbedTLS и может быть собран прямо из коробки с помощью компилятора GCC и утилиты make. Вам потребуется скачать mbedTLS из официального репозитория ARMmbed. Мы рекомендуем выбрать последнюю версию выпуска LTS Yöntem 2.16 для обеспечения актуальных исправлений безопасности.## Установка Эта секция объясняет шаги по получению необходимых файлов и сборке вашего первого приложения с использованием SDK устройства AWS IoT для встроенного C.

Шаги:

• Создайте директорию для хранения вашего приложения, например (/home/пользователь/aws_iot/my_app)
• Измените текущую директорию на новую
• Скачайте SDK на устройство и поместите в созданную директорию
• Распакуйте архив (tar -xf <tarball.tar>). Это создаст следующие директории:
  • certs — директория сертификатов TLS
  • docs — документация API и файлов SDK. Эта папка отсутствует на GitHub. Вы можете получить доступ к документации здесь
  • external_libs — исходные файлы mbedTLS и jsmn
  • include — заголовочные файлы AWS IoT SDK
  • platform — платформенно-зависимые файлы для слоев таймера, TLS и многопоточности
  • samples — образцы приложений
  • src — исходные файлы AWS IoT SDK
  • tests — содержит тесты для проверки корректной работы SDK. Дополнительная информация доступна здесь
• Узнайте больше информации о том, как использовать SDK, в файле README для образцов, который можно найти здесь. Кроме того, для примера с пошаговым руководством по началу работы с Thing Shadow посетите интерактивное руководство консоли AWS IoT.## Перенос на различные платформы Поскольку встраиваемые устройства работают на различных системах реального времени и стеках TCP/IP, одной из важнейших целей проектирования SDK устройств является его портабельность. Для получения более подробной информации о том, как сделать этот SDK совместимым с вашими устройствами (например, микроконтроллерами), обратитесь к руководству по переносу.

Перенос с версий 1.x на 2.x

Ветка 2.x вносит несколько изменений в SDK. В этом разделе приведена информация о том, какие изменения потребуются в клиентском приложении для перехода от версии 1.x к 2.x.* Первое изменение касается структуры папок. Клиентским приложениям, использующим SDK, теперь требуется хранить только папки с сертификатами, внешними библиотеками, заголовочными файлами, исходными файлами и платформой в своём приложении. Описание папок можно найти выше.

• Все заголовочные файлы SDK находятся в папке include. Эти файлы должны быть добавлены в файл Makefile как директории для включения.
• Исходные файлы расположены в папке src. Эти файлы также должны быть добавлены в файл Makefile как одна из директорий источников.
• Подобно версии 1.x, папка platform содержит заголовочные и исходные файлы, специфичные для конкретной платформы. Эти файлы также должны быть добавлены в файл Makefile.
• Папка platform/threading должна быть добавлена только в случае необходимости многопоточной работы, а макрос _ENABLE_THREAD_SUPPORT_ должен быть определён в конфигурации.
• Ниже представлено соответствие для перехода с основных API, использовавшихся в версии 1.x, на новые API:

 | Отмена подписки | ```IoT_Error_t aws_iot_mqtt_unsubscribe(char *pTopic);``` | ```IoT_Error_t aws_iot_mqtt_unsubscribe(AWS_IoT_Client *pClient, const char *pTopicFilter, uint16_t topicFilterLen);``` |
 | Управление потоком | ```IoT_Error_t aws_iot_mqtt_yield(int timeout);``` | ```IoT_Error_t aws_iot_mqtt_yield(AWS_IoT_Client *pClient, uint32_t timeout_ms);``` |
 | Публикация | ```IoT_Error_t aws_iot_mqtt_publish(MQTTPublishParams *pParams);``` | ```IoT_Error_t aws_iot_mqtt_publish(AWS_IoT_Client *pClient, const char *pTopicName, uint16_t topicNameLen, IoT_Publish_Message_Params *pParams);``` |
 | Разрыв соединения | ```IoT_Error_t aws_iot_mqtt_disconnect(void);``` | ```IoT_Error_t aws_iot_mqtt_disconnect(AWS_IoT_Client *pClient);``` |

Дополнительную информацию о том, как использовать новые API, можно найти в файле README, который доступен здесь## Обновление с версии 2.x до 3.x AWS IoT Device SDK для встраиваемых систем на языке C версия 3.0.0 исправляет две ошибки (см. #152 и #155), которые могут привести к переполнению буфера. Эта версия несовместима в обратную сторону с предыдущими версиями, поэтому пользователям потребуется пере компилировать свои приложения с новой версией.

Пользователям AWS IoT Device Shadows или функций работы с JSON, таких как extractClientToken, emptyJsonWithClientToken, isJsonValidAndParse и isReceivedJsonValid, рекомендуется обновиться до версии v3.0.0. Для пользователей, которые не могут обновиться, следует проверить все части решения, где пользовательский ввод может быть отправлен на устройство, и обеспечить достаточную авторизацию этих операций.

Подробности необходимых изменений в публичных функциях и данных структур показаны ниже:

Изменения в структуре данных jsonStruct:

Добавлена переменная dataLength к структуре jsonStruct, которая объявляется в include/aws_iot_shadow_json_data.h.

struct jsonStruct {
    const char *         pKey;
    void *               pData;
    size_t               dataLength;
    JsonPrimitiveType    type;
    JsonStructCallback_t cb;
};

Размер буфера pData теперь должен быть указан через dataLength. Не указание этого значения может привести к непредвиденному поведению. Ниже представлены примеры изменений кода, необходимых для использования нового jsonStruct.С примитивным типом данных, таким как int32_t:

…
jsonStruct_t exampleJsonStruct;
int32_t value = 0L;

/* Установка полей структуры exampleJsonStruct. */
exampleJsonStruct.pKey = "exampleKey";
exampleJsonStruct.pData = &value;
exampleJsonStruct.type = SHADOW_JSON_INT32;
exampleJsonStruct.cb = exampleCallback;

/* Регистрация дельты обратного вызова с использованием example JsonStruct. */
aws_iot_shadow_register_delta(&mqttClient, &exampleJsonStruct);
…

Версия 3.0.0 будет требовать следующий код:

…
jsonStruct_t exampleJsonStruct;
int32_t value = 0L;

/* Установка полей структуры exampleJsonStruct. */
exampleJsonStruct.pKey = "exampleKey";
exampleJsonStruct.pData = &value;
exampleJsonStruct.dataLength = sizeof(int32_t); /* sizeof(value) также допустимо. */
exampleJsonStruct.type = SHADOW_JSON_INT32;
exampleJsonStruct.cb = exampleCallback;
/* Регистрация дельты обратного вызова с использованием example JsonStruct. */
aws_iot_shadow_register_delta(&mqttClient, &exampleJsonStruct);
…

С использованием строки данных версии до v2.3.0 требуются следующие строки кода:

…
jsonStruct_t exampleJsonStruct;
char stringBuffer[SIZE_OF_BUFFER];
/* Установка полей exampleJsonStruct. */
exampleJsonStruct.pKey = "exampleKey";
exampleJsonStruct.pData = stringBuffer;
exampleJsonStruct.type = SHADOW_JSON_STRING;
exampleJsonStruct.cb = exampleCallback;
/* Регистрация дельты обратного вызова с использованием example JsonStruct. */
aws_iot_shadow_register_delta(&mqttClient, &exampleJsonStruct);
…
``````c
…
jsonStruct_t exampleJsonStruct;
char stringBuffer[SIZE_OF_BUFFER];
/* Установка полей exampleJsonStruct. */
exampleJsonStruct.pKey = "exampleKey";
exampleJsonStruct.pData = stringBuffer;
exampleJsonStruct.dataLength = SIZE_OF_BUFFER;
exampleJsonStruct.type = SHADOW_JSON_STRING;
exampleJsonStruct.cb = exampleCallback;
/* Регистрация обратного вызова изменения состояния с помощью example JsonStruct. */
aws_iot_shadow_register_delta(&mqttClient, &exampleJsonStruct);
…
```### Изменения в функции parseStringValue:
Функция `parseStringValue`, объявленная в [include/aws_iot_json_utils.h](include/aws_iot_json_utils.h#L179) и реализованная в [src/aws_iot_json_utils.c](src/aws_iot_json_utils.c#L184), теперь требует указание размера буфера. Её новое сигнатур выглядит так:

```c
IoT_Error_t parseStringValue(char *buf, size_t bufLen, const char *jsonString, jsmntok_t *token);

Ниже приведён пример изменений кода, необходимых для использования нового parseStringValue.

До версии v2.3.0:

…
char* jsonString = “…”; 
jsmntok_t jsmnTokens[NUMBER_OF_JSMN_TOKENS]; 
char stringBuffer[SIZE_OF_BUFFER]; 
parseStringValue(stringBuffer, jsonString, jsmnTokens); 
…

Версия OnClickListener 3.0.0 будет требовать следующий код:

…
char* jsonString = “…”; 
jsmntok_t jsmnTokens[NUMBER_OF_JSMN_TOKENS]; 
char stringBuffer[SIZE_OF_BUFFER]; 
parseStringValue(stringBuffer, SIZE_OF_BUFFER, jsonString, jsmnTokens); 
…

Изменения в функциях предназначенных для внутреннего использования:

Версия 3.0.0 меняет сигнатуру четырех функций, предназначенных для внутреннего использования. Новые сигнатуры явно передают информацию о размере буфера или JSON документа, передаваемого как параметра функциям. Пользователи SDK могут потребовать изменения своего кода и перекомпиляцию для применения этих изменений. Мы отчетливо представляем старые и новые сигнатуры ниже.#### Устаревшие сигнатуры:

bool extractClientToken(const char *pJsonDocument, char *pExtractedClientToken);

static void emptyJsonWithClientToken(char *pBuffer);

bool isJsonValidAndParse(const char *pJsonDocument, void *pJsonHandler, int32_t *pTokenCount);
```bool isReceivedJsonValid(const char *pJsonDocument);

Новые сигнатуры:

bool extractClientToken(const char *pJsonDocument, size_t json_size, char *pExtractedClientToken, size_t client_token_size);

static void emptyJsonWithClientToken(char *pBuffer, size_t buffer_size);

bool isJsonValidAndParse(const char *pJsonDocument, size_t json_size, void *pJsonHandler, int32_t *pTokenCount);

bool isReceivedJsonValid(const char *pJsonDocument, size_t json_size);

Ресурсы

Документация API

Спецификация MQTT 3.1.1

Поддержка

Если у вас есть технические вопросы по AWS IoT Device SDK, используйте форум AWS IoT. Для любых других вопросов по AWS IoT обратитесь в службу поддержки AWS.

Примеры API

Подключение к платформе MQTT AWS IoT

AWS_IoT_Client client;
rc = aws_iot_mqtt_init(&client, &iotInitParams);
rc = aws_iot_mqtt_connect(&client, &iotConnectParams);

Подписка на тему

AWS_IoT_Client client;
rc = aws_iot_mqtt_subscribe(&client, "sdkTest/sub", OnClickListener, QOS0, iot_subscribe_callback_handler, NULL);

Обновление Thing Shadow с устройства

rc = aws_iot_shadow_update(&mqttClient, AWS_IOT_MY_THING_NAME, pJsonDocumentBuffer, ShadowUpdateStatusCallback, 
                           pCallbackContext, TIMEOUT_4SEC, persistenSubscription);