DeepHub® API
Introduction
The DeepHub® offers a reference implementation of an omlox™ hub, including a REST API and a WebSocket API. This chapter focuses on these APIs and includes an overview and description of DeepHub specifics.
Latency and Asynchronous Behaviour
The DeepHub® is a single process application that is optimized for high throughput and low memory usage. It is capable of processing large amounts of requests per second, even on low-end hardware, such as a Raspberry PI or a NUC PC on the edge.
It provides several I/O APIs that are typically utilized simultaneously by 3rd party services - providing location data to the DeepHub to be processed on one hand, and events being generated by the DeepHub and published to potential subscribers on the other hand.
At the heart of the DeepHub lies an event bus that processes the many I/O channels and is responsible for the low overall latency of a single instance installation. Due to this architecture, the DeepHub acts asynchronously in the sense that delivered input data (e.g. via the REST API) is not synchronously delivered (e.g. through events via the output WebSocket API). This is noticeable in certain cases. For example, if a location update is provided as input but a configured mobile zone (see Mobile Zone Extension below) is updated within milliseconds.
Future versions of the DeepHub will support the deployment of several hubs working together as a system for redundancy and availability. In that configuration, it is the event bus of the hub instances that makes collaboration possible and allows them to be plugged together via an external message queue. The overall system latency would then be influenced by the network latency as well as the latency of the message queuing application itself.
REST API
WebSocket
Mobile Zone Extension
The Mobile Zone Extension (MZE) of the DeepHub® allows for the seamless integration of proximity-based positioning solutions that change their position. The MZE changes the position of your proximity zone by connecting the zone with location updates of a real-time locating system - via an omlox Location Provider or an omlox Trackable.
As an example use case, consider you have assets equipped with RFID tags, and you want to keep track of the exact location of your assets in your warehouse. The RFID tags do not provide exact location information. However, with omlox, you can combine multiple positioning technologies and thereby add location information. For example, you could combine an UWB positioning system with proximity information provided by an RFID positioning system.
To illustrate this further, consider you have a forklift equipped with an RFID scanner and an UWB tag. The UWB tag provides exact real-time location information about the forklift, while the RFID scanner provides information about the assets the forklift is carrying. The RFID scanner will receive proximity information as long as your forklift carries assets with RFID tags attached to them.
Normally, the position of a proximity-based zone has to be updated manually, because it cannot generate location information on its own. However, with the DeepHub MZE, you can keep track of the position where assets were dropped off by matching the location information of the forklift with the last-received proximity information of carried assets.
The DeepHub MZE makes this task as simple as possible.
Setup and Configuration
Setting up the MZE is done in two steps. First, a zone needs to be created representing each available proximity positioning system (e.g. RFID scanner). Next, an omlox trackable (e.g. representing a forklift) or an omlox location provider (e.g. an UWB tag) needs to be assigned to the zone in order to enable the MZE. By linking the trackable or location provider with the zone of the installed proximity system, the position of the proximity system will be updated in real-time as the trackable or location provider relocates.
Setting up a proximity zone in the DeepHub:
You may create a zone through the DeepHub API or the DeepHub UI. To do so in the UI:
Login to the DeepHub UI.
Choose Zones.
Create a new zone by setting a proper zone type (rfid or ibeacon) and floor level. You do not need to choose an exact position on the map, as the position will be updated automatically. Simply choose a nearby location.
Set a unique Foreign ID, for example “forklift-123-rfid”.
Click Save to create the zone.
You should now see location updates in real-time in the Live View of the DeepHub UI when location updates are received.
In order to enable the MZE for this zone, you must assign a location provider or trackable to the zone by adding a location provider or trackable to the zone’s properties. This is currently only possible through the DeepHub API. The member variables available for the zone properties are the following:
“com.hdm.hub.zone.autozoneupdate.trackables”: A list containing IDs of trackables. The zone’s position is updated whenever a trackable’s location is updated.
“com.hdm.hub.zone.autozoneupdate.providers”: A list containing IDs of location providers. The zone’s position is updated whenever one of the locations is updated.
An example zone with location providers and trackables configured for auto position updating of the zone:
{
"id": "ffffffff-bce8-6c23-e342-80bd5c938775",
"foreign_id": "rfid-provider-autozone",
"type": "rfid",
"floor": 4,
"need_transformation": true,
"name": "Zone R (RFID)",
"address": "",
"position": {
"type": "Point",
"coordinates": [
0,
0
]
},
"radius": 2.0,
"properties": {
"com.hdm.hub.zone.autozoneupdate.providers": [
"autozone-provider-123"
],
"com.hdm.hub.zone.autozoneupdate.trackables": [
"5EE9265B-EFDF-4EDB-98AD-9D01E11B687F"
]
}
}
Cisco CMX Location Notification Adapter
The Cisco CMX Location Notification Adapter enables the DeepHub® to be integrated with existing Cisco infrastructure, without the need for an additional middleware.
The DeepHub REST API endpoint /adapters/cisco/locations can be configured as a webhook in the Cisco CMX settings. The DeepHub supports version 10.6+ of Cisco CMX.
Setup and Configuration
Setting up the Cisco CMX adapter is done by first defining a webhook in the Cisco CMX settings. If the Cisco infrastructure is set up to provide GPS location data, this is the only configuration step.
If the Cisco infrastructure is set up to only send local coordinates, a zone configuration in the DeepHub is required to match the Cisco floor plan. This allows for the translation of incoming location data to projections supported by the DeepHub.
Setting up a Notification Webhook in Cisco CMX for the DeepHub:
You may create a new webhook through the Cisco CMX configuration page. To do so in the UI:
Login to Cisco CMX
Choose Manage → Notifications
Create a new notification and enter the host and port to your DeepHub instance and enter the URL /v1/adapters/cisco/locations
Save changes and exit
If your Cisco infrastructure is set up to only deliver local coordinates, you need to perform these additional steps:
Login to the DeepHub UI
Choose Zone Setup
Click to create a new zone
Select wifi as the zone type
Draw the zone using the drawing tool, or any of the available zone creation tools. The zone shape and location should match the location hierarchy (map) as defined in your Cisco CMX.
Enter the floor level for the zone and the address (optional).
In the Foreign ID field, enter the CMX location hierarchy name for this map. For example, “Mathematikon>Berliner Str. 41>5. OG komplett [f.4]”. Note: This field is used to link incoming data from your Cisco CMX with this omlox zone. Therefore, please ensure this field matches the value of your CMX location hierarchy.
Click save to create and activate the new zone.
Repeat the steps above for each floor plan in your Cisco CMX for which you want to get location data in the DeepHub.
Note
Setting up a zone in the DeepHub is optional if Cisco CMX is set up to deliver data in WGS84. Nevertheless, it’s strongly advised to create a zone for each CMX location hierarchy in order to assign correct floor level information to incoming locations from the corresponding CMX location hierarchies. Otherwise, some features that depend on correct floor information, such as geofencing and collision detection, may not behave as expected.
ISO-24730 Adapter
The ISO-24730 Adapter enables the DeepHub® to be integrated with ISO-24730-capable real-time locating systems. The ISO-24730 standard was created in the mid 2000s and revised in 2014. It is supported by several real-time locating systems e.g. utilizing ultra-wideband technology.
The standard consists of several air interface protocols as well as a single API called “RTLS API”. It is the latter, that the DeepHub supports and that is subject of this configuration documentation.
Setup and Configuration
A DeepHub can be configured to work together with several ISO-24739 locating systems at the same time, each one of them being treated as a separate zone.
The DeepHub acts as a client towards a configured ISO-24730 service of an ISO-24730 locating system and therefore requires a separate configuration block consisting of the host, port, type of locating system as well as an identifier for the zone (zone_id or foreign_id) for each of them.
Example:
- host: server
port: 4000
type: uwb
zone_id: FDE56BB8-64B1-4B95-ADEB-AB189EE937FE
- host: otherserver
port: 4000
type: gps
foreign_id: some_id
An ISO-24730 configuration can be provided in the same way as other configuration parameters. See the chapter Server Configuration for details.
RPC Interface
The DeepHub® can act as a Remote Procedure Call (RPC) gateway via WebSocket, allowing local devices or services to connect with other devices or services over a local network infrastructure and the internet (which are normally separate from each other and not reachable). This allows for querying of sensor data and device capabilities, or initiating firmware updates as well as other types of information exchange which can be handled via RPC. The DeepHub RPC interface is based on the JSON-RPC exchange format version 2.0 [1].
The endpoint for the DeepHub RPC interface is: /v1/ws/rpc.
The general data flow is as follows:
A service which provides certain functionality registers itself with the DeepHub and announces that it wants to handle a method. This can be anything from querying sensor data of local tags, managing firmware updates of on-site devices, or remote communication between services. In our example flow, we register for a method named “Blink LED” to control a local LED light.
A client application (e.g. a web browser in the local network or over the internet) can now send the RPC Request with the method name “Blink LED” with optional parameters. The DeepHub will forward this call with the parameters to all services handling the “Blink LED” request.
The services which registered themselves for handling “Blink LED” will receive the client request and reply with an RPC response message.
The DeepHub forwards this response message to the client. By default, only the first response is forwarded and the request is finalized.
Registering for RPC method handling is done by sending an RPC request containing the method name “register”, the “method” parameter, and a name for the method as values in the parameters of the request. Example:
{
"jsonrpc": "2.0",
"method": "register",
"params": {
"method": "Blink LED"
},
"id": 1
}
The DeepHub defines three optional properties for the JSON-RPC Request structure:
stream: When set to true, all responses are continuously forwarded to the client that created the request. The stream will end when the timeout for the request is reached (see timeout description below).
aggregate: All data is combined into a single response and forwarded to the client that created the request. The aggregated result is delivered after each registered handler sends a response or the timeout is reached - whichever comes first.
timeout: The timeout after which the request should expire. The timeout is expressed in milliseconds instead of seconds to allow for realtime applications.
The RPC response for aggregated results combines RPC messages into the result array of the final RPC response, and not only the results. This allows for the collection of error messages between success messages as shown in the example aggregate response below. Here, there is one error message next to a success message:
{
"jsonrpc": "2.0",
"id": 2,
"result": [
{
"jsonrpc": "2.0",
"id": 2,
"result": "blinking"
},
{
"jsonrpc": "2.0",
"error": {
"code": -32601,
"message": "Light is defect"
},
"id": 2
}
]
}
In addition, an optional property “zone_id” with a UUID of an omlox™ zone in the params section of a register request can be used to register for RPC calls for a particular zone. This allows RPC handlers which only work within a zone to avoid processing unnecessary requests (e.g. trying to reach tags which can only be reached when in that zone).
Example Message Flow
Alice registers herself for a method named “hello” and answers everybody who says hello to her with “Hello World!”.
Note: This example explains all intermediate steps of the message flow and thus looks longer-winded than it would be from an application perspective. From an application perspective, a client just sends a request and gets back a reply.
Alice connects to the RPC WebSocket interface of the Hub (e.g. ws://localhost:8081/v1/ws/rpc for a local instance).
Alice registers herself to handle a “hello” method by sending an RPC request to the Hub:
Alice -> Hub:
{
"jsonrpc": "2.0",
"method": "register",
"params": {
"method": "hello",
"zone_id": "123"
},
"id": 1
}
The Hub responds with an ok message:
Hub -> Alice:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
Another client, Bob, connects to the Hub and calls the “hello” method. Alice will get this request.
Bob -> Hub:
{
"jsonrpc": "2.0",
"method": "hello",
"id": 2,
"params": {
"zone_id": "123"
}
}
Bob’s message is processed by the Hub and forwarded to Alice.
Hub -> Alice:
{
"jsonrpc": "2.0",
"id": 10000,
"method": "hello"
}
Important details for Hub implementors (not application users): Notice that Alice will see a different id in the request. This is because the Hub uses it’s own IDs and will resolve back to the original ID which the caller used (in our example, Bob used ID 2) when a response is sent by Alice to the Hub. This is a necessary step done to fulfill the requirement of the JSON-RPC specification in order to uniquely relate requests and responses, and to respond with the same ID the client used in the original request sent to the Hub.
Alice can now respond to the hello request reply with a friendly “Hello World!”.
Alice -> Hub:
{
"jsonrpc": "2.0",
"result": "Hello World!",
"id": 10000
}
The hub processes Alice’s message, replaces the ID with the one Bob used in his request, and forwards the response to Bob:
Hub -> Bob:
{
"jsonrpc": "2.0",
"result": "Hello World1!",
"id": 2
}