This tutorial serves as an entry point for those who are interested in hooking up STM32 WiFi devices to Xively.
The steps below describe how to upload and run a pre-built Xively demo application on an STM32F4xx-Nucleo WiFi development board. No compilation of sources or link step is required at all.
- Nucleo board - STMicroelectronics STM32F4xx-NUCLEO. We use the Nucleo-F401RE
- Wi-Fi Expansion board - X-NUCLEO-IDW01M1™
- Sensor Expansion board - X-NUCLEO-IKS01A1™ or X-NUCLEO-IKS01A2™
These are the dependencies you'll need to install for this tutorial.
Prerequisite: Ensure that you have the most recent version of JAVA JRE or JAVA SDK installed. If not, install the Java JRE or Java SDK from Oracle download page.
System Workbench for STM32 is required to produce firmware images for STM32 devices. The installer will install an Eclipse-based IDE, a toolchain for cross compiling from your host PC to the target device, and serve as an interface for flashing images onto your STM32F4 Nucleo board.
- Go to the System Workbench for STM32 Installer download page.
- Scroll to your host platform and download the corresponding installer.
For Windows Users: execute the Installer and accept all of the defaults, and move on to the next step of this tutorial Download Xively C Client.
For MacOSX and Linux users: you will need to grant execution privileges to the installer before executing it:
- Open a terminal session to Installer File.
chmod +x <installation_file_name>For instance, on MacOSX this would be
chmod +x install_sw4stm32_macos_64bits-v2.3.run
- Execute the installer by running the installation file. For example, on MacOSX
Download the library source code from xively-client-c.
If you're running a Windows host machine, you will need to download and run the ST-LINK drivers. Without these drivers the IDE will report that it cannot communicate with your STM32F4 Nucleo board when attempting to flash the device.
- Open the
- In the menu, select
File->Importto open up the Import Menu.
General->Existing Projects into Workspaceand click
- Click the
Browsebutton next to the
Select root directorylabel.
- Find and highlight the
xively-client-c/examples/stm32folder and click
- In the Projects window, select only the following project xively_demo_stm32f4xx-nucleo-wifi
- In the Eclipse IDE, right-click the project name.
- Click on
Program Chip...- this will upload the pre-built application to the chip
Warning: known issue in Eclipse
Program Chip... list may contain no binaries to flash despite the binary is there. Refreshing the project may solve the issue: highlight the project in the Project Explorer and the hit
- To launch the Xively Application just push the reset button on the Nucleo board.
- The application emits status messages on UART. To capture these you'll need a serial terminal application running on the computer the device is connected to.
- The preferred serial terminal is coolTerm, due to the character transmission delay feature explained below. Settings: 115200 baud, 8 data bits, No parity, 1 stop bit
- At this point, the Xively Application is running on the device but unable to connect to any WiFi nor to Xively Service. Next two steps describe how to acquire Xively credentials, and how to upload them to the device along with the WiFi ones.
You should have a Xively account already created, but if you do not, register one for free at Xively.com.
Before connecting a physical device to Xively, create its digital representation in the system. Log into the Xively management app to complete the following steps.
This operation will create a device template and a device instance in Xively to represent your hardware setup.
- Click on
Add another device.
- From the pop-up window select
Choose from our template libraryand click
- From the sections tabs at the top of the window go to
Quickstart Kits, select your kit, and click
In order for your device to securely talk to Xively it needs credentials that it will use to authenticate itself as a valid device within your account.
- Go to
All devicesand look for your sample device. Click on its name.
- Click on
Save it for later, it will be needed in the next step.
- Click on Xively Device ID and Xively Account ID to copy them to clipboard.
The Device ID and the Password will be used to establish the MQTT connection from the device. The Account ID and Device ID are both used to create the name of the device's MQTT topics. That will all be handled by the example application. Write them down, or come back to this page when you're ready to configure your device.
This step describes how to tell the device your Wi-Fi SSID and password, as well as the Xively Credentials you just created. In this example, we'll manually upload them to the device via UART using a serial terminal.
Known Serial Terminal to STM32 device communication issue
This step incorporates sending strings from the serial terminal to the device. We've experienced character losses during this process when using copy/paste.
Good news is the issue is identified: the terminal may send the characters faster than the device is able to read them, resulting in mangled data. Some terminals have the option to include a delay between characters, solving this issue. This option is available in coolTerm as character transmission delay.
The coolTerm options: common serial communication settings (left) and the character transmit delay to prevent character loss during (right) sending Wi-Fi SSID/pwd and Xively Credentials.
Common serial terminal settings for STM32 board communication:
- Baud Rate: 115200bps
- 8 data bits, No parity, 1 stop bit
Options->Transmit->Use transmit character delayto 3ms
The first time you run the Xively Application on a given device, it will ask for WiFi SSID, password and encryption type. Next it will ask for Xively Credentials: Account ID, Device ID and Device Password. You can get these IDs from your Xively Account's device page described in the previous step. The Xively Application will store these settings on the device's flash and use it in subsequent runs.
To Change Credentials on the Device
You can update these settings anytime by restarting the device and holding the user button pressed during the boot. This will let you update the settings the same way you did the first time.
Setting the Wi-Fi (left) and Xively (right) Credentials for the STM32 board through serial terminal (coolTerm).
Aaaaand all set. At this point, the STM32 board is expected to be connected to the Xively Service. To validate the connectivity of your device you can check the device's UART output for outgoing messages, and Xively's Product Launcher page for the same messages being received.