Skip to content

MindConnect Library - Getting started

Requirements

  • In order to build the MCL you need first of all the cross make tool cmake (3.5.2 or newer).

  • The current version of the MCL works only (if not replaced by your implementation) together with Libcurl (7.52.1) and OpenSSL (1.0.2k). Other versions of the mentioned third party libraries are not tested.

    Please make sure, that your Libcurl installation is configured to use OpenSSL as the TLS v1.2 implementation.

    To use OpenSSL with your implementation one of following ciphers must be supported and configured for SSL handshaking:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    DHE-DSS-AES128-GCM-SHA256
    DHE-DSS-AES256-GCM-SHA384
    DHE-RSA-AES128-GCM-SHA256
    DHE-RSA-AES256-GCM-SHA384
    DHE-RSA-CHACHA20-POLY1305
    ECDHE-ECDSA-AES128-GCM-SHA256
    ECDHE-ECDSA-AES256-GCM-SHA384
    ECDHE-RSA-AES128-GCM-SHA256
    ECDHE-RSA-AES256-GCM-SHA384
    ECDHE-ECDSA-CHACHA20-POLY1305
    ECDHE-RSA-CHACHA20-POLY1305
    

    In order to verify the correctness of the MindSphere's certificate please enable host and peer verification.

  • If you want to have unit and integration test executables also be build with cmake, please ensure that ruby is installed and available on the path. If you don't have ruby on your path no test executables will be generated.

Preparing and Building

Building the MCL from source code is a simple task. In following steps we will guide you through each build process and also show you how to import and use the MCL inside your client application.

Creating a build directory

First you need to create a working directory where cmake can generate required files. We will use CMAKE_BUILD_DIR (e.g. ~/cmake_build_linux or C:\Temp\cmake_build_windows, ...) as a replacement for the build folder.

1
mkdir <CMAKE_BUILD_DIR>

Change your current directory to the new created folder

1
cd <CMAKE_BUILD_DIR>

All next build steps are done from now on under this working directory and source files of the MCL are not effected by any operation in those steps. Output files from the build are located under

1
<CMAKE_BUILD_DIR>\build\<CMAKE_BUILD_TYPE>\

Preparing build folder with cmake

If you want only to build MCL project from console just enter the following cmake command inside . We assume MCL_PROJECT_FOLDER points to location of MCL's source code folder with the top level CMakeLists.txt file.

1
cmake <MCL_PROJECT_FOLDER>

For creating the build files, cmake will look within the environment for a suitable compiler and linker. Please keep in mind, that for a build under windows with Visual Studio's toolchain, you need to run vcvarsall.bat (located in your VS installation) in order to set all environment variables.

Selecting a cmake generator (optional)

Depending on which IDE you want to use for development you can let cmake create project and makefiles for the MCL. Please use the help documentation of cmake to see the list of available generators depending on your environment.

1
cmake --help

You should see an output at the end which may look like:

The following generators are available on this platform:

Generator Description
Visual Studio 14 2015 [arch] Generates Visual Studio 2015 project files. Optional [arch] can be "Win64" or "ARM".
Unix Makefiles Generates standard UNIX makefiles.
Eclipse CDT4 - Unix Makefiles Generates Eclipse CDT 4.0 project files with with Unix Makefiles.

Each of these generators can be used to create project and makefiles in current build directory .

If you want to use one of the above generators just change the cmake call to:

1
cmake -G "name of the generator" <MCL_PROJECT_FOLDER>
example:
1
2
3
cmake -G "Unix Makefiles" <MCL_PROJECT_FOLDER>
cmake -G "Visual Studio 14 2015 Win64" <MCL_PROJECT_FOLDER>
cmake -G "Eclipse CDT4 - Unix Makefiles" <MCL_PROJECT_FOLDER>

If you choose the generator for Visual Studio or Eclipse then you will see that cmake also generates project files (like solutions for VS) which can be opened by the according IDE.

If you want to have an output for a specific build type use the parameter CMAKE_BUILD_TYPE. As an example:

1
cmake -G "Eclipse CDT4 - Unix Makefiles" -DCMAKE_BUILD_TYPE=<Debug|Release|..> <MCL_PROJECT_FOLDER>

Specifying MCL options for build process

There are other options you can enable or disable in order to modify how MCL is build. Each option is provided to cmake with:

1
cmake -D<MCL_OPTION>[=<OPTION_VALUE>] <MCL_PROJECT_FOLDER>

If the MCL_OPTION has no value you can skip the assignment in above command.

Allowed options can be listed as following:

Option Description
MCL_STATICLIB If set to ON MCL is build as static library.
If set to OFF (Default) MCL is build as dynamic library.
MCL_USE_LIBCURL If set to ON (Default) MCL is build with libcurl.
If set to OFF MCL is build without libcurl. In this case user has to provide a module which implements an HTTPS client. Currenlty user must be sure libcurl is available in path environment.
MCL_USE_OPENSSL If set to ON (Default) MCL is build with OpenSSL.
If set to OFF MCL is build without OpenSSL. In this case user has to provide a module which implements the security layer (SHA256, MD5 calculation etc.) of MCL. Please make sure OpenSSL 1.0.2k is available in path.
MCL_TESTING If set to ON (Default) and if ruby is found in path MCL is build with tests.
If set to OFF MCL is build without tests.
MCL_CREATE_DOXYGEN If set to ON (Default) and if doxygen is found in path MCL is build with target "mcl_doc" for generating doxygen documentation.
If set to OFF MCL is build without target "mcl_doc".
MCL_LOG_UTIL_LEVEL The value of this option is used to set log level for compilation.
Possible values from lowest to highest level are:
MCL_LOG_UTIL_LEVEL_VERBOSE
MCL_LOG_UTIL_LEVEL_DEBUG
MCL_LOG_UTIL_LEVEL_INFO
MCL_LOG_UTIL_LEVEL_WARN
MCL_LOG_UTIL_LEVEL_ERROR
MCL_LOG_UTIL_LEVEL_FATAL
MCL_LOG_UTIL_LEVEL_NONE

Invoking cross build with cmake (optional)

It is also possible to let cmake cross build the MCL for a different target system. For this, you need to support the required toolchain and to create a toolchain setup file. An example for building with a toolchain setup file you have to call cmake like:

1
cmake -DCMAKE_TOOLCHAIN_FILE=../Toolchain-i586-poky-linux.cmake <MCL_PROJECT_FOLDER>

Don't forget to add any required system root folders to your path, so cmake can find any includes for the target system. The content of the above Toolchain-i586-poky-linux.cmake may look like (example is for the build of MCL for an IoT2040 device with Intel's toolchain on a Debian OS):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
SET(CMAKE_SYSTEM_NAME Linux)
SET(CMAKE_SYSROOT ~/iss-iot-linux/devkit-x86/sysroots/i586-poky-linux)

SET(CMAKE_C_COMPILER i586-poky-linux-gcc)

SET(tools ~/iss-iot-linux/devkit-x86/sysroots/x86_64-pokysdk-linux/usr/bin/i586-poky-linux)
SET(CMAKE_FIND_ROOT_PATH ${tools})

SET(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
SET(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
SET(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
SET(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

Another example for building MCL for embedded devices may look like:

1
2
3
4
5
6
SET(CMAKE_SYSTEM_NAME Generic)
INCLUDE(CMakeForceCompiler)
CMAKE_FORCE_C_COMPILER(arm-none-eabi-gcc GNU)
CMAKE_FORCE_CXX_COMPILER(arm-none-eabi-g++ GNU)
SET(CMAKE_C_FLAGS "-Wall -ffunction-sections -fdata-sections -fno-builtin-memcpy -gdwarf-2 -mthumb-interwork -mcpu=arm926ej-s  -O0 -g3 -c -MMD -MP")
SET(CMAKE_EXE_LINKER_FLAGS "-nostdlib -nostartfiles -Wl,--gc-sections -Wl,--wrap=malloc -Wl,--wrap=calloc -Wl,--wrap=realloc -Wl,--wrap=free -Wl,--wrap=_malloc_r -Wl,--wrap=_calloc_r -Wl,--wrap=_realloc_r -Wl,--wrap=_free_r -Wl,--defsym -Wl,PAGE_SIZE=0 -Wl,--start-group -lgcc -lc -lm -lstdc++ -Wl,--end-group")

Invoking build with cmake

If the build folder preparation succeeds in previous steps now you should be able to build the MCL project. If the command "make" e.g. is in your toolchain then you could call it in your build folder directly, but for other toolchain setup you may want to call (builds all targets):

1
cmake --build .

It is also possible to choose one of the targets to be built instead of all:

Target Description
mc target for building the MCL
mcl_doc target for building the Doxygen documentation of the MCL project
package target for generating the distribution package of MCL
test_\<module_name> target for building a unit test executable for given module of the MCL
1
cmake --build . --target <target_name>

Creating doxygen documentation

The documentation of the MCL is built by doxygen. The project contains a doxygen configuration file which can be adapted to your needs. You can build the documentation by calling the cmake target:

1
cmake --build . --target mcl_doc

Generating distribution package

The distribution package of the MCL is generated using CPack. CPack is configured in CMake files. You can generate the distribution package "MCL--.zip" by calling the cmake target:

1
cmake --build . --target package

Executing unit and integration tests

If you build all targets with including tests you may run tests with

1
ctest .

See help of ctest (ctest --help) for running or excluding specific tests by selecting them with regular expressions.

After the build process you should be able to find all outputs in the subfolder /build/

Building and running a custom agent for linux

You can apply the following steps to build and run a custom agent using MCL for Linux from scratch.

Creating directory structure

  1. Create /usr/customAgentExample directory. This will be the parent directory for the whole process.
  2. Create /usr/customAgentExample/build directory. This will be the parent directory for build outputs.
  3. Create /usr/customAgentExample/build/openssl directory for openssl build outputs.
  4. Create /usr/customAgentExample/build/curl directory for curl build outputs.
  5. Create /usr/customAgentExample/build/mcl directory for mcl build outputs.
  6. Create /usr/customAgentExample/build/agent directory for agent build outputs.
  7. Copy MCL source code .../MCL_Core into /usr/customAgentExample.

Note

Change the modes of directories if needed by

1
$ sudo chmod 755 <directory_path>

Building OpenSSL

Download OpenSSL package openssl-1.0.2k.tar.gz. Unzip openssl-1.0.2k.tar.gz to /usr/customAgentExample.

1
2
3
$ cd /usr/customAgentExample/<downloaded_openssl_dir>
$ ./config --openssldir=/usr/customAgentExample/build/openssl shared -fPIC
$ sudo make install

Building libcurl

Download curl-7.52.1.zip. Unzip curl-7.52.1.zip to /usr/customAgentExample.

1
2
3
$ cd /usr/customAgentExample/<downloaded_curl_dir>
$ LDFLAGS="-Wl,-R/usr/customAgentExample/build/openssl/lib" ./configure --enable-http --with-ssl=/usr/customAgentExample/build/openssl --prefix=/usr/customAgentExample/build/curl --without-libssh2 --disable-ftp --disable-tftp --disable-file --disable-ldap --disable-rtsp --disable-dict --disable-telnet --disable-pop3 --disable-imap --disable-smb --disable-scp --disable-sftp --disable-smtp --disable-gopher --disable-manual
$ sudo make install

Building MCL

Create a bash file /usr/customAgentExample/build_mcl with the content:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
#!/bin/bash
OPENSSL_DIR="/usr/customAgentExample/build/openssl"
CURL_DIR="/usr/customAgentExample/build/curl"
MCL_SOURCE_DIR="/usr/customAgentExample/MCL_Core"
MCL_BUILD_DIR="/usr/customAgentExample/build/mcl"
if [ -d ${MCL_BUILD_DIR} ]; then
    sudo rm -rf ${MCL_BUILD_DIR}
fi
sudo mkdir ${MCL_BUILD_DIR}
sudo chmod 777 ${MCL_BUILD_DIR}
cd ${MCL_BUILD_DIR}
cmake -DCMAKE_PREFIX_PATH="${OPENSSL_DIR};${CURL_DIR}" -DCMAKE_BUILD_TYPE=Release -DMCL_STATICLIB=OFF -DMCL_USE_LIBCURL=ON -DMCL_USE_OPENSSL=ON -DMCL_CREATE_DOXYGEN=OFF -DMCL_TESTING=OFF -DMCL_LOG_UTIL_LEVEL=MCL_LOG_UTIL_LEVEL_NONE ${MCL_SOURCE_DIR}
cmake --build . --target mc

Build MCL by

1
$ sudo ./build_mcl

Make sure correct libraries are linked with the command:

1
$ ldd /usr/customAgentExample/build/mcl/build/Release/libmc.so

Building custom agent application

  1. Create /usr/customAgentExample/agent directory for agent application.
  2. Create CMakeLists.txt file in /usr/customAgentExample/agent with the content:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    CMAKE_MINIMUM_REQUIRED(VERSION 3.5 FATAL_ERROR)
    PROJECT(CustomAgentApplication LANGUAGES C)
    SET(CMAKE_C_STANDARD 99)
    SET(CMAKE_C_STANDARD_REQUIRED ON)
    FILE(GLOB SOURCES *.c)
    LIST(APPEND AGENT_SOURCES ${SOURCES})
    SET(MCL "/usr/customAgentExample/build/mcl/build/Release/libmc.so" CACHE INTERNAL "MCL" FORCE)
    SET(MCL_INCLUDE_DIRECTORIES "/usr/customAgentExample/build/mcl/include/" CACHE INTERNAL "MCL_INCLUDE_DIRECTORIES" FORCE)
    SET(AGENT_OUTPUT_DIR ${CMAKE_BINARY_DIR}/build)
    SET(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${AGENT_OUTPUT_DIR})
    SET(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${AGENT_OUTPUT_DIR})
    SET(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${AGENT_OUTPUT_DIR})
    ADD_EXECUTABLE(${PROJECT_NAME} ${AGENT_SOURCES})
    TARGET_INCLUDE_DIRECTORIES(${PROJECT_NAME} PUBLIC ${MCL_INCLUDE_DIRECTORIES})
    TARGET_LINK_LIBRARIES(${PROJECT_NAME} ${MCL})
    

  3. Make sure the provided MCL headers are in /usr/customAgentExample/build/mcl/include/mcl.

  4. Write your custom agent application with source code in /usr/customAgentExample/agent and then run the following commands:
    1
    2
    3
    4
    $ cd /usr/customAgentExample/build/agent
    $ cmake /usr/customAgentExample/agent
    $ cmake --build . --clean-first
    $ ./build/CustomAgentApplication
    

Replacing MCL modules with own implementation

You may want to replace some modules of the MCL project. Such modules can be listed as following:

Modules Description
memory.h Implements memory related functions. If not specified otherwise alloc, calloc, realloc and free will be used from the standard library. You could replace this module by your own implementation which handles the memory management for your target device and build environment.
random.h If not specified otherwise MCL will use the random generator from the standard library. If you have your own implementation for it you may replace this module.
security.h This module provides several functions which implements calculations like SHA256, MD5, RSA key generation etc. By replacing this module you can provide your own hardware specific implementation. Currently OpenSSL's crypto library is used to perform those calculations.
http_client.h This module is used by the MCL in order to send an HTTP request to MindSphere. In current implementation Libcurl is used to realize the communication. If Libcurl is not an alternative for your target device you may replace this module by your own implementation. Keep in mind that your implementation has to fulfill same security requirements with respect to TLS v1.2. The MindSphere's certificate of course must be also validated by your implementation during the SSL handshaking procedure.

For replacing a module keep the original *.h file and replace its implementation file *.c with the same name.

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.