Skip to content

Client API overview and examples

Client API overview (REQ/REP)

Requests sent to the control socket (ipc:///tmp/ubridgeReqResp by default) return JSON responses.

  • getDevices
    • Request: { "request": "getDevices" }
    • Response: { "devCount": <int>, "devices": [ { "channelID": "uThing::MNL_D657", ... }, ... ] }
  • getStatistics
    • Request: { "request": "getStatistics" }
    • Response: { "bridgeUpTime": <int>, "numConnectedDevices": <int>, ... }
  • queryDevice
    • Request: { "request": "queryDevice", "channelID": "<channelID>", "query": { ... } }
    • Response: device-specific JSON (e.g., { "status": { ... } })
  • sendCommand
    • Request: { "request": "sendCommand", "channelID": "<channelID>", "command": { ... } }
    • Response: device-specific JSON (often echoes status)

PUB stream (ipc:///tmp/ubridgeStream by default): topics like /sensors/<channelID> carry JSON payloads.

Minimal C++ client

The following example uses the bundled ReqRepClient from sources/uBridge/include/ubridgeClient.h.

#include "uBridgeConfig.h"
#include "ubridgeClient.h"
#include <iostream>

using json = nlohmann::json;

void handleMessage(ubridge::message& message) {
  std::cout << "Topic: " << message.topic << "\n" << message.data.dump() << std::endl;
}

int main() {
  ubridge::Config cfg; // uses defaults from uBridge
  ReqRepClient client(cfg.configSockUrl, cfg.streamSockUrl.c_str());

  if (client.connect() != 0) {
    return 1;
  }

  json devices;
  if (client.getDevices(devices) == 0) {
    std::cout << devices.dump(2) << std::endl;
  }

  // Subscribe to all sensor data
  client.subscribe("/sensors", handleMessage);
  return 0; // unreachable: subscribe() blocks and processes messages
}

Build notes: - Link against NNG and include headers as done in the upstream consumer (sources/uBridge/src/consumer.cpp). - Ensure configSockUrl/streamSockUrl match the server configuration.

Build with CMake (example project)

An example project is provided under examples/ubridge-cpp-client/:

cd examples/ubridge-cpp-client
cmake -S . -B build
cmake --build build -j
./build/ubridge-client-example

Next: other languages

Python (pynng)

Example project: examples/ubridge-python-client/

Usage:

cd examples/ubridge-python-client
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# REQ/REP examples
python ubridge_client.py

# Subscribe to all sensor data
python ubridge_client.py stream

If you see pynng.exceptions.PermissionDenied when using IPC, either run with sudo, adjust the service to create world/group-readable sockets (see server Troubleshooting), or switch both server and client to TCP.

Run with sudo using the venv interpreter explicitly:

# From examples/ubridge-python-client with the venv activated/created
sudo -E "$(pwd)/.venv/bin/python" ubridge_client.py
sudo -E "$(pwd)/.venv/bin/python" ubridge_client.py stream

Planned examples: - Node.js: nnx or TCP JSON bridge - Go: nng bindings - Java: TCP JSON bridge via simple helper