Software Documentation on Open Location Stack

API Reference

Mon, 01 Jan 0001 00:00:00 +0000

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

This page is generated from the Open Location Hub source documentation and should not be edited in the website repository.

Layers

cmd/hub: process bootstrap and wiring
internal/config: environment-driven configuration
internal/httpapi: API surface and handlers
internal/ws: OMLOX WebSocket wrapper protocol, subscriptions, and fan-out
internal/storage/postgres: durable store
internal/mqtt: MQTT topic mapping and broker integration
internal/auth: token verification middleware
internal/rpc: local-method dispatch, MQTT RPC bridging, announcements, and aggregation
internal/hub: shared CRUD, ingest, derived event generation, collision evaluation, and internal event bus emission

Metadata And Hot State

Postgres is the durable source of truth for hub metadata, zones, fences, trackables, and location providers.
The runtime resolves the singleton hub metadata row before the service starts so one stable hub_id and label are available for startup validation, internal event provenance, and identify responses.
The hub loads those resources into an immutable in-memory metadata snapshot before it accepts traffic.
Successful CRUD writes update Postgres first, then update the in-memory snapshot, invalidate any affected derived metadata such as zone transforms, and emit a metadata_changes bus event.
A background reconcile loop reloads durable metadata periodically and emits the same metadata_changes notifications when it detects out-of-band create, update, or delete drift.
Decision-critical ingest state is kept in process memory:
- dedup windows
- latest provider-source locations
- latest trackable locations and WGS84 motions
- proximity hysteresis state
- fence membership state
- collision pair state

Event Fan-Out

REST, MQTT, or WebSocket ingest enters the shared hub service.
The hub validates, normalizes, deduplicates, and updates in-memory transient state on the ingest path.
A buffered native-publication stage emits native location and motion events without blocking ingest on downstream fan-out.
A second buffered decision stage is the insertion point for future filtered or smoothed track processing and currently drives alternate-CRS publication, geofence evaluation, and optional collision evaluation.
MQTT and WebSocket consume the resulting internal event stream and publish transport-specific payloads in batches.
When any non-critical queue fills, the hub drops newer work on that path rather than backpressuring raw ingest.

Implications:

Authentication and Authorization

Mon, 01 Jan 0001 00:00:00 +0000

This page is generated from the Open Location Hub source documentation and should not be edited in the website repository.

This project supports standards-based JWT bearer authentication for the REST API and an authorization model built around JWT claims plus a server-side permissions file.

The same token verifier is also used for the OMLOX WebSocket surface, but WebSocket authentication happens per message through params.token instead of the HTTP Authorization header.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

This page is generated from the Open Location Hub source documentation and should not be edited in the website repository.

All runtime configuration is environment-driven.

Runtime lifecycle behavior:

the hub process runs from a single signal-aware root context created from SIGINT and SIGTERM
startup failures return structured process errors instead of panicking during early config or logger initialization
graceful shutdown uses a bounded timeout so HTTP shutdown and internal event-publisher fan-out can complete deterministically after a stop signal

Core

HTTP_LISTEN_ADDR (default :8080)
HTTP_REQUEST_BODY_LIMIT_BYTES (default 4194304)
LOG_LEVEL (default info)
HUB_ID (optional UUID bootstrap or reset value for the persisted hub identity)
HUB_LABEL (optional bootstrap or reset value for the persisted human-readable hub label)
RESET_HUB_ID (true/false, default false; when true, overwrite stored hub metadata with explicitly supplied env values)
POSTGRES_URL (default postgres://postgres:postgres@localhost:5432/openrtls?sslmode=disable)
MQTT_BROKER_URL (default tcp://localhost:1883)
WEBSOCKET_WRITE_TIMEOUT (duration, default 5s)
WEBSOCKET_READ_TIMEOUT (duration, default 1m)
WEBSOCKET_PING_INTERVAL (duration, default 30s)
WEBSOCKET_OUTBOUND_BUFFER (default 256)
EVENT_BUS_SUBSCRIBER_BUFFER (default 1024)
NATIVE_LOCATION_BUFFER (default 2048)
DERIVED_LOCATION_BUFFER (default 1024)

Hub metadata bootstrap behavior:

Connector Guide: MQTT

Mon, 01 Jan 0001 00:00:00 +0000

This page is generated from the Open Location Hub source documentation and should not be edited in the website repository.

Use MQTT when your deployment already centers on a broker, when trusted edge adapters naturally publish broker messages, or when broker-based routing fits better than a long-lived WebSocket client connection.

This repository ships a concrete MQTT connector example in connectors/gtfs/README.md. The MQTT connector path is documented here against the hub’s implemented OMLOX MQTT surface. Transport details live in specifications/omlox/mqtt.md.

Connector Guide: WebSocket

Mon, 01 Jan 0001 00:00:00 +0000

This page is generated from the Open Location Hub source documentation and should not be edited in the website repository.

Use WebSocket when you want the simplest connector path into the hub. It maps well to the current bundled demos, it works cleanly with the hub’s auth model, and it does not require you to design topic routing beyond the OMLOX WebSocket topic names.

The bundled connector demonstrators in this repository currently use this approach:

Connectors

Mon, 01 Jan 0001 00:00:00 +0000

This page is generated from the Open Location Hub source documentation and should not be edited in the website repository.

This repository keeps connectors outside the hub runtime. A connector is a small process that reads data from some upstream system, maps that data to the hub’s OMLOX-facing model, and submits it through the hub’s supported transport surfaces.

The key point is simple: creating a connector is easy. You do not need to patch the hub. In most cases you only need:

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

This page is generated from the Open Location Hub source documentation and should not be edited in the website repository.

If you want to try Open RTLS Hub on your laptop, start with the shared local runtime in local-hub/. That setup brings up the hub, Postgres, Mosquitto, Dex, and a ready-to-use observability stack so you can inspect what the hub is doing while you experiment.

Fast Path

Review local-hub/README.md.
Start the stack:

local-hub/start_demo.sh

If you need an auth token for manual calls or connector demos:

local-hub/fetch_demo_token.sh

Pick an example connector or continue with the docs below.

What This Setup Is For

local development and experimentation
validating connector behavior against a real hub runtime
inspecting OTLP telemetry during laptop demos and debugging

This starter stack is not positioned as a production deployment recipe.

RPC Guide

Mon, 01 Jan 0001 00:00:00 +0000

This page is generated from the Open Location Hub source documentation and should not be edited in the website repository.

What RPC is

RPC is the hub’s command and diagnostics interface.

Use it when you need to ask the hub or a downstream RTLS device/controller to do something right now. Examples:

check whether the control path is alive
identify a reachable handler
send an OMLOX core command through the hub

Do not use RPC for normal CRUD resource management. Use: