Downloading Ioto

To download the Ioto device agent, visit the Products page and click on the Download icon for the Ioto Evaluation Product. This will download the complete Ioto evaluation source code.

In the future, you can create a product definition for your product, purchase a subscription and download the release software or any historical device agent version.

Extracting the Ioto Source Code

Copy the downloaded ioto-eval-src.tgz compressed tar archive to a suitable directory and extract the contents. This will place the ioto source in a ioto-1.0.0 directory. The eval source code always has a 1.0.0 version.

The eval source is a somewhat recent copy of the full release and is always set to verion 1.0.0. It may not include all the latest features and patches that are present in the full release – but it is ideal for evaluating Ioto.

$ tar xvfz ioto-eval-src.tgz
x ioto-1.0.0/EVAL.md
x ioto-1.0.0/LICENSE.md
x ioto-1.0.0/Makefile
x ioto-1.0.0/README-CLOUD.md
...

Preparing to Build

To build Ioto from source, the NodeJS and NPM build tools must first be installed.

To install Node with NPM, goto: https://nodejs.org/en/ and download the LTS distribution. Follow the instructions to install.

Building Ioto

Two build environments are supported to build Ioto: Linux and Mac OS. For other environments, you will need to cross-compile. The source code has been designed to run on FreeBSD, Linux, Mac OS and other embedded operating systems.

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

To build Ioto for cloud-based management, select the Standard app which configures Ioto with the required cloud communication protocols and provisioning services.

Change to the ioto-1.0.0 directory and type “make APP=standard”. If you omit the “APP=standard”, the Console app for local-only device management will be built.

$ cd ioto-1.0.0
~/ioto-1.0.0 $ make APP=standard
      [Info] Building Ioto 2.1.1 optimized for debug with the "standard" app
   [Warning] Selected App has changed since the last build.
  [Selected] Selected App "standard".
      ...

This build will create the ioto command at ./build/*/bin/ioto. It will also create a copy of the Standard Device Manager which we don’t need for this exercise as it is already hosted for you by the Ioto Eval cloud.

For more details, please read the supplied README.md, README-CLOUD.md and the documentation:

• Building Ioto
• Ioto Configuration
• Ioto Sample Apps

Running Ioto

Run Ioto via make run or ioto -v.

When Ioto runs, it listens on the required HTTP ports and registers with the cloud.

$ make run
app: Starting Ioto 2.1.1, with "standard" app 1.0.0, using "dev" profile
setup: Enabling services: db provision register sync serialize
app: Device Claim ID: A9XXXXXXXX
register: Device registered with https://api.admin.embedthis.com/api
{
    "product": "01H4R15D3478JD26YDYK408XE6",
    "id": "A9XXXXXXXX",
    "created": "2024-04-02T02:41:49.048Z"
}
register: Device not yet claimed for cloud management
app: Ioto ready

Claiming the Device

When Ioto registers with the cloud, it waits to be “claimed” by a user for management. Until claimed, the agent is device can only be locally managed via the embedded web server, if enabled.

An Ioto enabled device can be claimed by an Ioto device cloud. During evalution, it is easiest to use the pre-existing Eval Cloud and Eval Device Manager. The Eval cloud is a multi-tenant, shared cloud for evaluating Ioto. The Eval Device Manager is an eval copy of the Standard Device Manager included with the Ioto agent code.

To claim the device, navigate to the builder and select the Managers page.

Click the Manage icon for the Eval manager. This will launch the Standard Device Manager.

When you register and log into the Device Manager, you are registering as a device user. This is a different account to your Builder login account. Device Manager logins are unique for each device cloud.

Enter your desired username and password and click Register. You will be sent an email confirmation code to complete your manager login.

After logging in, you will see the device list, which will be initially empty. Click the Claim Device button and enter your device claim ID to claim your device for management.

The Claim ID is the unique device ID displayed by Ioto when run. This ID is dynamically allocated when first run, but can be initialized via the config/device.json5 configuration file. During production, a generated device claim ID is typically printed on the device packaging and device label. Read more in the Builder Claiming Devices documentation.

$ make run
...
app: info: Device Claim ID: M77DANY8BZ

While an Ioto-enabled device is waiting to be claimed, Ioto will check upon reboot and then periodically with the cloud service to see if it has been claimed. Once claimed, Ioto will display:

provision: info: Device claimed
provision: trace: {
    accountId: "XXXXXXXXXXXXXXXXXXXXXXXXXX",
    certificate: "state/ioto.crt",
    endpoint: "xxxxxxxxxxxxx-ats.iot.xxxxxxxxxxxxxx.amazonaws.com",
    id: "M72DANY8BZ",
    key: "state/ioto.key",
    port: 443
}
provision: info: Device provisioned
checkin: info: Device has no pending updates for version: 1.3.0
mqtt: info: Connected to mqtt: xxxxxxxxxxxxx-ats.iot.xxxxxxxxxxxx-1.amazonaws.com:443
demo: info: Running demo cloud counter from start.c
demo: info: Send counter update via MQTT -- counter 0

When claimed, the Ioto agent will be provisioned with a unique device certificate for secure TLS communications and will connect to the cloud using the MQTT protocol. These will be saved under the ./state directory as ioto.crt and ioto.key.

Demonstration Cloud Messaging

The default Ioto configuration will run a demo routine to update a counter and send the updated value to the cloud. This counter updates every thirty seconds and can be monitored via the Device Manager.

In the Device Manager, select the claimed device from the device list.

This will then display the database tables and dashboard for this device.

The default device schema has a key/value table called the “Store”. The demo counter, will update a value with the key of “counter”. Click on the Store table to display the store contents.

This will display all the data items in the store for claimed devices. From here, you can modify an item by clicking the Edit icon or you can edit in place by clicking on a teal color cell and updating the value and then clicking Save. But note, the agent will reset the value every thirty seconds.

You can reload the table contents by clicking the table reload icon.

Manager Dashboard

The Device Manager includes the ability to display one or more dashboards with data widgets.

Click the Dashboard tab to display the default dashboard, then click the Add Widget icon to display the add widget panel.

You can display database and metric data using numeric, gauge or graphical widgets.

To display the demo counter as a numberic from the database, enter the following widget configuration:

This will select the Store table item that has a key value set to “counter” and display the “value” field.

After the ioto agent has run for a minute, there will be sufficient data points for a “COUNTER” metric to be created. Metrics permit the display of current and historical data using graphical widgets.

To display the demo counter as a graph using metrics, enter the following widget configuration:

That should get you started with Ioto and posting data to the cloud from your device.

Want More Now?

To learn more about EmbedThis Ioto, please read:

• Ioto Web Site
• Ioto Documentation
• Ioto Agent Download
• Builder Documentation
• Embedthis Web Site