MADS WebSockets Bridge

mads-websockets is a MADS agent that exposes MADS topics over WebSockets and can also serve a browser UI over plain HTTP. It subscribes to the MADS broker, forwards matching MADS JSON messages to WebSocket clients, and accepts JSON published by WebSocket clients back into the MADS network.

The bridge is implemented as a small layered runtime:

• MadsTransport handles broker-side I/O through Mads::Agent
• WebSocketTransport handles client-side I/O through libwebsockets
• the embedded web UI lives in web as a single vanilla HTML file and is served as static assets by libwebsockets
• BridgeCore routes validated messages between the two transports
• the FSM in src/fsm_agent_impl.hpp manages agent lifecycle

Protocol

The WebSocket API is topic-oriented.

• A client connects to ws://<host>:<port>/mads/<topic>
• The WebSocket path selects the MADS topic
• The WebSocket payload is raw JSON, without any envelope

Examples:

• listen to one topic: ws://localhost:8080/mads/perf_assess
• listen to all topics: ws://localhost:8080/mads/_all
• publish JSON to one topic: connect to ws://localhost:8080/mads/mytopic and send the JSON payload

_all is a wildcard subscription for receiving data. A connection on /mads/_all receives all MADS topics forwarded by the bridge.

Requirements

The project expects these libraries to be available on the system:

• Mads
• libwebsockets
• readline

The current CMake configuration finds Mads with find_package(Mads CONFIG) and finds libwebsockets through pkg-config. The terminal QR helper dependency libqrcode is fetched automatically with CMake FetchContent.

Build

Configure and build with CMake and Ninja:

cmake -B build -G Ninja
cmake --build build

This produces two executables:

• build/src/mads-websockets
• build/src/ws_client

Test

Run the unit test target with:

ctest --test-dir build --output-on-failure

Configuration

The bridge reads its settings from the MADS broker or from a local mads.ini file, depending on how the agent is launched.

A typical settings block is:

[websockets]
ws_port = 8080
ws_silent = true
sub_topic = [""]

Relevant settings:

• ws_host: interface to bind, default 0.0.0.0
• ws_port: WebSocket server port, default 9002
• ws_path: WebSocket root path, default /mads
• http_enabled: serve the browser UI, default true
• http_host: HTTP bind interface, default 0.0.0.0
• http_port: HTTP UI port, default 8080
• http_path: HTTP UI root path, default /mads
• period: FSM loop period in milliseconds
• receive_timeout: MADS receive timeout in milliseconds
• ws_silent: if true, suppress libwebsockets log messages
• sub_topic: MADS subscription topics for the bridge agent

sub_topic = [""] subscribes the bridge to all MADS topics.

Running The Bridge

Typical usage with broker-hosted settings:

./build/src/mads-websockets tcp://localhost:9092

You can also override the agent name:

./build/src/mads-websockets --name websockets tcp://localhost:9092

At startup the agent prints the standard MADS info block, then:

• Websocket addr: ws://<host>:<port>/mads for each detected external IPv4 endpoint
• HTTP UI addr: http://<host>:<port>/mads for each detected external IPv4 endpoint when HTTP is enabled
• Browser QR: containing the first detected HTTP UI URL
• Connected clients: N

The connected client count is updated in place whenever a client connects or disconnects.

Browser UI

The repository includes a lightweight browser UI under web. It is a single index.html file with inline CSS and JavaScript — no build tools, no Node.js, no npm required. During the CMake build the contents of web/ are embedded into the binary and served at http://<host>:<http_port>/mads.

The browser page fetches http://<host>:<http_port>/bootstrap.json from the same origin to learn the WebSocket scheme, port, and path.

The UI provides two tabs:

• Listen — subscribe to one or more MADS topics (or _all) and view incoming JSON messages in a collapsible tree
• Publish — pick a topic, edit a JSON payload, and send it into the MADS network

All settings (topics, draft message, publish history) are persisted in localStorage.

To enable the browser UI, launch the agent with the option -w or --webserver.

NOTE: upon launch, the command mads-websockets -w presents a QR code that links to the WebUI. Since the latter is exposed on unencrypted http://, though, come smartphone could point the browser to https://<ip>:8080, which is not available. If that happens, just manually edit the URL from https://<ip>:8080 to http://<ip>:8080 (no 's').

ws_client

ws_client is a simple CLI tool for testing the bridge.

Options

• -a, --address: base WebSocket address, default ws://localhost:8080
• -t, --topic: repeatable topic name appended as /mads/<topic>
• -l, --listen: listen and print incoming JSON to stdout
• -p, --publish: read JSON from stdin using readline and publish it
• --debug: enable libwebsockets logs

If no -t is given in listen mode, the default topic is _all.

Publish mode requires exactly one explicit -t.

Listen Examples

Listen to all topics:

./build/src/ws_client -a ws://localhost:8080 -l

Listen to one topic:

./build/src/ws_client -a ws://localhost:8080 -t perf_assess -l

Listen to multiple selected topics:

./build/src/ws_client \
  -a ws://localhost:8080 \
  -t perf_assess \
  -t agent_event \
  -l

Each topic opens its own WebSocket connection under the same client process.

Publish Example

Publish to one topic:

./build/src/ws_client -a ws://localhost:8080 -t mytopic -p

Then type JSON payloads at the prompt, for example:

{"value": 42}

An empty line exits publish mode.

Behavior Summary

• MADS messages are forwarded to WebSocket clients as raw JSON
• WebSocket client messages are published into MADS as raw JSON
• one WebSocket connection corresponds to one topic path
• _all is supported for wildcard receive subscriptions
• multiple topic subscriptions on the client side are implemented as multiple WebSocket connections

Notes

• CURVE-related CLI flags are accepted by mads-websockets for interface compatibility with other MADS commands, but bridge-specific crypto handling is not implemented here.
• remote_control is intentionally not used in this application.