DeepHub® API

Introduction

The DeepHub® offers a reference implementation of an omlox™ hub. The main part of the omlox™ standard is the REST API and the WebSocket API of an omlox™ hub. This chapter focuses on these APIs and includes an overview and description of DeepHub specifics.

REST API

REST API

WebSocket

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:

  1. Login to Cisco CMX

  2. Choose Manage → Notifications

  3. Create a new notification and enter the host and port to your DeepHub instance and enter the URL /v1/adapters/cisco/locations

  4. Save changes and exit

If your Cisco infrastructure is set up to only deliver local coordinates, you need to perform these additional steps:

  1. Login to the DeepHub UI

  2. Choose Zone Setup

  3. Click to create a new zone

  4. Select wifi as the zone type

  5. 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.

  6. Enter the floor level for the zone and the address (optional).

  7. 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.

  8. 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.

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 image below illustrates the building blocks of the architecture with a simple example data flow:

The endpoint for the DeepHub RPC interface is: /v1/ws/rpc.

The general data flow is as follows:

  1. 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.

  2. 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.

  3. The services which registered themselves for handling “Blink LED” will receive the client request and reply with an RPC response message.

  4. 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.

  1. Alice connects to the RPC WebSocket interface of the Hub (e.g. ws://localhost:8081/v1/ws/rpc for a local instance).

  2. 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
}
  1. 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"
  }
}
  1. 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.

  1. Alice can now respond to the hello request reply with a friendly “Hello World!”.

Alice -> Hub:

{
  "jsonrpc": "2.0",
  "result": "Hello World!",
  "id": 10000
}
  1. 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
}

[1] https://www.jsonrpc.org/specification

Changelog

Changelog