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.
    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 enable host and peer verification.

  • If you want CMake to build unit and integration test executables, ensure that ruby is installed and available on the path. Otherwise, no test executables will be generated.

Preparing and Building

Building the MCL from source code is a simple task. The following steps guide you through each build process and 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. This example uses {CMAKE_BUILD_DIR} as a placeholder for the build folder (e.g. ~/cmake_build_linux or C:\Temp\cmake_build_windows, ...):

1
mkdir {CMAKE_BUILD_DIR}

Change into the new folder:

1
cd {CMAKE_BUILD_DIR}

All following build steps are executed in this working directory. Source files of the MCL are not affected by any of these operations. Output files of the build are located under:

1
{CMAKE_BUILD_DIR}\build\{CMAKE_BUILD_TYPE}\

Preparing the Build Folder with CMake

If you want to build MCL project from console, enter the following CMake command inside CMAKE_BUILD_DIR. The placeholder {MCL_PROJECT_FOLDER} is used for the location of MCL's source code folder, which contains the top-level CMakeLists.txt file.

1
cmake {MCL_PROJECT_FOLDER}

When creating the build files, CMake looks for a suitable compiler and linker within the environment. 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 use for development you can have CMake create project and makefiles for the MCL. 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 which may look like:

1
2
3
4
5
6
The following generators are available on this platform:
  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 Unix Makefiles.

Each of the listed generators can be used to create project and makefiles in your build directory CMAKE_BUILD_DIR.

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

1
cmake -G "name of the generator" {MCL_PROJECT_FOLDER}

For example, here are the CMake calls using the generators listed above:

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, CMake also generates project files (like solutions for VS) which can be opened by the respective IDE.

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

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

Specifying MCL Options for the Build Process

There are other options you can enable or disable in order to modify how MCL is built. Each option is provided to CMake with the following command:

1
cmake -D{MCL_OPTION}[={OPTION_VALUE}] {MCL_PROJECT_FOLDER}

The part [={OPTION_VALUE}] is optional and can be omitted, if the MCL_OPTION has no value.

The following options are allowed options:

Option Description
MCL_STATICLIB If set to ON, MCL is built as static library.
If set to OFF (Default), MCL is built as dynamic library.
MCL_USE_LIBCURL If set to ON (Default), MCL is built with libcurl.
If set to OFF, MCL is built without libcurl. In this case the user has to provide a module which implements an HTTPS client. Users must make sure that libcurl is available in the path environment.
MCL_USE_OPENSSL If set to ON (Default), MCL is built with OpenSSL.
If set to OFF, MCL is built without OpenSSL. In this case the user has to provide a module which implements the security layer (SHA256, MD5 calculation etc.) of MCL. Make sure that OpenSSL 1.0.2k is available in the path.
MCL_TESTING If set to ON (Default) and Ruby is found in the path, MCL is built with tests.
If set to OFF, MCL is built without tests.
MCL_CREATE_DOXYGEN If set to ON (Default) and Doxygen is found in the path, MCL is built with target mcl_doc for generating Doxygen documentation.
If set to OFF, MCL is built without target mcl_doc.
MCL_LOG_UTIL_LEVEL The value of this option is used to set the 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)

CMake can also cross build the MCL for a different target system. The build system must support the required toolchain and a toolchain setup file must be provided. The CMake call for building with a toolchain setup looks like this:

1
cmake -DCMAKE_TOOLCHAIN_FILE=../Toolchain-i586-poky-linux.cmake {MCL_PROJECT_FOLDER}

Any required system root folders must be available in your path, so CMake can find any includes for the target system. The following example shows the Toolchain-i586-poky-linux.cmake for building 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 a build with CMake

After setting the folder structure 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 setups you may want to call (builds all targets):

1
cmake --build .

It is possible to choose only one of the targets. The following table lists the different targets:

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

Use the following command structure to build only one target:

1
cmake --build . --target {target_name}

Creating the 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 as follows:

1
cmake --build . --target mcl_doc

Generating a Distribution Package

The distribution package of the MCL is generated using CPack. CPack is configured in the CMake files. You can generate the distribution package MCL-{mcl_version}-{target_system}.zip by calling the CMake target as follows:

1
cmake --build . --target package

Executing Unit and Integration Tests

If you build all targets with including tests you may run tests with the following command:

1
ctest .

Refer to the help of CTest (ctest --help) for running or excluding specific tests using regular expressions.

The build process stores all outputs in the subfolder {CMAKE_BUILD_DIR}/build/{Debug|Release|...

Building and Running a Custom Agent for Linux

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

Creating the 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 using:

1
sudo chmod 755 {directory_path}

Building OpenSSL

Download the OpenSSL package openssl-1.0.2k.tar.gz. Unzip openssl-1.0.2k.tar.gz to /usr/customAgentExample. Enter the following commands:

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. Enter the following commands:

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 following 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 using:

1
sudo ./build_mcl

Make sure the correct libraries are linked using the following command:

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

Building a Custom Agent Application

  1. Create /usr/customAgentExample/agent directory for agent application.
  2. Create CMakeLists.txt file in /usr/customAgentExample/agent with the following 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 the source code for your custom agent application in /usr/customAgentExample/agent and 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 Custom Implementations

The following table list the modules of the MCL project, which can be replaced by custom implementations:

Modules Description
memory.h Implements memory related functions. If not specified otherwise, alloc, calloc, realloc and free are used from the standard library. You can replace this module by a custom implementation which handles the memory management for your target device and build environment.
random.h If not specified otherwise, MCL uses the random generator from the standard library. You can replace this module by a custom implementation.
security.h This module provides several functions which implements calculations like SHA256, MD5, RSA key generation. If not specified otherwise, these calculations are performed by OpenSSL's crypto library. Replace this module to provide your own hardware specific implementation.
http_client.h This module is used by MCL in order to send an HTTP request to MindSphere. If not specified otherwise, libcurl is used to realize the communication. You can replace this module by a custom implementation. Your implementation has to fulfill the same security requirements with respect to TLS v1.2. MindSphere's certificate must be 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.