symbIoTe offers a mediation framework, powerful core services, semantic interoperability, security by design and a common API system that allow SMEs and new entrants in the IoT domain to build innovative IoT applications within short development life-cycles.

symbIoTe can significantly simplify the development of cross-platform IoT applications.

Our project aims at creating an interoperable mediation framework that enables the discovery and sharing of connected devices across different IoT platforms. In fact, symbIoTe implements a unified entry point to interact with multiple IoT platforms exposing their resources (sensors, actuators, services). Moreover, it allows to directly exploit high-level APIs implemented through “Enablers”, that is, specialised software components that offer services, tailored to the needs of symbIoTe-specific use cases and based on machine-to-machine data obtained from the integrated IoT platforms.

Through symbIoTe, developers have a single interface to access a significant number of IoT resources, in a unified and agnostic way, without bothering with the implementation details of the various platforms behind. symbIoTe uses semantic web technologies to provide a detailed description of resources and, especially, to obtain semantic interoperability among different IoT platforms. Each platform, in fact, adheres to a specific semantic model when “publishing” its resources in symbIoTe. This way it is possible for App developers to have a unique and coherent naming and description for the resources they need to interact with, across the different IoT platforms they actually belong to (you can read more about semantic interoperability in symbIoTe in the blog post “Interoperability in the IoT world: why it is needed and just speaking the same language is not the perfect solution”).

Got your attention? Good! Follow us in this step-by-step introduction on the development of symbIoTe enabled Apps!

How to integrate your App in symbIoTe

To integrate your App in symbIoTe you must follow these steps, as explained in the symbIoTe Core documentation:

• Step 1: Search. First of all, the App looks for interesting resources in the symbIoTe Core to get their IDs
• Step 2: Fetch. The App needs to query the symbIoTe Core again to get the endpoints to interact with the resources.
• Step 3: Use. Finally the App can directly interact with each resource, by accessing its endpoint via OData protocol or REST.

Figure 1 – How to integrate an App in symbIoTe

Security first!

Security rules must be strictly applied by App developers when communicating with symbIoTe components.

In particular the App must gain explicit access rights to both interact with the Core and with any single IoT platform integrated in symbIoTe: in the latter case in fact, it is the platform that defines the policies for exposing its resources to third parties.

As far as security is concerned, we can distinguish how to access Public resources (e.g. some of the Core services) and those with a Restricted Access (e.g. platform resources under access control).

To secure access to public resources, an App needs to acquire Guest credentials. The full details to perform this task is described in the security documentation of the project.

It suffices to say here that if you are developing a Java application your life will be easier, since symbIoTe provides a ready-made library (SecurityHandler) for authentication and authorization, which hides all the implementation details of the interaction with security components.

If you are not using Java, fear not! Just interacts with these services through plain HTTPS calls.

As indicated in the security documentation, the steps to follow for gaining access to public symbIoTe services are the following:

• acquiring the Guest token
• generating the security headers, that include the obtained Guest token
• accessing the symbIoTe service by issuing a HTTPS call that includes the security headers
• verifying if the response actually came from the correct symbIoTe component, to protect against “man in the middle” attacks.

The procedure to interact with resources with restricted access is a bit different: it will be mentioned below, together with the instructions to access platform resources.

Step 1. Searching the Core

SymbIoTe Search Engine service provides a powerful way for an App to find the resources it needs. Say, you are developing a mobile App to monitor the air quality: you can ask the core to retrieve the list of pollution sensors around the current location of the user.

There are two possible ways to query the Core Registry. The simplest solution is by using the HTTP endpoint and by passing parameters via GET, e.g.:

There are many parameters that can be specified to search for resources, as indicated below.

It is also possible to perform wildcard searches on a certain number of parameters (name, platform_name, owner, description, location_name, observed_property): this way an App developer can also retrieve the resources of interest even without knowing the full details beforehand.
As a response, the Core Search Engine service returns a JSON with the details of the resources fulfilling the search criteria, as shown in the example below.

Another way to search for available resources in the Core is by specifying a more detailed SPARQL query. symbIoTe uses semantic web technologies for its Registry: resources can be therefore searched by interacting with the SPARQL Endpoint of the Core Search Engine, passing parameters in a JSON payload formed by the following structure:

Possible output formats include XML, JSON, CSV, RDF, TURTLE, TRIG and many more.

Every search to the symbIoTe Core must contain properly generated security headers: in particular, being the Search Engine a public service, the App needs only to obtain a Guest token.

Step 2. Fetching resources’ endpoints

Search allows to retrieve the IDs of the resources: now the App must obtain the actual endpoints to interact with in order to access resources.

Resource access URLs can be obtained from another Core component – the Resource Access Monitor (RAM) – by sending HTTPS GET requests with the IDs of the resources as parameters. E.g.:

The response, in JSON format, is as follows:

Requests to the Core RAM need properly generated security headers, as described in the previous step: again a Guest token suffices for this service.

Step 3. Accessing resources

As said, in symbIoTe a resource exposed by an integrated IoT platform can be:

• a sensor
• an actuator
• a web service.

From a functional viewpoint, Apps can:

• read the current value of a resource
• read historical values of a resource
• write a value into a resource (e.g. to perform actuation or to pass parameters to a service).

From an implementation viewpoint, resources can be accessed through OData or REST (of course, in case of services only the latter option applies). Applications can also receive notifications from resources via WebSockets.

In order to access resources, the App needs to create a valid security request to be submitted to each IoT platform.

When an IoT platform registers its resources in the Core, it defines their visibility status, that can be public or protected.

If a resource is public, the App needs only to acquire a Guest token from the symbIoTe security services of the IoT platform (the procedure is the same described above for the Core services).

On the other hand, if the resource is protected, a Home token is needed. Home token can be granted to registered actors only: therefore it is necessary for App developers to obtain credentials for each platform they want to interact with.

Again, life is easier for Java developers, since the aforementioned SecurityHandler library hides away a lot of the implementation details. The alternative is again to issue a sequence of HTTPS calls and explicitly manage the obtained security tokens and headers.

Full instructions are available at the symbIoTe Security page.

Once security has been managed, the App can access the desired resource. As said two are the main options to interact with a resource: OData and REST.

Using resources via OData is very easy as shown by the following examples.

Getting the current value of a resource:

GET https://myplatform.eu:8102/rap/{Model}s('symbioteId')/Observations?$top=1

Reading its historical values:

Historical readings can be also filtered, using the option $filter that supports the operators “Equals”, “Not Equals”, “Less Than”, “Greater Than”, “And”, “Or”.

To write a value to a resource (e.g. to perform an actuation) this is the example to follow:

Apps can interact with resources through REST as well.

Getting the current value of a resource:

GET https://myplatform.eu:8102/rap/Sensor/{symbioteId}

Getting its historical values:

Please bear in mind that through REST it is not possible to perform filtering as with OData.

To write a value to a resource (e.g. to perform an actuation but also to invoke a service) this is the example to follow with REST:

Some resources might also offer notifications via WebSocket. In order to do so, Apps must open a WebSocket connection towards a Server, e.g.:

where IP and PORT are the Interworking Interface parameters.

To subscribe or unsubscribe to resources, Apps must send a message to the WebSocket specifying actions through a JSON payload, e.g.:

Cool! Let’s build your first symbIoTe App!

Ok, you stayed with us until now and your fingers are itching for developing some code!

To try symbIoTe first-hand there are plenty of already available resources that you can use: they have been implemented for the symbIoTe use cases and are currently exposed by eight IoT platforms and one Enabler.

For example, if you plan to develop a Smart City solution you can use outdoor air quality and mobility data for three european cities (Porto, Zagreb and Vienna).

Figure 2 – An example of a symbIoTe-powered Web App using data from air quality sensors

The amount of integrated platforms and available resources is increasing, thanks to the growing number of IoT solution providers that are joining symbIoTe through its two Open Calls.

It is really the right moment to get onboard of symbIoTe and try hands-on the power of the Internet of Things: and don’t forget to give us a shout when your App is ready! Happy coding!

Follow-up

• Curious to know more about symbIoTe? These blog posts are the right starting points:
  • What is symbIoTe all about
  • Creating cooperative IoT platforms with symbIoTe
• Need detailed technical instructions for interacting with the symbIoTe Core services? This is the place: https://github.com/symbiote-h2020/SymbioteCore
• Security in IoT is essential, as explained in this blog post “Security in pervasively connected IoT world”
• symbIoTe has been designed with security in mind. Here you’ll find all the technical documentation for managing security in your symbIoTe-compatible App: https://github.com/symbiote-h2020/SymbIoTeSecurity

Luca De Santis, Danilo Giacomi

Navigo