Building Ioto

The Ioto source code has been designed to run on Arduino, ESP32, FreeBSD, FreeRTOS, Linux, Mac OS X, Windows, VxWorks and other operating systems. Ioto supports the X86, X64, Riscv, Riscv64, Arm, Arm64, and other CPU architectures. Ioto can be ported to new platforms, 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 Visual Studio 2022 or WSL v2
• ESP-32 — Using the ESP IDF in VS Code

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

Build Configuration

You do not need to use a configure program when building Ioto. Instead, you simply run make.

The Ioto distribution includes several sample apps. Apps demonstrate device-side logic to implement various management use cases. The default app is "http" which runs the embedded web server.

Name	Description
ai	Demonstrates using the OpenAI APIs.
blank	Empty slate application.
blink	Minimal ESP32 blink app to demonstrate linking with Ioto on ESP32 microcontrollers.
http	Simple embedded web server user/group authentication sample.
unit	Unit testing app.

The selectable Ioto services are:

• ai -- Enable the AI service
• database -- Enable the embedded database
• mqtt -- Enable MQTT protocol
• url -- Enable client HTTP request support
• web -- Enable the local embedded web server

Building

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

• Building on Windows
• Building for the ESP32
• Building for FREERTOS

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), utility tools (password, db, json, url, web) and all application binaries. Each app is built as ioto-NAME (e.g., ioto-http, ioto-ai) and placed in build/bin/. If you are embedding Ioto in another program, you should link the Ioto library with your program. See Linking below for details.

To build:

$ make

Make Targets

Target	Description
make	Build the library, all utility tools, and all apps (default)
make lib	Build libioto.a and utility tools only
make apps	Build all app binaries (requires library)
make name	Shortcut to build a single app (e.g. make http, make ai)
make run	Build and run the default app (http)
make test	Run the unit test suite
make clean	Remove all build artifacts
make doc	Generate API documentation
make dist	Create a source distribution tarball
make projects	Regenerate all premake project files (developer only)
make help	Show available targets and options

Make Variables

Variable	Description
OPTIMIZE=debug|release	Set optimization level (default: debug)
SHOW=1	Display compiler/linker commands during build
ME_COM_OPENSSL=1	Build with OpenSSL TLS (default)
ME_COM_MBEDTLS=1	Build with MbedTLS TLS

For example, to build a release build:

$ make OPTIMIZE=release

Building on Windows

For Windows, you can build one of three ways:

• Using Windows Visual Studio
• Using the Windows Command Prompt
• Using Windows WSL and make

Building with Windows Visual Studio

To build natively on Windows, you will need Visual Studio 2022 or later. You can download the installer from the Visual Studio website.

You will also need OpenSSL installed. You can use vcpkg to install it. Newer versions of Visual Studio include vcpkg. If you do not have vcpkg, you can install it by following the vcpkg documentation.

Install OpenSSL via vcpkg:

vcpkg install openssl

To build, first open the Ioto library solution file:

projects/vs2022/ioto.sln

Set the "Debug" configuration and build the solution. This builds the Ioto library and utility tools.

Then open the app solution for the app you want to build. For example, for the http app:

apps/http/projects/vs2022/ioto-http.sln

Build the app solution and set ioto-http as the startup project. Edit the project properties and set the working directory to the app directory (e.g., apps/http).

Building from the Windows Command Prompt

You can build from the Windows command line using the supplied make.bat which invokes msbuild on the VS2022 solution files. First, open a Visual Studio Developer Command Prompt, or set up the environment manually:

"c:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat"

The path varies by Visual Studio edition (Community, Professional, Enterprise).

Install OpenSSL via vcpkg as described in the Visual Studio section, then set the ME_COM_OPENSSL_PATH environment variable:

SET ME_COM_OPENSSL_PATH=C:\vcpkg\installed\x64-windows
make

Building with Windows WSL

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:

$ wsl --install

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

$ wsl

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

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

Then extract the Ioto source distribution:

$ tar xvfz ioto-VERSION.tgz ioto

Finally build via make:

$ cd ioto
$ make

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

$ cd ioto
$ code .

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

Building with an IDE

Ioto includes premake-generated IDE projects for Visual Studio 2022 and Xcode.

Xcode

To build with Xcode on Mac OS X, open the generated Xcode project:

$ open projects/xcode/ioto.xcworkspace

Then select the Product -> Build menu option to build the software. To debug, you will need to use Product -> Edit Scheme to set the executable to run under the Info tab, and define the working directory under the Options tab.

Visual Studio

See the Building with Windows Visual Studio section above.

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:

$ make clean
$ make

Changing the TLS Stack

Ioto includes support for multiple TLS stacks including:

• OpenSSL
• MbedTLS

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:

# On mac
$ brew install mbedtls

# On Linux
$ apt-get install libmbedtls-dev

Then build via:

make ME_COM_MBEDTLS=1 ME_COM_OPENSSL=0 SHOW=1

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

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

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

$ git tag
$ git checkout PICK-TAG

For a debug build:

cmake -DCMAKE_BUILD_TYPE=Debug .
make VERBOSE=1

Then build Ioto:

$ 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:

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