Demo App

The Demo app is a simple cloud-based app that demonstrates sending data to the device cloud.

The Demo app uses the Standard device manager UI with a customized data schema and custom device metrics.

The Demo App is an example of a Tailored Device Manager. This means it adds a device data schema to the Standard device manager.

Demo Dashboard

The Demo App demonstrates

How to download and build the Ioto agent with custom extensions
How to create a custom database schema
How to create a device cloud and manager app
How to send device data to the cloud

This sample will:

Download and build the Ioto device agent with custom logic.
Create a regional device cloud.
Create a device manager app.
Create a custom metric based on the device data.

Device Agent

The Demo app extends the Ioto agent by providing an extension code module, database schema and agent configuration.

Device Manager

The Demo app uses the unmodified, Standard Device Manager app — so you don't need to build or upload a manager UI app.

The Demo app UI is designed to run on a mobile device, but can also be used on a desktop.

Create Product

The first step is to create an Demo product definition in the Builder.

Navigate to the Builder site and select Products in the sidebar menu and click Add Product. Then create a product definition by entering a product name and description of your choosing. Select the Ioto Agent and select By Device Volume and enter 1 in the Total Device field. Your first device is free.

Demo Product

Download Agent

Once the product definition is created, you can click Download from the Products list and save the source distribution to your system. The eval version of Ioto will be fine for this solution.

Product List

Take note of the Product ID in the product listing. You can also click on the product ID to copy it to the clipboard. You will enter this product ID in the Ioto configuration file: apps/demo/config/device.json5.

Build Agent

To build the Ioto agent with Demo extensions, first extract the source files from the downloaded archive:

1	`$ tar xvfz ioto-demo-src.tgz`

Before building, edit the apps/demo/config/device.json5 file and paste in the Product ID into the product property.

Then build Ioto with the Demo app, by typing:

1	`$ make APP=demo`

This will build Ioto, the Demo app and will copy the Demo config files to the top-level ./config directory.

Create Device Cloud

Before running Ioto, you need to create a Device Cloud for your agent to communicate with. The device cloud manages communication with devices and stores device data.

To create a device cloud, navigate to the Builder Clouds List by selecting Clouds from the side menu. Then click Add Cloud. Enter your desired cloud name, and select Hosted by Embedthis in a region close to you. You can create the cloud and connect one device for free.

Check the Upload Schema option and upload the ./config/schema.json5 file from your extracted Ioto source code. This schema defines the database for the Demo app.

Create Device Manager

To view your device state, you need to create a Device Manager that will host the Demo App UI. This will create an instance of the Standard device manager and host it globally on the EmbedThis Ioto device cloud.

Select Managers from the Builder side menu and click Add Manager. Enter your desired manager name (Demo) and pick a domain name for your Demo app. The domain will be a subdomain of the ioto.me domain and will be automatically registered and published for you. Later, if you create a dedicated device cloud, you can select your own custom domain with any TLD extension.

The Demo App uses the Standard device manager UI. In the future, if you wish to customize the UI, you can modify, rebuild or replace the portions or the whole of the underlying manager app with your own custom app.

The Standard device manager is a VueJS app that provides the following components:

Login and auth
Navigation
Device claiming
Dashboards & widgets
Device Metrics and analytics
Device data display and tables
Alerts
Responsive mobile & desktop presentation
Dark/light mode support

After creating the manager, you need to wait a few minutes (and sometimes up to 30 minutes) to let the domain name entries propagate globally. While waiting, you can start the Ioto agent.

Run Agent

The easiest way to run the Ioto agent with Demo extensions is to type:

1	`$ make run`

When Ioto is run, the Demo app will run a demo routine that updates the Service table with a counter every 30 seconds. The demo is configurable via the ioto.json5 "demo" configuration collection. The demo can be configured to tailor the delay, number of updates and the mechanism used to perform updates. See comments in the demoApp.c for details.

In the console output, you will see a unique device ID displayed. This is a Device Claim ID that you can use to claim the device for exclusive management by your Demo app. Take note of that device claim ID.

When Ioto starts, it will register with the Builder and wait to be claimed by your Demo App.

Launch Device Manager

From the Builder manager list, click the "Manage" column to launch your device manager. This will launch your default browser and navigate to the domain URL you chose when creating the manager.

Manager List

Once launched, you will need to register and create a new account with the Device Manager. This is an "end-user" account for the owner of the device.

Note: this is not the same as your Builder login.

Demo Login

Enter a username and password and click register. A registration code will be emailed to you. Enter that code in the next screen to complete the registration.

Claim Device

Once logged in, you can claim your device.

Select Devices from the sidebar menu and click Claim Device and then enter the claim ID shown in the Ioto agent console output.

Demo Claim

The Ioto agent will poll regularly to see if it has been claimed. After starting, the Ioto delay between polling gradually increases. If the agent has been running a long time, the polling period may be up to 1 minute in length. You can restart the agent to immediately check with the Builder.

Import Dashboard

After claiming, you can import the Demo dashboard from ./config/Display.json5.

Select Dashboards from the sidebar menu and click Actions/Import and select the ./config/Dashboard.json5 file.

After loading the dashboard, you can select the DemoHouse dashboard from the Dashboard list to display the Demo Dashboard.

Note: you can remove the Default dashboard at any time as it is not used by this sample.

Device Data

After claiming the device for management, you will start to see device data in the Manager app. Navigate to Device Data and you will see a list of database tables.

Table List

From the table list, click on the Service table to display its contents.

Service Table

You can edit values inline, your select a row and click edit to display the item edit panel.

Table Edit

Data Metrics

You can create data metrics from device data so that you can track and manage device data values over time. Metrics can be used to provide data for dashboard widgets such as graphs and gauges. Metrics can also be used to invoke automatic actions via metric triggers.

To create a device metric, navigate to the Builder Automations page and select the Actions tab, select your device cloud and click Add Action. Give your action a name like "Metric" and select Manager Metric from the action type list. Some actions take addition parameters, but the ManageMetric action does not.

Then select the Triggers tab and click Add Trigger.

Demo Trigger

Select Database Update as the Trigger Source and select the name of your Action created above as the Action. Select "COUNTER" as the Metric Name, "Device=${deviceId}" as the Metric Dimensions and "${value}" as the Metric Value.

This will create a metric named "COUNTER" for each device and use the value field from the Service table as the value.

Data Widgets

You can display device data as graphical widgets from the Manager dashboard. Click Home to display the dashboard.

Then click the + plus icon to open the Create Widget panel and select "Graph" as the Widget type from the selection list. Then click the Data tab at the top to configure the data source for the widget.

Select Database as the namespace, Service as the table name and value as the item field.

Then click Save. This will display your graph on the dashboard.

Demo Dashboard

How It Works

The following section provides a background on some of the design and implementation of the Demo app.

Device Agent

The Ioto device agent is extended via an Demo module. There are three files:

File	Description
demoApp.c	Code for the Demo extension

This module uses the Ioto ioStart and ioStop hooks to start and stop the extension. When linked with the Ioto agent library, these hooks replace the stub functions and are called by Ioto on startup and shutdown.

The ioStart routine checks if the demo.enable property is true in the ioto.json5 configuration file. If true, it schedules the evalDemo routine to run when Ioto connects to the cloud by using the ioOnConnect API.

Database

The database schema is used by both the Ioto agent and device cloud to define the Demo data app tables and items.

The apps/demo/config/schema.json5 defines the overall schema and the DemoSchema.json5 file defines the Demo specific portions.

The underlying agent database and the cloud database are based on the AWS DynamoDB database which is a highly scalable, high-performance, NoSQL, fully managed database.

There are 2 database tables. These are:

Name	Sync Direction	Purpose
Service	up	A service-level table with a single item.
Log	up	Log table that creates new items with each update.

The Ioto database synchronization automatically replicates data up to the cloud and down to the device according to the sync direction. You do not need to explicitly send data to or from the cloud (unless you want to). Ioto database replication does this transparently, reliably and efficiently.

Device Manager

The Demo App is an example of a Tailored Device Manager. This means it adds device data schema to the Standard device manager.

See More

For another sample, checkout the EcoHouse Sample.

Directories

Directory	Purpose
config	Configuration files
src	Demo App C source code

Key Files

File	Purpose
DemoSchema.json5	Demo database schema file
ioto.json5	Primary Ioto configuration file
schema.json5	Complete database schema file
src/*.c	Device-side app service code