Skip to content

Running Ioto

After building Ioto, the Ioto and other binaries and libraries will be in the binaries directory at:

1
build/OS-ARCH-dev/bin

You may want to add this directory to your shell PATH.

1
export PATH=`pwd`/build/*-dev/bin:$PATH

Or you can easily run Ioto via:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
$ make run
app: info: Starting Ioto 2.1.1, with "standard" app 1.0.0, using "dev" profile
setup: info: Enabling services: db provision register sync serialize test web
app: info: Device Claim ID: M72DANY8BZ
register: info: Device registered with https://api.admin.embedthis.com/api
{
    "product": "01H4R15D3478JD26YDYK408XE6",
    "id": "M72DANY8BZ",
    "created": "2024-01-23T02:03:57.062Z"
}
register: info: Device not yet claimed
web: info: Listening http://:9090
web: info: Listening https://:4443
app: info: Ioto 1.4.0 ready, Device firmware 1.3.0

When Ioto runs, it listens on the required HTTP ports and registers with the cloud. By default, Ioto renders a few test pages on the embedded web server.

To manage your device from the cloud, read Managing from the Cloud.

Ioto Command Line

On Linux or Mac OS X, Ioto is installed by default in the directory /usr/local/lib/ioto. The Ioto binary program is installed at /usr/local/bin/ioto, and the Ioto configuration is at /etc/ioto.

The Ioto command line is:

1
ioto [options]

Ioto Command Options

Option Description
--account ID Manager account for self-claiming.
--background Run Ioto in the background detached from the terminal.
--cloud Token Cloud claim token for self-claiming.
--config dir Set the directory for config files.
--configFile Path to the ioto.json5 configuration file.
--debug Emit very verbose debug tracing.
--exit event or seconds Exit on event or after 'seconds'.
--home directory Change to directory to run.
--id Token Device claim ID. Overrides device.json5.
--ioto path Set the path for the ioto.json5 config.
--mode mode Select execution mode from ioto.json5 (dev,prod).
--nolocal Do not apply local.json5.
--nosave Run in-memory and do not save state.
--product Token Product claim ID. Overrides device.json5.
--profile profile Select execution profile from ioto.json5
--quiet Don't show web server headers. Alias for --show ''.
--reset Reset state to factory defaults.
--show [HBhb] Show request headers/body (HB) and response headers/body (hb).
--state dir Directory for the state files.
--test Suite Run test suite from config/test.json5.
--timeouts Disable timeouts for debugging.
--trace file[:types:from] Trace to file.
--verbose Verbose operation. Alias for --show Hhb plus module trace.
--version Output version information

Configuration

When Ioto starts, it reads the config/ioto.json5 and other configuration files from the Ioto config directory. These are copied at build-time from the apps/NAME/config directory. See Configuration Files for details.

The ioto.json5 file defines the default logging and tracing configuration. This can be overridden by command line options and environment variables. See below for details.

Logging and Tracing

Ioto provides detailed log tracing for all operational aspects of Ioto.

The Ioto tracing is configured via the log property collection in the /etc/ioto/config/ioto.json5 file.

The log property specifies the trace destination via the path property. This property can be set to stdout, stderr, or any filename or cloud to send log files to AWS cloudwatch.

1
2
3
4
5
6
log: {
    path: 'ioto.log',
    format: '%D %H %A[%P] %T %S %M',
    types: 'error,info',
    sources: 'all',
},

The format property specifies how the log messages will be formatted. It contains a printf style string with tokens that are expanded at runtime. The supported tokens are: 'A' for the application name, 'D' for the local datetime, 'H' for the system hostname, 'M' for the trace message, 'P' for the process ID , 'S' for the message source, and 'T' for the trace message type.

Message Types

Ioto classifies trace messages according to types. The supported types are: debug, error, fatal, info, and trace. The types property specifies a comma separate list of trace message types to emit.

Message Sources

Log messages are emitted from "sources". These are the names of the code module that originate the trace messages. The sources property is a comma separated list of sources. Some of the Ioto trace message sources are: "runtime", "tls", "json", "url" and "web".

You can use "all" for types and sources to match all types/sources. You can also use "!type" and "!source" to negate a type or source.

For example:

1
types: 'all,!debug,!trace'

This will emit messages of all types, except for debug and trace messages.

Command Line

The logging configuration defined in the ioto.json5 file can be overridden via via the --trace, --verbose and --debug Ioto command line options. It can also be overridden via the LOG_FILTER environment variable.

The --trace option specifies the trace file destination and a list of types and sources.

1
ioto --trace FILENAME[:TYPES[:SOURCES]]

The types are a comma separated list of message types. Valid types include: info, debug, error, trace and all. Sources are the code module names originating the trace messages. You can use "!type" and "!source" to negate a type or source.

For example:

1
2
3
4
5
ioto --trace trace.log  # Same as path:trace.log   
ioto --verbose          # Same as path:stdout, types:raw,error,info, sources:all
ioto --debug            # Same as path:stdout, types:raw,error,info,trace,!debug, sources:all
ioto --trace file:all:all 
ioto --trace file:all,!debug,!trace:all

You can also use the -v short cut for --verbose and -d for --debug.

Trace Environment Overrides

Similar to the command line options, you can override the trace configuration via two environment varables.

Command Line Options Environment Variable Description
--trace, --verbose, --debug LOG_FILTER Override the log filter definition
none LOG_FORMAT Override the log message format definition

These variables take the same string values as their command line option counterparts.

The order of precedence of configuration is:

  1. Command line --trace, --debug or --verbose options
  2. Environment variable LOG_FILTER, LOG_FORMAT values
  3. ioto.json5 configuration

Web Server Tracing

Ioto provides special control for the web server HTTP request and response tracing. You can selectively trace HTTP request and response headers and bodies via the show property.

1
2
3
4
5
6
7
log: {
    show: 'hB',
    path: 'ioto.log',
    format: '%D %H %A[%P] %T %S %M',
    types: 'error,info',
    sources: 'all',
},

The show property is a string with the following characters:

Character Description
b Show the response body
h Show the response HTTP headers
B Show the client request HTTP body
H Show the client request HTTP headers
empty Show no HTTP trace

You can override the ioto.json5 show property configuration via the --show Ioto command line option.

For example:

1
ioto --show hH

You can also override the configuration via the WEB_SHOW environment variable.

Command Line Options Environment Variable Description
--show WEB_SHOW Override the show definition

The order of precedence of configuration is:

  1. Command line --show option value
  2. Environment variable LOG_FILTER, LOG_FORMAT values
  3. ioto.json5 configuration

HTTP Client Tracing

Similar to the web server HTTP tracing, you can trace client HTTP requests and responses. Tracing HTTP client requests can be enabled via the URL_SHOW environment variable.

For example:

1
URL_SHOW=hH ioto --trace trace.log

This will trace any client HTTP requests issued via the URL module. This includes internal Ioto client requests and your own client HTTP requests that use the URL API.

Other Environment Varialbes

You can override the Ioto mode and profile settings via environment variables:

Command Line Option Environment Variable Description
--mode MODE IOTO_MODE Override the execution mode (cloud | local)
--profile PROFILE IOTO_PROFILE Override the execution profile (dev | prod)

Test Suites

Ioto provides a test facility via the test.json5 configuration file. This file describes various tests and suites of tests that are defined in the test.c source file.

The initial Ioto source distribution enables the cloud.services.demo property to be set to the demo-suite. This is the same as running Ioto with the --suite demo-suite switch. This will run a simple demo test that will measure the devices CPU load and post that to the device cloud.

You can create your own tests in the test.c source file and define them in the test.json5 config file.

Ioto Manual Pages

This Ioto distribution provides manual pages that can be viewed (on Unix-like systems) using the systems man command. Text copies of the pages are included below:

Topic Description
ioto Ioto device agent
db Database client program
pass Password manager
url URL HTTP client test program