HeliOS

https://docs.prometheus-dynamics.ca
Admin
HeliOS is an on-device runtime for vision pipelines, stream capture, telemetry, and operations that...
Tokens:56,231
Snippets:536
Trust Score:2.8
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install rpiboot on Arch Linux

Source: https://docs.prometheus-dynamics.ca/devices/hvs-raze/install

Installs necessary development packages and compiles the rpiboot utility from source on Arch Linux. This is required for the USB boot flashing method.

```bash
sudo pacman -S --needed git base-devel libusb
git clone https://github.com/raspberrypi/usbboot.git
cd usbboot
make
```

--------------------------------

### Install rpiboot on Fedora

Source: https://docs.prometheus-dynamics.ca/devices/hvs-raze/install

Installs required development tools and compiles the rpiboot utility from source on Fedora systems. This enables USB boot mode for flashing.

```bash
sudo dnf install -y git make gcc libusb1-devel pkgconf-pkg-config
git clone https://github.com/raspberrypi/usbboot.git
cd usbboot
make
```

--------------------------------

### Install rpiboot on Debian/Ubuntu

Source: https://docs.prometheus-dynamics.ca/devices/hvs-raze/install

Installs necessary packages and compiles the rpiboot utility from source on Debian/Ubuntu-based systems. This is a prerequisite for flashing images via USB boot mode.

```bash
sudo apt update
sudo apt install -y git build-essential libusb-1.0-0-dev pkg-config

git clone https://github.com/raspberrypi/usbboot.git
cd usbboot
make
```

--------------------------------

### Run rpiboot.exe on Windows

Source: https://docs.prometheus-dynamics.ca/devices/hvs-raze/install

Instructions for running the rpiboot utility on Windows. This involves downloading and executing the rpiboot.exe file, typically after installation.

```batch
rpiboot.exe
```

--------------------------------

### GET /v1/interdevice/hello

Source: https://docs.prometheus-dynamics.ca/guides/helios-interdevice-protocol

Performs a capability handshake with a peer Helios device to determine protocol support and capabilities.

```APIDOC
## GET /v1/interdevice/hello

### Description
Performs a capability handshake with a peer Helios device to determine protocol support and capabilities.

### Method
GET

### Endpoint
/v1/interdevice/hello

### Response
#### Success Response (200)
- **device_id** (string) - Stable UUID of the peer
- **protocol_version** (string) - Protocol version (e.g., 1.0)
- **capabilities** (array) - List of supported features (proxy_streams, remote_control, etc.)
- **api_base** (string) - Base URL for API requests
- **ws_base** (string) - Base URL for WebSocket connections

#### Response Example
{
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "protocol_version": "1.0",
  "capabilities": ["proxy_streams", "remote_control"],
  "api_base": "https://peer-device.local/v1",
  "ws_base": "wss://peer-device.local/v1"
}
```

--------------------------------

### GET /v1/peripherals/i2c

Source: https://docs.prometheus-dynamics.ca/os/systems/overview

Retrieves a list of detected I2C adapters and devices connected to the system.

```APIDOC
## GET /v1/peripherals/i2c

### Description
Returns the current inventory of I2C adapters and detected peripherals, useful for verifying hardware connectivity.

### Method
GET

### Endpoint
/v1/peripherals/i2c

### Response
#### Success Response (200)
- **adapters** (array) - List of detected I2C adapters and their associated devices.

#### Response Example
{
  "adapters": [
    {
      "bus": 1,
      "devices": ["0x68", "0x76"]
    }
  ]
}
```

--------------------------------

### Run rpiboot utility

Source: https://docs.prometheus-dynamics.ca/devices/hvs-raze/install

Executes the rpiboot utility after it has been compiled or installed. This command is used to prepare the device for image flashing via USB boot mode.

```bash
sudo ./rpiboot
```

--------------------------------

### GET /asyncapi.json

Source: https://docs.prometheus-dynamics.ca/reference/api

Retrieves the AsyncAPI specification for the HeliOS WebSocket API.

```APIDOC
## GET /asyncapi.json

### Description
Fetches the machine-readable AsyncAPI specification for the HeliOS WebSocket API.

### Method
GET

### Endpoint
/asyncapi.json (or /v1/asyncapi.json)

### Parameters
None

### Response
#### Success Response (200)
- **schema** (object) - The full AsyncAPI JSON definition.

#### Response Example
{
  "asyncapi": "2.0.0",
  "info": { "title": "HeliOS WebSocket API", "version": "1.0.0" },
  "channels": {}
}
```

--------------------------------

### TypeScript Bindings Generation

Source: https://docs.prometheus-dynamics.ca/reference/sdk

Example command to generate TypeScript bindings for the frontend using the API codegen tools.

```APIDOC
## TypeScript Bindings Generation

### Description
This command generates TypeScript bindings for the frontend using the provided API specifications.

### Command
```bash
./tools/api-codegen/run.sh
```

### Usage
Run this script in your local environment to generate or update TypeScript SDKs. Ensure you have the necessary build tools and dependencies installed.
```

--------------------------------

### GET /v1/ws

Source: https://docs.prometheus-dynamics.ca/api/websockets

Establishes a WebSocket connection to the HeliOS server for real-time data streaming and interactive sessions.

```APIDOC
## GET /v1/ws

### Description
Establishes a WebSocket connection to the HeliOS server. Clients can subscribe to various channels such as device telemetry, logs, and stream metrics.

### Method
GET

### Endpoint
ws(s)://<host>/v1/ws

### Channels
- **console.session**: Interactive PTY-backed shell session.
- **device.telemetry**: Realtime CPU, memory, and disk usage.
- **devices.updates**: Notifications for peripheral and stream inventory changes.
- **imu.stream**: Realtime IMU status payloads.
- **logs.stream**: Stream of device log lines.
- **ota.stream**: OTA update status and progress events.
- **processes.stream**: Per-process resource usage snapshots.
- **sensors.stream**: Peripheral sensor events (IMU, power, lighting).
- **streams.{stream_id}.frames**: Binary encoded frames for active pipelines.
- **streams.{stream_id}.metrics**: Periodic metrics for active streams.
- **updates.stream**: Global realtime change stream for API/WS settings.

### Request Example
{
  "action": "subscribe",
  "channel": "device.telemetry"
}

### Response
#### Success Response (101 Switching Protocols)
- **data**: (object) - The streaming payload corresponding to the subscribed channel.
```

--------------------------------

### GET /v1/device/nt4

Source: https://docs.prometheus-dynamics.ca/api/networktables

Retrieves the current NetworkTables (NT4) configuration settings for the device.

```APIDOC
## GET /v1/device/nt4

### Description
Retrieves the current NetworkTables (NT4) configuration settings for the device.

### Method
GET

### Endpoint
/v1/device/nt4

### Response
#### Success Response (200)
- **enabled** (boolean) - Whether NT4 subscriptions are enabled.
- **host** (string) - The host address of the NT4 server.
- **port** (integer) - The port of the NT4 server.

#### Response Example
{
  "enabled": true,
  "host": "127.0.0.1",
  "port": 5810
}
```

--------------------------------

### Download HVS - Raze Image

Source: https://docs.prometheus-dynamics.ca/devices/hvs-raze/install

Provides the URL to download the latest HVS - Raze image from the project's GitHub Releases page. This image is used for initial installation or recovery.

```text
https://github.com/Prometheus-Dynamics/HeliOS/releases
```

--------------------------------

### Scan for Web UI Port using nmap

Source: https://docs.prometheus-dynamics.ca/guides/get-online

This command uses nmap to scan a specified subnet for devices listening on port 5800, which is typically used by the Web UI. It helps identify the IP address of the device if other methods fail. Ensure you have nmap installed and know the correct subnet.

```bash
nmap -p 5800 --open 10.63.90.0/24
```

--------------------------------

### GET /v1/pipelines/graphs

Source: https://docs.prometheus-dynamics.ca/api/http

Retrieves a list of all stored pipeline graphs.

```APIDOC
## GET /v1/pipelines/graphs

### Description
List all stored pipeline graphs available in the system.

### Method
GET

### Endpoint
/v1/pipelines/graphs

### Response
#### Success Response (200)
- **graphs** (array) - List of graph objects

#### Response Example
{
  "graphs": []
}
```

--------------------------------

### Generate API Documentation

Source: https://docs.prometheus-dynamics.ca/api/sdk

This command generates API documentation from the OpenAPI and AsyncAPI specs. It is used to keep the documentation in sync with the latest API definitions. Navigate to the 'docs' directory before running this command.

```bash
cd docs
bun run gen:api-docs
```

--------------------------------

### Stream Recording API

Source: https://docs.prometheus-dynamics.ca/api/http

Endpoints for starting and stopping stream recordings.

```APIDOC
## POST /v1/streams/{id}/recording/start

### Description
Start recording a specific stream.

### Method
POST

### Endpoint
/v1/streams/{id}/recording/start

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the stream.
#### Request Body
- **recording_settings** (object) - Optional - Settings for the recording.

### Request Example
```json
{
  "output_path": "/mnt/recordings/stream_123.mp4",
  "duration_seconds": 3600
}
```

### Response
#### Success Response (201)
- **message** (string) - Confirmation message.
- **recording_id** (string) - The ID of the recording.

#### Response Example
```json
{
  "message": "Recording started successfully.",
  "recording_id": "rec-abcde"
}
```
```

```APIDOC
## POST /v1/streams/{id}/recording/stop

### Description
Stop recording a specific stream.

### Method
POST

### Endpoint
/v1/streams/{id}/recording/stop

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the stream.

### Request Example
None

### Response
#### Success Response (204)
No content. Indicates the recording was stopped successfully.

#### Response Example
None
```

--------------------------------

### GET /openapi.json

Source: https://docs.prometheus-dynamics.ca/reference/api

Retrieves the OpenAPI specification for the HeliOS HTTP API.

```APIDOC
## GET /openapi.json

### Description
Fetches the machine-readable OpenAPI specification for the HeliOS HTTP API.

### Method
GET

### Endpoint
/openapi.json (or /v1/openapi.json)

### Parameters
None

### Response
#### Success Response (200)
- **schema** (object) - The full OpenAPI JSON definition.

#### Response Example
{
  "openapi": "3.0.0",
  "info": { "title": "HeliOS API", "version": "1.0.0" },
  "paths": {}
}
```

--------------------------------

### POST /v1/ota/apply

Source: https://docs.prometheus-dynamics.ca/api/http

Schedules an OTA (Over-the-Air) update to be applied to the system.

```APIDOC
## POST /v1/ota/apply

### Description
Triggers the application of a staged OTA update.

### Method
POST

### Endpoint
/v1/ota/apply

### Response
#### Success Response (200)
- **status** (string) - Confirmation of the scheduled update

#### Response Example
{
  "status": "scheduled"
}
```

--------------------------------

### GET /limelight/{table}/status

Source: https://docs.prometheus-dynamics.ca/guides/limelight-api-emulation-plan

Retrieves the current status of the adapter, stream, and underlying device state.

```APIDOC
## GET /limelight/{table}/status

### Description
Returns diagnostic information about the Limelight adapter, including heartbeat, latency, and current configuration state.

### Method
GET

### Endpoint
/limelight/{table}/status

### Parameters
#### Path Parameters
- **table** (string) - Required - The name of the Limelight table/stream to query.

### Response
#### Success Response (200)
- **status** (object) - Current status object containing adapter and device health metrics.

#### Response Example
{
  "hb": 12345,
  "tl": 20,
  "cl": 5,
  "pipeline": 0
}
```

--------------------------------

### POST /api/restart

Source: https://docs.prometheus-dynamics.ca/os/settings/restart

Triggers a restart of specific system components or a full device reboot.

```APIDOC
## POST /api/restart

### Description
Queues a restart action for specific system services or a full device reboot.

### Method
POST

### Endpoint
/api/restart

### Parameters
#### Request Body
- **target** (string) - Required - The component to restart. Options: 'api', 'engine', 'peripherals', 'reboot'

### Request Example
{
  "target": "engine"
}

### Response
#### Success Response (202)
- **status** (string) - Confirmation message: "Restart queued"

#### Response Example
{
  "status": "Restart queued"
}
```

--------------------------------

### Configure IMU Runtime Settings

Source: https://docs.prometheus-dynamics.ca/os/systems/imu

Updates the runtime configuration for the IMU driver and fusion algorithms. Changes are applied immediately.

```APIDOC
## PATCH /v1/device/imu

### Description
Applies runtime configuration changes to the IMU driver and fusion algorithms.

### Method
PATCH

### Endpoint
/v1/device/imu

### Parameters
#### Request Body
- **fusion_method** (string) - Optional - The fusion algorithm/strategy to use (e.g., 'madgwick', 'mahony').
- **angle_range** (string) - Optional - The IMU measurement angle range option (e.g., '+/-180', '+/-90').
- **update_interval_ms** (integer) - Optional - The IMU sample interval in milliseconds.
- **yaw_reference_deg** (number) - Optional - Offset for the yaw heading in degrees.
- **gravity_alignment** (string) - Optional - Specifies which device axis is considered 'up'.

### Request Example
{
  "fusion_method": "madgwick",
  "update_interval_ms": 20,
  "yaw_reference_deg": 10
}

### Response
#### Success Response (200)
Indicates that the configuration was updated successfully. The response body may be empty or contain the updated configuration.

#### Response Example
{
  "message": "IMU configuration updated successfully."
}
```
Tokens:
Raw