Running Ioto

After building Ioto, the Ioto and other binaries and libraries will be in the bin directory.

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

export PATH=`pwd`/build/bin:$PATH

Or you can easily run Ioto via make run:

$ 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 2.4.0 ready, Device firmware 1.3.0

When Ioto runs, it listens on any required HTTP ports (if you are running the web server service) and registers with the cloud. If your selected services enable the web server, Ioto will listen for connections on ports 80 for HTTP and 443 for HTTPS and serve documents from the ./site directory.

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:

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

When Ioto starts, it reads the ioto.json5 and other configuration files from the Ioto config directory. These are copied at build-time from the apps/NAME/config directory. 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.

See Configuration Files 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 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.

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:

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.

$ 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:

$ 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	LOG_FILTER	Override the log filter definition
--verbose		Override the log filter definition
--debug		Override the log filter 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.

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:

$ 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:

$ 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 Unit testing app. The apps/unit/test.json5 configuration file defines the available test suites. You can create your own tests in the unitTest.c source file and define them in the test.json5 config file.

The default Ioto source distribution includes a demo property collection to run a simple demo test that will increment a counter and post to the device database.

demo: {
    count: 30,
    delay: '30sec',
    enable: true,
    type: 'sync',
},

The count property defines how many test iterations will be performed. The delay property indicates the delay between each test. The type property selects the type of test.

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