What you will learn

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.

Hardware you will need

• 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™

Step 1 of 4: Installing the necessary tools and dependencies

These are the dependencies you'll need to install for this tutorial.

• System Workbench for STM32
• Xively C Client MQTT library
• ST-LINK drivers for flashing

Install System Workbench for STM32

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.

1. Go to the System Workbench for STM32 Installer download page.
2. 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:

1. Open a terminal session to Installer File.
2. Run chmod +x <installation_file_name> For instance, on MacOSX this would be chmod +x install_sw4stm32_macos_64bits-v2.3.run
3. Execute the installer by running the installation file. For example, on MacOSX ./ install_sw4stm32_macos_64bits-v2.3.run

Download the Xively C Client

Download the library source code from xively-client-c.

Install the ST-LINK USB driver for the STM32F4

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.

Step 2 of 4: Running the prebuilt Xively application

Xively Demo Application project import

1. Open the Eclipse IDE
2. In the menu, select File->Import to open up the Import Menu.
3. Choose General->Existing Projects into Workspace and click Next.
4. Click the Browse button next to the Select root directory label.
5. Find and highlight the xively-client-c/examples/stm32 folder and click Open
6. In the Projects window, select only the following project xively_demo_stm32f4xx-nucleo-wifi
7. Click Finish.

Programming the device

1. In the Eclipse IDE, right-click the project name.
2. Click on Target->Program Chip... - this will upload the pre-built application to the chip

🚧

Warning: known issue in Eclipse

The Target->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 F5

Run the Xively application

1. To launch the Xively Application just push the reset button on the Nucleo board.
2. 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.
3. 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
4. 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.

Step 3 of 4: Create your Xively digital device

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.

Create a Nucleo device template using the Product Launcher

This operation will create a device template and a device instance in Xively to represent your hardware setup.

1. Click on Product Launcher > Add another device.

2. From the pop-up window select Choose from our template library and click Next.

3. From the sections tabs at the top of the window go to Quickstart Kits, select your kit, and click Next.

Get credentials for this device

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.

1. Go to Devices > All devices and look for your sample device. Click on its name.
2. Click on Get password.
   Save it for later, it will be needed in the next step.
3. 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.

Step 4 of 4: Upload the Wi-Fi and Xively Credentials

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.

Common serial terminal settings for STM32 board communication:

• Baud Rate: 115200bps
• 8 data bits, No parity, 1 stop bit
• Options->Transmit->Use transmit character delay to 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.

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.