What you will learn

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

This tutorial explains how to build and run the demo for two different internet connection types: Ethernet and 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 module is attached to the Nucleo board and controlled over UART.

Hardware you will need

Ethernet project

Wi-Fi project

Known hardware bug in old X-NUCLEO-IDW01M1 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.


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

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

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

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

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

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

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

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 Eclipse

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.

  1. Download the [Eclipse IDE for C/C++ Developers appropriate for your operating system.
  2. Once the download is complete, unzip the archive and install Eclipse.
    Note: This tutorial assumes that the Eclipse IDE has been installed on the $HOME drive and its root directory is $HOME/eclipse.

Install the System Workbench for STM32

System Workbench for STM32 is required to produce firmware images for STM32 devices.

  1. Run the Eclipse IDE.
  2. Confirm the default workspace.
  3. Open Help>Install New Software....
  4. Click the Add button.
  5. In the Add Repository window, enter the following:
  6. Click OK.
    A list of available software appears.
  7. From the list of available software select all of the options.
  8. Click Next >, confirm licenses, and click Finish.
    A pop-up window appears with installation progress bar.
  9. Click Yes to restart Eclipse.

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

Building for the Ethernet project

> make PRESET=STM32FX XI_STM32_PATH_SDK=$HOME/Downloads/STM32Cube_FW_F4_V1.14.0

Note: This command clones the wolfSSL library from

Building for the Wi-Fi project

The standard Cube SDK doesn't include the networking libraries used to control our Wi-Fi expansion board. We need to pass the path to the Wi-Fi SDK expansion.

> make PRESET=STM32FX_NUCLEO_WIFI XI_STM32_PATH_SDK=$HOME/Downloads/STM32CubeExpansion_WIFI1_V2.1.1

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

Compiling Xively demo application

Now you are ready to compile the project. In order to do this right click on the project name in the Project Explorer window and select Build Project. For the Ethernet project you need to build the WolfSSL project first.

Configuring the access point settings in the Wi-Fi example

In Project Explorer go to Example->User->main.c

Look for that fragment of code next to the line 96 in main.c file

char * ssid = "SSID";
char * seckey = "PASSWORD";
WiFi_Priv_Mode mode = WPA_Personal;

Update the ssid and seckey by entering your access point name and password.
Possible values for Wi-Fi authentication method:


Entering Xively's device and account data

In the Wi-Fi project, the credentials can be found at line 100 in Src/main.c:


In the Ethernet project, the credentials can be found at line 39 in Src/xively_client.c:


Building the project

  1. Right click on the project name
  2. Click on "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

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. The baudrate of the serial port is 115200bps; if your terminal asks for data, parity and stop bits, use 8 n 1 respectively.

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 Wi-Fi 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.