Bridge 1.1 API

This document details the API for the Bridge service designed to interface with a variety of USB host adapters, particularly the Supernova produced by Binho, and their connected downstream devices.

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. More host adapters can be added later without changing client applications.

Architecture Overview

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

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.

For instance, the Supernova and Nova host adapters, produced by Binho, currently have their respective command adaptors. Each of these adaptors understands the idiosyncrasies of its corresponding host adapter and facilitates communication by converting the generic JSON command requests into precise SDK calls that these host adapters can comprehend.

3. Command and Response Structure

The Bridge adopts a standardized communication protocol wherein all command requests and responses are structured as JSON objects. A typical command request is composed of a transaction_id, a command denoting the action to be undertaken, and a params dictionary housing any associated 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

To launch the Bridge for the Supernova host adapter:

python bridge.py BinhoSupernova

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

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

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"
  }
}

Exit

Command Request:

{
  "transaction_id": "421",
  "command": "exit"
}

Response:

{
  "transaction_id": "421",
  "status": "exit",
  "type": "command_response",
  "is_promise": false,
  "data": null
}

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

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

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.
Seek Support: If unable to resolve an error, consider reaching out to the support team or consulting the documentation.

Protocol-Specific Commands

Bridge 1.1 API - Basic I3C Commands Bridge 1.1 API - I3C Common Command Codes Bridge 1.1 API - I2C Commands Bridge 1.1 API - UART Commands Bridge 1.1 API - SPI Commands Bridge 1.1 API - GPIO Commands