blerc

BLE Command Protocol

Commands are JSON objects sent over BLE using the Nordic UART Service (NUS).

Command Format

All commands follow this structure:

{ "cmd": "<command>", ...additional fields }

Available Commands

ping

Health check to verify connection.

{ "cmd": "ping" }

Response:

{ "status": "ok" }

list

List all available apps.

{ "cmd": "list" }

Response:

{
  "status": "ok",
  "data": {
    "apps": [
      { "name": "echo", "type": "cli" },
      { "name": "hostname", "type": "cli" }
    ]
  }
}

run

Execute an app with optional parameters.

{ "cmd": "run", "app": "<app_name>", "params": { ... } }

Examples:

// Run without parameters
{ "cmd": "run", "app": "hostname" }

// Run with parameters
{ "cmd": "run", "app": "echo", "params": { "name": "World" } }

Response:

// Success (CLI app)
{ "status": "ok", "data": { "output": "Hello World\n", "exit_code": 0 } }

// Success (HTTP app)
{ "status": "ok", "data": { "status_code": 200, "body": "..." } }

// Error
{ "status": "error", "code": "APP_NOT_FOUND", "message": "App 'unknown' not found" }

Variable Commands

Manage persistent app variables stored at ~/.config/blerc/<app_name>/config.toml.

get_vars

Get all stored variables for an app.

{ "cmd": "get_vars", "app": "<app_name>" }

Response:

{ "status": "ok", "data": { "vars": { "default_step": 5, "max_volume": 100 } } }

set_vars

Set/replace all variables for an app.

{ "cmd": "set_vars", "app": "<app_name>", "vars": { "key": "value", ... } }

Example:

{ "cmd": "set_vars", "app": "volume_control", "vars": { "default_step": 10, "max_volume": 100 } }

Response:

{ "status": "ok" }

delete_var

Delete a single variable.

{ "cmd": "delete_var", "app": "<app_name>", "key": "<variable_name>" }

Response:

{ "status": "ok" }

Variable Merging

When running an app, stored variables are merged with command parameters. Command parameters take precedence.

Example:

Stored variables: { "step": 5, "device": "speakers" }

// Run with no params → uses stored vars
{ "cmd": "run", "app": "volume_up" }
// Result: step=5, device="speakers"

// Run with params → params override
{ "cmd": "run", "app": "volume_up", "params": { "step": 10 } }
// Result: step=10, device="speakers"

Response Format

Success

{ "status": "ok", "data": { ... } }

Error

{ "status": "error", "code": "<ERROR_CODE>", "message": "<description>" }

Error codes:

Code	Description
INVALID_JSON	Malformed JSON in command
UNKNOWN_COMMAND	Command not recognized
APP_NOT_FOUND	App name not in configuration
EXEC_FAILED	Command execution failed
HTTP_ERROR	HTTP request failed
VAR_ERROR	Variable operation failed

BLE Characteristics

The server uses Nordic UART Service (NUS):

Characteristic	UUID	Description
Service	6e400001-b5a3-f393-e0a9-e50e24dcca9e	NUS Service
RX	6e400002-b5a3-f393-e0a9-e50e24dcca9e	Write commands
TX	6e400003-b5a3-f393-e0a9-e50e24dcca9e	Read responses