Official Xively client (libXively)

The official Xively embedded MQTT client (libXively), built to run on any connected device.


Completely open source

The Xively C Client library is licensed under the BSD 3-Clause license.

For more information please read our file located in the base directory of the Xively C Client repository.

What is the Xively C Client?

The Xively C Client is an easy to port, open-source, C-client that connects low-end IoT devices to Xively services. Low resource use is achieved by implementing a cooperative multitasking pattern providing a single-threaded library with non-blocking behavior. Portability is achieved via a Board Support Package (BSP) which puts platform-specific functionality into a well-defined series of functions and directories. Specific Xively Client BSP modules are Networking, Transport Layer Security (TLS), Memory Management, Random Number Generator and Time. To take advantage of Xively's SFT for Over The Air file updates, you also need a filesystem BSP and a Firmware Update BSP.

Xively client library with BSP interfacing your microcontroller


The library is designed for security and scalability in resource-constrained device environments, where processing capacity and memory may be limited.

The Xively C client library incorporates lessons learned from building connected products on a variety of microcontroller families, and continues to evolve with new features including portability and remote administration.

For a detailed look at available features, see our GitHub

  • Scales from No-OS to RTOS to enterprise operating systems
  • Can operate on a single thread and in non-blocking mode
  • Does not use any CPU power when waiting for operations, so power consumption can be minimized as required
  • Provides a thread-safe event queue and optional thread pool for callbacks
  • Uses coroutines to handle multiple publish and subscribe requests concurrently while returning control to the microcontroller stack for OS requirements
  • Provides integrations for 3rd party TLS stacks including TLS1.2, modern cryptographic ciphers providing forward secrecy, and certificate verification
  • Implements intelligent networking behavior to optimize device fleet reconnect performance
  • Protocol module supports MQTT for device/broker communication
  • Small footprint with modularity for size optimizations to particular microcontroller environments
  • Devices can be easily updated in the field with new firmware and arbitrary files.
  • Data is downloaded in the background, no need to create a second connection to a new service.
  • Download and update status is reported by the Xively C Client to the SFT service automatically, helping you to monitor the progress of a software deployment across your fleet of devices.


Non-obstructing communication

The Xively embedded IoT client is the only embedded client on the market that is capable of multitasking while remaining single-threaded.

This means that unlike all other lightweight embedded clients that use MQTT (like PAHO's embedded MQTT client), it is capable of downloading file updates in the background without having to drop its current subscriptions, interrupt the download to publish a message, or handle user interaction from buttons and interfaces on the device.

Minimum system requirements

In additions to the many platforms that the client is already built for (Like the CC3200 from TI), our client can be ported to anything with the following system requirements:

  • Hardware requirements: Recommended minimum 32-bit processor, but the library is portable to all sorts of platforms
  • Security requirements: Secure TLS communication achieved using many implementations, on-board or compiled with the application. We provide "TLS BSPs" for 2 third party libraries: WolfSSL and mbedTLS, and you can implement new ports
  • Operating System requirements: The Xively C Client has been built and executed on RTOS, POSIX and bare metal environments, and it's highly portable to other Operating Systems
  • Space requirements: The embedded client compiles to around 26kB without a security layer, and our enhanced security implementation of WolfSSL comes in around 76 kB. Runtime heap requirements: 18.5 kB, runtime stack requirements: 10kB

Stability and QA

20 different combinations of compiler and feature sets are continously built by Travis CI. 58 functional, 23 integration and 256 unit tests are executed after each build. Tested with two TLS libraries: WolfSSL and mbedTLS. The library is open for further TLS libraries as well via its TLS BSP.

BranchBuild status
masterBuild StatusBuild Status
developmentBuild StatusBuild Status

How to get the sources?

Sources can be obtained by pulling from the master branch at our Xively Client github repository:

Directory structure

  • bin - executables resulting from a build
  • doc - documentation: doxygen API, User Guide, Porting Guide
  • examples - example sources with their own Makefiles. After building in this directory with make, the examples' executables will reside here as well.
  • include - header files of Xively C Client's API. You must add this directory to the include path when compiling and linking against a Xively C Client static library.
  • include/bsp - header files of the Board Support Package (BSP). Functions here shall be implemented during a porting process. Implementation of these functions contains all of the platform specific code needed tie the Xively C Client to a particular platform.
  • include_senml - header files of the Xively C Client's SenML API. This directory should be added to the include path when building an application that uses SenML to format timeseries messages.
  • make - build system configuration files
  • obj - object files generated during a build
  • proj - project files assisting development of the Xively C Client
  • res - resource files (e.g. trusted root CA certificates)
  • src - the source files of the Xively C Client

How to build it

The Xively C Client's preferred build environment is make with gcc on a POSIX platform, though it has been cross-ported to other platforms via toolchains and specific IDEs.

We recommend building the Xively Client on OSX or Linux before attempting to cross compile the sources to another target. This process could serve as an introduction to the basic architecture, tools and steps which will come handy during the final build onto the target platform.

Build prerequisites

  • autotools: autoconf, automake, libtool is needed by the default TLS library: WolfSSL
  • cmake is needed by the integration test framework cmocka

On OSX these are available through brew:

- brew install autoconf
- brew install automake
- brew install libtool
- brew install cmake

Building a TLS static library

By default, the Xively C Client library is built with secure connection support and therefore requires a 3rd party TLS implementation to link against. The build environment defaults to use wolfSSL, but it can be configured to use mbedTLS by setting variable XI_BSP_TLS in the make command like this:

    make XI_BSP_TLS=mbedtls

The default wolfssl will run the script xively-client-c/src/import/tls/, mbedtls will run xively-client-c/src/import/tls/

For information on how to run this script please see the Security section, then continue with Building the library step below.

Building the library is as simple as executing the following command in the terminal


Building the examples

Examples require both the Xively C Client library and a TLS library to be built beforehand.

You can build all the POSIX examples at once. They are implemented to showcase different features of the client, and to offer sample code you can re-use for any other platform.

cd examples

Execution of the examples requires Xively Account ID, username, password and usually an MQTT topic to communicate over. These credentials can be obtained via your Device Details page of the Xively management app.

For a secure connection, a file named xi_RootCA_list.pem is also required to be placed into the current working directory (CWD) of the example, although this is done automatically by the build system.

Building and executing the tests

make tests

By default the build process for tests includes the test execution as the final step. Although one can execute the tests manually as well by

cd xi_client_c/bin/osx/tests


For cross-compilation please see the porting guide under doc/ directory. But in short it consists of

  • extending the build system with a new cross-compilation preset in the file xively-client-c/make/mt-config/
  • a Board Support Package (BSP) implementation that you have written for your platform in the directory xively-client-c/src/bsp/platform/TARGETPLATFORM
  • a TLS library built for the target platform in the directoy xively-client-c/src/bsp/tls/TARGETTLSSOLUTION


The Xively C Client supports secure connection by utilizing a 3rd party TLS library service. The Xively C Client is built and tested against two TLS libraries: WolfSSL and mbedTLS. The Xively C Client repository itself does not directly contain TLS libraries in any forms but offers a script to download and build either WolfSSL and mbedTLS library on OSX and Linux. Please see the src/import/tls directory.

The Xively C Client is open to use any further TLS library solution through its BSP TLS API, please see the porting guide in doc/. If you choose a library other than mbedTLS or WolfSSL then ensure that it supports async I/O, the loading of custom root CA certificates, and OCSP.

The Xively C Client library can be built without TLS support. The primary purpose for a non-TLS build is to test against a localhost non-TLS mqtt server like the mosquitto. Turning off TLS is strongly discouraged for release versions. For turning off secure connection use the PRESET=POSIX_UNSECURE_REL in the make command:


For further fine tuning feature settings please see the porting guide in the doc/ directory.


Any issues that appear to be a bug in the library code, examples or documentation,
should be submitted via GitHub and will get fixed once confirmed and understood.
Feature requests should be submitted via GitHub too.


We use GitHub fork/pull-request model and encourage users to contribute
changes back. The general guideline is to submit no more than one feature
in a single pull-request and each individual commit should contain only
related changes.

Further readings

See more details in directory doc/

  • Connecting Hardware - A rundown of the currently supported platforms, and other technical details
  • doxygen/ - doxygen generated docs
  • - a detailed description to aid porting process
  • - a detailed descript to the Xively C Client
  • - a tutorial for Texas Instruments CC3200 board

Updated 2 years ago

Official Xively client (libXively)

The official Xively embedded MQTT client (libXively), built to run on any connected device.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.