IoT#
This example demonstrates how to control GPIO using MQTT.
Networking configuration#
In this example, we demonstrate using the Eclipse Mosquitto MQTT broker. Ensure that you have installed Mosquitto by following the instructions here: https://mosquitto.org/download/.
Note
You can modify the example code to connect to a different MQTT broker. When doing so, you will also need to modify the filesystem setup scripts before running them. This is to ensure that the correct client certificate, private key, and CA certificate are flashed. See filesystem_support/create_fs.sh
and the instructions for setting up the filesystem below.
Next, configure the example software to connect to the proper MQTT broker. If you are running the MQTT broker on your local PC, you will need to know that PC’s IP address. This can be determined a number of ways including the ifconfig
and ipconfig
commands in Linux/macoS and Windows operating systems, respectively.
Lastly, in appconf.h
, set appconfMQTT_HOSTNAME
to your MQTT broker IP address or URL:
#define appconfMQTT_HOSTNAME "your endpoint here"
Deploying the firmware with Linux or macOS#
Building the firmware#
Run the following commands in the repo’s root folder:
cmake -B build -DCMAKE_TOOLCHAIN_FILE=xmos_cmake_toolchain/xs3a.cmake
cd build
make example_freertos_iot
Setting up the hardware#
Note
The host applications are required to create the filesystem. See the installation instructions for more information.
Before the demo can be run, the filesystem must be configured and flashed.
make flash_app_example_freertos_iot
The script will create TLS credentials and prompt you for WiFi credentials:
Enter the WiFi network SSID:
Enter the WiFi network password:
Enter the security (0=open, 1=WEP, 2=WPA):
Add another WiFi network? y/[n]:
Enter the MQTT server's IP/hostname:
Note
The MQTT server’s IP/hostname is what is entered into the “Common Name” (CN) of the certification generation process. If a hostname was specified for the MQTT server, a DNS server must be available that is configured to resolve that name.
Note
Once these files have been created they will be automatically be used. If the WiFi profile or MQTT certificates/keys
need to be changed, delete the corresponding components (i.e. networks.dat
or files contained in mqtt_broker_certs
).
Running the firmware#
Run the following commands in the repo’s build folder:
make run_example_freertos_iot
Deploying the firmware with Windows#
In order to generate the certificates/keys, OpenSSL
must be installed. There are various options for obtaining
a Windows version of OpenSSL
that include MinGW
and Git
installations as well as standalone installations.
Prior to running the commands below, ensure the host system has been setup to permit PowerShell execution.
By default, Windows systems are set to the Restricted
execution policy, for more information see
about_Execution_Policies. Setting the policy to RemotedSigned
should be sufficient for proper execution; this can be set from an Administrator PowerShell instance via the command:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
Note
These scripts are not digitally signed, so depending on how they were acquired/downloaded, the policy set above may
still prevent execution. These files may be unblocked via PowerShell using the cmdlet Unblock-File
.
Building the firmware#
Run the following commands in the repo’s root folder:
cmake -G "NMake Makefiles" -B build -DCMAKE_TOOLCHAIN_FILE=xmos_cmake_toolchain/xs3a.cmake
cd build
nmake example_freertos_iot
Setting up the hardware#
Note
The host applications are required to create the filesystem. See the installation instructions for more information.
Before the demo can be run, the filesystem must be configured and flashed.
nmake flash_app_example_freertos_iot
The script will create TLS credentials and prompt you for WiFi credentials:
Enter the WiFi network SSID:
Enter the WiFi network password:
Enter the security (0=open, 1=WEP, 2=WPA):
Add another WiFi network? y/[n]:
Enter the MQTT server's IP/hostname:
Note
The MQTT server’s IP/hostname is what is entered into the “Common Name” (CN) of the certification generation process. If a hostname was specified for the MQTT server, a DNS server must be available that is configured to resolve that name.
Note
Once these files have been created they will be automatically be used. If the WiFi profile or MQTT certificates/keys
need to be changed, delete the corresponding components (i.e. networks.dat
or files contained in mqtt_broker_certs
).
Running the firmware#
Run the following commands in the repo’s build folder:
nmake run_example_freertos_iot
Testing MQTT Messages#
Running the broker#
From the root folder of the iot example run:
cd mosquitto
mosquitto -v -c mosquitto.conf
Note
You may need to modify permissions of the cryptocredentials for mosquitto to use them.
Sending messages#
To turn LED 0 on, from the IoT example’s filesystem_support subdirectory, run the following command (replacing <MQTT_SERVER> with the value used during certificate generation):
mosquitto_pub -h <MQTT_SERVER> --cafile mqtt_broker_certs/ca.crt --cert mqtt_broker_certs/client.crt --key mqtt_broker_certs/client.key -d -t "explorer/ledctrl" -m '{"LED": "0", "status": "on"}'
Supported values for “LED” are [“0”, “1”, “2”, “3”], supported values for “status” are [“on”, “off”].