Web of Things platform - Technical report

Abstract

This technical report presents the technical aspects regarding the implementation of the Web of Things platform project done for the Web Application Development course. The project consists of a Web application that allows its users to manage their own smart homes by adding smart devices to the homes, interacting with the smart devices and adding other users to the home.

Introduction

We developed the application using the REST paradigm, and the communication between the client (the front-end of the application) and the server (the back-end application) is done through a REST API. We made this design choice because the REST paradigm "enforces the separation of concerns and helps the client and the server components evolve independently" (Restful API website), which is a general development good practice that helped us better organize inside the team.

Use cases

The use cases that are covered in our application are the ones presented in the following use case diagram:

After creating an account and logging in to the application, a user can create homes, add smart devices to them, become part of another user's homes and interact with the smart devices inside the homes.

In the following sections, we will present more details regarding the implementation of this solution.

Internal data structures/models

The resources that are used inside our Web application are:

1. Users - at the root of the application, we have the application users, having their associated credentials that they need to use for accessing the application. Besides credentials and other user information, an application user will have associated a number of homes, inside which he will have a specific role:
2. Homes - a home will contain a list of smart objects with associated categories and a list of members (application users) with associated roles (either Owner, Member, Child or Guest).
3. Smart devices - each smart object will be stored with the relevant data obtained from its WoT specification. This is useful since we have easy access to the object’s properties and action.

The Owner of a home will be able to group the smart devices inside the home in the following categories:

1. Entertainment - for objects like televisions or smart speakers. Entertainment objects will be accessible for all roles inside a home, including guests.
2. Environment - objects like smart bulbs, blinds, humidifiers, fans, air conditioners or different sensors related to the environment. These will be accessible for all roles except guests, so only permanent members of a household can control the environment
3. Security - objects like security cameras, lockers, wall plugs. Only the Owner of the home and the Members of the home (excluding children) will be able to access these types of objects.

Other permissions related to each role inside the smart home are:

1. Owner - can manage the home and its linked smart objects. Can add new smart objects or remove existing ones and do any supported operation. Can invite new members, children or guests inside the home.
2. Member - can interact with all objects inside the home. Can invite new guests inside the home
3. Child - can only interact with specific categories of objects inside the home
4. Guest - can only interact with objects from the category Entertainment

Mozilla WebThings Framework

For this project, in order to simulate the IoTs adopting the WoT Thing Description specification, we are using Mozilla WebThings Framework. According to the project’s official webpage:

The WebThings Framework is a collection of reusable software components to help you build your own web things, which directly expose the Web Thing API. This means they can be discovered by a Web of Things gateway or client, which can then automatically detect the device's capabilities and monitor and control it over the web.

These IoTs are built in a server separate from the main Web Application. This server exposes different endpoints for each object, respecting the Web Thing API specification for that specific object. For the WebThings server, we use the official code example for the framework containing a lamp and a humidity sensor.

By using the URL of a smart device's WoT specification, a user will be able to save the new device in the application and then add it to his home. Adding a device to his home offers offer him the possibility to see the object’s properties and perform the supported actions on them.

The WoT descriptions of the objects are stored in the application's database, so that the user can easily control his linked smart devices. The back-end server then makes API calls to interact with the smart objects by using the base URL and constructing the endpoints for properties and actions using the base link and their names.

Linked Data Principles

This application adheres to the linked data principles as each resource has a unique HTTP URI (represented by the REST API endpoint /{resourceType}/{resourceIdentifier}, which returns relevant information about that resource in the JSON-LD format, containing data for discovering other linked resources. The JSON-LD responses also contain information about the context of each property, so that crawlers can also understand their meanings.

For expressing these properties, we used the following vocabularies:

• VCARD and VCARD4 - used for Users and Homes, we chose to use these because of the built-in support for those vocabularies in Apache Jena. They are built specifically for persons and organisations, so they had useful properties for modelling these two entities.
• Thing Description (TD) Ontology - built specifically by the Web Consortium for Web things, so it is very expressive for storing information about the smart devices from their WoT specifications
• JSON Schema - used for expressing smart device properties and action inputs, also expressive as it is created for the specific purpose of describing JSON schemas.
• Schema.org - used for expressing properties that we did not find in the other vocabularies - this is not as expressive as the others, but it contains a huge variety of properties where we could find the missing pieces from our data.

Data Storage

At first, we wanted to use BrightstarDB for storing the data, but we had issues configuring it in our project and we switched to Apache Jena, which is free, open-source and well-documented. Apache Jena offered us TDB, which, according to their website, is a native high performance triple store, and the RDF API, which enabled us to easily work with resources inside the model and perform various SPARQL queries on the data.

The most important interrogations that are used inside the applications are finding all homes linked to a user, all users that have a role inside a home, all smart devices inside a home and all properties and actions applicable to a smart device. The SPARQL queries are done in the back-end, so that the front-end does not need to handle the logic of building and executing these queries. The results of the SPARQL queries are also be parsed in the back-end so the REST API will return the responses structured in a way that will require less processing on the front-end side.

Frontend solution

The frontend solution is represented by a React web application that offers a user-friendly interface to the user and communicates with the backend server's REST API to offer full-functionality to the user. A user-guide for the application can be found here.

Backend solution

The backend application is a Spring server with three controllers, corresponding to the three main resources of the application. At the server startup, the application establishes the connection with the TDB triple-store, which is then used throughout the application for persistence.

Each controller contains the main logic for all the different endpoints it exposes, and uses some utilitary classes in order to perform the different SPARQL queries needed for reading the data from the database, and then processing the data so it's mapped to the internal models used in the application. In order to enrich those models with semantic information and respond with proper JSON-LD files, we use the Jackson-Jsonld Java library, which enables us to add annotations inside the models for expressing the context for the attributes, and then to serialize them in JSON-LD format.

A more complex SPARQL query that is used for fetching details about a device with a given id is built in the following code snippet:

        
String queryString = VocabularyConstants.VCARD_PREFIX + " " +
"SELECT ?title ?description ?property ?action ?baseLink ?category " +
"WHERE { ?device  vcard:CLASS \"DEVICE\" . " +
"?device vcard:UID \"" + id + "\" . " +
"?device <" + WOT.DESCRIPTION + "> ?description . " +
"?device <" + WOT.TITLE + "> ?title . " +
"OPTIONAL { ?device vcard:CATEGORIES ?category } " +
"OPTIONAL { ?device <" + WOT.HAS_LINK + "> ?baseLink } " +
"OPTIONAL { ?device <" + WOT.HAS_PROPERTY_AFFORDANCE + "> ?property } " +
"OPTIONAL { ?device <" + WOT.HAS_ACTION_AFFORDANCE + "> ?action } " +
"}";
        
      

Here we fetch all necessary data regarding a device by selecting all its properties, either literals or resources, using the relationships that were used when posting that device. There are four optional fields that do not depend on each other, meaning category, baseLink, property and action. They belong to separate OPTIONAL bodies since the absence of one of them does not mean that we don't want to fetch the other data.

We are also using constants for fetching URLS of vocabularies and properties, so that they are easy to change if the vocabulary is updated or we decide to use a different approach for expressing one of the relationships.

Another interesting SPARQL query is the one where we find the role of a user inside the home where a device is located, having as input the user id and the device id.

        
String queryString = VocabularyConstants.VCARD_PREFIX + " " +
VocabularyConstants.VCARD4_PREFIX + " " +
"SELECT ?userRole ?homeId " +
"WHERE { ?home vcard4:hasMember ?user . " +
"?home vcard:UID ?homeId ." +
"?home vcard4:hasRelated \"" + deviceId + "\" . " +
"?user vcard:UID \"" + userId + "\" . " +
"?user vcard:CLASS ?userRole " +
"}";
        
      

Here we find a home that has as one of its members a user with the given userId and also contains a device with the given deviceId, and then we extract the home id for logging purpose and the user role as part of the query, since this is something that we use for checking if a user is allowed to perform a certain action on a device.

Updating a resource is done through PATCH operations and is only possible for Users and Homes. In order to implement the PATCH operations, we use the Java library json-patch, which processes the standard operations for patching an object. After obtaining the patched object, we use an utilitary function (either from the class UserResourceUpdater or HomeResourceUpdater) to observe the differences between the old object and the patched object, and then to modify the corresponding triples inside the triple-store - which is done by deleting the old triples and adding new ones with the updated values.

An example of building a delete query that is used for updating the user's inside a home is the following:

        
String deleteQueryString = VocabularyConstants.VCARD_PREFIX + " " +
VocabularyConstants.VCARD4_PREFIX + " " +
"DELETE { ?blank_node vcard:UID ?userId . " +
"?blank_node vcard:CLASS ?userRole . " +
"?home vcard4:hasMember ?blank_node " +
"} WHERE { ?home vcard4:hasMember ?blank_node . " +
"?home vcard:UID \"" + oldHome.getId() + "\"} ";
        
      

Here we delete all three statements related to a user's relationship with a house: the hasMember relationship that is tied to a blank node and the two statements that are tied to the blank node, one related to the id of the user of the home and the other one related to the role of the user in that home.

Deleting a resource is done through the Apache Jena RDF API, by deleting all the statements inside the triple-store that contain the given resource.

Communication with a smart device is done for multiple endpoints:

• All endpoints where we fetch details about the smart device - there we also fetch the current values for each property of the smart device
• The endpoint for executing an action in a smart device - there we post the payload received to the corresponding endpoint of the smart device and then pass-through the response we receive from the smart device

Bibliography

1. WADe course , by Dr. Sabin-Corneliu Buraga (last accessed on 01 February 2022)
2. Restful API website (last accessed on 22 November 2021)
3. WebThings API (last accessed on 25 November 2021)
4. WebThings Framework (last accessed on 25 November 2021)
5. WebThing Simulation (last accessed on 01 February 2021)
6. BrightStar DB documentation (last accessed on 20 November 2021)
7. Apache Jena documentation (last accessed on 01 February 2022)