EmbedThis

Appearance

Building Ioto ​

The Ioto source code has been designed to run on Arduino, ESP32, FreeBSD, FreeRTOS, Linux, Mac OS X, VxWorks and other operating systems. Ioto supports the X86, X64, Riscv, Riscv64, Arm, Arm64, and other CPU architecutres. Ioto can be ported to new plaforms, operating systems and CPU architectures. Ask us if you need help doing this.

Several build environments are supported:

  • Linux — Linux 4 with GNU C/C++
  • Mac OS X — Mac OS X 11 or later
  • Windows — Windows 11 with WSL v2
  • ESP-32 — Using the ESP IDF

For other environments, you will need to cross-compile.

Build Configuration ​

You do not need to use a configure program when building via make. Instead, you select the desired sample app and just run make.

The Ioto distribution build includes several demo apps for local or cloud-based management. Apps demonstrate device-side logic to implement various management use cases. The default app is the "demo" app which sends device data and metrics to the cloud.

When make is invoked, it will copy the selected app's ioto.json5 file to the state directory and generate a src/ioto-config.h header that will ensure the required services are compiled.

Building ​

If you are building on Windows, or for ESP32 or FreeRTOS, please read the specific instructions for various build environments:

Read below for generic build instructions.

Building with Make ​

To build on Linux, MacOS or Windows via WSL, use the system make command. The supplied Makefile will build the Ioto library (libioto.a) and the "ioto" main program. If you are embedding Ioto in another program, you should link the Ioto library with your program. See Linking below for details.

The top level Makefile parses your selected App's ioto.json5 configuration file, detects your operating system and CPU architecture and then invokes the appropriate project Makefile for your system. It copies the select app configuration from the apps/NAME/config directory to the state directory.

To build, nominate your selected app via the "APP=NAME" makefile option:

bash
$ make APP=demo

The default build of Ioto is configured to build the Ioto agent and the demo management app which saves device data and metrics to the cloud.

Building on Windows ​

Building on Windows utilizes the Windows SubSystem for Linux (WSL). Using WSL, you get a tightly integrated Linux environment from which you can build and debug using VS Code.

To build, first install WSL by running the following command as an administrator:

bash
$ wsl --install

Then invoke wsl to run a wsl (bash) shell:

bash
$ wsl

To configure WSL for building, install the following packages from the wsl shell.

bash
$ apt update 
$ apt install make gcc build-essential libc6-dev openssl libssl-dev

Then extract the Ioto source distribution:

bash
$ tar xvfz ioto-VERSION.tgz ioto

Finally build via make:

bash
$ cd ioto
$ make

To debug with VS Code, add the WSL extentension to VS Code and then from a WSL terminal, open VS Code from the ioto directory:

bash
$ cd ioto
$ code .

This will open a remote WSL project for the Ioto distribution.

Building with an IDE ​

Ioto includes Xcode projects that provide easy access for building and debugging. The generated IDE projects will build Ioto using default settings and are somewhat limited in their configurability.

To build with the Xcode on Mac OS X, run Xcode 12 or later and open the projects/ioto-macosx.xcodeproj project. Then select the Product -> Build menu option to build the software. To debug, you will need to create use Product -> Edit Scheme to set the executable to run under the Info tab, and define the working directory under the Options tab.

Build Profiles ​

You can change the build and execution profile by editing ioto.json5. Two build profiles are supported:

  • dev
  • prod

The dev profile will build Ioto with debug symbols and local state directories suitable for debugging.

The prod profile will build Ioto optimized without debug symbols. Database state and logs will be stored in the appropriate O/S locations.

After changing the profile, run:

bash
$ make clean
$ make

Changing the TLS Stack ​

Ioto includes support for multiple TLS stacks including:

Ioto is built with OpenSSL by default. OpenSSL is a leading open source TLS stack that is faster, but bigger. MbedTLS is a compact TLS implementation. When built for ESP32, the supplied ESP32 MbedTLS will be used.

Downloading OpenSSL ​

Most Linux distributions include OpenSSL with their default distribution. We support the latest stable and LTS releases only. If you want to build with a custom OpenSSL build, you will need to supply the Ioto project with the pathname to your OpenSSL source code directory.

Building with MbedTLS ​

To build with MbedTLS, install MbedTLS version 3 or later using your O/S package manager. For example:

bash
# On mac
$ brew install mbeddtls

# On Linux
$ apt-get install libmbedtls-dev

Then build via:

bash
make ME_COM_MBEDTLS=1 ME_COM_OPENSSL=0 SHOW=1

To install MbedTLS from source, download and install MbedTLS from:

bash
$ git clone https://github.com/Mbed-TLS/mbedtls.git

Then checkout the latest stable release (at least version 3.6)

bash
$ git tag
$ git checkout PICK-TAG

For a debug build:

bash
cmake -DCMAKE_BUILD_TYPE=Debug .
make VERBOSE=1

Then build Ioto:

bash
$ make ME_COM_MBEDTLS=1 ME_COM_OPENSSL=0 ME_COM_MBEDTLS_PATH=/path/to/mbedtls SHOW=1

If you wish to use test certificates, you may need this patch (needed for 3.6.0): MbedTLS Issue 8509

OpenSSL via Make ​

Ioto will build with the system installed OpenSSL libraries by default on Linux.

If you want to use a custom OpenSSL build or you are cross-compiling, run make:

bash
$ make ME_COM_MBEDTLS=0 ME_COM_OPENSSL=1 ME_COM_OPENSSL_PATH=/path/to/openssl SHOW=1

OpenSSL via Xcode ​

Open the MacOS project:

bash
$ open projects/ioto-macosx-default.xcodeproj/project.pbxproj

Then click on "Build Settings" in the panel in the center. Scroll down to define the path to your OpenSSL source code directory in the ME_COM_OPENSSL_PATH property.