Skip to content

FAQ.md

Latest commit

 

History

History
203 lines (154 loc) · 11.5 KB

FAQ.md

File metadata and controls

203 lines (154 loc) · 11.5 KB

Frequently Asked Questions

Jump To:

Where should I start?

If you are just getting started, make sure you install this SDK and then build and run the X509 PubSub sample.

How do I enable logging?

#include <aws/crt/Api.h>

Aws::Crt::ApiHandle apiHandle;
apiHandle.InitializeLogging(Aws::Crt::LogLevel::Debug, stderr);

LogLevel: LogLevel has the following options: Trace, Debug, Info, Warn, Error, Fatal, or None. Defaults to Warn.

You can also enable CloudWatch logging for IoT which will provide you with additional information that is not available on the client side SDK.

How do I get more information from an error code?

When you encounter error codes in the SDK, you can use ErrorDebugString() to get a human-readable error message:

#include <aws/crt/Api.h>

printf("Error occurred: %s\n", ErrorDebugString(LastError()));

This function converts error codes into descriptive strings that help identify the specific issue.

I keep getting AWS_ERROR_MQTT_UNEXPECTED_HANGUP

This could be many different things, but it is most likely a policy issue. Start by using a super permissive IAM policy called AWSIOTFullAccess which looks like this:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iot:*"
            ],
            "Resource": "*"
        }
    ]
}

After getting it working make sure to only allow the actions and resources that you need. More info about IoT IAM policies can be found here.

Dependencies are bad

If you get the following error:

CMake Error at CMakeLists.txt:46 (include):
 include could not find load file:
  AwsFindPackage

Make sure to use --recursive in the git clone command: git clone --recursive https://github.com/aws/aws-iot-device-sdk-cpp-v2.git

If you have already downloaded this repository you can update the submodules with this command: git submodule update --init --recursive

Detecting connection loss (tldr use keepAliveTimeSecs and pingTimeoutMs)

There are 3 mechanisms for detecting connection loss:

  1. The keepAliveTimeSecs and pingTimeoutMs arguments passed to MqttConnection::Connect(). These control how often the SDK sends a PINGREQ, and how long the SDK will wait for a PINGRESP before assuming the connection is lost. YOU SHOULD USE THIS TO RELIABLY DETECT CONNECTION LOSS.
  2. If the OS socket says it's closed, the SDK immediately tries to reconnect. The timing of this is not reliable, it depends on the OS and how the connection is lost, it can take many minutes.
  3. The various TcpKeepAlive controls on the MqttClientConnectionConfigBuilder. These control a similar mechanism at the TCP layer, rather than the MQTT layer, but is implemented in the OS and behavior may vary across platforms

How to use a Pre-Built aws-crt-cpp (Most useful for development of this package)

Turning off the BUILD_DEPS option allows you to use your own pre-built AWS CRT dependencies instead of the bundled submodules. This is useful when you want to share dependencies across multiple projects (for example, sharing the aws-crt-cpp dependency with aws-sdk-cpp).

mkdir aws-iot-device-sdk-cpp-v2-build
cd aws-iot-device-sdk-cpp-v2-build
cmake -DCMAKE_INSTALL_PREFIX="<absolute path sdk-cpp-workspace dir>"  -DCMAKE_PREFIX_PATH="<absolute path sdk-cpp-workspace dir>" -DBUILD_DEPS=OFF ../aws-iot-device-sdk-cpp-v2
cmake --build . --target install

How to use USE_EXTERNAL_DEPS_SOURCES to build with external dependencies

The USE_EXTERNAL_DEPS_SOURCES option allows you to use your own external source directories for AWS CRT dependencies instead of the bundled submodules. Build Steps:

  1. Configure build options - Update your CMakeLists.txt to set the required flags. Set BUILD_DEPS to OFF and USE_EXTERNAL_DEPS_SOURCES to ON:

    option(BUILD_DEPS "Builds aws common runtime dependencies as part of build. Turn off if you want to control your dependency chain." OFF)
option(USE_EXTERNAL_DEPS_SOURCES "Use dependencies provided by add_subdirectory command" ON)

  2. Set up CMake module path - The aws-crt-cpp library requires certain CMake modules that are defined in aws-c-common. Add it to your CMake modules:

    add_subdirectory(<path-to-aws-c-common>/aws-c-common <binary-dir>/aws-c-common)
list(APPEND CMAKE_MODULE_PATH "${aws-c-common_SOURCE_DIR}/cmake")

  3. Add required dependencies - The following three dependencies are required as a minimum. You can also add other source dependencies as needed. Add them using add_subdirectory (or higher-level commands that use add_subdirectory, like FetchContent):

    • aws-c-common
    • aws-crt-cpp
    • aws-c-iot
    add_subdirectory(<path-to-aws-c-common>/aws-c-common <binary-dir>/aws-c-common)
add_subdirectory(<path-to-aws-crt-cpp>/aws-crt-cpp  <binary-dir>/aws-crt-cpp)
add_subdirectory(<path-to-aws-c-iot>/aws-c-iot  <binary-dir>/aws-c-iot)

Common Issues:

  • Missing submodules: While using FetchContent or ExternalProject_Add, remember to set GIT_SUBMODULES_RECURSE to make sure the library pulls the submodules.

I am experiencing deadlocks

You MUST NOT perform blocking operations on any callback, or you will cause a deadlock. For example: in the on_publish_received callback, do not send a publish, and then wait for the future to complete within the callback. The Client cannot do work until your callback returns, so the thread will be stuck.

How to debug in VSCode?

Here is an example launch.json file to run the x509 pubsub sample:

{
   // Use IntelliSense to learn about possible attributes.
   // Hover to view descriptions of existing attributes.
   // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
   "version": "0.2.0",
   "configurations": [
       {
           "name": "X509 PubSub",
           "type": "cppdbg",
           "request": "launch",
           "program": "${workspaceFolder}/samples/mqtt/mqtt5_x509/build/mqtt5_x509",
           "args": [
               "--endpoint", "<account-number>-ats.iot.<region>.amazonaws.com",
               "--cert", "<path to cert>",
               "--key", "<path to key>"
           ]
       }
   ]
}

What certificates do I need?

  • You can download pre-generated certificates from the AWS console (this is the simplest and is recommended for testing)
  • You can also generate your own certificates to fit your specific use case. You can find documentation for that here and here
  • Certificates that you will need to run the samples
    • Root CA Certificates
      • Download the root CA certificate file that corresponds to the type of data endpoint and cipher suite you're using (You most likely want Amazon Root CA 1)
      • Generated and provided by Amazon. You can download it here or download it when getting the other certificates from the AWS console
    • Device certificate
      • Intermediate device certificate that is used to generate the key below
      • When using samples it can look like this: --cert abcde12345-certificate.pem.crt
    • Key files
      • You should have generated/downloaded private and public keys that will be used to verify that communications are coming from you
      • When using samples you only need the private key and it will look like this: --key abcde12345-private.pem.key

Where can I find MQTT 3.1.1 Samples?

The MQTT 3.1.1 samples can be found in the v1.40.0 samples folder here

Certificate and Private Key Usage Across Different Versions of the SDK on macOS

A certificate and private key pair cannot be shared on a macOS device between aws-iot-device-sdk-cpp-v2 v1.41.0 and any other versions. In the update to v1.41.0 we migrated macOS from using Apple's deprecated Security Framework to SecItem API. In doing so, certificate and private keys are imported in a non-backwards compatible manner into the Apple Keychain.

Manual Publish Acknowledgement and QoS 1 Redelivery

When using manual publish acknowledgement, there are two important behaviors to be aware of regarding QoS 1 message redelivery:

Broker redelivery of unacknowledged publishes

The AWS IoT broker will periodically resend unacknowledged QoS 1 PUBLISH packets. These redeliveries should be treated as duplicates even if the DUP flag in the PUBLISH packet is not set. If the manual publish acknowledgement is not acquired again for a redelivered packet, the acknowledgement will be sent automatically.

Session resumption after disconnect/reconnect

Upon a disconnect and reconnect of the MQTT5 client, if a session is resumed, any previously acquired acknowledgement handle is void. The broker will resend the unacknowledged PUBLISH packet, and the acknowledgement must be reacquired from that resent packet. If the resent packet is not handled for manual acknowledgement, the acknowledgement will be sent automatically.

I still have more questions about this SDK?