Bridge 1.1 API
This page describes the API of the Bridge service, which interfaces with Binho USB host adapters, mainly the Supernova, and the devices connected to them.
Introduction
Section titled “Introduction”The Bridge sits between the client and a USB host adapter, mostly the Supernova. Clients send commands in one format, and the Bridge translates them for the adapter. Client applications do not change when an adapter is added.
Architecture Overview
Section titled “Architecture Overview”1. Bridge Service Layer
Section titled “1. Bridge Service Layer”The Bridge is a Python service with a JSON-based REPL. It reads command requests on stdin and writes command responses on stdout, so it runs from the command line or from an SDK that starts the process and redirects the pipes.
2. Command Adaptors
Section titled “2. Command Adaptors”The Bridge uses command adaptors, which work like drivers or plugins. Each one translates generic command requests into the SDK calls for one host adapter. The core Bridge stays small, and a new adapter is a new adaptor.
The Supernova and the Nova each have a command adaptor. Each adaptor converts the generic JSON command requests into the SDK calls for its adapter.
3. Command and Response Structure
Section titled “3. Command and Response Structure”All command requests and responses are JSON objects. A command request has a transaction_id, a command that names the action, and a params dictionary with its parameters.
When the Bridge receives a command, it first sends a promise response, so the client knows the request is queued. When the request is done, the Bridge sends a final response with the outcome.
Getting Started
Section titled “Getting Started”To launch the Bridge for the Supernova host adapter:
python bridge.py BinhoSupernovaCommand Structure
Section titled “Command Structure”Commands are structured as JSON objects. Each command request requires a transaction_id, command, and params:
{ "transaction_id": "<string>", "command": "<string>", "params": "<dictionary>"}The Bridge typically sends an immediate promise response to acknowledge that the request is queued for processing. Once processed, a final response is returned. Command responses have the following structure:
{ "transaction_id": "<string>", "status": "<string>", "type": "<command_response|notification>", "is_promise": "<boolean>", "data": "<dictionary>"}Device Management Commands
Section titled “Device Management Commands”Open a Connection
Section titled “Open a Connection”-
Command Request:
{"transaction_id": "2450","command": "open","params": {"address": "SupernovaSimulatedPort"}} -
Responses:
-
Immediate Promise Response:
{"transaction_id": "2450","status": "success","type": "command_response","is_promise": true,"data": {"command": "open"}} -
Final Response:
{ "transaction_id": "2450", "status": "success", "type": "command_response", "is_promise": false, "data": { "command": "open", "id": "<Unique ID>", "port": "<Port Address>", "productName": "<Name of the Product>", "vendorId": "<Vendor ID>", "productId": "<Product ID>", "firmwareVersion": "<Firmware Version>", "hardwareVersion": "<Hardware Version>", "mode": "<Mode>" } }
-
Close a Connection
Section titled “Close a Connection”-
Command Request:
{"transaction_id": "123","command": "close"} -
Response:
{"transaction_id": "123","status": "success","type": "command_response","is_promise": false,"data": {"is_response_to": "close","status": "success","result": "Supernova closed successfully"}}
-
Command Request:
{"transaction_id": "421","command": "exit"} -
Response:
{"transaction_id": "421","status": "exit","type": "command_response","is_promise": false,"data": null}
Error Handling
Section titled “Error Handling”The Bridge service returns error messages in a specific format when a command request fails to be executed as expected.
Error Message Structure
Section titled “Error Message Structure”Every error message returned by the Bridge service has the following structure:
{ "transaction_id": "<string>", "status": "failure", "type": null, "is_promise": false, "data": { "error": "<Description of the Error>" }}Where:
transaction_id: Represents the ID of the command request that resulted in the error.status: Always set to “failure” for error messages.type: Typically set to null for error messages.is_promise: Set to false for error messages as they represent the final state of the command request.data: Contains a description of the error.
Handling Errors
Section titled “Handling Errors”When encountering an error:
- Logging: Always log the error messages for future reference and troubleshooting.
- Validation: Ensure that the command requests being sent are valid and adhere to the Bridge’s API specification.
- Software Updates: Make sure the Bridge software and the SDK for the Supernova host adapter are up to date.
- Contact support: If an error persists, email [email protected].

