Skip to content

Building Ioto from Source

Ioto releases are available as source code distributions from the Builder Site.

The EmbedThis Builder is a site and service that helps you create and manage your internet connected devices. It is used to define your connected device products, download device agent software, and configure, control and monitor your devices. It is also the portal to purchase subscriptions, receive support, and resolve issues with the guidance of EmbedThis staff. The Builder is a developer's one-stop shop for creating connected devices.

Builder Site

Create a Builder Account

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.

Register

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.

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.

Products Page

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.

If you require a full local device management app, see the Kickstart sample local management app.

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 somewhat recent copy of the full 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.

1
2
3
4
5
6
$ 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
x ioto-1.0.0/README-CLOUD.md
...

Preparing to Build

To build Ioto from source, the NodeJS and NPM build tools must first be installed.

To install Node with NPM, goto: https://nodejs.org/en/ and download the LTS distribution. Follow the instructions to install.

Building Ioto

Two build environments are supported to build Ioto: Linux and Mac OS. For other environments, you will need to cross-compile. The source code has been designed to run on FreeBSD, Linux, Mac OS, VxWorks, FreeRTOS and other operating systems.

Ioto provides a suite of generated, pre-configured Makefiles for common platforms. These are simple, clean, generated makefiles that build a default configuration for a specific operating system. These makefiles are provided under the ./projects directory.

A top level Makefile is provided that parses your config/ioto.json5 configuration file, detects your operating system and CPU architecture, enables selected services and features and then invokes the appropriate project Makefile for your system.

The default build of Ioto is configured to run the embedded web server and listen on port 9090 for HTTP and port 4443 for HTTPS and to connect to the cloud for cloud-based management. If you change the service settings in ioto.json, rebuild via make clean; make to compile in the required services. To change the web ports, edit config/web.json5.

You can now build Ioto by changing to the ioto-1.0.0 directory and typing make.

1
2
3
4
5
6
7
$ cd ioto-1.0.0
~/ioto-1.0.0 $ make
       [Run] make --no-print-directory -f projects/ioto-macosx-dev.mk compile
      [Info] Use make SHOW=1 to trace executed commands.
      [Copy] build/macosx-arm64-dev/inc/osdep.h
      [Copy] build/macosx-arm64-dev/inc/uctx.h
      ...

For more details, please read the README.md, README-CLOUD.md included with the source distribution.

Running Ioto

If you want to skip ahead and run Ioto now, read Running Ioto. To manage your device from the cloud, read Managing from the Cloud

Installing Ioto to System Directories

You can also 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

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.

Configuration

You do not need to use a configure program when building via make. Instead, you edit the ioto.json5 configuration options and then run make to generate a src/ioto-config.h configuration file that will conditionally compile the required services.

If you change the ioto.json5 settings, you may need to rebuild to reflect the changed configuration. To rebuild:

1
2
make clean
make

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 mode and 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 mode and profile properties.

Operational Modes

You can select an operational mode that will customize the services and capabilities provided by Ioto.

The mode is determined by the ioto.json5 "mode" property. You can modify this by editing the ioto.json5 file.

The following modes are supplied, and you can easily add your own mode to the ioto.json5 file.

  • cloud
  • local

To display the current mode, invoke:

1
make mode

Cross Compiling

Building Ioto for platform different to that of the local system is called cross compiling. Sometimes this compiling is just for a different instruction set (say x64 instead of x86). Other times, it is for a completely different operating system and/or CPU architecture. In such cases, a cross-compiler is typically required to build for the target platform.

To cross compile, you will typically need to install a cross-compiler tool chain for your target architecture. Once installed and before you attempt to build Ioto, it is best to test compiling a simple, stand-alone HelloWorld program to ensure the cross compiler is working correctly.

To cross-compile Ioto, you invoke the relevant project makefile and pass the required CPU architecture as a make variable. For example, to cross compile for VxWorks on ARM:

make -f projects/ioto-vxworks-default.mk ARCH=arm PROFILE=debug

When make executes, it places the output products (executables, libraries and objects) in a platform-specific output directory. This is named using the form: OS-ARCH-PROFILE. For example: vxworks-arm-debug. In this manner, make can be invoked multiple times, once for each target platform and the results will be captured in separate platform output directories. Some of the supported architectures for the ARCH field are:

1
arm, mips, ppc, x64 and x86.

The PROFILE variable is a descriptive name chosen by you for your configuration.

If there is not a makefile for your target operating system, copy the closest makefile and edit to suit your target platform.

Specifying the CPU

The build will use the generic CPU type within the specified architecture. To override the default choice and specify a CPU type within an architecture, use the CPU variable. For example:

make OS=vxworks ARCH=arm CPU=arm7tdmi

Specifying a Tool Chain

You may need to specify where make can locate your cross-compiler and other tools. You can supply these via the make variables: CC, CFLAGS, DFLAGS, IFLAGS, LD and LDFLAGS. For example:

make CC=/opt/bin/ccarm.exe LD=/opt/bin/ccarm.exe ARCH=arm PROFILE=release -f projects/ioto-vxworks-default.mk

Building with an IDE

Ioto includes Visual Studio and 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.

Building with Xcode

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.

Building with OpenSSL

Ioto includes support for multiple TLS stacks including:

MbedTLS is a compact TLS implementation suitable for embedded devices. Ioto includes the MbedTLS distribution and will build with it by default on MacOS. Ioto is built with OpenSSL by default on Linux. OpenSSL is a leading open source TLS stack that is faster, but bigger.

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 OpenSSL via Make

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

If you are building with make and want to use a custom OpenSSL build or you are cross-compiling, first copy the built OpenSSL libraries (libcrypto and libssl) to your build/*/bin directory. Then set the path to your OpenSSL source directory when you run make:

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

Building Ioto with OpenSSL via Visual Studio

To set the path to your OpenSSL source directory, select "View -> Property Manager". Select "ioto" and edit the "product" property page by expanding Debug. In the "product Property Pages" dialog, add a User Macro definition for the OpenSSL source directory.

ME_COM_OPENSSL_PATH path/to/openssl

Building Ioto with OpenSSL via Xcode

To set the path to your OpenSSL source directory, click on "ioto-macosx-default" on the left to display the project settings. Select under "PROJECT" the "ioto-macosx-openssl_10" project and 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.