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 License.md 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 behaviour. 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.

Xively client library with BSP interfacing your microcontroller

Xively client library with BSP interfacing your microcontroller

Features

The library is designed for security and scalability in resource-constrained device environments, where processing capacity and memory may be extremely 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.

  • 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 an optional TLS stack including TLS1.2, modern cryptographic ciphers providing forward secrecy, and certificate verification with multiple roots of trust to maintain security in the event of CA compromise
  • 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

Non-blocking communication

The Xively embedded IoT client is the only embedded client on the market that is capable of multitasking while remaining multi-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, with an [ARM or MIPS] architecture
  • Security requirements: Secure TLS communication achieved using any of [Xively’s enhanced security implementation of WolfSSL, ARM’s mbed TLS, or TI’s implementation of WolfSSL]
  • Operating System requirements: Running either [No operating system, or the FreeRTOS embedded operating system]
  • Space requirements: The embedded client is 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.

Branch Build status
master Build Status
development Build Status

How to get the sources?

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

https://github.com/xively/xively-client-c

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.
  • licenses - licenses of 3rd party software used by the Xively C Client
  • 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 enviornment 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/download_and_compile_wolfssl.sh, mbedtls will run xively-client-c/src/import/tls/download_and_compile_mbedtls.sh

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

make

Building the examples

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

cd examples
make

Execution of the examples requires Xively accountId, username, password and usually an MQTT topic to communicate over. These credentails can be obtained via your Device Details page of the Xively management app. If you don't yet have a Xively account, then you may register for one here.

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
./xi_utests
./xi_itests

Cross-compilation

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/mt-presets.mk
  • 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

Security

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:

make PRESET=POSIX_UNSECURE_REL

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

Support

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.

Contributing

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/

  • doxygen/ - doxygen generated docs
  • porting_guide.md - a detailed description to aid porting process
  • user_guide.md - a detailed descript to the Xively C Client
  • tutorial_ti_cc3200.md - a tutorial for Texas Instruments CC3200 board

Official Xively client (libXively)

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