AWS IoT Firmware
Firmware code for AWS IoT Devices
AWS IoT Firmware Documentation

AWS IoT Device

Overview

This repo contains the device code running mongoose OS connecting to AWS mqtt server

How the system works

The system works by having a general function(handleAllReq in master_handler.cpp) handles all the initial request and then forward it to the correct one based on the message types, for Alexa events, the children of the ParentHandler class are used to fulfill them

All handler are children of the ParentHandler class which declares a few abstract methods that the handler must implment to fit into the system, typically, when a request is passed onto a handler, its job is to act on the request, then compose a message appropriate to its type of namespace and then return the reply, which will be sent by the general handler function to the lambda function on aws cloud throught mqtt

The device_config.hpp files are used to let the general handler function know more about the system(like which mqtt channel to sub/pub to), the device_config also carry customized info like the pin numbers of control pin used by the handler, the device_config.hpp file also define a few macros that must be implemented to initialize the handler list that the user implemented

The format specifier to the aws iot reply is stored in the aws_iot_fmt.hpp in the based_framework folder since aws iot devices that implement the same endpoints share the same reply format

Doxygen docs

Doxygen docs is hosted on readthedocs, as such it is Doxygen under the guise of Sphinx, every device and the base framework has its own module(aka Doxygen group), to add more devices to the docs, simply follow the appropriate syntax of doxygen to add a group and then add the directory of that device into the Doxyfile INPUT list

Docs Link

Backend of IoT

This project uses AWS lambda for triaging requests from Alexa, the essential detail of the request is passed onto the correct device thanks to a database corresponding between endpoint ID and the channel that the device pub/sub to

Replies from the devices are sent to the lambda function, then attched with more details to fit Alexa smart home json response format and then sent back to Alexa

The code for the lambda function backend is stored in another repo

Device List

Directory structure

NOTE: Some directories appear in the source code but are not present on github since they are sensitive files containing things like private key, wifi password, etc

Repo directory structure

Device code directory structure

All devices have a docs folder carrying their speciifc docs

based_framework code

device specific handler code (like bed_room_light_controller or pc_controller)

Most of the files in the fs/ dir are not on the public repo due to its sensitive nature, but yours should look like this(with file name matching the picture):

You can get those files by registering the devices on aws iot core console and download the file

Special notes about the ca_cert.pem: amazon will give you a list of certificates authorities files to download, just concatcenate all of them into one file and named it ca_cert.pem, the reason is that the server might choose a different ca_cert to talk with your devices so having all certs in one file make it harder to not have the correct certs, although if you are tight on memory, you might just need to find out which certs aws use consistently with your devices

Shell scripts documentation

To use it, launch the script with the folder name you want

1 ./device_init pc_controller/

For example, to flash the connected device with pc_controller code:

1 ./mongoose_setup.sh pc_controller/

Implementing a new aws devices

The code structure is designed to make implementing new devices as quickly as possible

For example, if we want to implement an iot device named pc_controller

1 ./device_init pc_controller/ # create new device structure
2 
3 #----------------------begin filling out info------------------------------
4 nano pc_controller/credentials/mongoose_info.sh # fill in devices info here
5 
6 # then go to aws iot core to register your devices, and then download the public, private keys,
7 # the certificate and certificate authority to the fs folder of the device,
8 # name them respectively according to the picture above
9 
10 # adjust mos.yml file according to your needs, remember to change things like device name,
11 # device ID, as well as the list of libraries you need
12 nano pc_controller/mos.yml
13 
14 # change the macro based on your devices, specific documentation can be found in
15 # the example devices folder, but mainly you will need to implement how
16 # to initialize handler list and how to regsiter the interrupts you need(leave blank if you don't need any)
17 nano pc_controller/device_config.hpp
18 
19 # implement the polling function, this function is called regularly when no major events are happening, if there is no need just leave it empty
20 nano pc_controller/polling_function.cpp
21 
22 # Then start writing your handler classes, all handler classes must derive from the
23 # ParentHandler class found in the parent_handler folder in the based_framework folder,
24 # for implementation example, check the docs of the example devices implemented
25 
26 #--------------------------Flashing and testing-----------------------------
27 ./mongoose_setup.sh pc_controller/ # compile the code, flash it to devices and open a console to the device