Building Ioto

Ioto releases are available as source code distributions from the Builder Site. The Builder portal provides an integrated service for creating connected devices, downloading device software, creating and managing device clouds.

To use Builder, you need to register and create an account. This is a simple, one-time task that will take you just a few minutes.

To register, navigate to the Builder site https://admin.embedthis.com, and enter your email address and desired password and click on the Register tab. You will be sent an email confirmation code to complete your builder login.

If you have been invited to a Builder account by a co-worker, please click on the link in the invite email. That will ensure you become a member of the account that invited you.

Management Apps

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. The "eco" app emulates a simple Home charging networks and a mobile app.

Name	Directory	Description
auth	Simple embedded web server user/group authentication.
blink	Minimal ESP32 (only) blink app to demonstrate linking with Ioto on ESP32 microcontrollers.
demo	Cloud-based management of a device. Demonstrates simple data synchronization and metrics.
eco	Customized cloud-based device management of an "EV Charger" demo app.
noapp	Stubs to build Ioto without an app

The separate Ioto Sample Apps package provides the following additional apps based on the Ioto Device Manager framework:

Name	Directory	Description
cloudkick	apps/cloudkick	Cloud-based Kickstart sample which emulates a simple "router" device.
kickstart	apps/kickstart	Kickstart local management sample which emulates a simple "router" device.
manager	apps/manager	Source code for the Ioto Device Manager framework.

Downloading Ioto

To download the Ioto device agent, visit the Products page and click on the Download icon for the Ioto Evaluation Product. This will download the complete Ioto evaluatione source code package.

Download Source Package

In the future, you can create a product definition for your product, purchase a subscription and download the release software or any historical device agent version.

You can also download the Ioto Apps package which is a suite of full device management apps.

Extracting the Ioto Source Code

Copy the downloaded ioto-eval-src.tgz compressed tar archive to a suitable directory and extract the contents. This will place the ioto source in a ioto-1.0.0 directory.

The eval source is a recent release and is always set to verion 1.0.0. It may not include all the latest features and patches that are present in the full release -- but it is ideal for evaluating Ioto.

$ tar xvfz ioto-eval-src.tgz
x ioto-1.0.0/EVAL.md
x ioto-1.0.0/LICENSE.md
x ioto-1.0.0/Makefile
...

Building Ioto

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.

The 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.

Build Configuration

You do not need to use a configure program when building via make. Instead, you edit the apps/NAME/ioto.json5 configuration file and then run make. This will copy the 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.

The ioto.json5 services property collection defines which services to build and enable when running Ioto.

The ioto.json5 configuration file has some conditional properties that are applied depending on the selected profile. These properties are nested under the conditional property and the relevant set are selected are copied to overwrite properties of the same name at the top level. This allows a single configuration file to apply different settings based on the current values of the profile property.

The selectable Ioto services are:

• database -- Enable the embedded database
• demo -- Demonstrate sending data to the cloud
• keys -- Get AWS IAM keys for local AWS API invocation (dedicated clouds only)
• logs -- Capture log files and send to AWS CloudWatch logs (dedicated clouds only)
• mqtt -- Enable MQTT protocol
• provision -- Dynamically provision keys and certificates for cloud based management
• register -- Register with the Ioto Builder
• serialize -- Run a serialization service when making the device
• shadow -- Enable AWS IoT shadow state storage
• sync -- Enable transparent database synchronization with the cloud
• 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) 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:

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

$ 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 extentension 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 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.

Running the Ioto Command

To run ioto, type:

$ make run

or add the directory build/bin to your PATH environment variable and invoke directly.

export PATH=`make path`

$ ioto -v

If your selected app enables the web server, Ioto will listen for connections on ports 9090 for HTTP and 4443 for HTTPS and serve documents from the ./site directory when run with the dev profile. When run with the prod profile, it will serve documents from /var/www/ioto and will listen on port 80 and 443.

Embedding Ioto

If you wish to embed the Ioto library in your main program, such as you will do with FreeRTOS, you will need to include the ioto.h header in your source and call Ioto APIs to initialize and run.

Including Ioto

In your main program, use:

    #include "ioto.h"

    int main() {
        // If FreeRTOS, you need to call vTaskStartScheduler() before ioRun

        //  Start the Ioto runtime
        ioStartRuntime(1);

        //  Run Ioto services until instructed to exit
        ioRun();

        ioStopRuntime();
    }

    int iotStart() {
        //  This is invoked by ioRun when Ioto is ready
        //  Put your user code here
    }
    void iotStop() {
        //  This is invoked by ioRun when Ioto is shutting down
    }

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

Installing Ioto

One Linux or MacOS, you can natively install Ioto to the standard system directories by using make install.

$ sudo make install
[Run] make --no-print-directory -f projects/ioto-macosx-dev.mk install
[Info] Ioto installed at /usr/local/lib/ioto/1.4.0
[Info] Configuration directory /etc/ioto
[Info] Documents directory /var/www/ioto
[Info] Executables directory /usr/local/lib/ioto/1.4.0/bin
[Info] Use "man ioto" for usage
[Info] Run via 'cd /etc/ioto ; sudo ioto'
[Info] Then browse to http://localhost
[Info] install complete

After installing, you can run via:

cd /etc/ioto
sudo ioto

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 mbeddtls

# 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

OpenSSL via Xcode

Open the MacOS project:

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

Product Issues

The Builder is used to track issues and security notices.

Go to the Builder Products List to see the product list and product security center.

To open a bug report, use the Builder Support Center to open a case ticket.