View source for Build Your Connected Thing with Datonis Agent SDK

 [[Datonis Documentation Home|Datonis Documentation Home]] > [[Build Your Connected Thing with Datonis Agent SDK|Build your connected Thing]]

== Modeling your Thing ==
Any entity that connects and transmits data to the Datonis platform is called a '''<nowiki/>'Thing'.''' There are two main aspects to creating a Thing.
* You first need to create a '''Thing Template.''' A Thing Template represents a '''model or a blueprint''' of a Thing.
* You need to create an actual '''Thing.''' A Thing always belongs to a Thing Template'''.''' Once this relationship is established, you cannot change it.
For instance, let us assume that you are building an home environment monitoring system. You wish to measure the temperature and humidity in your living room and your kitchen. You should then:
* '''Create a Thing Template''' and give it a suitable name, say HomeMonitor. Specify that the HomeMonitor Thing Template will transmit two '''metrics''': temperature and humidity.
** Metrics represent actual sensor values that you need to send to the platform.
* '''Create two Things.''' Call the things LivingRoom and Kitchen. These represent the actual entities that connect and transmit data to the platform.
Here's a diagram that explains the relationship between Things and Thing Templates

Once Things and Thing Templates are understood, building your first connected Thing has the following steps.
* Create and download a '''key pair'''. Key pairs ensure that the Thing is trusted and ensures that data transmission to the Datonis platform is secure.
* Create a Thing Template and a Thing.
* Coding an Agent using the the Altizon Internet of Things (Aliot) SDK in the programming language of your choice. You will need to write some code to programmatically send data to Datonis.
** The Aliot SDK is responsible for transmitting sensor data securely to Datonis. It is available in C, Java, Python and Ruby.
Here is a short video that explains how to create a Thing Template, Things and a key-pair.

{{#ev:youtube|https://youtu.be/eS1PP7cfUgA}}

Some additional detail on the concepts shown in the video are explained below.

== Datonis Concepts ==

=== Agents ===
Agents are software programs that are responsible for transmitting Thing data to Datonis and for receiving instructions from Datonis for a Thing. An agent can be responsible for transmitting data for a single Thing or for multiple Things. You can write an agent using the Aliot SDK which is explained in detail at a later point.

=== Key Pairs ===
A key-pair is ensures that Things that connect to Datonis are allowed to do so. A key-pair contains an access and a secret key. These keys ensure that the Agent has an identity that is understood by Datonis and also ensures that the data is being transmitted by Agents is okay.

You can choose to create a key-pair per Agent (most secure) or use a key-pair per across multiple agents (easier key-pair management) depending on the access control policy that you wish to impose.

=== Thing Templates ===
Thing Templates (TT) are blueprints of the Things that you wish to model. Here are some additional features of TTs that are not explained in the video.
* You can set an '''inactivity period''' for a TT. Things belonging to this Thing Template show up as inactive if it does not transmit data within that period.
*** Inactivity is just a way to quickly know if a Thing is transmitting data or not. Let's say that you expect your HomeMonitor to transmit data every 2 minutes.
*** You can set the inactivity to a value that is greater than 2. Let's say you have set it to 5. If the HomeMonitor does not transmit data in that 5 minute period, Datonis will set the Thing as inactive. This helps you diagnose if any of your Things are having connection issues and cannot send data.
*** You '''cannot''' set the inactivity period to a value that is '''less than 5 minutes.''' 
* While adding a metric.
** Only a metric name and Data Type values are mandatory. Every thing else is optional
** The Number Data Type supports all numeric data types.
** Datonis also supports String and Boolean data types
** Set an appropriate unit of measure based on the metric (for instance C or F for temperature or bar for pressure).
** The 'Use Expression' checkbox is used to create a a '''derived or computed metric'''. This allows you to specify simple compute expressions for metrics. This is explained in detail later.

=== Things ===
Things represent a manifestation of a TT. Every Thing is uniquely identified by a 10 digit alphanumeric '''Thing Key.'''

Things can transmit three kinds of data.

==== Metric Data ====
Metric data is the most common form of data that is transmitted by Things. You have already created a Thing Template called HomeMonitor and a Thing called LivingRoom. You have defined two metrics in the template called temperature and humidity. These represent metric data. Metric data consists of a '''value''' that was measured at some point in '''time'''. For instance, the temperature was 26 Celsius (metric value) measured in the LivingRoom (Thing) at 11:45 am (time). Metrics represent '''time-series''' data values for a Thing.

Metric values are almost always Numeric but Strings and Booleans are also supported by Datonis.

==== Alert Data ====
Alerts are information about the '''state of the Thing'''. For instance, your Thing might be battery operated and you might want to send a battery low battery alert to Datonis. Or you might have detected an error from your temperature sensor and you might wish to transmit that information to the platform. Alert Data is almost always used for diagnostics. Alerts can have the following levels of severity:
* '''Info:''' Used for informational data only.
* '''Warning:''' For alerts that are important but not an error.
* '''Error:''' For error messages
* '''Critical:''' Alert for critical situations.

==== Waypoints ====
Your thing might be moving around. For instance, you are monitoring the temperature and humidity of a refrigerated truck. You wish to transmit location data for the Thing. Waypoint data is used for this purpose.

== Writing a Datonis Agent ==
With everything now set up, we are ready to start building an agent. An agent is responsible for transmitting Thing data to Datonis and interpreting instructions for Things from Datonis. The Aliot (Altizon Internet of Things) Software Development Kit (SDK) provides building blocks to create an agent. The steps for wring an Agent are:
* Download the SDK in the programming language of your choice. There is SDK support for C, Java (compatible with Android), Python and Ruby. Sample reference code is also provided along with the SDK.
* You will need the key-pair that you had created earlier and the Thing key handy to run the sample code.
* Datonis provides support for two protocols to transmit data. HTTP and MQTT
** HTTP is handy due to its ubiquitous nature and support on any device. MQTT is a lightweight protocol suited for IoT devices and it provides bi-directional support. MQTT is the preferred mode as it is more efficient.
* SSL is highly recommended and can be configured in the SDK. Non SSL connection is also supported but not recommended.
Follow the language specific tutorials to program the SDK.
* '''[[Using the Datonis Java SDK|Using the Datonis Java SDK]]'''
* '''[[Using the Datonis Python SDK|Using the Datonis Python SDK]]'''
* '''[[Using the Datonis Ruby SDK|Using the Datonis Ruby SDK]]'''
* '''[[Using the Datonis C SDK|Using the Datonis C SDK]]'''