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 Supernova API serves as an intermediary service, acting as a conduit for various client-side entities to seamlessly interact with specific USB host adapters, notably the Supernova host adapter developed by Binho. The API's main objective is to provide a flexible, unified, and extensible interface that masks the underlying intricacies of interfacing with USB devices. This abstraction allows for easier scalability and integration of more host adapters in the future, without significant disruptions to client applications.

Architecture Overview

1. Bridge Service Layer

At its core, the Bridge is a service written in Python, characterized by its ability to operate through a JSON-based REPL mechanism. By receiving command requests via stdin and returning command responses via stdout, the Bridge can be invoked effortlessly either from the command line or through SDKs that establish a process and redirect the necessary pipes. This design choice ensures a lightweight and agile communication paradigm that's adaptable to various deployment scenarios.

2. Command Adaptors

A distinctive feature of the Bridge's architecture is its use of command adaptors. Command adaptors are akin to drivers or plugins; they're designed to translate generic command requests into specialized SDK calls tailored to specific host adapters. This modular approach ensures that the core Bridge service remains uncluttered and can easily be expanded with more adaptors in the future.

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.

Upon receiving a command, the Bridge sends an acknowledgment in the form of a promise response. This immediate feedback mechanism is crucial for clients to know that their request is in the processing queue. Once the request is fully processed, the Bridge then dispatches a comprehensive final response detailing the outcome of the command.

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:

1. Logging: Always log the error messages for future reference and troubleshooting.

2. Validation: Ensure that the command requests being sent are valid and adhere to the Bridge's API specification.

3. Software Updates: Make sure the Bridge software and the SDK for the Supernova host adapter are up to date.

4. 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