The ZeroKey Spatial Intelligence Platform (ZSIP) API is the main manner in which modules, applications, and tools interact with ZeroKey's Spatial Intelligence Platform. Through this API core functions of the underlying Quantum RTLS hardware are accessible, providing direct control of devices and system operation.

The Spatial Intelligence Platform relies on a SignalR based Event Hub system to relay real-time information from the Quantum RTLS hardware to ZSIP and then to connected modules and applications. End-users may establish a direct read-only SignalR connection to the Event Hub by requesting a connection ID through this API. Each connection to the Event Hub must specify a filter chain, which ultimately determines which messages transmitting through the Event Hub will be relayed to the client. Several pre-defined templates are available to handle a number of common use-cases.

• The Quality of Service (QoS) feature is a new addition to API that allows users to set the message rate per second and batch messages. This feature is for use cases where every position output from the system is not required. It is used to lower the rate of positioning messages for client consumption. This will not affect internal system latency or message rates.
  • When enabling the rate limit with no batching, the system will output LOCATION_FILTER_UPDATE per device. It will collect the latest position for each device, then at the interval for the rate specified, will produce a LOCATION_FILTER_UPDATE with the devices last known position.
  • When batching is selected, the system will collect all LOCATION_RAW_UPDATES for all devices, then at the specified rate interval will output one LOCATION_BATCH_UPDATE containing a list of LOCATION_RAW_UPDATE messages.
• The MQTT TLS is now available. This feature allows users to encrypt the whole MQTT communication by using TLS instead of plain TCP. This feature provides a secure and trusted communication channel between MQTT clients and brokers
• Certificate profile management is another feature that allows users to manage their certificates more efficiently. This feature enables users to create, update, and delete certificates easily. It also allows users to manage their certificate authority (CA), client certificate, client key under a certificate profile.

• LOCATION_UPDATE is deprecated. It is replaced with LOCATION_RAW_UPDATE
• BATCH_LOCATION_UPDATE is deprecated. It is replaced with LOCATION_BATCH_UPDATE

ASP.NET SignalR is a library for ASP.NET developers that simplifies the process of adding real-time web functionality to applications. This option offers the best solution for capturing and processing data as it happens. It enables you to access the most current and accurate information from our devices. This option can be beneficial for applications that need quick and reliable feedback, such as monitoring, analytics, or decision making.

Two authentication paradigms are available, OAuth2 (Client Credentials) and API keys. The OAuth method allows the greatest flexibility and security in allowing end-client applications to make API calls directly to the platform.

Three access paradigms are supported, with the first option being the preferred authentication flow:

1. End-user clients authenticate with the third-party backend. The backend service related to that application uses its API key or admin-level Client Credentials to obtain an OAuth token. This token may be relayed back to the end-client application, who can begin making API calls directly using the token.
2. Another approach is to simply make all API requests through the third-party backend entirely and pass no auth tokens to the end-client.
3. The last option is to create duplicate user accounts within the third-party application and ZSIP. The end-client application can then interact directly with the API and obtain its own auth_token using its Client Credentials.

The following sequence diagram illustrates the recommended approach (option 1):

• Install SignalR client library in languages supported. SignalR supports most of the popular languages. Make sure the language you use has a signalR client library available.
  • .NET
  • JavaScript
  • JAVA
  • Python
• Have a calibrated ZK system running. Refer to the User Guides that are included in ZeroKey SDK at your installed directory for details.
• Connect the Gateway from the above system to the ECD.

You need to find the Event Hub/API hosting IP address before starting the coding steps. There are two ways to do so:

• (AP Mode) Connect your machine to the ECD's WiFi. The default SSID is QuantumRTLS-[SERIALNUMBER] and the password is SpatialIntelligence. The hosting IP address by default is 10.42.0.1
• (Ethernet) Connect the ECD to your Ethernet. Plugin a monitor to the ECD and you will see the hosting IP show up.

To establish a connection to the SignalR Event Hub endpoint, it is first required to obtain an EndpointID by using the Connection Management API operation. After the new Event Hub connection request has been created, we are ready to connect to the Event Hub. Follow these steps to create a project that can connect to the Event Hub:

1. Create a Blazor app in your Visual Studio
2. Install the following NuGet packages from the NuGet package manager: SignalR.Client Newtonsoft.Json
3. Create a new .razor file under "Pages" folder and name it "ConnectionTest.razor"
4. Copy and paste the following code sample to the file
5. Replace {API Host Here} with your actual hosting address. For example, 127.0.0.1 . Replace {YOUR USERNAME}} and {YOUR PASSWORD} with your own credential info.

@using System.Text;
@using Microsoft.AspNetCore.SignalR.Client;
@using Newtonsoft.Json;

@page "/connectionTest"

<PageTitle>Connection Test</PageTitle>

<h1>Connection Test</h1>

@foreach (var item in m_receivedData)
{
   <p>@item</p>
}


@code {
   List<string> m_receivedData = new List<string>();
   //Declaring some C# classes to store the results
   private class AuthResponseData
   {
       public string access_token { get; set; }
       public string token_type { get; set; }
       public int expires_in { get; set; }
       public string scope { get; set; }
       public AuthResponseUserData User { get; set; }
   }
   private class AuthResponseUserData
   {
       public string auth_id { get; set; }
       public string AccessLevel { get; set; }
   }

   private class ApiKeyData
   {
       public string ApiKey { get; set; }
   }
   private class ConnectionData
   {
       public string EndpointURI { get; set; }
       public string EndpointID { get; set; }
       public HubInfo HubInfo { get; set; }
   }

   private class HubInfo
   {
       public string HubName { get; set; }
       public string HubTypeID { get; set; }
       public string HubInstanceID { get; set; }
   }

   protected override async Task OnInitializedAsync()
   {
       await StartConnectionAsync();
   }

   public async Task StartConnectionAsync()
   {
       var httpClient = new HttpClient();

       var authDataJson = "{\"grant_type\":\"client_credentials\",\"auth_id\":\"{YOUR USERNAME}\",\"auth_secret\":\"{YOUR PASSWORD}\"}";

       // Request OAuth token
       var oauthTokenResponse = await httpClient.PostAsync("http://{API Host Here}:5000/v3/auth/token", new StringContent(authDataJson, Encoding.UTF8, "application/json"));
       var oauthTokenJson = await oauthTokenResponse.Content.ReadAsStringAsync();
       var oauthToken = JsonConvert.DeserializeObject<AuthResponseData>(oauthTokenJson);

       // Register API Key
       httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {oauthToken.access_token}");
       var apiKeyResponse = await httpClient.PostAsync("http://{API Host Here}:5000/v3/auth/registerApiKey", new StringContent(string.Empty));
       var apiKeyJson = await apiKeyResponse.Content.ReadAsStringAsync();
       var apiKey = JsonConvert.DeserializeObject<ApiKeyData>(apiKeyJson);
       httpClient.DefaultRequestHeaders.Remove("Authorization");

       //Default filter to only receive position events
       var filterJson = "{\"Filters\":[{\"FilterTemplate\":\"position_events\"}]}";

       //Request connection info
       httpClient.DefaultRequestHeaders.Add("X-API-KEY", apiKey.ApiKey);
       var connectionInfoResponse = await httpClient.PostAsync("http://{API Host Here}:5000/v3/events/connections", new StringContent(filterJson, Encoding.UTF8, "application/json"));
       var connectionInfoJson = await connectionInfoResponse.Content.ReadAsStringAsync();
       var connectionInfo = JsonConvert.DeserializeObject<ConnectionData>(connectionInfoJson);

       //Build connection and handling of events
       var eventHubConnection = new HubConnectionBuilder().WithUrl("http://{API Host Here}:33001/hubs/eventHub",    //EndpointURI obtained from last step
           (opts) =>
           {
               opts.AccessTokenProvider = () => Task.FromResult(connectionInfo.EndpointID);    //EndpointID obtained from last step
           }).Build();

       var eventHubMessageSubscription = eventHubConnection.On<string>("Event", async (message) =>
       {
           //Handle the event here
           m_receivedData.Add(message);
           await InvokeAsync(StateHasChanged);
       });

       //Start the connection
       await eventHubConnection.StartAsync();
   }
}

6. In your Shared/NavMenu.razor file, insert the following code:

<div class="nav-item px-3">
   <NavLink class="nav-link" href="connectionTest">
       <span class="oi oi-list-rich" aria-hidden="true"></span> Connection Test
   </NavLink>
</div> 

7. Open the dropdown right beside launch project button. Select your_project_name Debug Properties. In App URL section, change the address from https to http
8. Run your app through Visual Studio

To establish a connection to the SignalR Event Hub Endpoint, it is first required to obtain an EndpointID by using the Connection Management API operation. After the new Event Hub connection request has been created, we're ready to connect to the Event Hub. Follow these steps to create a project that can connect to the Event Hub:

1. Create an .html file containing the following code:
2. Replace {API Host Here} with your actual hosting address. For example, 127.0.0.1 . Replace {YOUR USERNAME}} and {YOUR PASSWORD} with your own credential info.
3. Open the file in your web browser

<script src="https://code.jquery.com/jquery-3.6.3.js" integrity="sha256-nQLuAZGRRcILA+6dMBOvcRh5Pe310sBpanc6+QBmyVM="
   crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/microsoft-signalr/6.0.1/signalr.js"></script>

<body>
   <div id="container">

   </div>
</body>

<script>
   const eventHubUrl = "http://{API Host Here}:33001/hubs/eventHub"; // url of event hub signalR
   const apiUrl = "http://{API Host Here}:5000/v3/"; // url of the EventHub API

   $(document).ready(async function () {
       var endpointID = await getEndpointID();
       
       const connection = new signalR.HubConnectionBuilder()
           .withUrl(eventHubUrl,
               {
                   accessTokenFactory: () => {
                       return endpointID;
                   }
               })
           .configureLogging(signalR.LogLevel.Information)
           .build();

       connection.on("Event", data => {
           // TODO: do something with data
           var node = document.getElementById("container");
           var newNode = document.createElement("p");
           newNode.appendChild(document.createTextNode(data));
           node.appendChild(newNode);
       });

       connection.onclose(async () => {
           //TODO: do something for close event
       });

       await connection.start();
   });

   async function getEndpointID() {
       var accessToken;
       var endpointID;
       try {
           // Get the Bearer Token
           await fetch(
               apiUrl + "auth/token",
               {
                   method: "POST",
                   headers: {
                       "Content-Type": "application/json"
                   },
                   body: JSON.stringify({
                       grant_type: "client_credentials",
                       auth_id: "{YOUR USERNAME}",
                       auth_secret: "{YOUR PASSWORD}"
                   })
               })
               .then(response => response.json())
               .then(result => {
                   accessToken = result["access_token"];
               })
               .catch(error => {
               });

           // Initiate connection details
           await fetch(
               apiUrl + "events/connections",
               {
                   method: "POST",
                   headers: {
                       "Content-Type": "application/json",
                       "Authorization": `Bearer ${accessToken}`
                   },
                   body: JSON.stringify({
                       "Mode": "read",
                       "Filters": [{ "FilterTemplate": "position_events" }]
                   })
               })
               .then(response => response.json())
               .then(result => {
                   endpointID = result["EndpointID"];
               })
               .catch(error => {

               });
       } catch (e) {
           console.log(e);
       }

       return endpointID;
   }
</script> 

To establish a connection to the SignalR Event Hub endpoint, it is first required to obtain an EndpointID by using the Connection Management API operation. After the new Event Hub connection request has been created, we're ready to connect to the Event Hub. Follow these steps to create a project that can connect to the Event Hub:

1. Install required libraries through pip in your terminal:

pip install signalrcore 

2. Create a .py file containing the following code:

import requests
import json
from signalrcore.hub_connection_builder import HubConnectionBuilder

eventHubUrl = "http://{API Host Here}:33001/hubs/eventHub" # Url of event hub signalR
apiUrl = "http://{API Host Here}:5000/v3/"  # Url of the EventHub API

def main():
   hub_connection = HubConnectionBuilder()\
       .with_url(eventHubUrl,
                 options={
                     "access_token_factory": authenticateConnection
                 })\
       .build()

   hub_connection.on_open(lambda: print(
       "connection opened and handshake received ready to send messages"))
   hub_connection.on_close(lambda: print("connection closed"))
   hub_connection.on("Event", print)
   hub_connection.start()


def authenticateConnection():
   # Get Bearer token
   headers = {
       "Content-Type": "application/json"
   }
   body = json.dumps({
       "grant_type": "client_credentials",
       "auth_id": "{YOUR USERNAME}",
       "auth_secret": "{YOUR PASSWORD}"
   })
   authTokenResponse = requests.post(
       apiUrl + "auth/token", headers=headers, data=body)
   authToken = authTokenResponse.json()["access_token"]

   # Initiate connection details to obtain EndpointID
   headers = {
       "Content-Type": "application/json",
       "Authorization": "Bearer " + authToken
   }
   body = json.dumps({
       "QualityOfService": {
           "MaxUpdateRate": 20,
           "MaxThroughput": 10240,
           "AutotuneConnectionParameters": False
       },
       "Mode": "read",
       "Filters": [{"FilterTemplate": "position_events"}]
   })
   endpointIDResponse = requests.post(
       apiUrl + "events/connections", headers=headers, data=body)
   endpointID = endpointIDResponse.json()["EndpointID"]

   return endpointID

if __name__ == "__main__":
   main()

3. Replace {API Host Here} with your actual hosting address. For example, 127.0.0.1 . Replace {YOUR USERNAME}} and {YOUR PASSWORD} with your own credential info.
4. Run the .py file created by the terminal command:

python -i ./FILE_NAME_CREATED.py 

To establish a connection to the SignalR Event Hub endpoint, it is first required to obtain an EndpointID by using the Connection Management API operation. After the new Event Hub connection request has been created, we're ready to connect to the Event Hub. Follow these steps to create a project that can connect to the Event Hub:

1. Create a JAVA project. This example is using Gradle.
2. In build.gradle file, insert the following dependency under the dependencies section:

implementation 'org.slf4j:slf4j-jdk14:1.7.25'
implementation 'com.squareup.okhttp3:okhttp:4.9.0'
implementation 'org.apache.commons:commons-text:1.6'
implementation 'org.json:json:20231013' 

3. Create a new file called SampleClass.java in the same directory of the App.java. And copy paste the code below:

package javadoc;

import java.io.IOException;
import java.util.concurrent.CountDownLatch;

import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;

import com.microsoft.signalr.HubConnection;
import com.microsoft.signalr.HubConnectionBuilder;

import io.reactivex.rxjava3.annotations.NonNull;
import io.reactivex.rxjava3.core.Single;

import okhttp3.Call;
import okhttp3.Callback;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class SampleClass {
    private String eventHubUrl = "http://{API Host Here}/hubs/eventHub";
    private String apiUrl = "http://{API Host Here}:5000/v3";
    private String username = "{YOUR USERNAME}";
    private String password = "{YOUR PASSWORD}";

    public void init() throws Exception {
        String token = getToken();
        String eventHubApiKey = registerApikey(token);
        HubConnection hubConnection = GetEventHubConnection(eventHubApiKey);

        hubConnection.on("Event", (event) -> {
            System.out.println(event);
        }, String.class);

        hubConnection.start();
    }

    public String getToken() throws Exception {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("grant_type", "client_credentials");
        jsonObject.put("auth_id", username);
        jsonObject.put("auth_secret", password);

        OkHttpClient client = new OkHttpClient.Builder().build();
        MediaType mediaType = MediaType.parse("application/json; charset=utf-8");

        Request request = new Request.Builder()
                .url(apiUrl + "/auth/token")
                .post(RequestBody.create(mediaType, jsonObject.toString()))
                .build();

        final String[] result = { null };
        CountDownLatch latch = new CountDownLatch(1);
        client.newCall(request).enqueue(new Callback() {
            @Override
            public void onFailure(@NonNull Call call, @NonNull IOException e) {

                latch.countDown();
            }

            @Override
            public void onResponse(@NonNull Call call, @NonNull Response response) throws IOException {
                JSONObject j_response;
                String responseString = "";
                try {
                    responseString = response.body().string();
                } catch (Exception e) {
                    e.printStackTrace();
                }

                if (!response.isSuccessful()) {
                    latch.countDown();
                    return;
                } else {
                    try {
                        j_response = new JSONObject(responseString);
                        result[0] = j_response.getString("access_token");
                    } catch (Exception e) {
                        e.printStackTrace();
                    }
                }

                latch.countDown();
            }
        });

        latch.await();

        return result[0];
    }

    public String registerApikey(String apiToken) throws Exception {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("grant_type", "client_credentials");
        jsonObject.put("auth_id", username);
        jsonObject.put("auth_secret", password);

        OkHttpClient client = new OkHttpClient.Builder().build();
        MediaType mediaType = MediaType.parse("application/json; charset=utf-8");

        Request request = new Request.Builder()
                .url(apiUrl + "/auth/registerApiKey")
                .addHeader("Authorization", "Bearer " + apiToken)
                .post(RequestBody.create(mediaType, jsonObject.toString()))
                .build();

        final String[] result = { null };
        CountDownLatch latch = new CountDownLatch(1);
        client.newCall(request).enqueue(new Callback() {
            @Override
            public void onFailure(@NonNull Call call, @NonNull IOException e) {
                latch.countDown();
            }

            @Override
            public void onResponse(@NonNull Call call, @NonNull Response response) throws IOException {
                JSONObject j_response;
                String responseString = "";
                try {
                    responseString = response.body().string();
                } catch (Exception e) {
                    e.printStackTrace();
                }

                if (!response.isSuccessful()) {
                    latch.countDown();
                    return;
                } else {
                    try {
                        j_response = new JSONObject(responseString);
                        result[0] = j_response.getString("ApiKey");
                    } catch (Exception e) {
                        e.printStackTrace();
                    }
                }

                latch.countDown();
            }
        });

        latch.await();

        return result[0];
    }

    public HubConnection GetEventHubConnection(String eventHubApiKey) throws Exception {

        String connectionId = GetConnectionID(eventHubApiKey);

        HubConnection hubConnection = HubConnectionBuilder.create(eventHubUrl)
                .withAccessTokenProvider(Single.defer(() -> {
                    return Single.just(connectionId);
                })).build();
        return hubConnection;
    }

    public String GetConnectionID(String eventHubApiKey) throws Exception {
        JSONObject jsonObject = new JSONObject();
        JSONArray filters = new JSONArray();
        JSONObject filter = new JSONObject();

        filter.put("FilterTemplate", "position_events");
        filters.put(filter);

        jsonObject.put("Filters", filters);

        OkHttpClient client = new OkHttpClient.Builder().build();
        MediaType mediaType = MediaType.parse("application/json;");

        Request request = new Request.Builder()
                .url(apiUrl + "/events/connections")
                .post(RequestBody.create(mediaType, jsonObject.toString()))
                .addHeader("X-API-KEY", eventHubApiKey)
                .addHeader("Content-Type", "application/json")
                .build();

        final String[] result = { null };
        CountDownLatch latch = new CountDownLatch(1);

        client.newCall(request).enqueue(new Callback() {
            @Override
            public void onFailure(@NonNull Call call, @NonNull IOException e) {
                latch.countDown();
            }

            @Override
            public void onResponse(@NonNull Call call, @NonNull Response response) throws IOException {
                if (response.isSuccessful()) {
                    try {
                        JSONObject j_response = new JSONObject(response.body().string());
                        result[0] = j_response.getString("EndpointID");
                    } catch (JSONException e) {
                        e.printStackTrace();
                    }
                }
                latch.countDown();
            }
        });

        latch.await();

        return result[0];
    }

}

4. Insert the following code to main method of your App.java:

        SampleClass sample = new SampleClass();
        String token = sample.getToken();
        String eventHubApiKey = sample.registerApikey(token);
        HubConnection hubConnection = sample.GetEventHubConnection(eventHubApiKey);

        hubConnection.on("Event", (event) -> {
            System.out.println(event);
        }, String.class);

        hubConnection.start();

5. Replace {API Host Here} with your actual hosting address. For example, 127.0.0.1 . Replace {YOUR USERNAME}} and {YOUR PASSWORD} with your own credential info.
6. Build and run the project.

Within the Spatial Intelligence Platform, data is primarily routed between various logical components of the platform through a specialized Event Hub backed by .NET Core's SignalR protocol. SignalR is a highly efficient and scalable protocol for distribution of real-time data. The ZSIP implementation of SignalR as an Event Hub extends the standard functionality with the concept of a per-connection FilterChain, which matches against messages traversing the hub to select and relay only the relevant messages for a particular connection. This architecture enables a highly efficient communication backbone capable of exchanging high volume, low latency data, without saturating all client links with miscellaneous data unrelated to their particular function.

To establish a connection to the SignalR Event Hub endpoint, it is first required to obtain an EndpointID by using the Connection Management API operation. The EndpointID from the response must be presented as a Bearer token within the Authorization header of the SignalR connection request.

$(document).ready(function(){
    const oauth_token = "{TOKEN HERE}";
    
    const ZSIP_API = "https://{API Host Here}/v3/";
    const NewConnection_OperationID = "events/connections";
    
    $.ajax({
        url: ZSIP_API + NewConnection_OperationID,
        type: 'POST',
        beforeSend: function (xhr) {
            xhr.setRequestHeader('Authorization', 'Bearer ' + oauth_token);
        },
        contentType: 'application/json',
        data: JSON.stringify({
            Mode: 'read',
            Filters: [
                {
                    FilterTemplate: "dashboard"
                }
            ]
        }),
        success: function(data) {
            connectToEventHub(data.EndpointURI, data.EndpointID);
        },
        error: function() {
            console.log("API request failure");
        }
    });
});

Establishing a Connection

After the new Event Hub connection request has been created, we are ready to connect to the Event Hub.

function connectToEventHub(endpoint, id)
{
    var connection = new signalR.HubConnectionBuilder()
    .withUrl(endpoint,
    {
        accessTokenFactory: () => {
            return id;
        }
    })
    .build();
    
    connection.on("Event", function (message) {
        console.log(message);
    });

    connection.start().then(function () {
        console.log("Connected to Event Hub!");
    }).catch(function (err) {
        return console.error(err.toString());
    });
}

Several Quality of Service options are available to assist with managing low-bandwidth and/or high-latency links. The MaxUpdateRate indicates the maximum number of packets per second sent to a client. The Event Hub uses a sliding window algorithm to determine if this threshold has been exceeded, and once it has, it begins to batch messages together to avoid exceeding the limit. The MaxThroughput property monitors the total bandwidth (not including protocol overhead) and if exceeded, a notice message is forwarded to the client and excess data is truncated. An experimental auto-tune feature is enabled by setting the AutotuneConnectionParameters property to true. When this feature is enabled, the Event Hub will attempt to adjust the parameters in real-time to achieve the best available performance.

Once a connection is established, the client must handle a basic RPC method to receive messages from the server.

Messages routed through the Event Hub are serialized JSON objects and follow this schema definition, with event specific data being contained as a JSON object within the Content property.

Events are classified into a Category and Type, the latter indicating a sub-category specific to the particular Category. Event messages adhere to a common outer-schema with a event-specific Content property. Minimal validation of message content is done aside from schema validation, allowing for flexible and complex functionality between an expansive list of modules, integrations, and end-user solutions. As an example, just because a message may have the Category of POSITION, it is not always the case that this message originated from the Quantum RTLS hardware and may have originated from a simulator module.

POSITION

GATEWAY

ZONE

HARDWARE

SYSTEM

API

DATA EXPORT