This is a getting-started guide for new users of embedded SDK (eSDK). Below are both Windows and Linux steps for obtaining, deploying and using eSDK in your solution. The general overview of eSDK can be found at Embedded C++ SDK.

Getting started on Windows

Installing Visual Studio

For running eSDK on the Windows platform, you need to use Visual Studio 2013 in eSDK version up to 5.1 and Visual Studio 2017 starting from version 5.2. Visual Studio 2019 can also be used instead of Visual Studio 2017 but the v141 C++ toolsets must be included to the installation.

Go to the Visual Studio page and download Visual Studio 2013 (recommended Professional or Enterprise, with latest updates)
During Visual Studio installation, no optional features

Accessing TFS and Embedded SDK source code

Open Visual Studio
Connect to TFS cpmPlus project:
- In Team Explorer, click on Connect to Team Projects icon, then Select Team Projects, then click Servers... button
- Add tfsa.abb.com server (if not already present on the server list)
  - Click Add... button
  - Fill in information as on the picture below and press OK, and then Close
  - TODO: IMAGE HERE
- Select tfsa.abb.com from the server list, then cpmPlus Team Project, and connect
- You might receive SSL connection error with description "The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel". It means that you are missing ABB Root CA certification authority, the easiest fix is to export this certificate from computer that already has it installed and import it to your destination computer:
  - On your source computer, open command console and run mmc command, this will open Microsoft Management Console
  - Press File, then Add/Remove Snap-in..., then add Certificates for current user:
  - TODO: IMAGE HERE
  - Export ABB Root CA certificate to a file:
  - TODO: IMAGE HERE
  - On destination computer, also open Microsoft Management Console with mmc command
  - Import ABB Root CA from a file:
  - TODO: IMAGE HERE
In Source Code Explorer, map folder $/cpmPlus/History/Main/eSDK/ to a local folder of choice (in our examples it's C:\eSDK)
In Source Code Explorer, open solution $/cpmPlus/History/Main/eSDK/Projects/cpmPlus_eSDK.sln. After opening it, there should be 4 projects accessible:
- cpmPlus_eSDK - source code for eSDK API
- cpmPlus_eSDK_DemoApplication - sample application using eSDK API
- cpmPlus_eSDK_Test - tests for eSDK API
- MIA_Websocket - cross-platform wrappers for websocket communication, used for connecting to Vtrin (used internally by eSDK API)

Installing dependencies and building Embedded SDK library

Install the OpenSSL libraries - latest 1.1 version for both Win32 and Win64
- During installation, select option to copy OpenSSL DLLs to Windows system directory
To resolve includes in the project, run makelink.bat, which is located in C:\eSDK\Projects\include (from command line as administrator)
In Visual Studio, set up project cpmPlus_eSDK as StartupProject
Build the project in x86 mode
Output files cpmPlus_eSDK.lib and MIA_Websocket.lib are generated (in C:\eSDK\Projects\Win32\Debug or C:\eSDK\Projects\Win32\Release folder)

Creating a project that uses Embedded SDK library

Open Visual Studio, close previous solution and create a new project
TODO: IMAGE HERE
Open your Project Properties, and then:
- Set value of Configuration box to All Configurations
  - Go into C/C++ , then into General, and to the value of Additional Include Directories also add C:\eSDK\Projects\include
- Set value of Configuration box to Debug
  - Go into C/C++ , then into Code Generation, and set the value of Runtime Library to Multi-threaded Debug (/MTd)
  - Go into Linker , then into General, and to the value of Additional Library Directories also add:
    - C:\eSDK\Projects\Win32\Debug
    - C:\eSDK\Projects\libs\openssl\lib
  - Go into Linker, then into Input, and to the value of Additional Dependencies also add:
    - cpmPlus_eSDK.lib
    - MIA_Websocket.lib
    - libsslMTd.lib
    - libcryptoMTd.lib
- Set value of Configuration box to Release
  - Go into C/C++ , then into Code Generation, and set the value of Runtime Library to Multi-threaded DLL (/MD)
  - Go into Linker, then into General, and to the value of Additional Library Directories also add:
    - C:\eSDK\Projects\Win32\Release
    - C:\eSDK\Projects\libs\openssl\lib
  - Go into Linker, then into Input, and to the value of Additional Dependencies also add:
    - cpmPlus_eSDK.lib
    - MIA_Websocket.lib
    - libsslMT.lib
    - libcryptoMT.lib
Now you are ready to build and debug your project

In your application, to use eSDK functionality be sure to include following header files and Mia namespace:

#include "Mia_Driver.h"
#include "Mia_Exception.h"
#include "Mia_Base.h"
#include "Mia_Equipment.h"
#include "Mia_Device.h"

using namespace ABB::Mia;

To use eSDK, you also have to initialize the platform and connect to the edge:

static std::string g_Host = "wss://55.55.55.55/view/connectionstring.data";
static std::string g_Username = "username";
static std::string g_Password = "password";

int main()
{
	ABB::Mia::G_PlatformInit();

	ABB::Mia::C_MiaDriver driver(g_Host);
	try
	{
		std::cout << "[" << ABB::Mia::C_DateTime::M_S_Now() << "] [ INFO  ]: Connecting to " << g_Host << std::endl;
		driver.M_Connect(g_Username, g_Password);
	}
	catch (ABB::Mia::C_Exception &ex)
	{
		std::cout << "[" << ABB::Mia::C_DateTime::M_S_Now() << "] [ ERROR ]: Failed to connect!! Reason: " << ex.M_ToString().c_str() << std::endl;
		return -1;
	}
}

Getting started on Linux

Prerequisites

For running eSDK on the Linux platform, the minimal dependencies are:

g++
CMake (a project build system)
Openssl development library

On debian-based systems with apt repository support, the below script can be used for installing dependencies:

#!/bin/sh

sudo apt-get update
sudo apt-get --yes install g++ build-essential openssl libssl-dev

Getting the code

The SDK code can be obtained from the TFS repository, with one of the following steps:

NFS synchronization
Using Eclipse and Team Explorer Everywhere plugin (the following steps were tested in Eclipse minimum version 4.0):
1. Install Eclipse: https://www.eclipse.org/downloads/
2. Install Team Explorer Everywhere plugin: https://marketplace.eclipse.org/content/team-explorer-everywhere
3. Navigate to Windows → Preferences → Team → Team Fundation Server and enable "Accept untrusted SSL certificates" (see the picture below)
4. TODO: IMAGE HERE
5. Open Team Explorer perspective (Windows → Perspective)
6. Use Connect to Team project for connecting to TFS server
7. After a successful connection, the eSDK project should be accessible from Source Control view
tfs-cli command line interface (only if the basic-auth authentication or authentication token is enabled in the TFS repository)

Build and configuration

After obtaining the source code, navigate into the eSDK root folder, make the desired directory, where the library will be built into, and use cmake to build the project. An example of building the project can be found below. The recommended way is the out of source build:

cd eSDK
mkdir build
cd build
cmake ..
make

The following CMake options are available:

BUILD_TESTS=[ON/OFF] for building eSDK tests
BUILD_DEMO=[ON/OFF] for building sample project
XCOMPILE=[ON/OFF] for cross-compilation

The options are used as follows:

cmake -DBUILD_TESTS=ON -DBUILD_DEMO=ON ..

📘
The build options must be specified before the project path.

There are also two UI applications for more user-friendly cmake options editing:

ccmake - Console gui app
cmake-gui - Qt-based GUI, which allows for easy configuration of the build directory and build options. Example usage is shown in the picture below

TODO IMAGE HERE

Installation

Installation of Device API might be done with make install command. By default, targets are installed into /usr/local/ directory. The installation directory might be specified by setting cache variable during make generation:

cmake -DCMAKE_INSTALL_PREFIX=/path/to/install

Or, the whole installation might be relocated by using DESTDIR variable during install step:

make install DESTDIR=/path/to/install

In the case of setting DESTDIR targets will be put into path DESTDIR/CMAKE_INSTALL_PREFIX. For more information about DESTDIR see: https://cmake.org/cmake/help/v3.0/variable/CMAKE_INSTALL_PREFIX.html

After installation step, in the desired target directory will be 11 header files installed into include folder:

Mia_Base.h
Mia_Device.h
Mia_Driver.h
Mia_Exception.h
Mia_Equipment.h
WS_Error.h
WS_Socket.h
WS_Util.h
WS_Websocket.h
Mia_Base_LINUX.h
Mia_DriverBase.h

And two static libraries in the lib folder:

libcpmplus-sdk.a
libMIA_Websocket.a

Cross compilation

Enabling cross-compilation is done by a flag XCOMPILE in CMake options. When cross-compilation is enabled, it is obligatory to specify CMAKE_CXX_COMPILER, CMAKE_C_COMPILER and CMAKE_SYSROOT cache variables. For example:

-DCMAKE_CXX_COMPILER=/path/to/g++compiler

Those variables might be set from cmake-gui by the Add Entry

🚧
After every change of the compilator, the CMake cache files MUST be deleted.

It can be done manually:

Remove the CMakeCache.txt file
Remove the CMakeFiles directory

It is also possible to use the python script cmake-clean.py with the build directory as an argument:

python cmake-clean.py <build directory>

📘
Pay attention to the cmake command output, as it provides warning information if something is not set properly.

The compiled libraries would be in the <build_dir>/<target architecture>/lib folder, and executables in <build_dir>/<target architecture>/bin.

For example, in a 32-bit Linux system, the target libraries will be in: build/i686/lib

Running test and sample API usage

Test methods are using the gtest framework (bundled into the eSDK project). The source of the test is located in eSDK/SDK/src/MIA_Test/.

An example application using the eSDK API is located in eSDK/UseCases/

After successful compilation, there should be 2 Device API library files in the .../lib directory:

cpmplus-sdk with Device API eSDK
MIA_Websocket with multi-platform websocket API

Also, there should be 2 executables in the .../bin directory:

cpmPlus_eSDK_Test with the SDK tests
cpmPlus_DemoApplication with the example application

The test and demo code is the same for Linux and Windows, so you can also refer to the Windows part of this onboarding guide.

Writing CMake files for API usage

The following example will show how to make your own CMake file for your project to find, link and use the eSDK API. Add a file named CMakeLists.txt to your project root:

First, specify the used CMake version and desired C++, so your CMakeLists.txt should start like:

#specify required cmake version
cmake_minimum_required(VERSION 2.8)

project(eSDK_App)

#specify desired C++ standard
set(CMAKE_CXX_STANDARD 11)

Add the files with your code to the project files. You can set some name for them, or just add them in the add_executable section further on:
```
#set files where your code is
set(SOURCE_CODE Mia_BasicApplication.cpp)
```

Specify, where to look for the eSDK API libraries. Let's assume that they are located in /opt/eSDK/build/i686/lib. If the libraries are not found, cmake will show information about that fact, when generating the makefiles.

#specify, where to look for eSDK compiled static libraries 
set(ESDK_LIB_DIR /opt/eSDK/build/i686/lib)

#look for desired libraries
find_library(ESDK_LIB NAMES cpmplus-sdk PATHS ${ESDK_LIB_DIR}) #Device SDK API
find_library(MIA_WEBSOCKET_LIB NAMES MIA_Websocket PATHS ${ESDK_LIB_DIR}) #Websocket connection API required for eSDK API

Include Device API headers and Websocket API headers:

#include Device API headers
set(ESDK_HEADERS /opt/eSDK/SDK/src) #set directory where API source is located
include_directories(${ESDK_HEADERS }/MIA_Driver) #include all headers in Device API directory
include_directories(${ESDK_HEADERS }/MIA_Websocket) #include all headers in Websocket API directory

Specify the build target for your application, and link against the required libraries:

#specify executable name
add_executable(eSDK_BasicApp ${SOURCE_CODE})

#link against required libraries
target_link_libraries(eSDK_BasicApp cpmplus-sdk MIA_Websocket pthread ssl crypto)

📘
Note
If the make install for eSDK was done, there is only need to include one folder: /path/to/installation/include and all libraries are in /path/to/installation/lib folder, so following might be used instead of steps 3 and 4:
 include_directories(/path/to/installation/include)
 link_directories(/path/to/installation/lib)

In the end, the complete CMakeLists.txt file should look like:

#specify required cmake version
cmake_minimum_required(VERSION 2.8)

#specify desired C++ standard
set(CMAKE_CXX_STANDARD 11)

#specify, where to look for eSDK compiled static libraries 
set(ESDK_LIB_DIR /opt/eSDK/build/i686/lib)

#look for desired libraries
find_library(ESDK_LIB NAMES cpmplus-sdk PATHS ${ESDK_LIB_DIR}) #Device SDK API
find_library(MIA_WEBSOCKET_LIB NAMES MIA_Websocket PATHS ${ESDK_LIB_DIR}) #Websocket connection API required for eSDK API

#set files where your code is
set(SOURCE_CODE Mia_BasicApplication.cpp)

#include Device API headers
set(ESDK_HEADERS /opt/eSDK/SDK/src) #set directory where API source is located
include_directories(${ESDK_HEADERS }/MIA_Driver) #include all headers in Device API directory
include_directories(${ESDK_HEADERS }/MIA_Websocket) #include all headers in Websocket API directory

#specify executable name
add_executable(eSDK_BasicApp ${SOURCE_CODE})

#link against required libraries
target_link_libraries(eSDK_BasicApp cpmplus-sdk MIA_Websocket pthread ssl crypto)

It is recommended to have an out of source build with CMake. To do an out of source build, use the following commands from the directory where your CMakeLists.txt is located:

mkdir build
cd build
cmake ..
make

For more examples of how to write CMake files, please refer to the cmake-tutorial.

Embedded C++ SDK onboarding

Getting started on Windows

Installing Visual Studio

Accessing TFS and Embedded SDK source code

Installing dependencies and building Embedded SDK library

Creating a project that uses Embedded SDK library

Getting started on Linux

Prerequisites

Getting the code

Build and configuration

The build options must be specified before the project path.

Installation

Cross compilation

After every change of the compilator, the CMake cache files MUST be deleted.

Pay attention to the cmake command output, as it provides warning information if something is not set properly.

Running test and sample API usage

Writing CMake files for API usage

Note