Test Case Title
Using a PC or Mobile with a web browser. You need a Snap4City account.
Some of the following functionalities are available for specific roles (Final User, Area Manager and Root Admin), as described below.
Expected successful result
The user is able to search, visualize details, change properties of the public and private devices that are collected in the IoT directory according to their role and access control policies specified in the system. Moreover, it is possible to handle also the single values that are associated to the devices, thus making easily the management of the single observations from sensors and the identification of the actuators to which commands can be sent. Finally, advanced users can also search, visualize and change properties of the IoT brokers required for accessing.
overview on IOT directory and management:
IOT Directory is providing information about (i) sensors and actuators from IOT devices, (ii) data sources for real-time data coming from ETL, (iii) data sources coming from inputting widget of the Dashboard Builder.
The Web interface for accessing IOT Directory has been customized according to the role of the user accessing the directory in order to make easily the management of devices for final users and, at the same time, provide a powerful tool for advanced users.
- at each new registration of an IOT Device on an IOT Broker, it is registered into the IOT Directory by the latter.
- IOT Directory stores any changes about IOT Device status (arrival or departure) and generates corresponding triples to the Knowledge Base. The Iot Directory keeps track of the required information needed for the registration in the Knowledge base. When the information is provided the device is registered in the Knowledge based and can be exploited by the other components of the system. This approach guarantees that a common minimal representation is provided for all the devices and their values in the Knowledge Base.
- IOT Directory provides access to make search on the list of IOT Devices, via suitable API, which are also exposed as MicroService for Snap4City Applications, as reflection.
- IOT Directory also shows all the measures and actuators that are provided by the available devices.
- Context brokers. Devices and their measurements and actuators can be shown on a map in order to identify their position in the different city areas.
The IoT directory has been deeply revised with respect to previous version from different points of views. First the graphical representation has been cured for making it more integrated with the other functionalities of snap4city. Then, the module is able to manage both public and private devices and to handle the access only to the private devices belonging to the current user and to those for which the user got a delegation.
In the remainder of the test case, we organize the presentation according to the role of the user that access the IoT Directory.
- Access to snap4city with your credentials.
- Click on “My IOT Devices” and you accesses to the page for managing the personal devices of the current final user.
3. The final user is authorized to access to his personal devices (private devices for which he is the owner) or devices belonging to other users for which he has been delegated. For these devices he receives a value based representation of the devices. That is, he can see the attributes (i.e. sensors and devices) that are associated with the devices. For what concerns the single value, in the interface are reported the name of the device and the value type. Moreover, a semaphore is reported. Its colour is green when the device is correctly registered in the Knowledge Base and it is working (“active”). It is yellow when further information should be specified for its registration in the Knowledge base (“iddle”). It is red when it is registered but it is not working properly (“inactive”). Finally a globe allows the user to see the position of the device on the map as follows:
Further information is shown to the user by clicking on the blue plus button at the beginning of each line of the table as follows:
Note that in the detailed information about the single value, also the pairs of key k1 and k2 are reported. These keys are generated (or assigned) during device registration and guarantee authenticated access to the IOT broker that handle the device and allow to read the events generated by the sensors and to send commands and notifications to the actuators. We remark that the user is authorized to remove a device by cancelling one of its value (in this case the entire device is removed)
Similar information are shown if you click on . The only difference is that you are not allowed to delete a device (the delegation allow you only to see devices and their properties).
4. By clicking on , it is possible to register a new personal device and the following interface is shown:
With few clicks, the user can easily register his personal device. He has to specify the name, its model, and position on the map (you can specify the location by exploiting the map on the right of the figure). In our environment we have considered a list of device models (whose characteristics are already specified) and deeply discussed in https://www.snap4city.org/drupal/node/76. When the model is sigfox, the user has to access the sigfox server for receiving the pair of keys (Key1 and key2) needed for accessing the device. In all the other cases, the pair of keys are automatically generated by the system.
Final user, Manager: Creating My IOT Devices
Suppose we wish to generate a new device “TestDevice333” whose model is a “Raspberry snap4city 1” (this model has been realized for being easily configured with node-red directly on the device board) and should be positioned in the center of Firenze. By choosing the model, the two keys are automatically generated.
When clicking on the “register device”, the device is registered in the IOT directory and also on the context broker that is in charge of its handling. Moreover, the two keys are registered in the Personal data of the current user.
When the operation ends successfully the following message is reported to the user.
By navigating on the link the user receives instructions for the configuration of the physical device and the new registered device is reported in the list of personal device as shown in the following figure
Now, you can try to delete the registered device, by clicking on . After a request of confirmation, the device is removed from the IOT directory and the context broker. Moreover, the ownership of the device is removed from My personal data.
Area Manager User
1. Access to snap4city.org with your credentials.
This page offers the list of devices that are public or private of the current user. For each device, it provides the name of the device, the name of the context broker that handle the device, the protocol, format and device type. Moreover, the area manager can see the ownership of the device and its status. Moreover, a semaphore is reported. Its colour is green when the device is correctly registered in the Knowledge Base and it is working (“active”). It is yellow when further information should be specified for its registration in the Knowledge base (“iddle”). It is red when it is registered but it is not working properly (“inactive”). A globe allows the user to see the position of the device on the map. The area manager can edit and delete any public device and its own private device. By contrast, he can simply views the position on the map of devices for which he got a delegation.
The Area Manager (as well as the other users) can use different facilities for filtering the devices. First through the following bar you can specify filtering conditions for retrieving devices presenting determined characteristics (e.g. public device whose broker is orionUNIFI and presenting a device type containing the string “Lamp”).
Moreover, device can be selected on the map through the button . The following modal is displayed and the user can use different approaches (devices within a circle, devices within a polygon, devices along a polylines) for selecting the devices he is interested in.
The Area Manager can create new devices. By clicking on the , a modal is shown through which the user can specify the parameters of the device.
The user can create a device of model “custom” and in this case he has to specify all the parameters by hands or he can exploit one of the models made available in snap4city. In this case all the required information are automatically filled out. In case the device is private, a couple of keys is automatically generated for basic models. In case of the sigfox model, this keys should be retrieved from the SigFox server for completing the operation. For the insertion of a new device, the information to be provided have been categorized in:
- “Info”. Basic information about the device: name, model, frequency and visibility that are mandatory, and type, mcaddress, k1 and k2 that are optional;
- “IoT Broker”, information about the broker in charge of the device;
- “Position”, position of the device on the map
- “Values”, list of the sensors and actuators that are contained in the device.
Once the required data are specified, by clicking on the confirmation button, the devise is registered in the IoT Directory. Whenever all the required data have been specified, the device is also registered on the Km4City Ontology and thus made available to the entire platform.
By using an interface similar to the one described for the registration of a new device , through the button , it is possible to modify the properties of the device and make them permanently in the IoT Directory. Finally, a device can be removed from the IOT Directory by clicking on the button.
3. Click now on the “IoT Sensors and Actuators” button and you can see the following view of the values that are associated with the devices stored in the IoT Directory
On this interface, the user can see the sensors and actuators that are connected with the devices along with their properties (like latitude, longitude, etc.). The Area Manager can edit and delete the single values for each sensor and actuator belonging to a public device or to private device that he owns. Finally, he can require the introduction of a new value . When clicking on this button, the following interface is shown.
By mean of which the user should specify the characteristics of the value to be associated to a device. We remark that the device should exist in the list of IoT Devices, otherwise the insertion of a new value cannot be completed successfully.
4. Click now on the “IOT broker” on the left-side menu, and you can see the list of available Broker
The Area Manager is only authorized to see the list of brokers with their detailed characteristics, but no specific actions can be performed on them.
1. Access to snap4city.org with your credentials.
2. Click in the left menu on “IoT Directory and Devices” and then on “IoT Devices” and you accesses to the page for managing the public and private devices. The functionalities offered to the toolAdmin for the management of devices are the same presented for the Area Manager, with the following peculiarities:
- The ToolAdmin has a synthesis of the devices that are currently registered in the platform
- The ToolAdmin is authorized to access and manage all the devices that have been registered in the IOT directory independently from their ownership.
3. Click now on the “IoT Sensors and Actuators” button and you can see the following view of the values that are associated with the devices stored in the IoT Directory. The functionalities offered to the toolAdmin for the management of devices are the same presented for the Area Manager, with the same peculiarities discussed for the devices.
4. Click now on the “IOT broker” on the left-side menu, and you can see the list of available Broker
a. Click on the button, we can create a new one. A modal menu appears in which you can specify the properties of the new context broker
Context broker properties are organized in three tabs:
- Info: It contains the unique logical name associated with the context broker, the IP address, port, and protocol according to which events are transmitted.
- Geo-Position: the longitude and latitude in which the context broker is located
- Security: login and password required for accessing the context broker (in our experiments are not required).
The geo-position of the Context Broker can be specified by the user by clicking on the map as follows.
b. Please feel out the form as follow (login and password are related to the context broker that at current stage are not specified).
All the fields (with the exception of Login/Password) are mandatory. If you do not insert them or specify a wrong value (e.g. Port number, IP address) a specific error message is reported. When you have concluded click on the “confirm” button.
c. If the operation is concluded with success, the context broker appears in the list of available context brokers.
d. Click on the button corresponding to the “orionUNIFI2”. In this way a connection is established with the context broker, all available devices is retrieved and included in the context broker. When the operation is concluded, the colour of the button is changed, and it appears as follow. Note that the stub is activated and will remain active on such context brokers for identifying new devices. When they appear, they are included in the IOT Directory automatically. In the future version of the IOT Directory, the notification of the inclusion of new devices is shown in the interface.
5. At this point you can click on “device” and typing “orionUNIFI2” on the search input element and see the list of sensors that have been automatically registered as reported in the following figure.
You can see the devices that have been included in the IOT Directory. However, the devices are not yet included in the Knowledge Base. Indeed, the automatic extraction from the Orion Context Broker does not provide the required information for being included in it. At this point you can access device-by-device and provide the required information for each device by clicking on the button. We remark that, the context broker does not provide information on the kind of device (sensor/actuator). They are automatically classified as sensors and the user has to change their kind when needed. In the next release of the system, we will introduce some other facilities for simplifying the introduction of the sensor properties. In the remainder of this test case, we show the activity for configuring a specific device “thermometer01”.
6. The interface shows the devices that have been automatically detected from the Context Broker. You can modify the fields of a sensor by clicking on the button. The following interface shows the properties that can be modified for the “thermometer01” device (organized according to 5 tabs):
The first tab contains the basic information about the device (name, type, contextBroker, protocol, and format) that have been extracted from the context broker (in case of the Orion Context Broker). The URI is the identifier associated with this device in the Km4City Ontology (not yet assigned because of the lack of mandatory information).
The “manufacture” and “geo-position” tabs contain information about the producer of the device (macaddress, model, producer) when available and the latitude and longitude in which the sensor is located.
All the fields are optional, and the name and URI cannot be modified. You can for example specify the latitude and longitude (45.464211, 9.191383) and click on “confirm”. The modifications are applied, and you are redirected to the main page. The Value tab contains the measurements and actuators that are available for this device. The user can complete the missing information (like value_type, healthiness criteria, healthiness value and value unit). These data are mandatory for the registration of the device in the context broker.
7. If you click again on the button and move to the “Value” tab the following interface is shown:
The interface shows the measurement and actuator that have been detected in the device with their type. For each value, the interlace shows:
- The label used in the context broker
- The basic data type (extracted from the context broker)
- The value type that is a concept of the Km4City Ontology that describes the current value
- Whether the value is editable or not (that is it can only be read or a value can be set on it)
- The value unit
- And the criteria for determining its healthiness (and the corresponding value).
Once these properties have been specified, the device is updated and the registration to the knowledge base is applied. Then, the semaphore associated with this device turns green as follow.
This operation should be applied to all the other devices to register them in the Knowledge base.
As a consideration:
- The API of the IOT Directory is a solution to perform registration of massive number of IOT Devices with limited user intervention.
- The same approach of API is used to register into the IOT Directory, IOT networks that are already organized under some IOT Broker listing the IOT Devices.
- The loading of this information in the IOT directory can be exploited for inquiries and makes it possible to create an uniform approach for accessing the sensors and actuators handled in the Snap4City environment.