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:
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:
The CCC (Common Command Codes) provides a set of universal commands supported across multiple devices. The Bridge for Supernova has a few CCCs which can be used to interact with the downstream devices. This section details these CCCs.
