Installing AWS IoT Core - FreeWaveTechnologies/ZumIQ GitHub Wiki

Installing AWS IoT Core on a ZumIQ

Introduction

This is based on the "Getting Started" tutorials on the AWS website. It adheres closely to the instructions there, but it resolves some ambiguities in the official instructions, as noted below.

Sources:

Getting Started with AWS IoT

AWS IoT SDK Tutorials

Using the AWS IoT Embedded C SDK

The ZumIQ wiki FAQ

Installing the AWS CLI

AWS CLI User Guide

Create a Thing, a Certificate and a Policy on your AWS account

Sign into the AWS IoT console as described here.
Register your device by following the instructions here. Note the following details.

a. Step 2 - If you've already created a Thing, then you won't see the "You don't have any things yet" message. Click on "Create" in the upper-right corner to create a new Thing.

b. Step 4 - Give it a name like "ZumIQ3050", where "ZumIQ" is the model name and "3050" is the last 4 digits of the serial number.

c. Step 6 - You want to end up with three (3) certificates and an AmazonRootCA1.pem file stored in a directory on your PC. To create the AmazonRootCA1.pem file:
```
i. In the "Certificate Created!" window, click "A root CA for AWS Download".

ii. Click "AmazonRootCA1".

iii. The webpage will display the contents of the root CA. Press
    Control-S on your keyboard to save the root CA as a file, 
    in  the same directory as your certificates.

iv. If steps i. and ii. opened two additional tabs in your
   browser, close the tabs.
```
d. Step 9 - on the Create a Policy page, again give it a meaningful name, like "ZumIQ policy".
Do not click Next> at the bottom of the page, which will take you to the "Create and Activate a Device Certificate" page. This will walk you through creating a second set of certificates, which will cause problems when you try to run the AWS IoT Core.

Start up the ZumIQ device

Connect the ZumIQ to your PC using a USB A to micro USB cable. This will allow you to communicate with the ZumIQ through a serial interface and a terminal emulator program such as TeraTerm or PuTTY.
Connect the ZumIQ to your network using an Ethernet cable. This will also allow the ZumIQ to connect to the AWS cloud servers. It will also allow you to communicate with the ZumIQ through its web-based interface, and optionally via SSH if desired.
Connect the ZumIQ to the power supply included with the ZumIQ, or to a DC power supply rated at 6-30VDC, and at least 2W.
The ZumIQ will go through a boot sequence, as indicated by flashing sequences on the COM1 and COM2 LEDs. At the end of the boot sequence, the CD LED will be solid red or green, and the TX and RX LEDs will be dark. Both LEDs on the Ethernet port will be green, blinking whenever network traffic is detected.

Connect your PC to the ZumIQ device via the serial port

On a Windows 10 PC, click the Start button. In the "Type here to search" window, type "device manager" and press Enter. The Device Manager window opens. Expand the "Ports (COM and LPT)" item, and make a note of the COM port corresponding to the ZumIQ. It may be "COM8", for example.

HINT: If it's not clear which port corresponds to the ZumIQ, unplug the USB cable. You should see a COM port disappear from the list. Reconnect the USB cable and make a note of the new COM port that appears.
Open a terminal emulator program like TeraTerm or PuTTY. Create a Serial connection, specifying the COM port from step 1, and a speed of 9600 bps.
Press Enter repeatedly until the freewave-ib login: prompt appears.
The default login is devuser, and the default password is devuser.

Check the firmware revision and licensing

At the devuser@freewave-ib:~$ prompt, enter the command cliBridge. This takes you to the FreeWave Shell, with a > prompt.
At the > prompt, enter the command systemInfo. Verify the contents of the following lines of output:

    deviceFirmwareVersion=FWT1112TB.45
    rteVersion=FWT1120TP.12
    rteTemplateVersion=FWT1120TP.12
    licenses=Custom Apps

The version numbers may be different, but none of the lines should be blank, and the rteVersion and rteTemplateVersion values should be identical. If any of these lines are blank, or the rteVersion and rteTemplateVersion values are not identical, contact [email protected].

Set up the network connection

On a Windows 10 PC, click the Start button. In the left margin of the Start menu, click the Settings icon (the gear). In the Settings window, select Network & Internet. Towards the bottom of the list, select "View your network properties".
Make a note of the Default Gateway setting.
The current version of the ZumIQ does not support DHCP, so you will need to contact your IT support desk to obtain a static IP address for the ZumIQ.
On the ZumIQ, at the > prompt, enter the command network. You should see this response:

    >network
    [Page=network]
       mac_address=xx:xx:xx:xx:xx:xx
       ip_address=192.168.111.100
       netmask=255.255.255.0
       gateway=192.168.111.1
       stpEnabled=false
       txqueuelen=25
       mtu=1500
       netmaskFilterEnabled=false
       nameserver_address1=8.8.8.8
       nameserver_address2=8.8.4.4
       arpFilterEnabled=false
       vlanTag=0

At the > prompt, enter the following commands to change the IP address to the IP address you obtained from the IT support desk, and the gateway to the Default Gateway setting on your computer.

    > network.ip_address=<the new IP address>
    > network.gateway=<the Default Gateway>
    > config.save

To check the network connection, open a browser and enter the IP address of the ZumIQ. If the ZumIQ's "System Info" page appears, then the ZumIQ is configured correctly.
At the > prompt, enter the command exit to return to the devuser@freewave-ib:~$ prompt. Everything else happens from that prompt, which will be abbreviated to $ below.

Install the AWS IoT embedded C SDK

Download the AWS IoT Embedded C SDK from Github, by entering the command:

    $ git clone https://github.com/aws/aws-iot-device-sdk-embedded-C.git  -b release

You should see a new directory, aws-iot-device-sdk-embedded-C.
Download mbedTLS into the SDK's directory. You need to specify the LTS (long term support) version of mbedTLS. As of 11 March 2019, the LTS version is version 2.16. Type the following commands:

    $ cd aws-iot-device-sdk-embedded-C/external_libs
    $ git clone https://github.com/ARMmbed/mbedtls.git -b mbedtls-2.16
    $ rm mbedTLS
    $ mv mbedtls mbedTLS
    $ cd mbedTLS
    $ git status
    On branch mbedtls-2.16
    Your branch is up-to-date with 'origin/mbedtls-2.16'.
    nothing to commit, working tree clean

Copy your certificate, private key, and root CA certificate, from your PC, to the directory aws-iot-device-sdk-embedded-C/certs on the ZumIQ. The contents of the 'certs' directory should be something like this:

    $ ls
    xxxxxxxxxx-certificate.pem.crt.txt
    xxxxxxxxxx-private.pem.key
    AmazonRootCA1.pem
    README.txt

Now the device is ready for compiling and running the sample program.

Compile and run the sample program

Navigate to the directory aws-iot-device-sdk-embedded-C/samples/linux/subscribe_publish_sample .
Edit the file aws_iot_config.h. In the //Get from console section, update the following values:

    // Get from console
    // =================================================
    #define AWS_IOT_MQTT_HOST "a3vddxxxxxxxxx-ats.iot.us-west-2.amazonaws.com"
    #define AWS_IOT_MQTT_PORT              443 ///< default port for MQTT/S
    #define AWS_IOT_MQTT_CLIENT_ID         "zumiq"
    #define AWS_IOT_MY_THING_NAME          "ZumIQ"
    #define AWS_IOT_ROOT_CA_FILENAME       "AmazonRootCA1.pem"
    #define AWS_IOT_CERTIFICATE_FILENAME "xxxxxxxxxx-certificate.pem.crt.txt"
    #define AWS_IOT_PRIVATE_KEY_FILENAME   "xxxxxxxxxx-private.pem.key"
    // =================================================

AWS_IOT_MQTT_HOST is the name of your REST API endpoint. If you don't remember what it is, then open a browser, login to the AWS IoT console and navigate to Manage > Things > the ZumIQ thing that you created > Interact. Near the top, where it says "HTTPS", is the REST API endpoint. It ends in "amazon.aws.com". Copy the entire line and paste it into the file aws_iot_config.h.
You don't need to change AWS_IOT_MQTT_PORT.
AWS_IOT_MQTT_CLIENT_ID is whatever you want. Make it meaningful.
AWS_IOT_MQTT_MY_THING_NAME is whatever you want. Make it meaningful.
AWS_IOT_ROOT_CA_FILENAME is the name of the root CA file in 'certs'.
AWS_IOT_CERTIFICATE_FILENAME is the name of the certificate file in 'certs'.
AWS_IOT_PRIVATE_KEY_FILENAME is the name of the private key file in 'certs'.

The Makefile is in the same directory as aws_iot_config.h. Compile the sample program using the command:

    $ make -f Makefile

This will take a while.

Run the subscribe_publish_sample app by entering the command:

    $ ./subscribe_publish_sample

You will see a lot of initialization text, followed by continuous output like this:

    Subscribing...
    -->sleep
    Subscribe callback
    sdkTest/sub     hello from SDK QOS0 : 0
    Subscribe callback
    sdkTest/sub     hello from SDK QOS1 : 1
    -->sleep
    Subscribe callback
    sdkTest/sub     hello from SDK QOS0 : 2
    Subscribe callback
    sdkTest/sub     hello from SDK QOS1 : 3
    ...
    ...
    ...

If you see similar output, then you have successfully installed AWS IoT Core on the ZumIQ.

Install the AWS Command Line Interface (CLI)

The AWS CLI is a separate application, but it is useful for a lot of AWS work. You must install it using pip (or pip3), the Python Installer Program. The ZumIQ comes with Python and pip installed.

If you try to install the AWS CLI on the ZumIQ using the suggested command

    $ pip install awscli --upgrade --user

you will get the error message 'No space left on device'. You need to tell pip to use a different tmp directory, one with more space. See Step 1 below.

Install the AWS CLI using these two commands:

    $ mkdir /home/devuser/tmp
    $ pip install awscli --upgrade --user -b /home/devuser/tmp

Verify that the AWS CLI has been installed:

    $ type -a aws
    aws is /home/devuser/.local/bin/aws

Add the AWS path to your PATH variable, by adding these lines to the end of /home/devuser/.profile or /home/devuser/.bashrc file:

    if [ -d "$HOME/.local/bin" ] ; then
        PATH="$HOME/.local/bin:$PATH"
    fi

To configure the AWS CLI, you will need the AWS Access Key ID and AWS Secret Access Key that you got when you first created the AWS IAM user or role associated with your account. You may have them saved in a file somewhere, or you may have them stored in Windows or Linux environmental variables. If you can't find them, you will have to create new ones. Instructions on creating new keys are under "Access Key and Secret Access Key" here.
Once you know where the keys are, you can copy and paste them as appropriate into the 'aws configure' command:

    $ aws configure
    AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
    AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    Default region name [None]: us-west-2
    Default output format [None]: json

Specify the region as us-west-2 and the default output format as json.

The AWS CLI uses groff to format its help output. If groff isn't installed on your device, you will need to install it.

    $ type -a groff
    (if it returns 'bash: type: groff: not found': )
    $ sudo apt-get update
    $ sudo apt-get upgrade
    $ sudo apt-get install groff

To verify that groff is installed and working, try a help command, like:

    $ aws ec2 help

You should see nicely formatted help output.