search

xively / xively-client-c

The official and highly portable Xively C Client designed for embedded platforms.
Other
18 stars 22 forks source link

readme

Xively C Client

Copyright (c) 2003-2018, Xively All rights reserved.

This is part of the Xively C Client library, it 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.

Stability and QA

20 different combinations of compiler and feature sets are continuously 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

How to Build?

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

On OSX these are available through brew:

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

On Ubuntu these are available through apt-get:

- sudo apt-get update
- sudo apt-get install autoconf
- sudo apt-get install autotools-dev
- sudo apt-get install libtool
- sudo apt-get 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/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 credentials can be obtained via your Device Details page of the Xively Connected Product Management (CPM). 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

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/