ITTIA DB SQL Getting Started Guide

Phytec phyCORE-i.MX 8M Mini/Nano

June 2021
Contents

Introduction.....................................................................................................................................................................3
About ITTIA DB SQL Database ...............................................................................................................................3
About Phytec phyCore-i.MX 8M Mini ..................................................................................................................3
Obtaining ITTIA DB SQL for phyCore-i.MX 8M Mini/Nano ......................................................................3
Running the Database for the First Time ..........................................................................................................4
Connecting to the ITTIA DB Console with a Browser..................................................................................5
Process Time Series Embedded Data .............................................................................................................5
Concurrent Read and Write to Flash Media ................................................................................................8
Secure Data on the Device with DB-SEAL ....................................................................................................9
ITTIA DB SQL Package Contents......................................................................................................................... 10
Programs ................................................................................................................................................................... 11
Libraries .................................................................................................................................................................... 11
Documentation....................................................................................................................................................... 11
How to Setup Yocto Linux for Application Development with ITTIA DB SQL.............................. 12
Technical Support ...................................................................................................................................................... 12
Introduction
The purpose of this document is to provide information on data processing, management,
and distribution for i.MX 8M Mini/Nano devices manufactured by Phytec. The i.MX 8
applications processor is a feature- and performance-scalable multicore platform that
includes single-, dual- and quad-core families based on the Arm Cortex architecture. Each
section on this document describes a specific set of steps to embed database with this i.MX
8 applications processor. The target audience for this document is developers.

About ITTIA DB SQL Database

ITTIA DB SQL is an embedded relational database management system for intelligent
applications on mobile devices and other embedded systems. ITTIA DB SQL brings robust
data management facilities to bear on the tough data management problems now faced by
embedded developers, in a package that is lightweight, cross-platform, fast, and easy to use.

About Phytec phyCore-i.MX 8M Mini

The Phytec phyCore-i.MX 8M Mini can have access to full data management capabilities,
even when disconnected, by using ITTIA DB SQL.
PHYTEC hardware and software solutions enable product engineers to quickly bring new
applications to market. PHYTEC SOMs are used in a range of industrial applications with
various performance, power, and I/O requirements. ITTIA DB SQL empowers edge Phytec
SOMs to monitor and process a large volume of data quickly and efficiently. PHYTEC
devices embedded with ITTIA DB SQL database experience great performance with low
latency and high throughput.

Obtaining ITTIA DB SQL for phyCore-i.MX 8M Mini/Nano

To download ITTIA DB SQL:
1. Visit https://www.ittia.com/downloads
2. Choose Target Platform: Linux Arm Arch 64
3. Enter Target Development Board: phyCore-i.MX 8M Mini
4. Complete and Submit your contact information
You will receive:
• ITTIA DB SQL package: ittia_db_sql-x.x.x-aarch64-poky-linux.tar.gz
• License Certificate: ittia_license.dat

Running the Database for the First Time

To download and run ITTIA DB SQL:
1. Follow Linux Kit Quickstart Instructions for Preparing the Hardware
2. Follow Linux Kit Quickstart Instructions for Getting Connected
3. Determine the network address of the target hardware. Run the following command
on the target through the serial connection:
# ip addr | grep eth0$
inet 192.168.3.11/24 brd 192.168.3.255 scope global eth0

4. Transfer ITTIA DB SQL and License Certificate file to the target hardware. For
example, from a Linux host or Windows 10 host with April 2018 Update:
$ scp ittia_db_sql-*-aarch64-poky-linux.tar.gz [email protected]:
$ scp ittia_license.dat [email protected]:

5. On the target hardware, set the ITTIA_LICENSE environment variable to file name of
the License Certificate:
# export ITTIA_LICENSE=$HOME/ittia_license.dat
 6. Extract ITTIA DB SQL on the target hardware:
# tar xf ittia_db_sql-*-aarch64-poky-linux.tar.gz

7. Run ITTIA DB Console on the target hardware:

# meta-ittia-ittiadb-sdk/recipes/ittiadb/ittiadb-*/*/bin/ittiadb console \
--config-data="ittiadb-console: { default: { database: {\
example: { location: example.ittiadb, access: write, open_mode: create }\
} } }"

This command starts the ITTIA DB Console HTTP server and creates an empty database file
in the current directory.

Connecting to the ITTIA DB Console with a Browser

ITTIA DB Console is a tool for applications and developers to access ITTIA DB SQL through
robust web services with a web-based graphical user interface. It provides a simple yet
powerful way to create and manage data, design schemas, generate simulated data, and test
SQL queries. ITTIA DB Console includes many features to remotely manage data:
1. SQL: Execute SQL statements and queries
2. Database Monitoring: Monitor schema definitions and describe tables
3. Table Schema: Monitor table structures and content (columns, fields, indexes, etc.)
4. Replication: Monitor and configure data distribution settings for both databases and
tables
5. Import and export: Access data in XML or JSON format
To access ITTIA DB Console, open a web browser on the host computer and connect to the
network address of the target hardware. For example:
http://192.168.3.11:8080

Process Time Series Embedded Data

ITTIA IoT Stream Processing is a high-performance data processing solution for IoT edge
network devices. An IoT Stream receives data from sensors and other data sources in real
time. Continuous queries process data as it arrives and push the results to applications and
materialized views.
Developers create IoT Streams with SQL create stream statements and write continuous
queries as SQL cselect statements. This tutorial explains how to quickly get started
processing data using only the ITTIA DB IoT Stream server and a web browser.
An IoT Stream is created with an SQL create stream statement. Go to the Continuous Query
tab and execute this statement to create an IoT Stream named drill_sensors.
create stream drill_sensors (
 sensor_id bigint primary key,
start_time timestamp not null,
end_time timestamp not null,
temperature_C float64 not null,
pressure_Pa float64 not null
)

You can use the ITTIA DB Console to submit data to an IoT Stream directly from a web
browser. Open ITTIA DB Console in a new browser window, select drill_sensors from the
sidebar, and go to the Content tab.

Press the Generate button to start generating data at a constant sample rate. Press
Increment or Random next to any field to change the value over time.
A continuous query processes new data from a data source and displays changes to the
query result state in real time.
To manually execute a continuous query in your web browser, open ITTIA DB Console in a
new browser tab or window, select drill_sensors from the sidebar. Go to the Query tab and
execute this statement:
cselect *
from drill_sensors
where temperature_C > 70

The results of this query will initially be empty. But when data matching the where clause is
submitted by a sensor_data data source, it will be immediately displayed in the continuous
query browser tab or window. Furthermore, if data is submitted that does not match the
where clause, the row corresponding to that sensor will be immediately removed.
Multiple continuous queries can be run at the same time. To run another query, open the
same drill_sensors Query tab but in another browser tab. Execute this statement:
cselect sensor_id,
8.314 * (temperature_C + 273.15) / pressure_Pa
as volume_m3_per_mol
from drill_sensors

This query calculates the volume per mol of each sensor from the ideal gas law, PV=nRT.

Concurrent Read and Write to Flash Media

IoT streams are also integrated with a database storage engine. The results of a stream can
be stored in a database table. To create a database table, click on the database and go to the
Query tab. Execute this statement:
create table high_temperature_events (
sensor_id integer not null,
start_time timestamp not null,
end_time timestamp not null,
temperature_C float64 not null,
primary key (sensor_id, start_time)
)
To put the data of the drill_sensors stream into the high_temperature_events table, click on
drill_sensors and go to the Query tab. Execute this statement:
insert into persistent_database.high_temperature_events
cselect sensor_id, start_time, end_time, temperature_C
from drill_sensors
where temperature_C > 70

Once the data from the drill_sensors stream is in the high_temperature_events table, more
traditional SQL queries can be executed in the Query tab. This can be useful to answer
questions that require looking back at the data over a long period of time. For example, the
following query identifies the sensors that spent the most time with a temperature
exceeding 70 degrees Celsius over the last 24-hour period.
select sensor_id,
count(*) as number_of_events,
sum((end_time – start_time) second) as total_duration
from high_temperature_events
where start_time > localtimestamp – interval '1' day
group by sensor_id
order by sum((end_time – start_time) second) desc
fetch first 10 rows only

Secure Data on the Device with DB-SEAL

Though applications can specify multiple different queries that they are interested to run,
there is potential for side channel attacks. An attacker can intercept queries and modify
them by performing injection attacks. To combat this, there is a security agent, called DB-
SEAL, built into the library that keeps track of queries that have been executed. DB-SEAL
uses that data as training data. A developer can then enable a watchdog that rejects any
queries that were not recognized during the training phase. This ensures that the
applications using the database on the board are only running queries only vetted by the
developers.
ITTIA DB SQL Package Contents
The ITTIA DB SQL SDK for Phytec phyCore-i.MX 8M Mini is packaged in an OpenEmbedded
Layer. This layer can be added to a Yocto Linux project before building a custom system
image. The package contains the following folders:

Folder Description
meta-ittia-ittiadb-sdk/recipes/ittiadb ITTIA DB SQL SDK
meta-ittia-ittiadb-sdk/recipes/ittia-api-examples-c C API example programs
meta-ittia-ittiadb-sdk/recipes/ittia-api-examples-cpp C++ API example
programs
meta-ittia-ittiadb-sdk/conf OpenEmbedded layer
configuration

The contents of the ITTIA DB SQL SDK can also be accessed directly from the meta-ittia-
ittiadb-sdk/recipes/ittiadb/ittiadb-${VERSION}/${ARCH}/ directory inside the
package. This directory has the following folder structure:
Folder Description
include Header files for ITTIA DB SQL
lib ITTIA DB SQL libraries
bin Utilities and applications
share/doc/ittiadb/manuals Manuals
examples Example programs
src Supplemental database support source code

When added to a Yocto Linux project as a layer, the following packages are available:

Package Description
ittiadb ITTIA DB SQL programs
libittiasql1 ITTIA DB SQL libraries
libittiasql1-dev Headers for ITTIA DB SQL libraries
libstorage-staticdev ITTIA DB C++ API
ittia-api-examples-c C API example programs
ittia-api-examples-cpp C++ API example programs

Programs
Programs are available after installing the ittiadb package or copying the contents of
meta-ittia-ittiadb-sdk/recipes/ittiadb/ittiadb-${VERSION}/${ARCH}/bin/ to the
target system.
ITTIA DB SQL includes an interactive utility that can be run with the command ittiadb.
ITTIA DB SQL includes a light-weight data server for shared access to database files. Run
the dbserver command to start the data server.

Libraries
The ITTIA DB SQL kernel is a software library that can be directly embedded in an
application or accessed through a separate server process. The database kernel provides a
transactional C API that the application can use directly or through a variety of higher-level
APIs, include the ITTIA DB SQL C++ API, libstorage.

Documentation
ITTIA DB documentation includes:
6. Embedded Database Manual: The essential guide to ITTIA DB usage and software
development.
7. C API Reference: Reference manual for the ITTIA DB C API.

8. C++ API Reference: Reference manual for the ITTIA DB C++ API.
How to Setup Yocto Linux for Application Development with ITTIA DB
SQL
The Phytec L-1002e.A0 i.MX 8M Mini BSP Manual provides instructions to build the BSP
image and boot it onto the phyCORE-i.MX 8M Mini/Nano environment. Application
development requires a Linux build host. Follow the BSP Manual:
1. Start with the Get the BSP section and continue and stop when you get to the
Starting the Build Process section.
2. Install dependencies for the BSP using the command:
$ sudo apt-get install gawk wget git-core diffstat unzip texinfo \
gcc-multilib build-essential chrpath socat libsdl1.2-dev xterm

3. Extract the ITTIA DB SQL package into the $HOME/yocto directory.

$ cd $HOME/yocto
$ tar xf ittia_db_sql-*-aarch64-poky-linux.tar.gz

4. Configure the build:

$ source sources/poky/oe-init-build-env
$ bitbake-layers add-layer ../meta-ittia-ittiadb-sdk

5. Add ITTIA packages to the local configuration:

$ echo 'LICENSE_FLAGS_WHITELIST = "commercial"' >> conf/local.conf
$ echo 'IMAGE_INSTALL_append=" ittiadb"' >> conf/local.conf
$ echo 'IMAGE_INSTALL_append=" ittia-api-examples-c"' >> conf/local.conf
$ echo 'IMAGE_INSTALL_append=" ittia-api-examples-cpp"' >> conf/local.conf

6. Build a system image:

$ bitbake core-image-minimal

7. Deploy the system image to the target device. Directions for different deployment
options can be found in the BSP Manual under the section System Booting.

Technical Support
Do you need assistance with edge device data processing and management? Contact
[email protected] to request support.

An evaluation license includes 30-day technical support.

 Disclaimer

Information in this document is provided solely to enable system and software implementers
to use ITTIA products. No express or implied copyright license is granted hereunder to design
or implement any database management system software based on the information in this
document. ITTIA reserves the right to make changes without further notice to any products
described herein. ITTIA makes no warranty, representation or guarantee regarding the
suitability of its products for any particular purpose, nor does ITTIA assume any liability
arising out of the application of or use of any product, and specifically disclaims any and all
liability, including without limitation consequential or incidental damages. Statistics and
parameters provided in ITTIA white papers and data sheets can and do vary in different
applications and actual performance may vary over time. All operating parameters must be
validated for each customer application by customer's technical experts. ITTIA and the ITTIA
logo are trademarks or registered trademarks of ITTIA L.L.C. in the U.S. and other countries.
All other product or service names are the property of their respective owners.

Copyright (c) 2021 ITTIA L.L.C. All rights Reserved. References in this document to ITTIA
products and services do not imply that ITTIA intends to make them available in every
country.