> Complete documentation index: [llms.txt](/llms.txt). Markdown versions of all pages are available by appending `.md` to page URLs.

# Bridge 1.1 API

> Overview of the legacy Bridge 1.1 API, the JSON interface that lets client software drive Binho USB host adapters, mainly the Supernova, through bmcbridge.

:::caution
**Legacy: Bridge 1.1 API.** This is the JSON interface of the Mission Control 2 bridge (`bmcbridge`). For new code on the Binho Supernova and the Binho Pulsar, use [PyCosmicSDK](https://binhollc.github.io/pycosmicsdk/) (Python) or [CosmicSDK](https://binhollc.github.io/CosmicSDK/) (C++).

:::

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:

```shell
python bridge.py BinhoSupernova
```

## Command Structure

Commands are structured as JSON objects. Each command request requires a `transaction_id`, `command`, and `params`:

```json
{
  "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:

```json
{
  "transaction_id": "<string>",
  "status": "<string>",
  "type": "<command_response|notification>",
  "is_promise": "<boolean>",
  "data": "<dictionary>"
}
```

## Device Management Commands

### Open a Connection

*   **Command Request:**

    ```json
    {
      "transaction_id": "2450",
      "command": "open",
      "params": {
        "address": "SupernovaSimulatedPort"
      }
    }
    ```
* **Responses:**
  *   Immediate Promise Response:

      ```json
      {
        "transaction_id": "2450",
        "status": "success",
        "type": "command_response",
        "is_promise": true,
        "data": {
          "command": "open"
        }
      }
      ```
  *   Final Response:

      <pre class="language-json"><code class="lang-json"><strong>{
      </strong>  "transaction_id": "2450",
        "status": "success",
        "type": "command_response",
        "is_promise": false,
        "data": {
          "command": "open",
          "id": "&#x3C;Unique ID>",
          "port": "&#x3C;Port Address>",
          "productName": "&#x3C;Name of the Product>",
          "vendorId": "&#x3C;Vendor ID>",
          "productId": "&#x3C;Product ID>",
          "firmwareVersion": "&#x3C;Firmware Version>",
          "hardwareVersion": "&#x3C;Hardware Version>",
          "mode": "&#x3C;Mode>"
        }
      }
      </code></pre>

### Close a Connection

*   Command Request:<br>

    ```json
    {
      "transaction_id": "123",
      "command": "close"
    }
    ```
*   Response:<br>

    ```json
    {
      "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:<br>

    ```json
    {
      "transaction_id": "421",
      "command": "exit"
    }
    ```
*   Response:<br>

    ```json
    {
      "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:

```json
{
  "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](/software/legacy/bridge-11-api/bridge-11-api-basic-i3c-commands/)
* [Bridge 1.1 API - I3C Common Command Codes](/software/legacy/bridge-11-api/bridge-11-api-i3c-common-command-codes/)
* [Bridge 1.1 API - I2C Commands](/software/legacy/bridge-11-api/bridge-11-api-i2c-commands/)
* [Bridge 1.1 API - UART Commands](/software/legacy/bridge-11-api/bridge-11-api-uart-commands/)
* [Bridge 1.1 API - SPI Commands](/software/legacy/bridge-11-api/bridge-11-api-spi-commands/)
* [Bridge 1.1 API - GPIO Commands](/software/legacy/bridge-11-api/bridge-11-api-gpio-commands/)