This repository contains the sources and documentation of the FUI StoreConnect project's Sensors API server.
Aurélien Bourdon, Romain Rouvoy, Lionel Seinturier.
This directory is organized as follows:
| Directory | Description |
|---|---|
| docker | Docker files of the FUI StoreConnect's Sensors API |
| third-parties | Third parties used by the FUI StoreConnect's Sensors API |
- The FUI StoreConnect's Sensors API server specification follows the OGC SensorThings API specification;
- The FUI StoreConnect's Sensors API server specification uses the GeoJSON format to encode geographic data;
- The FUI StoreConnect's Sensors API server implementation is based on the FraunhoferIOSB's GOC SensorThings implementation server.
The StoreConnect’s Sensor API data model extends the OGC SensorThings API data model as expressed by the following picture (in white the original OGC SensorThings API data model, in red the extension brought by the StoreConnect's Sensor API specification).
NB: this diagram has been generated via Draw.io. Any modification can be applied by importing its associated raw file.
The following section defines all extensions brought by the StoreConnect's Sensor API to the OGC SensorThings API data model. Before to read next, be sure to correctly understand the OGC SensorThings API data model.
The main StoreConnect preoccupation is the ability to observe phenomenons within a given store. From the StoreConnect point of view, any FeatureOfInterest is then the store or, even better, parts of the observed store. These parts (or the store himself), are defined as a GeoJSON Feature value represented by the FeatureOfInterest#feature attribute to fit with OGC SensorThings API specification. This way, any FeatureOfInterest must contain an encodingType set as application/vnd.geo+json.
Following what we want to observe (the store himself or parts of the store), the associated GeoJSON would be a GeoJSON Feature with Point geometry (in case of observing the whole store) or Polygon geometry (in case of observing parts of the store).
In addition a FeatureOfInterest#feature MAY define the venue (or place) from which the associated GeoJSON coordinates (Point or Polygon) are related. To do that, this venue MUST:
- Be declared as a GeoJSON property
- Named
venueId - Have an integer value that point to the identifier of the venue that make sense in your external system
A StoreConnect Sensor API's Location represents the location of a given Thing.
This way:
- the
Location#locationattribute is a GeoJSON Feature with a GeoJSON Point geometry representing the coordinates of this location - the
Location#encodingTypeis always set asapplication/vnd.geo+jsonto fit with OGC SensorThings API specification
In addition a Location#location MAY define the venue (or place) from which the associated GeoJSON coordinates are related. To do that, this venue MUST:
- Be declared as a GeoJSON property
- Named
venueId - Have an integer value that point to the identifier of the venue that make sense in your external system
In the OGC SensorThings API data model, the ObservedProperty is a FeatureOfInterest property which can be observed.
From the StoreConnect Sensor API point of view, these properties can be:
- A human motion
- A contextual value (e.g. weather)
Hence, the StoreConnect Sensor API defines the following ObservedProperty instances:
- A
motion, that represents a human motion - A set of contextual values, as the
weather(not shown in the diagram)
Each of these ObservedProperty instances defines the associated result type of an Observation. In addition, the associated ObservedProperty#definition URI must point to an existing JSON Schema that describes the Observation#result type structure.
Hence, for each Observation#result type, there is an associated ObservedProperty instance (motion for MotionEvent, weather for WeatherEvent...).
NB: Only the ObservedProperty's motion instance is shown in the diagram.
A StoreConnect Sensor API's Datastream is always encoded as the complex OM_Observation observationType.
To know what is the concrete type used by associated Observation, you must refer to the associated ObservedProperty.
As explained previously, any StoreConnect Sensor API's Observation#result type is defined by the associated ObservedProperty.
The diagram only represents the MotionEvent type (but keep in mind there would be more Observation#result types, as the WeatherEvent for instance). A MotionEvent is described below.
In the same way as the StoreConnect's main ontology, a MotionEvent (or sc:MotionEvent in the StoreConnect's main ontology) represents a human motion caught by a StoreConnect's Sensor.
A MotionEvent is composed of the following attributes and relations:
| Name | Type | Description |
|---|---|---|
location |
GeoJSON Feature with GeoJSON Point geometry |
The dynamic location within the FeatureOfInterest#feature. Represented by a GeoJSON Feature with a GeoJSON Point geometry by adding the floor and the building as additional parameters |
orientation |
Float |
(Optional) Orientation of the perceived phenomenon |
subject |
MotionSubject |
The associated subject (or target) to this MotionEvent |
As for the sc:MotionSubject in the StoreConnect's main ontology, a MotionSubject describes identification information about the perceived phenomenon. It consists of two parts:
- An identifier
- Some physical or behavioural trait characteristics
An identifier is always relative to the associated Sensor from which the Observation has been made.
NB: For the moment, there is no existing physical or behavioural trait characteristics (coming in a future StoreConnect's Sensor API version). This value can so be omitted, and then, a MotionSubject is, for the moment, only pointing to a given identifier.
Use the FUI StoreConnect Sensor API's client Java library.
The table bellow lists the set of FUI StoreConnect's Sensors API instances and their associated access links.
| Instance name | Description | Access link |
|---|---|---|
| integration | Integration deployment environment | http://bit.ly/2vjJhAP |
This project uses Git submodules, then beware to clone this project by using the --recurse-submodules option:
git clone --recurse-submodules https://github.com/StoreConnect/storeconnect-sensors-api.gitFor the moment, there is no additional check for incoming data. Indeed, the StoreConnect Sensor API implementation is a copy of the FraunhoferIOSB's GOC SensorThings implementation. Thus, there is no type control over extended types brought by the StoreConnect Sensor API model. Hence, we suppose that StoreConnect Sensor API clients respect the StoreConnect Sensor API's data model.
Wants to contribute? Feel free to make a pull request following the contributing instructions.