Configuration Properties
These are the configuration properties for the primary ioto.json5 configuration file.
See the following descriptions for other configuration files:
File | Description |
---|---|
config/device.json5 | Device configuration file. |
config/web.json5 | Web server configuration file. |
modes/*/schema.json5 | Database data schema. |
api
Name | api |
---|---|
Description | Collection of API endpoint URLs. |
Synopsis | api: { "builder": "value", serialize: "value" } |
Notes | The api property collection defines various API endpoints. The api.builder endpoint is for the Builder public API. The api.serialize endpoint is for your local device serialization service employed during device manufacture. |
Example
certs
Name | certs |
---|---|
Description | Ioto Certificates. |
Synopsis | certs: { aws: 'path', url: 'path' } |
Notes | The certs.aws property defines a filename for the AWS root certificate bundle. The certs.url property defines a root certificate bundle that is used to verify domains used by the URL client. Ioto includes default certificates for the AWS root and URL root certificates. |
Example
conditional
Name | conditional |
---|---|
Description | Conditional configuration properties. |
Synopsis | conditional: { "Set-Name": { /* properties */ } |
Notes | The conditional property collection is used to define a suite of different configurations for Ioto. For example, it can select a "dev" profile for development and a "prod" profile for productions. Selections are made based on a controlling top level property. The mode and profile properties are used to select relevant configuration sets to apply. |
Example
database
Name | database |
---|---|
Description | Control the Ioto database. |
Synopsis | database: { properties... } |
Notes | The database property collection defines the database, schema and operational parameters that govern the Ioto database.The path property defines the filename of the on-disk database store. Ioto will also create a database journal log file that appends a ".jnl" extension to this path. The schema property defines the database scheme that defines the database indexes, entities and data types. The maxJournalSize defines how big the database journal log should grow before Ioto rewrites the database. The maxJournalAge defines how long data should be preserved in the journal log before the database file is updated. These values should be sufficiently log as writing updated data to the journal is much more efficient that updating the database file. The maxSyncAge property defines how long changed database data should be buffered before synchronizing to the cloud. The maxSyncSize property defined how much data should be buffered before synchronizing to the cloud. |
Example
directories
Name | directories |
---|---|
Description | Define default Ioto directories. |
Synopsis | directories: { "log": ".", state: "./state" } |
Notes | The directories property collection defines various directories used by Ioto. The directories.log directory is where log files will be saved. The directories.state directory is where runtime state including databases, provisioning information and shadow state will be stored. |
Example
limits
Name | limits |
---|---|
Description | Define execution limits for Ioto. |
Synopsis | limits: { "key": "value", ... } |
Notes | The limits property collection defines various execution limits for Ioto. The limits.reconnect property defines the delay after MQTT communications are lost before the agent will reconnect. This is useful to throttle network load in the event of a network disconnection. The limits.stack property defines the default size of fiber coroutine stacks. |
Example
limits.stack
Name | limits.stack |
---|---|
Description | Define the stack size of fiber coroutines for Ioto. |
Synopsis | limits: { stack: "Number" } |
Notes | The limits.stack property specifies the stack size for Ioto coroutines. This should be set to the maximum anticipated stack size for your executing code. The default stack size is 64K. The core Ioto code requires a stack size of 12K. It is recommended that you minimize your use of big stack buffer variables and your use of deep recursion both of which require much bigger fiber stacks. |
Example
logs
Name | logs |
---|---|
Description | Define the list of log files to ingest and send to CloudWatch logs. |
Synopsis | logs: { path: "filename", group: "log-group', stream: "log-stream" } |
Notes | The files property contains one or more file definitions to ingest and send to CloudWatch logs. The definitions define the log file name, AWS CloudWatch log group and stream names. The path property may contain wild cards and all matching files will be ingested. The group property specifies the AWS log group name which must exist. The stream property specifies the AWS log stream name which must exist. The group and stream properties may contain tokens that are expanded before use. The supported tokens are: "{hostname}" which translates to the system hostname, "{instance}" which expands to the AWS EC2 instance name and "{deviceId}" which expands to the provisioned provision.deviceId property. |
Example |
mqtt
Name | mqtt |
---|---|
Description | MQTT configuration. |
Synopsis | mqtt: { properties }" |
Notes | The mqtt property collection is used to configure MQTT communications to the cloud. The mqtt.cert and mqtt.key properties define filenames to the X.509 certificate and key used to secure MQTT communications. The mqtt.client defines the MQTT client ID used to uniquely identify the device. The alpn property defines the HTTPS ALPN identification string required when using HTTP port 443 for communications. The mqtt.ca property defines the authority certificate from AWS that is used as the root certificate to verify the MQTT broker endpoint. The cert, key, client and endpoint properties can be set to "auto" to have their values dynamically configured from AWS IoT core at runtime. |
Example
optimize
Name | optimize |
---|---|
Description | Build for debug or production release. |
Synopsis | optimize: "debug|release" |
Notes | If debug is selected, Ioto will be built with debug symbols. If release is selected, Ioto will be built optimized without debug symbols. |
mode
Name | mode |
---|---|
Description | Operational mode to select. |
Synopsis | mode: "cloud | local | ..." |
Notes | The mode property is used to select different operational modes when Ioto runs. For example, it can select a "cloud" mode to enable cloud-based management. Set to "local" to enable local device management using the embedded web server and disable cloud-based management. |
Example
scripts
Name | scripts |
---|---|
Description | Set of scripts used for various management tasks. |
Synopsis | scripts: { update: './scripts/update'} |
Notes | The scripts.update property defines a script that is invoked to apply software updates. The script is invoked with the pathname to the update image as the first and only argument. |
services
Name | services |
---|---|
Description | Configure which Ioto services to enable at runtime. |
Synopsis | services: { 'Service-Name': true | false, ... } |
Notes | The services property collection defines which Ioto services to enable. The supported services are:
Some services depend on others. Lower-level services will be forcibly enabled if upper level services require them. |
Example
trace
Name | trace |
---|---|
Description | Control the Ioto log trace file. |
Synopsis | trace: { path: 'path', format: 'format', types: 'types', sources: 'sources' } |
Notes | The trace property collection defines how and where Ioto traces execution information. The trace.path property specifies the destination of the Ioto trace log. Set it to "stdout" or "stderr", "aws" or a filename. If set to "aws", then the trace.group property specifies the AWS log group name and the trace.stream property specifies the AWS log stream name. The format specifies a leading format for the message that contains printf style 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 message, 'P' for the process ID , 'S' for the message source, and 'T' for the message type. The types property specifies the types of messages to emit. It may contain the following types: debug, error, info and trace. It may be set to "all" for all types. The sources property specifies a comma separated list of message sources to emit. Sources may be prefixed with "!" to subtract from the list. For example: "all,!mbedtls" will emit messages from all sources except "mbedtls". |
Example
version
Name | Version |
---|---|
Description | Set the agent version. |
Synopsis | version: "SemVer Version String" |
Notes | The version string defines the versions of the embedded agent including your software. It is used when selecting software upgrades deployed from the Builder. Don't confuse this with the underlying Ioto version. The version string must conform to the Semantic Versioning 2.0 spec. |