Mar 1, 2023

Using the Ioto Embedded Web Server

home

Ioto has a high performance embedded web server for local device management that can be used as a dedicated embedded web server with or without any cloud management. The Ioto embedded web server has everything you need to create fast, efficient direct device management applications.

This post is the start of a series focussing on the embedded web server inside Ioto.

This article will cover installation and building. Subsequent posts will cover:

Ioto Features

Blazing fast, secure and compact embedded web server.
HTTP/1.1 and SSL/TLS support.
Sessions and cookie management.
Authentication and user management.
Embedded database for device data.
URL actions bind URLs to C functions with exceptional performance.
Transfer chunking and mulit-part mime file upload.
HTML helpers for encoding, decoding and escaping.
Tiny footprint: Web server component is 25K code.
Easy extensions via the simple integration API.
Hardened security from extensive peer-review and fuzz stress testing.
Unrivaled performance: >9,300 request per second on a Raspberry PI.

Background

The challenge of implementing effective device management can be tackled using various approaches. However, some designs that have been widely used are slow, inefficient, and less secure. One such technique that should be avoided is the use of CGI to create embedded management apps.

Fortunately, a better approach has emerged in recent times, which involves the use of Single Page Applications (SPAs) built using frameworks like VueJS or React. This approach splits the task of device management into two parts - a UI/UX portion that runs in the browser and a device-resident portion that provides data-only to the browser or mobile UI. With this approach, the device agent with the embedded web server does not generate HTML pages, as they are generated dynamically in the browser. Instead, the focus of the device agent is on managing the device hardware and not on creating user interfaces.

The end result is a simpler, more secure, focused device agent.

What is needed for effective device management

Embedded web server to listen for HTTP requests and respond with device data
Effeciently capture, store and manage device data and configuration
Generate dynamic data responses based on current device data
Receive requests and respond with data in JSON format
Support TLS (SSL) for secure communications
Support Optional file upload
Efficient and impose little load on the device
Fast – serve device data with minimal delay
Support the needs of single-page management apps via: user login, management and sessions

Ioto is the latest generation of embedded web server and includes the lessons learned from over 20 years developing and creating connected devices and embedded web servers. It implements all that you need for secure, efficient device management.

Getting Started

Create a Builder Account

The first step is to go to the EmbedThis Builder Portal and create an account.

The Builder Portal is a site that supports device manufacturers to design, configure, and manage device management solutions. It provides access to device agent software, helps creates and manages Device Clouds and includes a support portal to engage with EmbedThis support staff.

Create a Product Definition

Once you have created your account, create a product definition for your project. For each product or product family, you should to create a Builder product definition that describes your device and selects the Ioto device agent.

Product Add

Download the Ioto Agent Software

From the product list, you can now click the Download link to download the Ioto Software.

Product List

You can also download the Kickstart sample device management application. We’ll discuss that in another blog post.

Extracting

Once downloaded, extract the files and move into the top level directory.

$ tar xvfz ioto-src.tgz
$ cd ioto-VERSION
$ more README.md

The README.md includes a wealth of information. You can also read the README Online.

Ioto Configuration

Ioto is controlled by several configuration files in the ./config directory.

ioto.json5 — for top level Ioto configuration
web.json5 — for the embedded web server component
device.json5 — for device registration and provisioning

These files are in JSON5 format which is a more human-readable extension to JSON.

The configuration files support multiple configurations that can be selected based on the defined profile and mode properties.

The profile property defines whether the product is built for development (dev) or production (prod). The mode property selects an operational mode (cloud or local) that defines which services to enable.

The config/ioto.json5 is the primary Ioto configuration file. It controls which services are enabled and important global configuration parameters.

The web.json5 controls the embedded web server and the device.json includes device identification and provisioning information.

Enabled Services

You can customize the enabled services services changing the appropriate properties in the services collection.

{
    services: {
        database: true,
        keys: false,
        logs: false,
        mqtt: true,
        provision: true,
        shadow: false,
        sync: true,
        register: true,
        serialize: "auto",
        url: true,
        web: false,
    }
}

See the ioto.json5 documentation for the meaning of each of the services.

Preparation

To build from source, NodeJS must first be installed which is used during the build process.

To install Node, go to: https://nodejs.org/en/ and download the LTS distribution and follow the instructions to install.

Building from Source

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, CPU architecture and then invokes the appropriate project Makefile for your system.

You can configure Ioto to compile and build only the required services. When run, Makefile will parse the config/ioto.json5 configuration file for the enabled services and will then create a src/ioto-config.h C header that is included by the source.

To build, run:

$ make

Customizing the build

If you change your operational mode or customize the services enabled in the config/ioto.json5 configuration file, you will need to rebuild via:

$ make clean
$ make

To see the build commands, add the SHOW=1 argument to the make command:

$ make SHOW=1 build

By default Ioto will build using MbedTLS for the TLS (SSL) protocol. To build with OpenSSL instead, use the following:

$ make ME_COM_OPENSSL=1

If you are using a custom OpenSSL build, you can provide the path to your OpenSSL build via the ME_COM_OPENSSL_PATH. For example:

$ make ME_COM_OPENSSL=1 ME_COM_OPENSSL_PATH=/path/to/openssl/build

Running

To run, first put the directory “build/OS-CPU-PROFILE/bin” in your path.

Then invoke ioto.

$ ioto

app info: Starting Ioto 1.0.0 in "local" mode using "dev" profile
web info: Listening http://:80
web info: Listening https://:443
app info: Ioto 1.0.0 ready

Invoke with the ‘-D’ option for debug trace.

Configuring the web server

The Ioto web server is configured via the web.json5 config file. Here is a sample:

{
    documents: "./site",
    listen: [
        "http://:80",
        "https://:443",
    ],
    redirect: [
        { status: 302, to: "https://" },
    ],
    roles: ["user", "admin"],
    routes: [
        { match: '/api/public/' }
        { match: '/api/', role: 'user' }
        { match: '/assets/' }
        { match: '/index.html' },
        { match: '/' },
    ],
}

This will serve static documents from the site directory over port 80 and over port 443 using TLS. All non-encrypted traffic will be redirected to use TLS. A set of routes are defined that define how requests are to be processed and what authenticated role is required to access the route.

See the web.json5 reference for full details of all the configuration properties.