Skip to content

Building Ioto Apps

This Ioto Apps distribution provides several sample device management applications for Ioto and includes a copy of the Ioto agent distribution.

The Ioto samples are available as source code distributions from the Builder Site. To download, first create an account and login, then navigate to the product list, select the Ioto Eval and click the download link. Then select the desired Ioto or Ioto sample package.

Download Source Package

The Ioto samples distribution contains all the required source files, headers, and build tools to build both the Ioto agent and Ioto samples.

Several build environments are supported:

  • Linux — Linux 4 with GNU C/C++
  • Mac OS X — Mac OS X 11 or later

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.

Preparing to Build

To build the samples, NodeJS must first be installed. NodeJS is used as part of the build process to build the UI apps.

To install Node, go to:

1
https://nodejs.org/en/

and download the LTS distribution. Follow the instructions to install.

Management Apps

The Ioto distribution build includes several demo apps for local or cloud-based management. Apps demonstrate device-side logic and include the client-side UI to manage devices.

The default app is the "manager" app which builds the standard Ioto Device Manager using a developer skin.

Name Directory Description
cloudkick apps/cloudkick Cloud-based Kickstart sample "router" skin for the cloud Device Manager.
console apps/console Local developer console for Ioto.
kickstart apps/kickstart Local Kickstart sample "router" management app.
manager apps/manager Build the standard cloud-based Ioto Device Manager with a developer skin.

The "console" app is a local developer management app that communicates with the local web server in Ioto. This app is ideal for testing local management.

Each application has a README.md in the app directory that describes the application and provides operational instructions.

You can select the desired app when building via the APP=NAME option:

1
$ make APP=kickstart

Configuration

You do not need to use a configure program when building via make. Instead, you simply run make and select your desired App. This will copy the App's configuration and conditionally compile the required services based on the App's config/ioto.json5 configuration settings.

The configurable 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 with Make

If you are using ESP32, please follow the instructions in the Building ESP32 document.

The top level Makefile parses your selected App's config/ioto.json5 configuration file, detects your operating system and CPU architecture and then invokes the appropriate project Makefile for your system.

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

1
$ make APP=manager

Running Ioto

To run ioto, type:

1
$ make run

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

1
2
3
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.

Build Profiles

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

  • dev
  • prod

The dev profile will configure Ioto suitable for developement. It will define use local directories for state, web site and config files. It will also define the "optimize" property to be "debug" which will build Ioto with debug symbols.

The prod profile will build Ioto suitable for production deployment. It will define system standard directories for state, web site and config files. It will also define the "optimize" property to be set to "release" which will build Ioto optimized without debug symbols.

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 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 value of the profile property.

You can override the "optimize" property by building with a "OPTIMIZE=release" or "OPTIMIZE=debug" make environment variable.

Debugging

To build Ioto with additional memory and stack debug checks, enable the ME_FIBER_CHECK_STACK compilation variable. This will cause the Ioto runtime to check stack integrity and track overall stack and fiber usage. This does have a performance impact and should only be used in debug builds.

1
DFLAGS=-DME_FIBER_CHECK_STACK=1 make clean build

Stack Size

Ioto uses fiber coroutines for parallelism instead of threads or callbacks. The size of fiber stacks is defined via the limits.stack property in the ioto.json5 configuration file. Set this value to be sufficient for your application needs.

In general, it is recommended that you avoid the use of large stack-based allocations and use heap allocations instead. It is also advised to limit the use of recursive algorithms.

A default stack of 32K should be sufficient for core Ioto use on 32-bit systems. For 64-bit systems, 64K should be a minimum.

Directories

Directory Purpose
apps Managmement applications
bin Build tools
build Build artifacts
config Ioto configuration files for device registration, testing and web server
ioto Ioto source code distribution
scripts Device management scripts including OTA script
site Web documents for embedded web server
state Runtime Ioto provisioning state and

Key Files

File Purpose
LICENSE.md License information
config/device.json5 Device registration file
config/display.json5 UI display configuration for management apps
config/ioto.json5 Primary Ioto configuration file
config/schema.json5 Database schema
config/signature.json5 Web server REST API signnatures
config/web.json5 Embedded web server configuration