Latest STM32F4 WiFi SDK Support Under Development

This Tutorial Is currently not supported by the latest Xively C Client source base and Latest STM32 Cube SDK.

STM32 Cube Expansion WIFi SDK 3.1 has breaking changes in the WiFi API, and the WiFi board must be flashed with new firmware to support it. We are currently working with ST Micro to determine the best process for this, and we will update the tutorial once we have the details.

In the meantime you can use our Precompiled Binary Image Tutorial to connect your device to Xively. Instructions for configuring your STM32F4 Nucleo Ethernet or WiFi device an be found in the STM32F4xx Nucleo QuickStart Guide here.

Please contact Xively if you have any questions.

What you will learn

This tutorial will teach you how to build, link, and deploy the Xively Client Library on STM32F4xx-NUCLEO board, and how to connect your device to Xively. This tutorial supports Linux, macOS and Windows.

You must chose between two different internet connection types: Ethernet or Wi-Fi. In the Ethernet project, the Nucleo board itself provides internet connectivity over its Ethernet port. In the Wi-Fi project, a Wi-Fi expansion board X-NUCLEO-IDW01M1 (based on the SWPF01SA WiFi module) sold separately and is attached to the Nucleo board through a simple PIN interface. No soldering is required.

Hardware you will need

Wi-Fi project

Known hardware bug in old X-NUCLEO-IDW01M1 WiFi revisions

There are some Wi-Fi extension boards in the market with a known hardware bug that will cause the Nucleo's firmware flashing process to fail.

Check if your board has resistor R21 soldered in; if it does, remove it.

STM32F401RE Nucleo board (white) with Wi-Fi expansion board X-NUCLEO-IDW01M1 (blue, only used in Wi-Fi project)

STM32F401RE Nucleo board (white) with Wi-Fi expansion board X-NUCLEO-IDW01M1 (blue, only used in Wi-Fi project)

Ethernet project

Ethernet-enabled Nucleo STM32F429ZI board (used in Ethernet project)

Ethernet-enabled Nucleo STM32F429ZI board (used in Ethernet project)

A Note About the Motion MEMS Sensor Expansion board


The A2 model of the sensor board requires some modifications to the demo project, so before using this model of the sensor board make sure you have adjusted your projects accordingly to our guidelines. The required changes will be pointed out using the X-NUCLEO-IKS01A2 symbol

MEMS Sensor expansion boards: X-NUCLEO-IKS01A1 and X-NUCLEO-IKS01A2 (used in Ethernet and Wi-Fi projects)

MEMS Sensor expansion boards: X-NUCLEO-IKS01A1 and X-NUCLEO-IKS01A2 (used in Ethernet and Wi-Fi projects)

Step 1 of 5: Installing the necessary tools and dependencies

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

Following this tutorial on Windows

The software on this tutorial was developed mostly on MacOS; you should be able to follow it step by step on Linux and MacOS.

If you're a Windows user, consider using cygwin to replicate the steps that use make.

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.


As of the writting of this tutorial (August 2017) the toolchain requires that a 32-bit version of the JRE be installed. The 64-bit version may return a build error claiming that the toolchain cannot find a valid 32-bit Java JRE with the 64-bit version. We recommend installing the 32-bit JRE even if your host system is a 64 bit machine.

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
  3. Execute the installer by running the installation file. For example, on MacOSX ./

Install STM32CubeF4

  1. Open the STM32CubeF4™ download page
  2. Navigate to the bottom of the page and click "Get Software" button
  3. Accept the license
  4. Register or Fill in the form
  5. Download and unzip the STM32CubeF4™ SDK

This tutorial assumes that the path to the uncompressed directory is $HOME/Downloads/STM32Cube_FW_F4_V1.14.0/

Install X-CUBE-MEMS1

  1. Open the X-CUBE-MEMS1™ download page
  2. Follow the steps from 2 - 5 from the STM32CubeF4 installation

This tutorial assumes that the path to the uncompressed directory is $HOME/Downloads/STM32Cube_FW_F4_V1.14.0/

Install X-CUBE-WIFI1 - Wi-Fi demo only

  1. Open the X-CUBE-WIFI1™ download page
  2. Follow the steps from 2 - 5 as from the STM32CubeF4 installation

This tutorial assumes that the path to the uncompressed directory is $HOME/Downloads/STM32CubeExpansion_WIFI1_Vx.x.x

Download Xively C Client

Download the library source code from xively-client-c. Git clone the repository or download the source archive from the right side of the github page.

Step 2 of 5: Building Xively C Client

Compilation of Xively C Client

Run the following commands depending on if you're building for the Nucleo WiFi board or the Nucleo Ethernet Board, respectively.

Building for the Wi-Fi project

We need to pass the path to the Wi-Fi SDK expansion and to your toolchain to the makefile command line. the XI_STM32_PATH_SDK should be the path that you've unzipped the X-CUBE-WIFI1 archive you downloaded above. The XI_GCC_ARM_NONE_EABI_PATH will include the toolchain version number in text, which varies often so please update it based on the toolchain you installed on your machine while installing System Workbench above.

For instance:

gmake PRESET=STM32FX_NUCLEO_WIFI XI_STM32_PATH_SDK=c\:\dev\st\STM32CubeExpansion_WIFI1_V3.1.1 XI_GCC_ARM_NONE_EABI_PATH=C:\Ac6\SystemWorkbench\plugins\fr.ac6.mcu.externaltools.arm-none.win32_1.15.0.201708311556\tools\compiler\bin

Building for the Ethernet project

We need to define the path to the STM32 Cube SDK and the path to your toolchain when executing make. The XI_STM32_PATH_SDK should be the path that you unzipped the STM32CubeF4 archive you downloaded above. The XI_GCC_ARM_NONE_EABI_PATH will include the toolchain version number in text, which varies often so please check the path of your installed based on the System Workbench installation location above.

For instance:

make PRESET=STM32FX XI_STM32_PATH_SDK=~/STM32Cube_FW_F4_V1.18.0 XI_GCC_ARM_NONE_EABI_PATH=/Applications/Ac6/

TLS and Windows Host Environments

Xively requires a TLS connection from its devices for security reasons. Because the Ethernet version of the Nucleo board does not include a hardware TLS implementation, we will need to build a third party software library for TLS. The above make command clones the wolfSSL sources from and builds it into a library for you on OSX and Linux. Unfortunately, the WolfSSL build system has some issues on Windows, so you must checkout WolfSSL yourself:

  1. Download version 3.9.6 of WolfSSL from their GitHub repository.
  2. Uncompress the .zip or .tar.gz file.
  3. Move the resulting wolfssl-3.9.6 directory to $XI_CLIENT_C/src/import/tls/, and rename it to wolfssl.

Please see the script src\import\tls\ for more information.

Step 3 of 5: Create your Xively digital device

_You should have a Xively account already created, but if you do not, register one for free at

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.
  1. From the pop-up window select Choose from our template library and click Next.
  1. 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 5: Building Xively's demo application

If everything went well, you should have a file called libxively.a inside the xively-client-c's bin directory. That is the library binary file that will be used by our applications. You're free to modify the library and its BSP, but remember you'll have to re-compile it every time you do; cleaning and re-building your application from Eclipse is not enough.

Now that the MQTT library is ready, let's set up the application's environment and compile everything together into a working binary.

Xively demo application project import

  1. Open System Workbench for STM32
  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 projects:
    • For the Ethernet Project:
      • STM32F429ZI_NUCLEO_144
      • WolfSSL
    • For the Wi-Fi Project:
      • xively_demo_stm32f4xx-nucleo-wifi
  7. Click Finish.
  8. The demo application project now it's ready to be configured

Xively demo application project configuration

  1. In Project Explorer window right click on the project name and choose properties
  2. Click the Resource->Linked Resources
  3. Select STM_CUBE_PATH and click Edit
  4. Click Folder button and navigate to STM32CubeExpansion_WIFI1_V2.1.1 for the Wi-Fi project or STM32Cube_FW_F4_V1.14.0 for the Ethernet project. Finish with clicking OK
  5. Select STM_MEMS_CUBE_PATH and click Edit
  6. Click Folder button and navigate to STM32CubeExpansion_MEMS1_V3.0.0 finish with clicking OK
  7. Select XI_CLIENT_PATH and click Edit
  8. Click Folder and navigate to xively-client-c confirm and click OK
  9. From left side menu select C/C++ Build->Build Variables
  10. Note those can also be called XI_STMCUBE_PATH and XI_MEMS_CUBE_PATH depending on the version you're running
  11. Confirm changes with Apply and Ok

In the left bar of the "Properties" window, select C/C++ Build->Build Variables and repeat the same process.


In order to make the xively demo application to work on X-NUCLEO-IKS01A2 you have to replace the Drivers/BSP/Components/X_NUCLEO_IKS01A1 folder in the project settings with the Drivers/BSP/Components/X_NUCLEO_IKS01A2. In order to do that find this directory in Project Explorer and simply delete it. Next drag & drop directory STM32CubeExpansion_MEMS1_V3.0.0/Drivers/BSP/X_NUCLEO_IKS01A2 directly under the Drivers/BSP in Eclipse's Project Explorer.

Configuring Your Credentials for the Device

By default the application will prompt you for your Xively and WiFi credentials via the serial command line interface at runtime. You will need to setup a connection with a serial terminal program if you wish to enter your credentials this way. For more information on setting up a serial connection, please see Appendix A: Connecting To Device Over Serial. You can subsequently update your credentials by holding down the blue "User" button on the device during boot.

Alternatively you can compile-in your credentials by altering your source code.

In the Wi-Fi project, the credentials can be found in Src/main.c.
In the Ethernet project, the credentials can be found Src/xively_client.c.

In Project Explorer go to Example->User->main.c and search for:


Update the 0, to 1. and the subsequent code section simply cut and paste the credentials into the respective strings.

For WiFi connections, you can choose your WiFi security type. By default this is WPA_Personal, but you can select fro the following constants:


Compiling Xively demo application

Now you are ready to compile the project.

WiFi Project

  1. Right click on the xively_demo_stm32f4xx... project name in the Project Explorer window
  2. Select Build Project.

Ethernet Project

  1. Right click on the WolfSSL project name in the Project Explorer window
  2. Select Build Project.
  3. Right click on the xively_demo_stm32f4xx... project name in the Project Explorer window
  4. Select Build Project.

Step 5 of 5: Flashing the binary

Connecting the hardware

Connect the Nucleo board to its expansions, and connect it to your computer's USB port.

Programming the device

  1. In the Eclipse IDE, right-click the project name.
  2. Click on Target->Program Chip...
  3. If compilation succeded, you'll see your binary as an .elf file in the window that popped up. Select that binary, check the Reset after program box and click OK

Reading the device debug logs

In order to see logs on the device you will need to setup a serial connection. For more information on how to setup this connection, please see Appendix A: Connecting To Device Over Serial below.

Once connected, you should see text coming from the device. This serial port can be used to make sure the code is working, debug issues, set new credentials, etc.


You did it! You now have a Nucleo board connected and communicating with Xively.

To see the status of your device, go back to the device page in the Xively management app. The device status is now Connected, and on the Logs tab you see its Device connected lifecycle log.

To see the graphical representation of data received from your device such as temperature and button states, go to Product Launcher where you can also turn on and off LEDs on the board using toggles.

You will notice the graphs for the Accelerometer, the Magnetometer and the Gyroscope don't change. Due to the 3 axes in each of those sensors, the information is sent as JSON, which isn't recognized by these graphs at the moment. You can see the JSON messages you're receiving by selecting the MQTT tab between the graphs and the device description.


Build Issues

Missing File

This error can occur when running gmake on Windows without a PRESET command line argument. Please double check your build command against the one specified in Step 2 of 5: Building Xively C Client.

Fatal error: lwip/netdb.h: No such file or directory

This is a sign that the SDK path that you set on the make commandline is not configured correctly. For the WiFi demo this should be pointed to your STM32CubeExpansion_WIFI1 SDK , for the Ethernet board it should be the STM32Cube_FW_XXX SDK. Please see the sections Step 1 of 5: Installing the necessary tools and dependencies and Compilation of Xively C Client for more information.

WolfSSL Project Build Failure -- Missing Sources

The WolfSSL library is required for the Ethernet board in this tutorial. On Linux and Mac OSX Hosts, the sources for this library will be downloaded in a script kicked off by the make process. You will need to agree with the WolfSSL license before continuing.

On Windows machines, the shell script will not run. You will need to checkout the specific Revision of WolfSSL that this tutorial has been tested against. Please see TLS and Windows Host Environments

Appendix A: Connecting To Device Over Serial

Known Serial Terminal to STM32 device communication issue

We've experienced character losses when cutting and pasting credentials over serial. If you are connecting over serial to store credentials then please read this note:

The 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.

Use a serial terminal like miniterm to connect to your device's serial port.

On Linux and OSX, that port can be found at /dev/tty.usbmodem****.
Windows users can use the device manager to find out which COM port has been assigned to the device.

Please configure your Serial terminal settings for STM32 board communication:

  • Baud Rate: 115200bps
  • 8 8 data bits, No parity, 1 stop bit
  • Optional: Transmit Character Delay: 3ms. (example, on coolTerm: Options->Transmit->Use transmit character delay)