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.
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 | |
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 | |
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 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 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 | |
Running Ioto
To run ioto, type:
1 | |
or add the directory build/bin to your PATH environment variable.
1 2 3 | |
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 | |
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 |
| scripts | Device management scripts including OTA script |
| state | Ioto runtime state configuration, certificates, database and web pages |
Key Files
| File | Purpose |
|---|---|
| LICENSE.md | License information |
| device.json5 | Device registration file |
| display.json5 | UI display configuration for management apps |
| ioto.json5 | Primary Ioto configuration file |
| schema.json5 | Database schema |
| signature.json5 | Web server REST API signnatures |
| web.json5 | Embedded web server configuration |