u-blox

u-Locate 0.1.0 Documentation

1. Abbreviations

AoA

Angle of Arrival

AP

Anchor Point

API

Application Programming Interface

BLE

Bluetooth Low Energy

CRS

Coordinate Reference System

HTTP

Hypertext Transfer Protocol

ID

Identifier

ISO

International Organization for Standardization

JSON

JavaScript Object Notation

MAC

Media Access Control

MQTT

Message Queuing Telemetry Transport

REST

Representational State Transfer — an architectural style for distributed systems like APIs, using HTTP requests.

RSSI

Received Signal Strength Indicator

UTF-8

Unicode Transformation Format 8-bit

2. Definitions

Anchor Point

A device/receiver that receives the AoA consisting of an array of antennas.

Area

The spatial region covered by a set of APs.

MQTT Broker

A server that facilitates communication using the MQTT protocol.

MQTT clients

Devices or applications that connect to an MQTT broker to publish or subscribe to messages.

MQTT Payload

The data transmitted via MQTT between clients and brokers.

MQTT protocol

A lightweight communication protocol specifically designed for low-bandwidth, high-latency, or unreliable networks.

MQTT Topic

A :term: UTF-8 string used by the MQTT broker to filter messages for each connected client.

Tag

A device/transmitter equipped with positioning technology, in our case BLE.

3. Software

3.1. u-locateEngine

3.1.1. u-locateEngine APIs

Interaction with u-locateEngine can be achieved using the following application interface and data types.

u-locateEngine uses JSON over MQTT protocol through the deployment of an MQTT Broker. Interaction with the MQTT Broker can be achieved using MQTT clients. The address (default : localhost) and the port (default : 1883) of this server is preset in the device but can be changed to use your own server.

The u-locateEngine provides both REST and MQTT APIs for different tasks:

  • RESTAPI (at http://ulocateengine.local:8000) handles device management and configuration using JSON over HTTP.

  • MQTTAPI (broker at ulocateengine.local:1883) manages real-time tasks like location updates and sensor data via JSON over MQTT protocol. The MQTT Broker is preset in the device but can be changed to use your own server.

3.1.1.1. MQTTAPI

This documentation provides an overview of the MQTTAPI topics and their respective operations.

3.1.1.1.1. AoA

u-locateEngine retrieves AoA from APs and registers Tags by subscribing to this topic.

MQTT Topic

MQTT Payload

Example

angles

Default  
{
   "beacon_id": <str>,
   "anchor_id": <str>,
   "rssi": <float>,
   "psi": <float>,
   "theta": <float>,
   "timestamp_ms": <str>
}
JSON  
{
   "beacon_id": "beacon_7",
   "anchor_id": "Anchor_2_1",
   "rssi": -67.0,
   "psi": -1.3592131620438384,
   "theta": -81.18442779427915,
   "timestamp_ms": "1700236466232"
}

where:

  • beacon_id : is the ID of the Tag (usually the MAC address)

  • anchor_id : is the ID of the AP

  • rssi : is the RSSI of the received bluetooth signal

  • psi : is the psi angle (degrees) of AoA

  • theta : is the theta angle (degrees) of AoA

  • timestamp_ms : is the time(ms) recording of the received AoA

3.1.1.1.2. Position

u-locateEngine publishes the calculated positions to this topic.

MQTT Topic

MQTT Payload

Example

positions

Default  
{
   "id": <str>,
   "area_id": <str>,
   "x": <float>,
   "y": <float>,
   "z": <float>,
   "timestamp": <str>
}
JSON  
{
   "id": "beacon_24",
   "area_id": "demo",
   "x": 20.000090086770115,
   "y": 12.000017734613778,
   "z": -0.00032371167700522615,
   "timestamp": "2023-11-17T15:59:15.350Z"
}

where :

  • id : is the ID of the Tag (usually the MAC address)

  • area_id : is the term:’ID’ of the Area where the APs, that define the position, belong to

  • x : is the x coordinate of the Tag relative to an arbitrary user-selected coordinate system

  • y : is the y coordinate of the Tag relative to an arbitrary user-selected coordinate system

  • z : is the z coordinate of the Tag relative to an arbitrary user-selected coordinate system

  • timestamp : is the time formatted according to ISO

3.1.1.1.3. APs Configuration

The configuration of each AP is defined by the following JSON format:

MQTT main AP’s configuration Payload

Default  
{
   "anchor_id": <str>,
   "area_id": <str>,
   "x": <float>,
   "y": <float>,
   "z": <float>,
   "azimuth_norm": <int>,
   "elevation_norm": <int>
}

where :

  • anchor_id : is the ID of the AP

  • area_id: is the term:’ID’ of the Area where the APs belong to

  • x : is the x coordinate of the AP relative to an arbitrary user-selected coordinate system

  • y : is the y coordinate of the AP relative to an arbitrary user-selected coordinate system

  • z : is the z coordinate of the AP relative to an arbitrary user-selected coordinate system

  • azimuth_norm : is the azimuth angle of the AP

  • elevation_norm : is the elevation angle of the AP

MQTT main AP’s configuration Example

JSON  
{
   "anchor_id": "Anchor_0_0",
   "area_id": "26771c4e-593f-4447-a467-cdc9516d0b95",
   "x": 0.0,
   "y": 0.0,
   "z": 2,
   "azimuth_norm": 0,
   "elevation_norm": 90
}

The respective API for APs configuration consists of the below topics:

3.1.1.1.3.1. AP creation

u-locateEngine publishes the new created AP to this topic.

MQTT Topic

MQTT Payload

Example

provision/anchor/created

AP’s main payload

AP main payload example
3.1.1.1.3.2. AP updated

u-locateEngine publishes the updated or the new created if it doesn’t exist AP to this topic.

MQTT Topic

MQTT Payload

Example

provision/anchor/updated

AP’s main payload

AP main payload example
3.1.1.1.3.3. AP deletion

u-locateEngine publishes the deleted AP id to this topic.

MQTT Topic

MQTT Payload

Example

provision/anchor/deleted

Default  
<str>
JSON  
"Anchor_0_0"
3.1.1.1.4. Areas’ Configuration

The configuration of each Area is defined by the following JSON format:

MQTT main Area’s configuration Payload

Default  
{
   "area_id": <str>,
   "name": <str>
}

where :

  • area_id : is the ID of the Area

  • name : it is the name of the Area

MQTT main Area’s configuration Example

JSON  
{
   "area_id": "26771c4e-593f-4447-a467-cdc9516d0b95",
   "name": "demo"
}

The respective API for Areas configuration consists of the below topics:

3.1.1.1.4.1. Area creation

u-locateEngine publishes the new created Area to this topic.

MQTT Topic

MQTT Payload

Example

provision/area/created

Area’s main payload

Area’s main payload example
3.1.1.1.4.2. Area updated

u-locateEngine publishes the updated Area to this topic.

MQTT Topic

MQTT Payload

Example

provision/area/updated

Area’s main payload

Area’s main payload example
3.1.1.1.4.3. Area deletion

u-locateEngine publishes the deleted Area id to this topic.

MQTT Topic

MQTT Payload

Example

provision/area/deleted

Default  
<str>
JSON  
"26771c4e-593f-4447-a467-cdc9516d0b95"
3.1.1.1.5. Tags’ Exclusion

Tags’ exclusion of tracking their position to u-locateEngine (black listed) is achieved by using the topics below.

3.1.1.1.5.1. Get updated Tags’ black list

u-locateEngine publishes the updated array of black listed Tags to this topic.

MQTT Topic

MQTT Payload

Example

beaconsBlackList/get

Default  
[<str>]
JSON  
["beacon_1", "beacon_2"]
3.1.1.2. RESTAPI
3.1.1.2.1. anchors
POST/anchors

Create Anchor

Creates a new anchor.

Example request:

POST/anchorsHTTP/1.1Host:example.comContent-Type:application/json{"anchor_id":"string","area_id":"string","x":1.0,"y":1.0,"z":1.0,"azimuth_norm":1.0,"elevation_norm":1.0}
Status Codes:

  • 201 Created –

    Resource created successfully

    Example response:

    HTTP/1.1201CreatedContent-Type:application/json{"anchor_id":"string","area_id":"string","x":1.0,"y":1.0,"z":1.0,"azimuth_norm":1.0,"elevation_norm":1.0}

  • 409 Conflict –

    Conflict between given and existing data

    Example response:

    HTTP/1.1409ConflictContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 422 Unprocessable Entity –

    Validation Error

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"loc":["string",1],"msg":"string","type":"string"}

  • 500 Internal Server Error –

    An unexpected error occurred

    Example response:

    HTTP/1.1500Internal Server ErrorContent-Type:application/json{"msg":"string","type":"string","input":"string"}

GET/anchors

Get Anchors

Get all anchors.

Query Parameters:

  • area_id ({'null', 'string'}) –

Example request:

GET/anchorsHTTP/1.1Host:example.com
Status Codes:

  • 200 OK –

    Request successful

    Example response:

    HTTP/1.1200OKContent-Type:application/json[{"anchor_id":"string","area_id":"string","x":1.0,"y":1.0,"z":1.0,"azimuth_norm":1.0,"elevation_norm":1.0}]

  • 422 Unprocessable Entity –

    Validation Error

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"loc":["string",1],"msg":"string","type":"string"}

PUT/anchors/{anchor_id}

Update Anchor

Updates or creates an anchor with the specified ID.

Parameters:

  • anchor_id (string) –

Example request:

PUT/anchors/{anchor_id}HTTP/1.1Host:example.comContent-Type:application/json{"anchor_id":"string","area_id":"string","x":1.0,"y":1.0,"z":1.0,"azimuth_norm":1.0,"elevation_norm":1.0}
Status Codes:

  • 200 OK –

    Request successful

    Example response:

    HTTP/1.1200OKContent-Type:application/json{"anchor_id":"string","area_id":"string","x":1.0,"y":1.0,"z":1.0,"azimuth_norm":1.0,"elevation_norm":1.0}

  • 201 Created –

    Resource created successfully

    Example response:

    HTTP/1.1201CreatedContent-Type:application/json{"anchor_id":"string","area_id":"string","x":1.0,"y":1.0,"z":1.0,"azimuth_norm":1.0,"elevation_norm":1.0}

  • 400 Bad Request –

    The payload does not match the URL parameters

    Example response:

    HTTP/1.1400Bad RequestContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 422 Unprocessable Entity –

    Validation Error

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"loc":["string",1],"msg":"string","type":"string"}

  • 500 Internal Server Error –

    An unexpected error occurred

    Example response:

    HTTP/1.1500Internal Server ErrorContent-Type:application/json{"msg":"string","type":"string","input":"string"}

DELETE/anchors/{anchor_id}

Delete Anchor

Delete the anchor with the specified ID.

Parameters:

  • anchor_id (string) –

Status Codes:

  • 200 OK –

    Request successful

    Example response:

    HTTP/1.1200OKContent-Type:application/json{}

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1404Not FoundContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 422 Unprocessable Entity –

    Validation Error

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"loc":["string",1],"msg":"string","type":"string"}

  • 500 Internal Server Error –

    An unexpected error occurred

    Example response:

    HTTP/1.1500Internal Server ErrorContent-Type:application/json{"msg":"string","type":"string","input":"string"}

GET/anchors/{anchor_id}

Get Anchor

Get the anchor with the specified ID.

Parameters:

  • anchor_id (string) –

Example request:

GET/anchors/{anchor_id}HTTP/1.1Host:example.com
Status Codes:

  • 200 OK –

    Request successful

    Example response:

    HTTP/1.1200OKContent-Type:application/json{"anchor_id":"string","area_id":"string","x":1.0,"y":1.0,"z":1.0,"azimuth_norm":1.0,"elevation_norm":1.0}

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1404Not FoundContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 422 Unprocessable Entity –

    Validation Error

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"loc":["string",1],"msg":"string","type":"string"}

3.1.1.2.2. areas
GET/areas

Get Areas

Get all areas.

Example request:

GET/areasHTTP/1.1Host:example.com
Status Codes:

  • 200 OK –

    Request successful

    Example response:

    HTTP/1.1200OKContent-Type:application/json[{"area_id":"string","name":"string","anchors":["string"]}]

  • 422 Unprocessable Entity –

    Validation Error

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"loc":["string",1],"msg":"string","type":"string"}

POST/areas

Create Area

Creates a new area.

Example request:

POST/areasHTTP/1.1Host:example.comContent-Type:application/json{"name":"string"}
Status Codes:

  • 201 Created –

    Resource created successfully

    Example response:

    HTTP/1.1201CreatedContent-Type:application/json{"area_id":"string","name":"string"}

  • 409 Conflict –

    Conflict between given and existing data

    Example response:

    HTTP/1.1409ConflictContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 422 Unprocessable Entity –

    Validation Error

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"loc":["string",1],"msg":"string","type":"string"}

  • 500 Internal Server Error –

    An unexpected error occurred

    Example response:

    HTTP/1.1500Internal Server ErrorContent-Type:application/json{"msg":"string","type":"string","input":"string"}

PUT/areas/{area_id}

Update Area

Updates the area with the specified ID.

Parameters:

  • area_id (string) –

Example request:

PUT/areas/{area_id}HTTP/1.1Host:example.comContent-Type:application/json{"name":"string"}
Status Codes:

  • 200 OK –

    Request successful

    Example response:

    HTTP/1.1200OKContent-Type:application/json{"area_id":"string","name":"string"}

  • 422 Unprocessable Entity –

    Validation Error

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"loc":["string",1],"msg":"string","type":"string"}

  • 409 Conflict –

    Conflict between given and existing data

    Example response:

    HTTP/1.1409ConflictContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1404Not FoundContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 500 Internal Server Error –

    An unexpected error occurred

    Example response:

    HTTP/1.1500Internal Server ErrorContent-Type:application/json{"msg":"string","type":"string","input":"string"}

DELETE/areas/{area_id}

Delete Area

Delete the area with the specified ID.

Parameters:

  • area_id (string) –

Status Codes:

  • 200 OK –

    Request successful

    Example response:

    HTTP/1.1200OKContent-Type:application/json{}

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1404Not FoundContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 409 Conflict –

    Conflict between given and existing data

    Example response:

    HTTP/1.1409ConflictContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 422 Unprocessable Entity –

    Validation Error

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"loc":["string",1],"msg":"string","type":"string"}

  • 500 Internal Server Error –

    An unexpected error occurred

    Example response:

    HTTP/1.1500Internal Server ErrorContent-Type:application/json{"msg":"string","type":"string","input":"string"}

GET/areas/{area_id}

Get Area

Get the area with the specified ID.

Parameters:

  • area_id (string) –

Example request:

GET/areas/{area_id}HTTP/1.1Host:example.com
Status Codes:

  • 200 OK –

    Request successful

    Example response:

    HTTP/1.1200OKContent-Type:application/json{"area_id":"string","name":"string","anchors":["string"]}

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1404Not FoundContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 422 Unprocessable Entity –

    Validation Error

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"loc":["string",1],"msg":"string","type":"string"}

3.1.1.2.3. logs
GET/logs

Retrieve Logs

Retrieve logs for all containers.

Example request:

GET/logsHTTP/1.1Host:example.com
Status Codes:

  • 200 OK – Request successful

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1404Not FoundContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 422 Unprocessable Entity –

    Validation Error

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"loc":["string",1],"msg":"string","type":"string"}

  • 500 Internal Server Error –

    An unexpected error occurred

    Example response:

    HTTP/1.1500Internal Server ErrorContent-Type:application/json{"msg":"string","type":"string","input":"string"}

GET/logs/{container}

Retrieve Specific Logs

Retrieve logs for a specific folder.

Parameters:

  • container (string) –

Example request:

GET/logs/{container}HTTP/1.1Host:example.com
Status Codes:

  • 200 OK – Request successful

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1404Not FoundContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 422 Unprocessable Entity –

    Validation Error

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"loc":["string",1],"msg":"string","type":"string"}

  • 500 Internal Server Error –

    An unexpected error occurred

    Example response:

    HTTP/1.1500Internal Server ErrorContent-Type:application/json{"msg":"string","type":"string","input":"string"}

GET/logs-structure

Get Folder Structure

Get logs’ folder structure.

Example request:

GET/logs-structureHTTP/1.1Host:example.com
Status Codes:

  • 200 OK –

    Request successful

    Example response:

    HTTP/1.1200OKContent-Type:application/json{"folder_name":"string","items":[{"name":"string","is_folder":true}]}

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1404Not FoundContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 422 Unprocessable Entity –

    Validation Error

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"loc":["string",1],"msg":"string","type":"string"}

  • 500 Internal Server Error –

    An unexpected error occurred

    Example response:

    HTTP/1.1500Internal Server ErrorContent-Type:application/json{"msg":"string","type":"string","input":"string"}

3.1.1.2.4. beacons_black_list
GET/beacons_black_list

Get Beacons Blacklisted

Get all blacklisted beacon ids.

Example request:

GET/beacons_black_listHTTP/1.1Host:example.com
Status Codes:

  • 200 OK –

    Request successful

    Example response:

    HTTP/1.1200OKContent-Type:application/json{"beacons_blacklisted":[{"beacon_id":"string"}]}

  • 422 Unprocessable Entity –

    Validation Error

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"loc":["string",1],"msg":"string","type":"string"}

POST/beacons_black_list

Add Beacon Black List

Adds a beacon in blacklist.

Example request:

POST/beacons_black_listHTTP/1.1Host:example.comContent-Type:application/json{"beacon_id":"string"}
Status Codes:

  • 200 OK –

    Request successful

    Example response:

    HTTP/1.1200OKContent-Type:application/json{}

  • 409 Conflict –

    Conflict between given and existing data

    Example response:

    HTTP/1.1409ConflictContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 422 Unprocessable Entity –

    Validation Error

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"loc":["string",1],"msg":"string","type":"string"}

  • 500 Internal Server Error –

    An unexpected error occurred

    Example response:

    HTTP/1.1500Internal Server ErrorContent-Type:application/json{"msg":"string","type":"string","input":"string"}

DELETE/beacons_black_list

Remove Beacon Black List

Remove a beacon from blacklist.

Example request:

DELETE/beacons_black_listHTTP/1.1Host:example.comContent-Type:application/json{"beacon_id":"string"}
Status Codes:

  • 200 OK –

    Request successful

    Example response:

    HTTP/1.1200OKContent-Type:application/json{}

  • 404 Not Found –

    Resource not found

    Example response:

    HTTP/1.1404Not FoundContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 422 Unprocessable Entity –

    Validation Error

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"loc":["string",1],"msg":"string","type":"string"}

  • 500 Internal Server Error –

    An unexpected error occurred

    Example response:

    HTTP/1.1500Internal Server ErrorContent-Type:application/json{"msg":"string","type":"string","input":"string"}

3.1.1.2.5. statistics
GET/statistics/{component}

Get Engine Statistics

Get statistics data for the ulocateEngine.

Parameters:

  • component (string) –

Query Parameters:

  • field ({'null', 'string'}) –

Example request:

GET/statistics/{component}HTTP/1.1Host:example.com
Status Codes:

  • 200 OK –

    Successful Response

    Example response:

    HTTP/1.1200OKContent-Type:application/json{"fields":{}}

  • 404 Not Found –

    Not Found

    Example response:

    HTTP/1.1404Not FoundContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 400 Bad Request –

    Bad Request

    Example response:

    HTTP/1.1400Bad RequestContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 422 Unprocessable Entity –

    Unprocessable Entity

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"msg":"string","type":"string","input":"string"}

GET/statistics

Get Statistics

Get combined statistics data for each component.

Example request:

GET/statisticsHTTP/1.1Host:example.com
Status Codes:

  • 200 OK –

    Successful Response

    Example response:

    HTTP/1.1200OKContent-Type:application/json{"components":{}}

  • 404 Not Found –

    Not Found

    Example response:

    HTTP/1.1404Not FoundContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 422 Unprocessable Entity –

    Unprocessable Entity

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"msg":"string","type":"string","input":"string"}

GET/statistics-structure

Get Statistics Structure

Get statistics’ structure.

Example request:

GET/statistics-structureHTTP/1.1Host:example.com
Status Codes:

  • 200 OK –

    Successful Response

    Example response:

    HTTP/1.1200OKContent-Type:application/json{"components":{}}

  • 404 Not Found –

    Not Found

    Example response:

    HTTP/1.1404Not FoundContent-Type:application/json{"msg":"string","type":"string","input":"string"}

  • 422 Unprocessable Entity –

    Unprocessable Entity

    Example response:

    HTTP/1.1422Unprocessable EntityContent-Type:application/json{"msg":"string","type":"string","input":"string"}

Last updated: Feb 3, 2025
Need help?Contact Support
Questions?Contact us