HOW TO: Create an IOT Device Model

It’s necessary to make a preliminary analysis to understand what you need in order to define what should (or should not) be included in the device model.

First, you need to know if the dataset is only static or if it has also some dynamic fields that can change in the future (and with what rate):

  • The static case is the easiest, such as the collection of POI data: the data does not change over time but remains the same once set
    • In this case you will only have to follow the Device/s Creation in Snap4City and IoTApp – Static Data sections of this manual
  • The dynamic case is more interesting as a non-regular dataset can have both static and dynamic info
    • In this case the whole manual will help you manage both aspects

Afterwards it’s important to have a general overview of the dataset so that you can write a schematic of the model. The idea is to compile two tables: one in which there is the general information of the devices, the other in which are reported the attributes (variables / values) that the devices must have. In this way it will be much easier to create the IoT model and furthermore the tables can be used in the future to get an immediate idea of what has been done.

General info table:

Name

 

Device Type

 

Kind

 

Producer

 

Frequency

 

 

  • Name: an indicative prefix of the Device Model so that the name of each device begins with that prefix (e.g. “[deviceID]” -> “FlorenceAirQuality_[deviceID]” where deviceID is a string that identifies the single device). This field will be useful during devices creation. By entering this prefix, it will be possible to identify the model to which it belongs simply by its name
  • Device Type: what is the working scope of the devices? Air Quality, Weather, ...
  • Kind: will the devices be sensors or actuators?
  • Producer: where does the data come from?
  • Frequency: how often will the sensor data be updated?

Values (attributes) table:

Value Description

Value Name

Value Type

Data Type

Value Unit

Notes

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Observation time

dateObserved

timestamp

time

s

 

 

 

 

 

 

 

 

N.B.: each row corresponds to a dataset value. In the table above, dateObserved has been inserted as an example, in reality this value is mandatory in every model

  • Value Description: a brief description of the value. It must not be inserted in the model, but it is useful for you (e.g. for future uses)
  • Value Name: what name do you want to give to the value in the model? Consider using a camelCase style
  • Value Type: what is the working scope of the value? When you create the model, it will be possible to choose only from a predetermined list. For now, enter a free text and when you have created the IoT Model, replace the one you wrote with one of the choices proposed by the platform. If the value type you want isn't listed, contact the Snap4City team to get it added
  • Data Type: what type is the value, in computer programming? Float, integer, string, …?
  • Value Unit: what unit of measure does the value have? If it doesn't have one (e.g. a string), enter a dash - . When you create the model, it will be possible to choose only from a predetermined list. For now, enter a free text and when you have created the IoT Model, replace the one you wrote with one of the choices proposed by the platform. If the value unit you want isn't listed, contact the Snap4City team to get it added
  • Notes: Any notes that may be helpful in the future to justify certain choices or to remember something additional. They must not be inserted in the model

 

Path in Snap4City: “MENU > IOT Directory and Devices > IoT Devices Models > New Model

Type of user:  Tool admin

Guidelines to create the model:

  • General Info Tab:
    • Name: model name in upper camel case style (e.g. FlorenceAirQuality)
    • Description: short description of the model
    • Device Type: kind of device sensors in upper camel case style. The name must not relate to ontology. E.g. AirQuality, TerrainSensor, SoilHumidity, etc.
    • Kind: sensor or actuator
    • Producer: name of the sensor’s producer
    • Frequency: time (in seconds) to update the sensors data in the IoTApp
    • Healthiness Criteria: Refresh rate (default value)
    • Healthiness Value: same value as frequency (default value)
    • Key Generation: Automatically generated (default value)
    • Edge-Gateway Type: void (default value)
  • IoT Broker Tab:
    • ContextBroker: choose the broker according to the Organization
    • Protocol: ngsi (default value)
    • Format: json (default value)
  • Values Tab:
    This is the core of the model. Remember that the association with one of the ontology classes depends on the value type.
    • Value Name: name of the variable in camel case style (e.g. batteryLevel)
    • Data Type: type of data in computer programming
    • Value Type: kind of data, ontologically
    • Editable: false (default value)
    • Value Unit: unit of measurement of the variable
    • Healthiness Criteria: Refresh rate (default value)
    • Healthiness_Value: time (in seconds) to update the variable in the IoTApp
      WARNING:  Value Type = timestamp there can be only one for each model (and Device) and must be associated with the Value Name: dateObserved, mandatory in each model (see below). If other dates are present, they must be put as datetime.
      If data types, value types, value units are not enough, contact snap4city@disit.org
      dateObserved: it must contain the measurement date of each sensor connected to the device and must have the following characteristics in the model:
  • Value Name: dateObserved
  • Data Type: time
  • Value Type: timestamp
  • Value Unit: s

Example:

Florence Charging Stations (open data municipality of Florence) – Florence organization

General Info Tab:

IoT Broker Tab:

Values Tab:

Comments

Just wanted to ask if my understanding is correct.

An IoT Device Model I assume will describe a Device Type. So in our case we have an Outdoor Lamp Controller (for controlling and monitoring Streetlights). 
The device itself includes both sensor and actuator parts. In our case the the Device Type is general for our streetlight application so there is no sense to lock the name of the Device Model to a certain locality/city. The same devices wil be used in many places.

Regarding frequency; mainly the device will send updates when something change more that a specified delta. 
However, there will be an event that if a max time that expires a value will be sent even if it has not changed. However, different values may have different of these so called MaxSendTimeout.

So assume that we have multiple types of Outdoor Lamp Controllers (OLC), and they may have a different set of features and attributes. It could be small differences but still.

As I understand an Device Model is actually describing a single Device Type.
So if we have five different OLC types, hence five different Device Types. So here we would create five different IoT Device Models, for example.
OLC01a
OLC02a
OLC03a
OLC04a
OLC05a

In the IoT Device Model there are Name and Device Type as attributes.

I would say that the Name is then the unique ID/Name for the Device Model. And the Device Type is catagory that can be "Outdoor Lamp Controllers".

What about the Healthiness Criteria and Healthiness Value? What is it? Is it to validated the value? What happens if the criteria is not met?

roottooladmin1's picture

The Device Type is substantially defined in what we call IOT Device Model, which can be generic of a certain range of cases.
the frequency is jsut indicative, an can be taken into account for quality control. So that do not be afraid of the number you palce there. The data can arrive when change, fine.
For the different model, ok, all of them cane be created and you can classify the different devices into the  same Nature/Subnature.
a group of device can be also Grouped with the concept of Group to manage them for access in one shoot.

"I would say that the Name is then the unique ID/Name for the Device Model. And the Device Type is catagory that can be "Outdoor Lamp Controllers".

yes!!!

What about the Healthiness Criteria and Healthiness Value? What is it? Is it to validated the value? What happens if the criteria is not met?

We have in place 3 approached for the Healthiness assessment:

1) the usage of the  criteria that is presently not used much 
2) an automated verification of the healthiness (the red and green dots you see on the Wizard and Data Inspector. Which become red if the sensor is not providing data since more than 24 hours
3) an approach based on machine learning which is the second red/green dots in the healtiness reported into the Data  Inspector. This solution is accessible only for a number of sensors and it is under beta testing.