This is the full developer documentation for Binho Support # Binho Customer Support > Documentation and support for Binho host adapters, Mission Control, and SDKs. // CUSTOMER SUPPORT Ship Better\ Hardware,\ Faster. ======= Documentation for Binho host adapters, Mission Control, and SDKs — written for engineers, readable by your AI agents. [Getting Started →](/getting-started/) // TRUSTED BY ENGINEERS AT  [01](/getting-started/) ## [Getting Started](/getting-started/) [Hardware setup, Mission Control quickstart, first transactions.](/getting-started/) [→](/getting-started/)[02](/user-guide/) ## [User Guide](/user-guide/) [Nova & Supernova, protocols, Bridge 1.1 API, firmware.](/user-guide/) [→](/user-guide/)[03](/examples/) ## [Examples](/examples/) [Working setups: SupernovaController, notebooks, target boards.](/examples/) [→](/examples/)[04](/troubleshooting/) ## [Troubleshooting & FAQ](/troubleshooting/) [Drivers, detection issues, protocol questions.](/troubleshooting/) [→](/troubleshooting/)[05](/orders-and-shipping/) ## [Orders & Shipping](/orders-and-shipping/) [Quotes, purchase orders, distributors, tax exemption.](/orders-and-shipping/) [→](/orders-and-shipping/)[06](/contact-us/) ## [Contact Us](/contact-us/) [Engineers answer the email: techsupport@binho.io.](/contact-us/) [→](/contact-us/) # 404 — Page not found // ERROR 404 # Page not found. This page moved or never existed. Try the docs from the top, use search (`Ctrl` `K`), or head back to binho.io. [Getting Started](/getting-started/)[binho.io ↗](https://binho.io) # Contact Us The best way to reach us is at . We reply to all emails within 24 hours, usually sooner. Additionally, one of us is usually hanging out on our website chat support for immediate responses. # Dropping Legacy Terminology The *Binho* support portal and product documentation have been updated to replace legacy industry terms with modern terminology. ### I2C Terminology [Section titled “I2C Terminology”](#i2c-terminology) Tip The usage of I2C Master/Slave terminology is considered obsolete. Master and Slave are now *Controller* and *Peripheral*. Regrettably as of yet, there has been very little consensus within the industry as to which terms to adopt for devices on the I2C bus. We’re involved in this conversation taking place and plan to update our documentation once the industry has settled on a set of new terms. ### SPI Terminology [Section titled “SPI Terminology”](#spi-terminology) Tip The usage of SPI Master/Slave terminology is considered obsolete. Master and Slave are now *Controller* and *Peripheral*. As such, the usage of MOSI/MISO/SS for pin and signal names has been replaced with SDI/SDO/CS. #### New Signal Names: [Section titled “New Signal Names:”](#new-signal-names) * **SDO** - Serial Data Out. An output pin on a device where data is sent out to another SPI device. * **SDI** - Serial Data In. An input pin on a device where data is received from another SPI device. * **CS** - Chip Select. Activated by the controller to initiate communication with a given peripheral. Often drawn C̅S̅ to indicate active low but not required. #### Deprecated Signal Names: [Section titled “Deprecated Signal Names:”](#deprecated-signal-names) * **MOSI** - Master Out Slave In * **MISO** - Master In Slave Out * **SS** - Slave Select #### Unchanged Signal Names: [Section titled “Unchanged Signal Names:”](#unchanged-signal-names) * **SCK** - Serial Clock. The clock for the bus generated by the controller. While many microcontroller and processor manufacturers lag behind, the SDI/SDO/CS terminology is already widely adopted by several large semiconductor companies and can be found extensively used in the datasheets for their new devices. ### 1-Wire Terminology [Section titled “1-Wire Terminology”](#1-wire-terminology) Tip The usage of 1-Wire Master/Slave terminology is considered obsolete. Master and Slave are now Host and Device. Maxim Integrated has already been using the terms Host and Device in their documentation for a while, and we regret that we did not make this change to our documentation earlier. Thankfully this means there should be little confusion as a result of this change in our documentation. ### Why did we change our documentation? [Section titled “Why did we change our documentation?”](#why-did-we-change-our-documentation) The electronics industry in particular has been using an embarrassingly outdated lexicon when it comes to discussing communication bus topology and the various roles and modes of operation of devices on the bus. It’s unfortunate that this has gone on this long without acknowledging the need to leave these terms in the past. Thankfully, the industry is already making the shift, and many device manufacturers have already begun to adopt new terminology. *Binho* is proud to help push for the [industry-wide adoption of modern terminology](https://www.oshwa.org/a-resolution-to-redefine-spi-signal-names/) that is inclusive. Let’s celebrate the ability to change and improve over time! # Examples This section presents examples to illustrate the use of Binho Host Adapters across various abstraction layers, demonstrating potential use cases and introducing the user straightforwardly in the integration of our adapters into their hardware development and testing setups. # Other Examples > Many examples are present throughout this documentation. Here, you can find quick-access links to the most important ones. ## Related to the Binho Mission Control App [Section titled “Related to the Binho Mission Control App”](#related-to-the-binho-mission-control-app) Example on the UI with GPIO and Simulator at [GPIO Protocol Example](/getting-started/binho-mission-control/communication-protocols/gpio/#example). You can also find some real device examples with Mission Control for [I2C](/getting-started/binho-mission-control/communication-protocols/i2c/#real-world-example) and [SPI](/getting-started/binho-mission-control/communication-protocols/spi/#real-world-examples). ## Related to the Python SDKs [Section titled “Related to the Python SDKs”](#related-to-the-python-sdks) For Nova SDK examples, see the [Example Scripts](/getting-started/python-sdks/nova-sdk/#example-scripts). For Supernova Python SDK (Supernova Controller), check out the [In-Package Examples](/getting-started/python-sdks/supernovacontroller/#examples). ## Related to the C++ SDK [Section titled “Related to the C++ SDK”](#related-to-the-c-sdk) For the C++ SDK, you can check out the [Included Example Applications](/getting-started/c-sdk/example-applications/#example-applications). # SupernovaController ## ICM42605 accelerometer/gyroscope example [Section titled “ICM42605 accelerometer/gyroscope example”](#icm42605-accelerometergyroscope-example) The following link takes you to a repository with an advanced example of SupernovaController usage: The “demo\_supernova\_icm42605” repository offers a Python script for using an ICM42605 sensor with a Supernova host adapter, demonstrating real-time data reading and visualization. Setup requires at least Python 3.10, an ICM42605 sensor, and involves cloning the repo, environment setup, and dependency installation (see README in the repository). Running the script displays live sensor data plots, as can be seen in the figure shown below:  Plot showing Accelerometer and Gyroscope real-time data # FAQ # Can multiple devices be used at the same time? **Yes!** One of the key features is that it’s easy to use multiple devices on the same computer at the same time. Each device will be enumerated as a different COM port / HID address on the machine. This eliminates device management headaches and limitations that occur when using other types of USB device classes. Our Python SDK was designed for usage with multiple host adapters connected to a PC and provides mechanisms for straightforward device management, both within scripts and on the command line interface. In the case of using Binho Mission Control app with multiple devices, simply launch multiple instances of the app for each device. # Is the ADC calibrated? **No**. The ADC is not calibrated. The analog features of the *Binho Nova Host Adapter* are not meant to serve as an oscilloscope or other precise piece of analog test equipment. It is not characterized for performance on AC signals and should only be considered suitable for measurement of \~DC signals. # Is the DAC calibrated? **No**. The DAC is not calibrated. This feature should be regarded as a simple way to produce a nearly \~DC analog voltage signal as a test stimulus. It is not suitable for a fully-featured analog waveform generator. # Is there a GUI available? **Yes!** Our desktop GUI software is called *Binho Mission Control*. It is fully cross-platform, supporting Windows, MacOS, and Ubuntu (and select other Linux distributions). [download-and-installation.md](/getting-started/binho-mission-control/download-and-installation/) # What is a host adapter? ## About Host Adapters [Section titled “About Host Adapters”](#about-host-adapters) In general terms, a *host adapter* (also sometimes called a *host bus adapter*) is a device which connects a computer (the host system) to other peripheral devices. Within the computer, there are many ICs on the motherboard communicating using various protocols, such as PCIe, SATA, SMBus, USB, etc. But within the world of electronics, interesting sensors, actuators, and application-specific ICs use several different standard protocols such as SPI, I2C, 1-Wire, and SWI. These protocols are not typically supported directly by the motherboard chipset or otherwise exposed, either physically or programmatically, for user access. We partnered with Shannon Morse to help us answer the question “What is a host adapter?”: [YouTube video player](https://www.youtube.com/embed/49SveRYJpWA) So what happens when you want to connect one of the devices that communicates via SPI, I2C, I3C, 1-Wire, or SWI to your computer? Well, you’ll need to use an adapter to interface between one of the protocols on the host computer to the desired new protocol. That’s where *Binho Multi-Protocol Host Adapters* comes in. *Binho Multi-Protocol USB Host Adapters* are the tools that enable one to connect sensors, actuators, and other devices communicating over SPI, I2C, I3C, 1-Wire, or SWI to your computer via USB. The USB host adapter can receive commands and provide data to the host PC over USB, while also managing connections with target I2C/I3C/SPI/1-Wire devices and carrying out the desired interactions as directed by software on the host PC.  #### Why would I need a host adapter?[](#why-would-i-need-a-host-adapter) [Section titled “Why would I need a host adapter? ”](#why-would-i-need-a-host-adapter-) There are many occasions when a host adapter would be a tool of great convenience and utility, throughout all stages of the product development cycle. Essentially these situations can be classified into three groups: **1 Rapid Prototyping & Development** Early in the product development cycle, a host adapter can allow engineers to rapidly build prototypes and perform concept validation before any custom hardware or PCBs have been designed or produced. When custom hardware is a scarce resource, host adapters allow developers to emulate the microcontroller, allowing code to be developed and executed on a PC. This enables engineering team members to develop and verify low-level device drivers and subsystem operation. Essentially this ensures the team is unblocked while waiting for hardware to be ready. Then, upon arrival of the hardware, the team is ready to hit the ground running. Discrete real-world examples of this can be seen in how self-driving car algorithms are being developed. Engineers directly interface their computers to an automobile’s systems and sensors on the vehicle by tapping into the vehicle communication bus (typically CAN or LIN) with a USB host adapter. In this manner, all of the necessary data can be gathered and processed on their computers while they train their algorithms that will eventually run on custom-developed on-board automotive computers. This is similar to many industries where high-level software developers are working on AI/ML algorithms. It enables the training of neural nets to be performed on high-end systems with tons of compute while the hardware team is developing the custom hardware that will ultimately be employed in the end product. In this case, the use of host adapters to get the desired sensor data onto computers ensures that software development will not be bottle-necked by hardware development. **2 Automated Testing** As a team progresses in the development cycle, the concept has been proven and the focus has shifted into turning the prototype into a rock-solid high quality product, testing becomes extremely important. Hardware testing can become quite cumbersome, and as the firmware evolves and the PCBs are revised and re-fabricated, it becomes imperative that tests are repeated. As such, best practices in the industry incorporate a high level of testing automation, which is less prone to human error and also reduces the amount of time needed to execute thorough test plans from hours down to minutes. This ensures the developers are spending their time making forward progress rather than needing to spend hours ensuring that their latest change didn’t break a feature that’s been working for months. This one can be divided into two sub-categories: *A) Automated Hardware Testing* — each time there is a new build/ revision of the board, a test can be performed to verify key hardware performance parameters are within specification. Using a scripted test with a host adapter allows engineers on the hardware team to vet the boards before handing them over to firmware engineers in an unknown state without the need for the firmware team to develop a test mode first. *B) Automated Firmware Testing* – Best practice in industry includes Continuous Integration, where each time a change to the codebase has been pushed to the code repository, it is automatically recompiled. At a minimum, the result of the compilation needs to be error free, however, the best teams are then extending their CI process to deploy the new firmware build to actual hardware, where a series of scripted tests can be performed and executed. Just because firmware compiles does not mean that it’s working as expected or that some functionality wasn’t broken when running on an embedded system. Host adapters are a perfect way to stimulate various test conditions. **3 Production Line Programming & Provisioning** Aside from the flashing of firmware on to the microcontroller, many devices also have some on-board memory (EEPROM, FRAM, or FLASH) that needs to be pre-loaded to a certain state. This could something as simple as programming a specific pair of values to be used as the USB VID/PID values in a USB device, or loading audio/visual assets onto a product with an interactive UI design. Host adapters can be used to Erase, Program, and Verify the data on these memory chips. Additionally, these adapters can be used to provision certain devices which require a one-time setup process during manufacturing, such as assigning unique serial numbers or MAC addresses or provisioning a CryptoAuthentication IC with secret keys in order to obtain the desired level of hardware security. Good host adapters are gang-able (meaning that you can attach many of them to the same host computer and control them in parallel) so it will be easy to scale up the throughput / efficiency of the programming/provision process so that it’s not a bottleneck in your product assembly procedure. # What protocols are supported? The Binho Nova Host Adapter currently supports SPI, I2C, UART, Dallas 1-Wire, and Atmel Single-Wire Interface. Beyond these protocols, the device also can operate in IO mode where the pins can be configured to use other peripherals, such as ADC inputs, DAC output, or just standard GPIO. The Binho Supernova Host Adapter currently supports I3C, I2C, and SPI protocols in both controller and target modes, plus UART and GPIO. See the Binho Nova / Supernova Comparison Table: [hardware-comparison-table.md](/user-guide/hardware-comparison-table/) # Where can I find the product datasheet? The product datasheet, along with other technical assets can be found on the [downloads page](https://binho.io/pages/downloads). For convenience, it can also be directly downloaded from the link below: #### Download [Binho Nova Multi-Protocol USB Host Adapter Datasheet v1.4](https://cdn.binho.io/doc/nova/datasheet/1.4/Binho%20Nova%20Datasheet%20v1.4.pdf) \[pdf] [Section titled “Download Binho Nova Multi-Protocol USB Host Adapter Datasheet v1.4 \[pdf\]”](#download-binho-nova-multi-protocol-usb-host-adapter-datasheet-v14-pdf) # Getting Started Welcome to our Getting Started Guide. Both the *Binho Nova* and the *Binho Supernova* were designed for ultimate flexibility, as such, there are multiple ways to control and interact with them. First, follow the Hardware Setup Guide to quickly get your device connected to the host computer and your electronics: [hardware-setup](hardware-setup/) Once everything is connected, follow the guides below to learn how to interact with the Binho Nova and/or the Binho Supernova, using our GUI desktop application Binho Mission Control. Alternatively you can use one of the SDKs we offer to obtain more configurability. ### Desktop App Guide [Section titled “Desktop App Guide”](#desktop-app-guide) The best way to familiarize yourself with the Binho host adapter is to test it using Binho Mission Control, the cross-platform desktop software designed for interfacing with host adapters. Even if you plan to use it in automated settings, starting with the GUI is recommended before you begin writing scripts. [binho-mission-control](binho-mission-control/) ### Python SDK Guide [Section titled “Python SDK Guide”](#python-sdk-guide) When you’re ready to start writing your own automated scripts, take a look at our guide for using our Python SDKs. [python-sdks](python-sdks/) # Binho Mission Control Binho Mission Control is a multi-platform desktop app for seamless embedded system development and testing. It replaces the tedious coding, building, and testing loop with a simple GUI.  Screenshot of Binho Mission Control interacting with a downstream device using the I3C protocol ## Summary [Section titled “Summary”](#summary) ### **Supported Devices** [Section titled “Supported Devices”](#supported-devices) * Supports Binho Nova and Supernova Host Adapters. * Plans for future host adapter compatibility. * Test-drive the app with built-in Binho Nova and Binho Supernova simulators. ### **Features** [Section titled “Features”](#features) * Supports protocols like I2C, I3C, SPI, GPIO, UART, and 1-WIRE. * Enables easy protocol transactions, from basic to advanced. * Intuitive device configuration, from bus voltage to address settings. * Clear interface for all user levels. * Consistent experience across Binho devices. ### **System Compatibility** [Section titled “System Compatibility”](#system-compatibility) * Works on Windows, Linux, and macOS. ### **Elevating Your Engineering Process** [Section titled “Elevating Your Engineering Process”](#elevating-your-engineering-process) Many semiconductor manufacturers create their own engineering tools to aid customers in product development with their chips, as existing tools are usually poor. This leads to various evaluation tools specific to manufacturers, making the development process unnecessarily complex, inefficient and painful. Binho Mission Control is designed for engineering prototypes, development, and testing equipment. Its main goal is to become a single, user-centered software tool that sets the standard, allowing engineers to streamline the development and testing phases by eliminating the long feedback loop that arises when coding, building, and testing devices through a microcontroller. With this software, the user can easily perform the allowed transactions of each protocol, such as write, read, transfer, CCC commands, etc. Besides, the user can configure several parameters depending on the protocol activated. For example, the bus voltage, the clock frequency, the read payload size, the address, etc. *** The upcoming sections provide a quick introduction to some of the varied functionalities offered by Binho Mission Control. These segments aim to offer a limited but rapid insight of the range of features available for each host adapter. The focus is on providing a primary contact into the app’s capabilities and possible usages. # Communication Protocols In this section we dive into each protocol, unraveling their functionalities and elucidating the efficacy of the Binho Mission Control app through practical examples and use-cases. Below there is a table that indicates which protocols are available for each Binho host adapter: | Host adapter | GPIO | SPI | UART | I2C | I3C | 1-Wire | | ------------ | ---- | --- | ---- | --- | --- | ------ | | Nova | Yes | Yes | - | Yes | - | Yes | | Supernova | Yes | Yes | Yes | Yes | Yes | - | | Pulsar | Yes | Yes | Yes | Yes | - | - | # 1-WIRE The 1-Wire protocol is a unique half-duplex communication protocol that allows devices to interact using a singular data line along with a ground reference. Though asynchronous in design, specific timing specifications are employed to differentiate between 1-Wire commands. Similar to I2C, the 1-Wire protocol utilizes an open-drain configuration at the hardware level. .png) 1-Wire command panel ## Settings [Section titled “Settings”](#settings) .png) Settings sub-panel Within this segment, users can opt to use internal pull-up resistors if available in the host adapter. Accessing the Command dropdown menu reveals available ROM Commands: SKIP and SELECT (often referred to as MATCH). The SKIP command broadcasts a message to all connected target devices, while the SELECT command communicates with a specific device. If there’s only one target device on the 1-Wire bus, these commands are disregarded. The SCAN button initiates a series of SEARCH commands, unveiling the 64-bit addresses of all target devices connected to the bus. ## Transfer [Section titled “Transfer”](#transfer) .png) Transfer sub-panel This segment features two inputs: ‘Bytes to Read’ and ‘Bytes to Write’. It also includes three action buttons: READ, WRITE, and TRANSFER. As with other protocols, the ‘Bytes to Write’ field recognizes bytes in hexadecimal format. Activating the TRANSFER button initiates a Write action, immediately followed by a Read action. # GPIO When the user selects .png) from the Navigation Menu, the GPIO (*General-Purpose Input/Output*) command panel shows up.  Initial GPIO command panel for Supernova. For GPIO, there are six potential configurations for a pin: Analog Input (AIN), Analog Output (AOUT), Pulse Width Modulation (PWM), Digital Input (DIN), Digital Output (DOUT) and Interruptions. The table below delineates the capabilities for each Nova IO pin (N), Supernova IO pin (SN) and Pulsar IO pin (P). | Pin | AIN | AOUT | PWM | DIN | DOUT | Interruption | | :-: | :-: | :--: | :-: | :--------: | :--------: | ------------ | | IO0 | N | - | N | N | N | - | | IO1 | N | N | - | N - SN - P | N - SN - P | SN - P | | IO2 | N | - | N | N - SN - P | N - SN - P | SN - P | | IO3 | N | - | N | N - SN - P | N - SN - P | SN\* - P | | IO4 | N | - | N | N - SN - P | N - SN - P | SN - P | | IO5 | - | - | - | SN - P | SN - P | SN - P | | IO6 | - | - | - | SN - P | SN - P | SN - P | \*Supernova Rev. B does not support GPIO interruptions on pin 3. Notes: * **Analog Input (AIN)**: When a pin is set to AIN, a READ button appears. Pressing this button prompts the host adapter to gauge the pin’s voltage, displaying the result in the Transactions Log View. * **Digital Input (DIN)**: Pins configured as DIN behave similarly to AIN. However, the measurement is binary, indicating either a Low or High value. * **Analog and Digital Output (AOUT/DOUT)**: For these output configurations, a WRITE button accompanied by a textbox is presented. For AOUT, users can input a voltage value ranging from 0.0 V to 3.3 V. For DOUT, this textbox transforms into a dropdown list, offering either Low or High options. * **Pulse Width Modulation (PWM)**: Pins with PWM capabilities allow users to modify both the duty cycle and frequency. Frequency can be adjusted from 750Hz to 80kHz via the provided textbox, while the duty cycle ranges from 0% to 100% (integer values only). It’s important to note that IO0 and IO2 share a frequency setting, as do IO3 and IO4. Adjusting the frequency for one channel will also alter its corresponding channel. ## Example [Section titled “Example”](#example) To better understand the user interface, let’s walk through a simple example using the simulator: 1. An analog READ operation on the IO0 pin yielded a result of 0.0 V. 2. An analog WRITE operation was performed on the IO1 pin, setting its value to 1.0 V. 3. A PWM WRITE was executed on the IO2 pin, with a frequency of 1950 Hz and a duty cycle set at 75%. 4. A digital READ operation on the IO3 pin returned a value of High. 5. A digital WRITE operation was conducted on the IO4 pin, selecting a Low value. .png) GPIO example for Nova. For all protocols, both READ and WRITE operations log their results in the Transactions Log. # I2C I2C, which stands for *Inter-Integrated Circuit,* is a de-facto standard protocol for inter-chip communication widely used for attaching lower-speed peripheral ICs to processors and MCU in short-distance, intra-board communication. With a similar approach as SPI, Binho Mission Control presents a streamlined yet potent interface to operate the I2C protocol. The Command Panel is divided into three segments: settings, selection of target devices by address, and execution of I2C transactions.  I2C command panel for Supernova and Pulsar. ## Settings [Section titled “Settings”](#settings) .png) Settings segment for Nova. The Settings segment allows users to adjust the following parameters: | Parameter | Nova values | Supernova and Pulsar values | Comment | | -------------------------- | ------------------ | --------------------------- | --------------------------------------------------------------------------------------- | | Clock Frequency | 100 kHz to 3.4 MHz | 100 kHz to 1 MHz | 4 values available if Non-Standard Frequencies switch is off (for Nova). | | Internal Pull-Up Resistors | On/Off | 150 Ω to 10 kΩ | Nova pull-up resistor value is fixed. | | Bus Voltage | 3.3 V | 1.2 V to 3.3 V | In Supernova and Pulsar, users can measure voltage and select an external power source. | Notes: * **Clock Frequency**: The Binho Nova and Binho Supernova facilitate I2C bus clock frequencies ranging from 100 kHz to 3.4 MHz, covering all typical operating modes. Enabling the “Non-Standard Frequencies” option lets users input any desired clock frequency within this range. * **Open Drain Configuration**: I2C’s electronic-level execution employs an open-drain configuration, necessitating at least one pull-up resistor for the SDA and SCL pins. The app allows users to activate the in-built pull-up resistors in the Binho Nova. ## Target Device [Section titled “Target Device”](#target-device) The app simplifies device detection on the I2C bus. Clicking the “Address” textbox prompts the host adapter to scan for connected devices, listing them for easy selection. Alternatively, users can manually input an address (in hexadecimal). .png) Target Device segment for Nova Featured parameters and allowed values: | Parameter | Admited values | Comment | | ---------------- | -------------- | ------------- | | Address | *Hexadecimal* | Byte grouped. | | *Address format* | 7-bit, 8-bit. | | | Subaddress | *Hexadecimal* | Optional. | Notes: * **Address Formats**: Both 7-bit and 8-bit address lengths are accommodated. The former uses its initial bit to discern between read and write operations, while the latter assigns distinct addresses for both procedures. * **Subaddress**: This optional parameter can pinpoint a specific device register or a memory cell. ## Transactions [Section titled “Transactions”](#transactions)  Transactions segment This segment is dedicated to I2C read/write transfers: 1. **Write Buffer**: Users enter the data payload meant for the target device here, in hexadecimal format grouped by byte packets. The WRITE button confirms the transaction. 2. **Read Size**: Specifies the byte amount to be retrieved from the target device. Initiating a read operation is as simple as pressing the READ button. ## Real-world Example [Section titled “Real-world Example”](#real-world-example) The Onsemi CAT24C512 is an I2C EEPROM 512 kb memory that supports Standard, Fast, and Fast-Plus modes. To our knowledge, it lacks pull-up resistors for its SCL and SDA pins, so we activate them via the I2C command panel. We also select a clock frequency of 400 kHz (Fast mode). When we place the cursor within the “Address” input box, the app automatically detects the memory at address 0x50. We write the payload 0xDE.AD.BE.EF to the subaddress 0xAB.CD. Subsequently, altering the subaddress to 0xAB.CB and requesting an 8-byte read yields the result 0xFF.FF.DE.AD.BE.EF.FF.FF – precisely what we anticipated based on the datasheet’s default register values. .png) Write and Read transactions performed with an EEPROM memory. # I3C I3C, or *Improved Inter-Integrated Circuit,* is the successor of the I2C communication protocol, adopting backward compatibility. Additionally, the I3C protocol incorporates several features that allow for more communication flexibility, extends the spectrum of possible applications, increases performance and robustness. Some of these features include Dynamic Address Assignment, Higher Data Rates, CCC commands, Multi-Controller support, Hot Join/Removal events support, In-Band Interruptions (IBIs), etc. The Binho Supernova host adapter proudly supports the I3C protocol. The I3C command panel is organized in five segments: Available Devices, Clock Settings, Bus Voltage, Private Transactions, and Common Command Code transfers.  I3C command panel. ## Available Devices [Section titled “Available Devices”](#available-devices) When the INIT BUS button is pressed, *Binho Supernova* initializes the bus, sets the bus voltage and assigns dynamic addresses to the target devices. In this process, the targets send their BCR, DCR and PID to the Controller, so it can identify them and assign them the dynamic addresses. After this is concluded, all target devices are listed up in the Available Devices table:  Available Devices segment The Available Devices panel also offers other functionalities that allows, for example, resetting the bus, resetting targets (via the Target Reset Pattern specified in the I3C protocol), obtaining the I3C connector status and also refreshing the targets table (managed by our SDK). ## Clock Settings [Section titled “Clock Settings”](#clock-settings) .png) Clock Settings sub-panel. In the Clock Settings segment the user can configure two different clock frequencies: | Parameter | Admited values | Comment | | ---------- | ---------------- | ----------------- | | Push-Pull | 3.75 to 12.5 MHz | 6 possible values | | Open Drain | 0.1 to 4.17 MHz | 7 possible values | Notes: * **Push-Pull Clock**: Standard for regular transactions like Reads and Writes. * **Open Drain Clock**: Employed during the Dynamic Address Assignment phase to circumvent potential short-circuits, particularly when multiple targets access the bus concurrently. ## Bus Voltage [Section titled “Bus Voltage”](#bus-voltage) The *Bus Voltage* section enables users to configure the operational voltage of the bus within a range of 0.8 to 3.3 V. Once the desired voltage is specified, pressing the *SET* button applies the new setting. Additionally, users can measure the bus voltage and choose to use an external power source. Using an external source is equivalent to measuring the voltage and setting it to match the external supply.  Bus Voltage sub-panel ## Private Transactions [Section titled “Private Transactions”](#private-transactions) The Private Transactions segment is dedicated to I2C read/write transfers. 1. **Address and Subaddress**: Positioned at the top, users can input these in hexadecimal format. 2. **Write Buffer and Read Size**: The subsequent row houses fields to specify the payload (in hexadecimal) and the byte count for reading. 3. **Read and Write Buttons**: Positioned on the final row, these buttons execute the aforementioned operations. .png) Private Transactions sub-panel. ## Common Command Code (CCC) Operations [Section titled “Common Command Code (CCC) Operations”](#common-command-code-ccc-operations) The CCC sub-panel is dedicated to the unique I3C CCC commands, indicative of the protocol’s novel offerings. It comprises a dropdown menu, textbox, and a TRANSFER button for seamless command execution. .png) Common Command Code sub-panel The BMC App currently supports the following CCC. | CCC command | Description | | ------------- | --------------------------------------- | | GETBCR | Get the Bus Characteristics Register | | GETDCR | Get the Device Characteristics Register | | GETPID | Get Provisioned ID | | GETMRL | Get Max Read Length | | GETMWL | Get Max Write Length | | DIRECT SETMRL | Set Max Read Length | | DIRECT SETMWL | Set Max Write Length | Notes: * The Write Buffer is relevant only for CCC commands that send data, such as DIRECT SETMRL and DIRECT SETMWL. * As more CCC commands are added with new versions of the app, this table serves as a reference. We recommend users to download the latest version of Binho Mission Control for the most up-to-date features. # SPI SPI, short for *Serial Peripheral Interface*, is a widely-used communication protocol in the realm of electronics. Binho Mission Control optimizes the user’s interaction with the SPI protocol, presenting an intuitive approach to its functionalities. When the SPI communication protocol is selected and activated, the Command Panel gets segmented into three distinct sections, each dedicated to a specific facet of the SPI communication: settings, chip selection, and transaction execution. .png) SPI command panel for Supernova and Pulsar The Bus Voltage section allows the user to initialize and set the bus voltage. Additionally, in the case of Supernova and Pulsar, users can measure the bus voltage and choose to use an external power source. Using an external source is equivalent to measuring the voltage and setting it to match the external supply. ## Settings [Section titled “Settings”](#settings) .png) Operation Settings for Nova The Settings segment allows users to adjust the following parameters: | Parameter | Nova values | Supernova and Pulsar values | Comment | | ------------------- | ------------- | --------------------------- | ------------------------------------------- | | **Clock Freq** | 0.8 to 12 MHz | 10 kHz to 50 MHz | Discrete values. | | **Bit Order** | MSB, LSB. | MSB, LSB. | Most/Least Significant Bit first. | | **Bits / Transfer** | 8, 16. | - | Bits per transfer. | | **Mode** | 0, 1, 2, 3. | 0, 1, 2, 3. | (CPOL, CPHA) ∈ {(0,0); (0,1); (1,0); (1,1)} | CPOL and CPHA refer to the clock’s polarity and phase. In tandem, they designate the precise timing and edge (be it rising or falling) at which data is sampled. ## Chip Selection [Section titled “Chip Selection”](#chip-selection) .png) Chip Select for Nova | Parameter | Admited values | Comment | | ---------- | -------------- | ---------------------------------------- | | Pin Select | CS0, CS1. | CS = Chip Select | | Polarity | Low, High. | Active Low/High polarity for CS. | | Pre-Delay | *Numeric* | Only positive integer numbers. Unit: μs. | | Post-Delay | *Numeric* | Only positive integer numbers. Unit: μs. | Pre/Post Delays pertain to the time gap between the inactive-to-active transition of the CS (Chip Select) signal and the sampling of the initial payload bit. ## Transactions [Section titled “Transactions”](#transactions)  Transactions sub-panel. This segment comprises two text fields and a dedicated TRANSFER button, simplifying SPI transaction processes. 1. **Write Buffer**: Here, users input the data payload designated for the target device. It’s important to note that entries should be in hexadecimal form, grouped in byte packets. For instance, inputs like ‘00’ or ‘FF’ (contingent on the chosen polarity) symbolize a read-only operation. 2. **Read Size**: This field allows users to determine the quantity of bytes they wish to retrieve from the target device. Initiating an SPI transaction is as simple as hitting the TRANSFER button. ## Real-world Examples [Section titled “Real-world Examples”](#real-world-examples) Outlined below are hands-on tests with tangible devices, offering a glimpse into the SPI protocol in action. **Flash Memory Test with W25Q128fV**: Utilizing a Winbond flash memory model W25Q128fV, we explored the Binho Mission Control app’s SPI capabilities. The device’s datasheet elucidates an instruction to fetch the JEDEC designated manufacturer ID, Memory Type, and its Capacity concurrently. This is executed by transmitting the byte ‘0x9F’ to the flash memory input. Winbond’s ID, as per the datasheet, is ‘0xEF’. With a permissible clock frequency of up to 50 MHz and compatibility with SPI modes 0 and 2, our test was conducted at a 12 MHz clock frequency in mode 0. The subsequent results, especially concerning the JEDEC ID, aligned with our expectations. .png) Write operation to a SPI flash memory **Pressure Sensor Test with BMP280**: This example delves deeper, showcasing the capabilities of the SPI protocol using the BMP280 pressure sensor. .png) # UART UART, short for Universal Asynchronous Receiver-Transmitter, is a fundamental serial communication protocol widely used in electronics. The Binho Mission Control app facilitates seamless interaction with the UART protocol, providing users with an intuitive interface for setting up and executing UART communication. ## **Command Panel Overview** [Section titled “Command Panel Overview”](#command-panel-overview) When the UART protocol is selected and activated, the Command Panel is divided into three main sections: **Bus Voltage**, **Settings**, and **Transactions**.  Screenshot of the UART command panel ### **Bus Voltage** [Section titled “Bus Voltage”](#bus-voltage) This section allows users to configure and monitor the UART bus voltage. It includes the following functionalities: * **Set Voltage**: Users can set the bus voltage (from 1.2 V to 3.3 V) by specifying the desired value. * **Measure Voltage**: Measure the current voltage on the bus. * **Use External Voltage**: Select an external voltage source for powering the UART bus.\* ### Settings [Section titled “Settings”](#settings) The Settings section provides options for configuring key UART parameters, allowing users to adjust the communication to match the requirements of their target devices: | Parameter | Admitted Values | Description | | --------- | ----------------------------------------- | --------------------------------------- | | Baudrate | 11 available values (e.g., 115200, 19200) | Communication speed in bits per second. | | Parity | Even, Odd or No Parity | Error-checking mechanism. | | Data Size | 7 bits or 8 bits | Number of bits per word. | | Stop Bits | 1 or 2 | Number of stop bits. | | RTS/CTS | Enabled, Disabled | Hardware flow control option. | **Example**: In the provided screenshots, one configuration uses a baud rate of 115200 bps with even parity while another uses 19200 bps, odd parity, and 8-bit data size (see below). ### Transactions [Section titled “Transactions”](#transactions) The Transactions section is where users define and execute data transfers between the UART interface and the connected device. It includes: * **Write Buffer**: Input field for specifying the data to send (e.g., `1A.2B.3C.4D`). * **Transfer Button**: Executes the data transmission. * **Incoming Data**: When a target sends data to the host adapter, it is received as a notification shown in the BMC App’s transaction log.  Another screenshot of the UART panel ## Real-world Example [Section titled “Real-world Example”](#real-world-example) ### **Echo/Loopback Test** [Section titled “Echo/Loopback Test”](#echoloopback-test) A loopback test involves connecting the RX and TX pins directly. This simple yet effective diagnostic tool ensures that data sent is received back correctly.\ Example: 1. Configure UART with a baud rate of 19200 bps, odd parity, and an 8-bit data size. 2. Input the payload `1A.2B.3C.4D` in the Write Buffer and click **TRANSFER**. 3. The terminal log shows: * Data `1A.2B.3C.4D` sent successfully. * Notification: The same data is received, confirming proper operation.  Terminal view showing some transactions performed in the echo test \*When USE EXTERNAL button is pressed, what happens under the hood is that the host adapter measures the voltage in VTAR and then sets the bus voltage to that value using its internal circuitry. # Download & Installation ## Download and Install the Binho Mission Control Software[](#step-1-download-and-install-the-binho-mission-control-software) [Section titled “Download and Install the Binho Mission Control Software ”](#download-and-install-the-binho-mission-control-software-) Binho Mission Control app is available for Windows, Mac, and Linux. It provides an easy-to-use GUI interface for your *Binho Nova* and *Supernova* Host Adapters. Find and download the Binho Mission Control installer suitable for your OS (Windows, Linux, or Mac) in the following public repository. * For **Mac** users, download either the `Binho-Mission-Control-2-x.y.z-mac.zip` or the `Binho-Mission-Control-2-x.y.z.dmg` file. If you choose the .zip file, unzip it to access the application. If you opt for the .dmg file, mount it and drag the application to your Applications folder. * **Linux** users should download the `Binho-Mission-Control-2-x.y.z.AppImage` file. Once downloaded, make it executable (using a tool like `chmod`) and then run it. * For **Windows** users, download the `Binho-Mission-Control-2-Setup-x.y.z.exe` file and run the installer. Please note that `.blockmap` files and `.yml` files are not required for the installation process. They are used for update checks and differential updates. If you’re interested in the source code, it’s available in both zip and tar.gz formats. ### Windows Installer Notes [Section titled “Windows Installer Notes”](#windows-installer-notes) The Windows Defender SmartScreen prompt is displayed when running the installer. Click “*More Info*” and then the “*Run Anyway*” button to continue. Our software releases are code-signed, however we’re still building our reputation within Microsoft SmartScreen so that eventually this warning will go away. ### Mac Installer Notes [Section titled “Mac Installer Notes”](#mac-installer-notes) If this is your first time connecting to a virtual COM port on your Mac, ensure that your user account has the necessary permissions. Here is a list of potential Issues with USB Serial or HID drivers: * **Driver Conflicts:** Sometimes, multiple drivers can try to control the same piece of hardware, leading to conflicts. Ensure that you don’t have conflicting drivers installed. * **System Integrity Protection (SIP):** On newer versions of macOS, SIP can prevent certain drivers from loading. If you encounter issues, consider checking if the driver is compatible with SIP or if there’s a need to temporarily disable SIP (though this is generally not recommended for security reasons). * **Access Permissions:** Ensure that any required drivers or applications have the necessary permissions to access USB devices. You can check this in System Preferences > Security & Privacy > Privacy tab. * **Cable Issues:** Sometimes, the problem might be as simple as a faulty USB cable. Always try a different cable to rule out this possibility. * **Update Drivers:** Ensure that you have the latest drivers installed for your device. Outdated drivers can sometimes cause compatibility issues, especially after a macOS update. ### Linux Installer Notes [Section titled “Linux Installer Notes”](#linux-installer-notes) **Problem:** When trying to connect to the Binho host adapter using Binho Mission Control on Linux, you might encounter an error related to USB access permissions. This is because, by default, certain USB devices may not have the appropriate permissions set for user-level access. **Detection:** Binho Mission Control should automatically detect this issue and provide you with instructions to resolve it. **Solution:** To grant the necessary permissions, follow the steps below: 1. Open a terminal. 2. Create a new user group named ‘binho’ and add your user to this group: ```bash groupadd binho usermod -a -G binho $USER ``` 3. Add a new udev rule to set the correct permissions for Binho devices: ```bash echo 'SUBSYSTEM=="usb", MODE="0666", GROUP="binho"' | sudo tee /etc/udev/rules.d/99-binho.rules ``` 4. Reload the udev rules. If this doesn’t work, you might need to reboot your system: ```bash sudo udevadm control --reload sudo udevadm trigger ``` 5. Once done, you should see a confirmation message: ```bash echo "USB device configuration has been installed. Please log out and log back in or reboot." ``` After following these steps, Binho Mission Control should be able to access the Binho host adapter without any permission issues. ## Launch the Mission Control Software & Connect to the Device[](#step-2-launch-the-mission-control-software-and-connect-to-the-device) [Section titled “Launch the Mission Control Software & Connect to the Device ”](#launch-the-mission-control-software--connect-to-the-device-) Now it’s time to launch the software. If you haven’t done so already, plug your host adapter to your computer using the provided USB Cable. Launch the BMC App just by double-clicking the app icon. At this point, you’re all set to start interacting with your device. # Interactive Tour Throughout this tour, you can expand or shrink the panels, connect to a device, and get a glimpse of the settings menu. Subsequent sections will delve deeper into the Navigation Menu, Command Panel, and the Transaction Log View. # App Layout Upon launching Binho Mission Control, the initial screen showcases several features designed for ease of use and convenience. * **Navigation Menu (Left Panel):** Positioned vertically on the left, this menu can be expanded or minimized with a click of the + or − button. At its top, you’ll notice two prominent buttons: the On/Off button and the Settings button. * **Command Panel (Center Panel):** By pressing the On/Off button, devices connected to the computer via USB are displayed here. For our demonstration, four devices are listed: a Binho Nova Host Adapter, a Binho Supernova Host Adapter, and two built-in simulators that emulate these host adapters. Users have the option to disable these simulators through the settings menu. * **Device Info Panel (Right Panel):** When a device, such as the Binho Nova Host Adapter, is connected, this panel provides detailed information. Displayed metrics include the device ID, the connected port, product name, vendor and product IDs, as well as firmware and hardware versions. [Interactive demo](https://app.arcade.software/share/wo705dgvL57O8MO4p0s9) # Command Panel By navigating this interactive tour, gain a hands-on understanding of the dynamic capabilities and user-friendly design of the Command Panel. *** Centrally positioned between the Navigation Menu and the Transaction Log View, the Command Panel serves as the primary input panel. Here, users can interface directly with devices connected via the chosen host adapter. The options displayed within the Command Panel dynamically adapt based on the selected protocol. To provide a tangible example, the interactive tour below showcases configurations and transactions with an accelerometer sensor, interfaced through a Binho Supernova Host Adapter. [Interactive demo](https://app.arcade.software/share/7hhZNoAk9gp6eF2Pj2yn) Walk through the following steps in the example: 1. Initialize the bus by clicking the “INIT BUS” button. 2. Select the accelerometer sensor, identified by the address 0x08. 3. Opt for a push-pull clock frequency set at 12.5 MHz, the maximum frequency supported by the I3C protocol. 4. Adjust the bus voltage to 3.3 V. 5. Proceed to read a sequence of 10 bytes. 6. Conclude by executing two CCC command requests: GETBCR and GETMWL. # Protocol Activation Dive into the interactive tour below to explore and experience switching protocols as if using a Binho Nova Host Adapter. *** Situated vertically on the left side of the user interface, the Navigation Menu enables users to seamlessly switch between the different protocols supported by the currently connected host adapter. [Interactive demo](https://app.arcade.software/share/ZGVjeeWU1oNVZRNxEnwH) While navigating, you may observe that when the SPI protocol is activated followed by the activation of I2C, a warning message ‘Pin conflict: shutting SPI down’ appears. This is due to the Nova host adapter’s design, which features a versatile port accommodating all protocols. Some pins can overlap between protocols. To prevent any pin conflicts, the app proactively shuts down any conflicting protocol. However, such an issue is absent in the Supernova host adapter. This is because the Supernova boasts four distinct ports: 1 QWIIC I2C, 1 I2C/UART/SPI/GPIO, 1 LV I3C, and 1 HV I3C, eliminating any potential for pin overlap and conflicts. # Transaction Log View Building on the I3C example from the [Command Panel](/getting-started/binho-mission-control/interactive-tour/command-panel/), the interactive tour sheds light on several invaluable features of the Transaction Log View. *** Positioned on the right-hand side of the BMC layout, the Transaction Log View serves as a dynamic transaction logger, capturing every transaction between your PC and connected devices via the Host Adapter. Transaction Log View features: 1. **Log Management:** Easily save the transaction log data to a file, clear its contents, and restore it as needed. 2. **Data Formatting:** Toggle between different display formats for your logs. 3. **Clipboard Utility:** Conveniently copy the log content directly to your clipboard for effortless pasting elsewhere. 4. **View Customization:** Choose how you’d like your data organized, with options to present it in either a console or table format. [Interactive demo](https://app.arcade.software/share/gZgPWslWb6LOTgbLM2PK) # Settings Access the Settings segment by selecting the “Settings” button located at the bottom of the Navigation Menu. Within this section, users can: * Toggle preferences such as Dark Mode. * Toggle the simulators. * View the log path, where the log file is saved. * Decide if the Privacy Policy Dialog and the Launch Onboarding Tour should appear upon the next launch of the BMC App.  Settings section # Simulators The Binho Nova Simulator and Binho Supernova Simulator are integral features of the Binho Mission Control desktop application. These simulators accurately reflect their real-world counterparts, the Binho Nova and Binho Supernova host adapters. They provide a user-friendly environment for users to familiarize themselves with the Binho Mission Control App. The Binho Nova Simulator mimics the behavior of the Binho Nova host adapter, simulating protocols such as GPIO, SPI, I2C, and 1-Wire. In the same vein, the Binho Supernova Simulator emulates the Binho Supernova host adapter, facilitating interactions with GPIO, I2C, I3C, and UART protocols. Both simulators are designed to act as introductory tools, allowing engineers and developers to acquaint themselves with the Binho Mission Control interface before working with the actual host adapters. Both simulators come enabled by default and, when active, appear in the Available Devices list. If a simulator is connected, its device information will be displayed on the right side of the screen, as illustrated in the following image.  Simulators in the Available Devices list ### Toggling Simulators On/Off [Section titled “Toggling Simulators On/Off ”](#toggling-simulators-onoff-) You can enable or disable the simulators via the Settings panel.  # Updating Binho Mission Control Software Keeping your Binho Mission Control software updated ensures you’re utilizing the most recent features, optimizations, and security enhancements. Here’s how to make sure your software is always current: ## **Auto-Update** [Section titled “Auto-Update”](#auto-update) 1. **Automatic Detection**: When a new version of the Binho Mission Control software is available, the app’s built-in auto-updater will notify you. 2. **Installation**: Once notified, you can choose to immediately update. The software will handle the download and installation for you.  3. **Relaunch & Review Release Notes**: After the update is complete and you’ve relaunched the app, the release notes for the new version will be displayed. This helps you quickly understand the improvements and changes.  ## **Manual Update** [Section titled “Manual Update”](#manual-update) If for any reason you’d like to install a specific version, follow these steps: 1. **Visit the Releases Page**: Head over to the Binho Mission Control releases page on GitHub: [Binho Releases](https://github.com/binhollc/MissionControl2-releases/releases). 2. **Choose Your Version**: Browse through the available versions and select the one you want. 3. **Download & Install**: Click on the desired version to download the installation file. Once downloaded, follow the on-screen instructions to install. ## **Accessing Release Notes Later** [Section titled “Accessing Release Notes Later”](#accessing-release-notes-later) Should you want to revisit the release notes at any time, you can find them in the app under the Settings menu.  # C++ SDK ## Introduction [Section titled “Introduction”](#introduction) Binho Mission Control C++ SDK (or BMC C++ SDK for short) is a dynamic library designed to streamline interactions with Binho Nova and Supernova host adapters. It can be easily integrated into any C++ development ecosystem. > *The BMC C++ SDK was developed in response to requests from early adopters for a C++ dynamic library, allowing them to integrate our USB host adapters into their C/C++ development environments. Unlike the Python SDK, the C++ SDK is built on a machine code version of the Python SDK, offering similar functionality but tailored for environments where native C/C++ integration is required. This allows developers to leverage the same powerful features of our Python SDK while working within a C++ framework.* *** The next subsection explains the installation and setup steps. [installation.md](/getting-started/c-sdk/installation/) The second subsection demonstrates the use of the BMC SDK library through some included examples. [example-applications.md](/getting-started/c-sdk/example-applications/) Finally, the last section provides a general overview of how to use the library. [using-the-library.md](/getting-started/c-sdk/using-the-library/) # Building a Project Using the SDK ## Overview [Section titled “Overview”](#overview) The provided example applications can serve as a guide for creating a new project using the BMC C++ SDK. The examples are located in the `examples` directory, and the instructions to build and execute them are similar to those related with [building the C++ SDK Library](/getting-started/c-sdk/building-the-c-sdk-library/). ### Step by Step Guide [Section titled “Step by Step Guide”](#step-by-step-guide) Here is a step-by-step guide on how to build a project that uses the library: 1. Navigate to the directory containing the project that uses the BMC C++ SDK. 2. Ensure that the development environment is properly set up. To do this, follow the instructions in the [Environment Setup](/getting-started/c-sdk/environment-setup/) section of our guide. 3. Create a `CMakeLists.txt` file in the root directory of the project. An example of this file can be found [below](#cmake-example-for-building-applications). 4. Create a `build` directory inside the project. 5. Navigate to the `build` directory. 6. Configure CMake: * Linux/macOS ``` cmake -DLIBRARY_PATH=[Path to the dir containing the library] -DINCLUDE_PATH=[Path to the dir containing the include files] .. ``` * Windows 64 ``` cmake -DLIBRARY_PATH=[Path to the dir containing the library] -DINCLUDE_PATH=[Path to the dir containing the include files] .. -G "Visual Studio 17 2022" -A x64 ``` * Windows 32 ``` cmake -DLIBRARY_PATH=[Path to the dir containing the library] -DINCLUDE_PATH=[Path to the dir containing the include files] .. -G "Visual Studio 17 2022" -A win32 ``` 7. Build with CMake: ``` cmake --build . --config Release ``` 8. On Windows, verify that within the `build` directory, there is a `Release` (or `Debug` ) directory containing the project’s executable. On Linux/macOS, look for the executable in the `build` directory. ### CMake Example for Building Applications [Section titled “CMake Example for Building Applications”](#cmake-example-for-building-applications) Below is an example of a `CMakeLists.txt` file for building a sample application (`i3c_cccs`) that uses the BMC C++ SDK as a dynamic library: ```cmake cmake_minimum_required(VERSION 3.5) project(MyProject) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED True) # Accept library path as an argument set(LIBRARY_PATH "" CACHE PATH "Path to the static library") # Accept include path as an argument set(INCLUDE_PATH "" CACHE PATH "Path to the include directory") if(NOT LIBRARY_PATH) message(FATAL_ERROR "LIBRARY_PATH is empty") endif() if(NOT INCLUDE_PATH) message(FATAL_ERROR "INCLUDE_PATH is empty") endif() include(FetchContent) FetchContent_Declare(json URL https://github.com/nlohmann/json/releases/download/v3.11.2/json.tar.xz) FetchContent_MakeAvailable(json) # --- # Target Definition, Properties and Commands # --- add_executable(my_project main.cpp ) set_target_properties(my_project PROPERTIES OUTPUT_NAME my_app) # Include needed headers target_include_directories(my_project PRIVATE ${INCLUDE_PATH} ) # Link against needed libraries if(WIN32) target_link_libraries(my_project nlohmann_json::nlohmann_json ${LIBRARY_PATH}/bmc_sdk.lib ) # To link against the static library on Windows, use the following line instead: # target_link_libraries(my_project ${LIBRARY_PATH}/bmc_sdk_static.lib) elseif(APPLE) target_link_libraries(my_project nlohmann_json::nlohmann_json ${LIBRARY_PATH}/libbmc_sdk.dylib ) # To link against the static library on macOS, use the following line instead: # target_link_libraries(my_project ${LIBRARY_PATH}/libbmc_sdk_static.a) else() target_link_libraries(my_project nlohmann_json::nlohmann_json ${LIBRARY_PATH}/libbmc_sdk.so ) # To link against the static library on Linux, use the following line instead: # target_link_libraries(my_project ${LIBRARY_PATH}/libbmc_sdk_static.a) endif() ``` # Building the C++ SDK Library For ease of use, we recommend using the provided build scripts to compile the C++ SDK library and stage the output files. Depending on your platform, use either the `build_and_stage.sh` script for macOS/Linux or `build_and_stage.bat` for Windows. These scripts automate the process of setting up, building, and staging the SDK along with its examples. However, if you’d prefer to build the SDK manually, jump to the [Manual Build Instructions](#manual-build-instructions) below. ### Automated Build with Script [Section titled “Automated Build with Script”](#automated-build-with-script) * **For macOS/Linux**: Run the `build_and_stage.sh` script: ```bash ./build_and_stage.sh ``` * **For Windows**: Run the `build_and_stage.bat` script: ```cmd build_and_stage.bat ``` These scripts will handle the build process, including cleaning up previous builds, creating the necessary directories, running CMake, and building both the library and example applications. After running the script, your build output will be placed in the `staging` directory, as shown below: **macOS Staging Directory Example:** ```plaintext staging/ ├── docs/ ├── examples/ │ ├── i3c_cccs/ │ ├── i3c_ibis/ │ ├── i3c_ICM42605/ │ ├── list_devices/ │ ├── mock_notifications/ │ ├── nova_breathing_leds/ │ ├── sample_app_using_sample_library/ │ ├── sample_library/ │ ├── supernova_101/ │ ├── supernova_i2c/ │ ├── supernova_i2c_benchmark/ │ └── supernova_spi/ ├── include/ │ ├── bridge_reader.h │ ├── BridgeReader_windows.h │ ├── CommandDispatcher.h │ ├── CommandManager.h │ ├── CommandRequest.h │ ├── CommandResponse.h │ └── definitions.h └── lib/ ├── libbmc_sdk_static.a ├── libbmc_sdk.1.1.0.dylib ├── libbmc_sdk.1.dylib ├── libbmc_sdk.dylib ``` *** ### Manual Build Instructions [Section titled “Manual Build Instructions”](#manual-build-instructions) #### Prerequisites: [Section titled “Prerequisites:”](#prerequisites) * **CMake**: Ensure CMake is installed on your system. * On macOS: `brew install cmake` * On Linux: Use your package manager (`apt-get`, `yum`, etc.) to install CMake, e.g., `sudo apt-get install cmake`. * On Windows: Download and install CMake from [here](https://cmake.org/download/). * **Bridge Executable**: Ensure the `bmcbridge` executable is installed and accessible in your system’s `PATH`. If it’s not available, follow the [installation guide for BMC Bridge](/getting-started/c-sdk/installation/) in the documentation. * **Visual Studio** (Windows only): You must have **Visual Studio 2022** or a similar version installed with C++ development tools. #### macOS & Linux Instructions: [Section titled “macOS & Linux Instructions:”](#macos--linux-instructions) 1. **Clone the Repository**\ Start by cloning the SDK repository from GitHub: ```bash git clone https://github.com/binhollc/MissionControlTowerSDK.git cd MissionControlTowerSDK ``` 2. **Clean Previous Builds (if any)**\ If you have previously built the SDK, it’s recommended to clean up old build files before starting a new build. * If the `build` directory exists, remove it: ```bash rm -rf build ``` * If the `staging` directory exists, remove it: ```bash rm -rf staging ``` 3. **Create Staging and Build Directories** * Create the `staging` directory to store the built library: ```bash mkdir staging ``` * Create a new `build` directory where the compilation process will occur: ```bash mkdir build cd build ``` 4. **Run CMake to Configure the Build**\ Use CMake to generate the necessary build files. Specify the build type as `Release`: ```bash cmake -DCMAKE_BUILD_TYPE=Release .. ``` 5. **Build the C++ SDK Library**\ After configuring, initiate the build process: ```bash cmake --build . --config Release --target install ``` 6. **Return to the Project Directory**\ After the build is complete, navigate back to the root directory: ```bash cd .. ``` #### Windows Instructions: [Section titled “Windows Instructions:”](#windows-instructions) 1. **Clone the Repository**\ Open the Command Prompt and clone the SDK repository: ```cmd git clone https://github.com/binhollc/MissionControlTowerSDK.git cd MissionControlTowerSDK ``` 2. **Set Up Staging and Clean Previous Builds (if any)**\ If a previous build exists, clean it: * Remove the `staging` directory if it exists: ```cmd rmdir /S /Q staging mkdir staging ``` * Remove the `build` directory if it exists: ```cmd rmdir /S /Q build mkdir build ``` 3. **Change to the Build Directory**\ Navigate into the newly created `build` directory: ```cmd cd build ``` 4. **Run CMake to Configure the Build**\ Configure the build using CMake with Visual Studio as the generator. Set the platform (`win32` or `x64`), defaulting to `win32` if none is provided: * For `win32` builds: ```cmd cmake -DCMAKE_BUILD_TYPE=Release .. -G "Visual Studio 17 2022" -A win32 ``` * For `x64` builds: ```cmd cmake -DCMAKE_BUILD_TYPE=Release .. -G "Visual Studio 17 2022" -A x64 ``` 5. **Build the C++ SDK Library**\ Once configured, compile the SDK library: ```cmd cmake --build . --config Release --target install ``` 6. **Return to the Project Directory**\ After building, return to the project root directory: ```cmd cd .. ``` #### Output: [Section titled “Output:”](#output) After following these steps, the compiled SDK library and example applications will be stored in the `staging` directory on all platforms. You can now link this library to your projects or distribute it as needed. # Environment Setup ## Overview [Section titled “Overview”](#overview) To develop a C++ application using the BMC C++ SDK, ensure that both the BMC bridge executable and the SDK library are reachable in the system’s PATH (the latter is only necessary for Windows users). Additionally, the library uses the `nlohmann_json` library, which is a requirement for formatting the parameters of the command requests. Follow these steps to set up the environment: 1. Add the directory containing the BMC bridge executable and the directory containing the library to the PATH environment variable before running the application. Alternatively, prepend the PATH variable to the command execution: **On macOS:** ```shell DYLD_LIBRARY_PATH=/path/to/dynamic_library PATH=$PATH:/path/to/bmcbridge ./your_app ``` **On Linux:** ```shell LD_LIBRARY_PATH=/path/to/dynamic_library PATH=$PATH:/path/to/bmcbridge ./your_app ``` **On Windows (using Command Prompt):** ```shell set PATH=%PATH%;\path\to\installation_dir\bmcbridge;\path\to\installation_dir your_app.exe ``` **Or on Windows (using PowerShell):** ```shell $env:PATH += ";\path\to\installation_dir\bmcbridge\;\path\to\installation_dir" .\your_app.exe ``` Replace `/path/to/installation_dir` with the actual path to the `installation_dir` directory. Ensure to use the correct slashes for your operating system (`/` for Mac/Linux, `\` for Windows). # Example Applications A set of example applications is provided to demonstrate the usage of the Binho Mission Control SDK. Below are the general steps to build and run each example application, along with a brief description of each application’s functionality. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * A development environment compatible with C++17. * The Binho Mission Control SDK installed on the system. ## Example Applications [Section titled “Example Applications”](#example-applications) ### **Nova Host Adapter** [Section titled “Nova Host Adapter”](#nova-host-adapter) * **nova\_breathing\_leds**: Simulates a breathing LED effect, showcasing PWM control with a BinhoNova host adapter. ### **Supernova Host Adapter** [Section titled “Supernova Host Adapter”](#supernova-host-adapter) * **list\_devices**: Lists connected USB devices, displaying details such as the product name, type, port, and manufacturer. This example highlights the capability to query and process information about connected devices using the CommandDispatcher framework. * **supernova\_101**: Demonstrates fetching USB strings like `MANUFACTURER`, `PRODUCT_NAME`, etc., from a BinhoSupernova host adapter. * **supernova\_i2c**: Showcases I2C operations using the BinhoSupernova host adapter. * **supernova\_i2c\_benchmark**: Performs benchmarking of I2C communication with the BinhoSupernova host adapter. It measures and displays the average round-trip time for a series of I2C write operations, offering insight into the performance and efficiency of I2C communications. * **i3c\_cccs:** Demonstrates how to use a variety of CCC with the Supernova, assuming there’s an I3C target device connected to the I3C bus. * **i3c\_ibis:** Demonstrates how to capture and handle In-Band Interrupts (IBIs). * **i3c\_ICM42605:** Showcases a typical interaction with an I3C target device. In this case, it’s an ICM42605, but the template hopefully can be extrapolated to any device. * **sample\_library**: A custom library that provides a simplified interface for interacting with Binho devices. It includes functions for retrieving device information such as firmware and hardware versions, and serial numbers. * **sample\_app\_using\_sample\_library**: An application that demonstrates how to use the `sample_library` to interact with Binho devices. It shows how to integrate the custom library into a larger application, retrieve device information, and handle different types of exceptions. ## Building the Example Applications [Section titled “Building the Example Applications”](#building-the-example-applications) 1. **Open the Project**: Navigate to the directory of the desired sample application (e.g., `supernova_101/`). 2. **Prepare for Build**: Set up the build environment. This might involve generating project files or configuring your build system. Ensure the Binho Mission Control SDK is properly referenced, including the library and header files. 3. **Build the Application**: Compile the application using the build system or IDE. It may be necessary to specify build configurations such as the target platform or build type. 4. **Run the Example Application**: After building, execute the example application to test and explore its functionality. Ensure any required runtime dependencies or environment variables are set up correctly. # Installation ## Overview [Section titled “Overview”](#overview) The BMC C++ SDK Windows installer sets up the necessary components for the SDK on the system. This includes: * A dynamic library: * `bmc_sdk.dll` on Windows * `libbmc_sdk.dylib` on macOS * `libbmc_sdk.so` on Linux * A static library: * `bmc_sdk_static.lib` on Windows * `libbmc_sdk_static.a` on macOS * `libbmc_sdk_static.a` on Linux * Example applications to test the SDK * Header files for integration (`include` directory) ## Prerequisite [Section titled “Prerequisite”](#prerequisite) As a prerequisite, the C++ SDK requires having the BinhoMissionControl Bridge (bmcbridge) utility installed and added to the PATH environment variable. > *To improve modularization and streamline our update process, we’ve decided to separate the BinhoMissionControl Bridge from the BMC C++ SDK. The BMC Bridge, which connects high-level interfaces like Binho Mission Control to our host adapters, is updated frequently. By decoupling it from the BMC C++ SDK, we can deliver more focused updates to each component. Additionally, as we continue to meet the growing demand for a native C/C++ SDK, we’re also planning to open-source the BMC C++ SDK to further empower the developer community.* ### Windows [Section titled “Windows”](#windows) 1. Download BMC Bridge installers:\ \ \- [BMC Bridge for Windows 32-bit](https://cdn.binho.io/sw/MissionControlBridge/1.1.1/BinhoMissionControlBridge-1.1.1-win32.exe)\ \- [BMC Bridge for Windows 64-bit](https://cdn.binho.io/sw/MissionControlBridge/1.1.1/BinhoMissionControlBridge-1.1.1-x64.exe) 2. Once installed, proceed with the following setup instructions: * The bridge is typically installed in `C:\Program Files (x86)\BinhoMissionControlBridge` * Add this path to your system’s PATH environment variable. * Press `Win + R` , type `sysdm.cpl` , and press Enter. * Go to the Advanced tab, and click on Environment Variables. * In the System variables section, find the PATH variable, select it, and click Edit. * Click New and add `C:\Program Files (x86)\BinhoMissionControlBridge` * To verify the installation, open Command Prompt and execute: * `bmcbridge --version` ### Linux and macOS [Section titled “Linux and macOS”](#linux-and-macos) 1. Download Linux or macOS binaries:\ \- [Bridge macOS binaries for ARM](https://cdn.binho.io/sw/MissionControlBridge/1.1.1/bmc_bridge-1.1.1-mac-arm-binaries.zip)\ \- [Bridge macOS binaries for Intel](https://cdn.binho.io/sw/MissionControlBridge/1.1.1/bmc_bridge-1.1.1-mac-intel-binaries.zip)\ \- [Bridge Linux binaries](https://cdn.binho.io/sw/MissionControlBridge/1.1.1/bmc_bridge-1.1.1-linux-binaries.zip) 2. Extract the binaries and place the extracted folder in a location of your choice. 3. Open a Terminal window and navigate to the directory where you extracted the binaries. 4. To make the binaries easily accessible, add the directory to your PATH environment variable. You can do this by editing your `~/.zshrc` (for Zsh users) or `~/.bashrc` (for Linux or macOS bash users):\ \ `nano ~/.zshrc`\ \ or, if you use Bash:\ \ `~/.bashrc` 5. Add the following line at the end of the file:\ \ `export PATH=/path/to/your/extracted/folder:$PATH`\ \ Replace `/path/to/your/extracted/folder` with the actual path to the extracted folder. 6. Save the file and apply the changes by running:\ \ `source ~/.zshrc`\ \ or, for Bash users:\ \ `source ~/.bashrc` 7. To verify the installation, run the following command in Terminal:\ \ `bmcbridge --version` ## Installation of the C++ SDK [Section titled “Installation of the C++ SDK”](#installation-of-the-c-sdk) ### Windows [Section titled “Windows”](#windows-1) #### Setup instructions [Section titled “Setup instructions”](#setup-instructions) * Add `C:\Program Files (x86)\BinhoMissionControlSDK` to your system’s PATH environment variable. 1. **Download the Installer:**\ \ \- [BMC C++ SDK for Windows 32-bit](https://cdn.binho.io/sw/MissionControlTowerSDK/latest/bmc_cpp_sdk-win32.exe)\ \- [BMC C++ SDK for Windows 64-bit](https://cdn.binho.io/sw/MissionControlTowerSDK/latest/bmc_cpp_sdk-x64.exe) 2. **Run the Installer:** Double-click on the installer and follow the on-screen prompts. 3. **Installation Directories:** By default, the SDK will be installed into the `c:\Program Files (x86)\BinhoMissionControlSDK` directory. Inside this directory, you will find: * `bmc_sdk.dll`: The SDK dynamic link library. * `bmc_sdk_static.lib`: The SDK static library. * `README.md`: Read-me file in markdown format for users. * `examples`: A directory containing example applications. * `include`: A directory containing various header files necessary for SDK integration. 4. **Add to PATH Environment Variable.** For the applications to function correctly:\ Both the `bmcbridge` and the BMC C++ SDK installation directories must be added to the system’s PATH environment variable. 5. **Integration:** To integrate the BMC C++ SDK into a project: * Reference the SDK library using the static or dynamic library files. * Include necessary headers from the `include` directory. 6. **Test the Example Applications:** After setting up the PATH, you can run the example applications in the examples directory. ### Linux and macOS [Section titled “Linux and macOS”](#linux-and-macos-1) * Download Linux or macOS binaries:\ \ \- [BMC C++ Linux binaries](https://cdn.binho.io/sw/MissionControlTowerSDK/latest/bmc_cpp_sdk-linux-binaries.zip)\ \- [BMC C++ macOS binaries for ARM](https://cdn.binho.io/sw/MissionControlTowerSDK/latest/bmc_cpp_sdk-mac-arm-binaries.zip)\ \- [BMC C++ macOS binaries for Intel](https://cdn.binho.io/sw/MissionControlTowerSDK/latest/bmc_cpp_sdk-mac-intel-binaries.zip) * Extract the binaries and place the extracted folder in a location of your choice. * To verify the installation, run the example applications in the examples directory. ### Installation Directory Structure [Section titled “Installation Directory Structure”](#installation-directory-structure) ```plaintext └── BinhoMissionControlSDK ├── bmc_sdk.dll (or lib/libbmc_sdk.dylib on macOS, lib/libbmc_sdk.so on Linux) ├── bmc_sdk_static.lib (or lib/libbmc_sdk_static.a on macOS and Linux) ├── README.md ├── examples │ ├── list_devices │ ├── nova_breathing_leds │ ├── sample_app_using_sample_library │ ├── sample_library │ ├── supernova_101 │ ├── supernova_i2c │ ├── supernova_i2c_benchmark │ ├── i3c_cccs │ ├── i3c_ibis │ ├── i3c_ICM42605 │ ├── ... └── include ├── bridge_reader.h ├── BridgeReader_windows.h ├── CommandDispatcher.h ├── CommandManager.h ├── CommandRequest.h ├── CommandResponse.h └── definitions.h ``` # Using the Library ## General Overview [Section titled “General Overview”](#general-overview) Using the Binho Mission Control C++ SDK library typically involves a series of steps to communicate with a target connected to the host adapter, execute commands and handle responses. Command requests and responses follow the Bridge API v1, which can be found at [Bridge 1.1 API Documentation](/user-guide/protocols-and-interfaces/bridge-11-api/). Bellow is a high-level overview based on the provided example applications: ### 1. **Include Necessary Headers** [Section titled “1. Include Necessary Headers”](#1-include-necessary-headers) Include the necessary headers to access library’s functionality: ```plaintext #include "CommandDispatcher.h" #include ``` ### 2. **Define Response Handler** [Section titled “2. Define Response Handler”](#2-define-response-handler) Define a function to handle responses from the commands sent to the target adapter. This function is responsible for displaying relevant information about the command’s execution. ```plaintext void printCommandResponse(const CommandResponse& cr, const std::string& action); ``` ### 3. **Initialize the Dispatcher** [Section titled “3. Initialize the Dispatcher”](#3-initialize-the-dispatcher) Create an instance of `CommandDispatcher` and specify the name of the target host adapter: ```plaintext CommandDispatcher dispatcher("BinhoNova"); // For connecting with the Binho Nova host adapter CommandDispatcher dispatcher("BinhoSupernova"); // For connecting with the Binho Supernova host adapter ``` **Note**: The argument passed to the `CommandDispatcher` initializer is the name of the target host adapter. ### 4. **Start the Dispatcher** [Section titled “4. Start the Dispatcher”](#4-start-the-dispatcher) Before sending any commands, start the dispatcher: ```plaintext dispatcher.start(); ``` ### 5. **Invoke Commands** [Section titled “5. Invoke Commands”](#5-invoke-commands) With the dispatcher running, invoke commands as needed: * Synchronous Commands (waits for the command to finish before moving on): ```plaintext dispatcher.invokeCommandSync("transaction_id", "command_name", command_params, response_handler); ``` * Asynchronous Commands (doesn’t wait for the command to finish): ```plaintext dispatcher.invokeCommand("transaction_id", "command_name", command_params); ``` ### 6. **Wait for All Commands to Finish (Recommended)** [Section titled “6. Wait for All Commands to Finish (Recommended)”](#6-wait-for-all-commands-to-finish-recommended) To ensure all issued commands are finished before proceeding: ```plaintext dispatcher.waitForAllCommands(); ``` ### 7. **Stop the Dispatcher** [Section titled “7. Stop the Dispatcher”](#7-stop-the-dispatcher) Once all tasks are completed, stop the dispatcher: ```plaintext dispatcher.stop(); ``` # Hardware Setup **Great News!** Setting up your Binho Nova or Binho Supernova is straightforward. While the Binho Nova utilizes the USB Communications Device Class (CDC) for compatibility, the Binho Supernova uses the Human Interface Device (HID) class. Fortunately, most modern operating systems come with the necessary device drivers pre-installed for both devices. This means there’s typically no additional driver to download and install. However, there are a few things to note: * Windows 7 does not have the standard USB CDC driver that the Binho Nova requires. If you’re using this OS, please refer to the troubleshooting article linked below. * If this is your first time connecting a hardware device from your account on your Mac, you’ll need to grant permission to your user account. * Ubuntu or other Linux distribution users might encounter issues with the device. If this happens, please follow the procedure in the provided troubleshooting article. #### Connection to the Computer[](#connection-to-the-computer) [Section titled “Connection to the Computer ”](#connection-to-the-computer-) Use the provided USB Type-C (male) to USB Type-A (male) cable to connect your Binho device to your host PC. Whether it’s the Binho Nova or the Binho Supernova, it can be plugged into any available USB port. There’s no specific requirement to use a USB 3.0 port. #### Indicators for Binho Supernova [Section titled “Indicators for Binho Supernova”](#indicators-for-binho-supernova) The Binho Supernova comes with enhanced indicators to keep you informed about its status: * **MCU Operation Indicators**: * **RGB Neopixels**: * **Normal Operation**: Cycles between green and blue in a sinusoidal pattern when the device is in a resting state. * **Command Reception**: Pauses for 30 seconds upon receiving a command. * **USB Communication**: * **Fourth Neopixel**: Illuminates when the Supernova receives a message via USB. * **Fifth Neopixel**: Lights up upon sending a response back to the USB host. #### Indicators for Binho Nova [Section titled “Indicators for Binho Nova”](#indicators-for-binho-nova) For the Binho Nova, upon powering up, the Status LED will shine yellow, indicating it’s waiting for the COM port to be opened. When connected correctly, the device should immediately enumerate and become available as a new COM port. Once a connection has been established between the device and the host computer, the Status LED will turn blue. ### Testing Your Device with Binho Mission Control [Section titled “Testing Your Device with Binho Mission Control”](#testing-your-device-with-binho-mission-control) To ensure your device is functioning correctly, we highly recommend using the **Binho Mission Control (BMC) App**. This multi-platform desktop application is meticulously designed to optimize and simplify device orchestration. Once your Binho device is connected, launch the BMC App. It should automatically detect your device and, if there’s any issue, provide guidance on how to resolve it. This includes common challenges like the Linux permission issue. By using the BMC App, you can be confident that your device is set up correctly and ready for use. Remember, while both devices share some similarities, they also have unique features. Ensure you’re referring to the correct documentation and SDK for your specific device, whether it’s the Nova SDK for the Binho Nova or the Supernova SDK for the Binho Supernova. # Binho Nova ## Connection to the Test Circuit[](#connection-to-the-test-circuit) [Section titled “Connection to the Test Circuit ”](#connection-to-the-test-circuit-) The *Binho Nova Multi-Protocol USB Host Adapter* features an integrated wire harness terminated with a 1.27mm pitch 2x5 IDC Connector. This harness contains the 5 signal pins, 1 x 3V3 power signal, 1 x VUSB power signal, and 3 x GND signals. The figure below shows the connector pinout and channel functions:  Now you’re ready to begin interacting with the device. See the following QuickStart Guides in this section to learn how to interact with the device via your preferred interface. # Binho Supernova ## Connection to the Test Circuit[](#connection-to-the-test-circuit) [Section titled “Connection to the Test Circuit ”](#connection-to-the-test-circuit-) The *Binho Supernova Multi-Protocol USB Host Adapter* features an array of connectors including an I2C qwiic 4-pin port, a versatile 2x15 pins connector for I2C/UART/SPI/GPIO functions, and a duo of I3C dedicated 10-pin ports segmented for low and high voltage.  ### Pinout Guide [Section titled “Pinout Guide”](#pinout-guide) The figure below shows the connector pinout and channel functions: .png) #### **QWIIC I2C Port** [Section titled “QWIIC I2C Port”](#qwiic-i2c-port) | 1 - GND | 2 - VTARGET | 3 - SDA | 4 - SCL | | ------- | ----------- | ------- | ------- | #### **I2C / UART / SPI / GPIO Port** [Section titled “I2C / UART / SPI / GPIO Port”](#i2c--uart--spi--gpio-port) * I2C | 1 - SCL | 2 - GND | 3 - SDA | 4 - GND | | ------- | ------- | ------- | ------- | * UART | 5 - RX | 6 - GND | 7 - TX | 8 - GND | | ------- | -------- | -------- | -------- | | 9 - RTS | 10 - GND | 11 - CTS | 12 - GND | * SPI | 13 - MOSI (SDO) | 14 - GND | 15 - MISO (SDI) | 16 - GND | | --------------- | --------- | --------------- | --------- | | 17 - CLK | 18 - GND | 19 - CS 0 | 20 - CS 1 | | 21 - CS 2 | 22 - CS 3 | | | * GPIO | 23 - GPIO 1 | 24 - GPIO 2 | 25 - GPIO 3 | 26 - GPIO 4 | | ----------- | ----------- | ------------ | ----------- | | 27 - GPIO 5 | 28 - GPIO 6 | 29 - VTARGET | 30 - AIN | #### Low Voltage I3C Port [Section titled “Low Voltage I3C Port”](#low-voltage-i3c-port) | 1 - VTARGET | 2 - DETECT | 3 - VTARGET | 4 - GND | | ----------- | ---------- | ----------- | ------- | | 5 - VTARGET | 6 - GND | 7 - SCL | 8 - GND | | 9 - SDA | 10 - GND | | | #### High Voltage I3C Port [Section titled “High Voltage I3C Port”](#high-voltage-i3c-port) | 1 - VTARGET | 2 - DETECT | 3 - VTARGET | 4 - GND | | ----------- | ---------- | ----------- | ------- | | 5 - VTARGET | 6 - GND | 7 - SCL | 8 - GND | | 9 - SDA | 10 - GND | | | Now you’re ready to begin interacting with the device. See the following QuickStart Guides in this section to learn how to interact with the device via your preferred interface. ### Examples of circuit setups [Section titled “Examples of circuit setups”](#examples-of-circuit-setups) Below are shown two examples of circuit setups where the Binho Supernova host adapter is being used to interact with I3C targets. This illustrates how simple can be to implement a hardware setup and start rapidly to test/develop devices.  Two examples of Supernova being used with I3C targets # Python SDKs The Binho Host Adapters aren’t just limited to the Binho Mission Control app. For those who prefer direct interaction through programming, our specialized Python SDKs provide an alternative pathway to harness the full potential of your host adapter. ## Binho Supernova [Section titled “Binho Supernova”](#binho-supernova) For owners of the Binho Supernova host adapter, the SupernovaController package offers an API for interacting with target devices through I3C and I2C protocols. Dive deep and discover advanced functionalities with this SDK: [supernovacontroller.md](/getting-started/python-sdks/supernovacontroller/) ## Binho Nova [Section titled “Binho Nova”](#binho-nova) If you have the Binho Nova host adapter and wish to leverage its capabilities through the Python SDK, refer to the guide below to kickstart your journey with the Nova SDK: [nova-sdk.md](/getting-started/python-sdks/nova-sdk/) # Nova SDK Thanks to incredible feedback and support from our customers, we’ve released an entirely rebuilt python library for Binho Nova. While we’ll continue to support our previous library, active development will only take place on this one. Aside from taking a more ***pythonic*** approach to implementing the library, we’ve also introduced a lot of structure and abstraction to make it even easier to use your Nova, including a command line interface and interactive shell. We’ve also baked numerous example scripts right into the library for easy reference. ## Getting Started [Section titled “Getting Started”](#getting-started) The easiest way to get started is to install this library using pip: ```plaintext pip install binho ``` Using Nova in your scripts is as simple as importing the library: ```python import binho ``` Then initialize a connection to the binho device as such: ```python # grab the first device found the system finds binho = binhoHostAdapter() ``` When working on setups with multiple devices, you can specify the device to connect to in the following 3 ways: 1. grab the device with a specific index\ `binho = binhoHostAdapter(index=0)` 2. or get the device using the COM port\ `binho = binhoHostAdapter(port=targetComport)` 3. or get the device using the deviceID number\ `binho = binhoHostAdapter(deviceID = targetDeviceID)` At this point it’s possible to control the device as desired. Examples of common use cases are included in this library and are briefly discussed below. When you’re done with the device, be sure to close out the connection with the following: ```plaintext binho.close() ``` That’s all there is to it. The example scripts are introduced below, but it may also make sense to review the new Command line interface as well, as it may be possible to achieve your goals without writing any code at all. ## Example Scripts [Section titled “Example Scripts”](#example-scripts) Take a look in the [/binho/examples](https://github.com/binhollc/binho-python-package/tree/main/binho/examples) folder of the codebase (hosted on github) to see example scripts which demonstrate how to use this library in your own scripts to automate Nova. These example scripts feature a lot of commentary and serve as a tutorial for using this library. **Basic Examples:** * [Hello World LED](https://github.com/binhollc/binho-python-package/blob/main/binho/examples/00_hello_world_led.py) This example shows the basics of establishing a connection with device and setting it’s LED to BLUE. It’s a boring example, but introduces the typical script structure and basics of working with this library. * [Digital IO and PWM](https://github.com/binhollc/binho-python-package/blob/main/binho/examples/01_digitalio_and_pwm.py) This example shows how to use IO pins for digital input and output, as well as configuring hardware PWM. * [Analog IO, DAC, and ADC](https://github.com/binhollc/binho-python-package/blob/main/binho/examples/02_analogio_dac_and_adc.py) This example shows how to use IO pins for analog input (using the ADC) and output (using the DAC). * [SPI Communication](https://github.com/binhollc/binho-python-package/blob/main/binho/examples/03_spi_communication.py) This example shows how to configure the device for SPI communication and transfer data. This example can be run by connecting SDI and SDO signals to loopback the data. * [I2C Communication](https://github.com/binhollc/binho-python-package/blob/main/binho/examples/04_i2c_communication.py) This example demonstrates how to configure the device for I2C communication and perform reads and writes. It also shows how to scan the bus, and perform read register and write register commands. This example is easily adaptable to work with any I2C device you have available. * [1-Wire Communication](https://github.com/binhollc/binho-python-package/blob/main/binho/examples/05_1wire_communication.py) This example demonstrates how to configure the device for (Dallas / Maxim) 1-Wire communication by writing to and reading from a [DS24B33+ 1-Wire EEPROM](https://www.mouser.com/ProductDetail/Maxim-Integrated/DS24B33%2b/?qs=%2F%2FkzJz%252Bz9F%2F59wgCoS63UQ%3D%3D). Note that the command set for most 1Wire EEPROMs is very similar so this example may work with other devices too. **Advanced Examples:** * [I2C EEPROM Demo](https://github.com/binhollc/binho-python-package/blob/main/binho/examples/10_i2c_eeprom_demo.py) - Reading and Writing common EEPROM devices has never been easier. Also shows how to read to / write from, and verify against .bin and .hex files. * [SPI Flash Demo](https://github.com/binhollc/binho-python-package/blob/main/binho/examples/20_spi_flash_demo.py) - Reading and Writing common FLASH devices has never been easier using our SPI * [SPI Flash SFDP](https://github.com/binhollc/binho-python-package/blob/main/binho/examples/21_spi_flash_sfdp.py) - Discover the parameters of a SPI Flash device without any prior knowledge by reading the JEDEC ID and SPI Flash Discoverable Parameters. * *more coming soon* ## Command Line Interface [Section titled “Command Line Interface”](#command-line-interface) The installation of this library also includes the new command line interface which makes it possible to perform a lot of common functions without needing to write any code. The format of the commands is as follows: ```plaintext binho <> [arguments] ``` Each command has their own unique arguments, but all commands except ‘info’ support the following: * `-h, --help`: prints the list of arguments * `-v, --verbose`: display more details on the console during execution * `-d, --device `: connect to the device with the provided deviceID number * `-p, --port `: connect to the device on the provided COM port * `-i, --index `: connect to the device at index i *Note that only one of `-d`, `-p`, or `-i` arguments can be supplied to any command.* **Device Management Subcommands** * **`binho info`** This command can be used to find all Novas connected to the PC and get their associated information such as serial number, COM port, and firmware version. It will also indicate if a device is in DAPLink or Bootloader mode as well. * **`binho dfu`** This command can be used to automatically update device firmware or just enter Bootloader mode. **IO Subcommands** * **`binho gpio`**\ This command can be used to take digital readings or drive IO pins as digital outputs. Note that the device does not retain its state between consecutive runs of this command. As such, a subsequent run will overwrite any previous pin configurations. * **`binho dac`** This command can be used to set the DAC output to a given voltage or raw 10bit value. * **`binho adc`**\ This command can be used to take readings from IO pins using the analog inputs (ADC). * **`binho pwm`**\ This command can be used to configure the IO pins to be used as PWM outputs. **Protocol Subcommands** * **`binho i2c`**\ This command can be used to perform I2C Scans, Reads, and Writes. * **`binho eeprom`**\ This command can be used to read from and write to common I2C EEPROM devices. * **`binho spi`**\ This command can be used to perform SPI transfers. * **`binho spiflash`** \[Coming Soon!]\ This command can be used to read from and write to common SPI Flash devices. * **`binho 1wire`** This command can be used to communicate with 1-Wire devices. **DAPLink Subcommands** Binho Nova can be used to program and debug microcontrollers by operating in DAPLink mode. * **`binho daplink`**\ Use this command to switch Nova into and out of DAPLink mode. * **`binho flasher`**\ While in DAPLink mode, this command can be used to program bin/hex files into microcontrollers. **Misc. Subcommands** * **`binho shell`**\ This command can be used to open up a connection to the device and begin an interactive shell. * **`binho custom`**\ Adding custom commands is very easy! This command is just meant as a template which can be used to create your own commands to extend the command line functionality for any specific tasks. You can see the implementation [here](https://github.com/binhollc/binho-python-package/blob/main/binho/commands/binho_custom.py). ## Development [Section titled “Development”](#development) We welcome contributions to our library, and we’ve made it easy. Here’s some brief guidance to get started developing with the library. #### Installation [Section titled “Installation”](#installation) ```plaintext python3 setup.py install ``` #### Building Docs [Section titled “Building Docs”](#building-docs) We’re planning to use ReadTheDocs to host detailed library documentation in the near future. You can build the documentation with the following command. ```plaintext pip3 install .[dev] docs\make.bat html ``` #### Roadmap [Section titled “Roadmap”](#roadmap) We’re looking forward to adding support for various common UART use-cases. Additionally, we’ll be adding in support for Atmel SWI if we find enough folks interested in that protocol. Our development roadmap is highly determined by customer requests and feedback, so please feel free to reach out if there’s a particular feature you’d like to see added into this library. ## Additional Resources [Section titled “Additional Resources”](#additional-resources) The release can be viewed on PyPi here: And here’s another direct link to the our public repo on Github: # SupernovaController > Python SDK for the Binho Supernova Host Adapter ## Summary [Section titled “Summary”](#summary) SupernovaController is a Python-based tool designed to interface with the Supernova host-adapter USB HID device. Offering a blocking API, it simplifies command sequences and interactions in the context of asynchronous operation environments like the one offered by the Supernova host-adapter. This approach enhances usability and efficiency, providing a streamlined experience for developers working with the Supernova device. The SupernovaController currently supports I2C and I3C protocols, allowing effortless communication with I2C and I3C devices as the host adapter acts as a controller device. In the near future, we are excited to announce that the SupernovaController will also support I3C Target mode, further expanding its capabilities and offering more versatile communication options for developers. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) Before installing and using SupernovaController, please ensure your system meets the following requirements: * Python 3.5 or higher. * Windows, MacOS or Linux operating systems. * Binho Supernova USB host adapter with up-to-date firmware. * It’s recommended to use a virtual environment for the installation to avoid any conflicts with other Python packages. You can create a virtual environment using tools like `venv` or `conda`. ## Installation [Section titled “Installation”](#installation) * Open your command line interface (CLI). * Navigate to your project directory or the directory where you want to install the SupernovaController. * Run the following command: ```sh pip install supernovacontroller ``` This command will download and install the SupernovaController package along with its dependencies (`transfer_controller` and `BinhoSupernova`) from PyPI: ## Getting Started [Section titled “Getting Started”](#getting-started) This example showcases how to use the SupernovaController with a Supernova device using the I3C protocol interface. 1. **Initializing the Supernova Device:** Import and initialize the `SupernovaDevice`. Optionally, specify the USB HID path if multiple devices are connected: ```python from supernovacontroller.sequential import SupernovaDevice device = SupernovaDevice() # Optionally specify the USB HID path device.open(usb_address='your_usb_hid_path') ``` Call `open()` without parameters if you don’t need to specify a particular device. 2. **Creating an I3C Interface:** ```python i3c = device.create_interface("i3c.controller") ``` 3. **Setting Bus Voltage:** This step is required before initializing the bus if you don’t specify the voltage parameter in `init_bus`: ```python i3c.set_bus_voltage(3300) ``` 4. **Initializing the I3C Bus:** The voltage parameter is optional here if already set via `set_bus_voltage`: ```python i3c.init_bus() # Voltage already set, so no need to specify it here ``` If the bus voltage wasn’t set earlier, you can initialize the bus with the voltage parameter: ```python i3c.init_bus(3300) # Setting the voltage directly in init_bus ``` 5. **Discovering Devices on the Bus:** ```python success, targets = i3c.targets() if success: for target in targets: print(f"Found device: {target}") ``` 6. **Reading and Writing to a Target Device:** Replace `0x08` with the dynamic address of the device: ```python # Write data i3c.write(0x08, i3c.TransferMode.I3C_SDR, [0x00, 0x00], [0xDE, 0xAD, 0xBE, 0xEF]) # Read data success, data = i3c.read(0x08, i3c.TransferMode.I3C_SDR, [0x00, 0x00], 4) if success: print(f"Read data: {data}") ``` 7. **Closing the Device:** ```python device.close() ``` ## Examples [Section titled “Examples”](#examples) After installing the `SupernovaController` package, you can further explore its capabilities by trying out the examples included in the installation. These examples demonstrate practical applications of both I2C and I3C protocols: * **Basic I3C Example (`basic_i3c_example.py`):** Learn the basics of I3C bus initialization and device communication. * **Basic I2C Example (`basic_i2c_example.py`):** Get started with fundamental I2C operations. * **IBI Example (`ibi_example.py`):** Understand handling In-Band Interrupts (IBI) in I3C. * **ICM42605 I3C Example (`ICM42605_i3c_example.py`):** Explore a real-world application of I3C with the ICM42605 sensor. **Accessing the Examples** To access the examples, you first need to find the installation directory of the `SupernovaController` package. This can be done using the following Python commands: ```python import supernovacontroller import os examples_path = os.path.join(supernovacontroller.__path__[0], 'examples') print(f"Examples are located in: {examples_path}") ``` Navigate to this directory to find the example scripts. You can run an example directly from this directory using Python. For instance: ```sh python /path/to/examples/basic_i2c_example.py ``` Replace `/path/to/examples/` with the actual path printed in the previous step and `basic_i2c_example.py` with the name of the example you wish to run. # Software Releases This section contains links to the latest stable releases for all software applications and packages in the Binho ecosystem, which can be used to interact with Binho Nova and Supernova host adapters. | Tool | Download link | | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | BMC desktop app | | | SupernovaController(Python High-Level SDK for Supernova) | | | BinhoSupernova (Python Low-Level SDK for Supernova) | | | BMC C++ SDK (C++ SDK for Nova and Supernova) | Follow the instructions on the [BMC C++ SDK installation page](/getting-started/c-sdk/installation/). | | Binho (Python SDK for Nova) | | # Orders & Shipping Everything you need to know about placing an order can be found here. Buying direct from our website is fast and easy, and we also accept Purchase Orders when necessary. [place-an-order.md](/orders-and-shipping/place-an-order/) [requesting-a-quotation.md](/orders-and-shipping/requesting-a-quotation/) Have questions about how and when we ship orders? Check out the page below: [shipping-policy.md](/orders-and-shipping/shipping-policy/) Finally, if you made it this far, you must be looking for a discount: [discounts.md](/orders-and-shipping/discounts/) # Discounts ### Student / Educator Discounts [Section titled “Student / Educator Discounts”](#student--educator-discounts) Students currently spending 20+ hours/week in school are eligible to purchase a *Binho Nova Multi-Protocol USB Host Adapter* at a reduced price of **$149.00**. Professors and teachers can enjoy the same discount. If you’d like to purchase a device at this discounted price, please contact us at **** using your school email address. The student/educator discounts require a unique discount code to be used during checkout. ### Quantity Discounts [Section titled “Quantity Discounts”](#quantity-discounts) Quantity discounts for all customers start at orders of 5 or more units. Binho offers 10% off orders of 5+ units of *Binho Nova Multi-Protocol USB Host Adapter.* This discount is applied automatically during the checkout process. # Distributors We’re in the process of developing a world-wide network of reputable distributors. If you’re interested in becoming an official distributor of Binho products please fill out [this form](https://forms.gle/AJkLwm19QSuzFV8EA) and we’ll be reaching out to you shortly. ## Authorized Distributors[](#authorized-distributors) [Section titled “Authorized Distributors ”](#authorized-distributors-) ### USA[](#usa) [Section titled “USA ”](#usa-)    ### Australia[](#australia) [Section titled “Australia ”](#australia-)  ### South Korea[](#south-korea) [Section titled “South Korea ”](#south-korea-)  ### China / Hong Kong / Taiwan[](#china-hong-kong-taiwan) [Section titled “China / Hong Kong / Taiwan ”](#china--hong-kong--taiwan-)  *Also serving Malaysia, Singapore, and Vietnam* ### Europe[](#europe) [Section titled “Europe ”](#europe-) **Sweden**  Serving the EU and nearby markets including the UK and Russia. **Norway**  ### Israel[](#israel) [Section titled “Israel ”](#israel-)  ### United Kingdom[](#united-kingdom) [Section titled “United Kingdom ”](#united-kingdom-)  # International Shipping We offer international shipping using UPS or DHL. All orders ship from our office in California, USA. The shipping costs are automatically calculated during the checkout process, so you can check the rate to the destination by simply adding the items to the cart and providing your address. The shipping charges will be calculated and displayed as part of the order balance. Note that the recipient is responsible for paying all taxes/fees/duties related to the package upon arrival in the destination country. The United States defines products using its Harmonized Tariff Schedule (HTS). An HS code, or HTS code, stands for Harmonized System or Harmonized Tariff Schedule. Export Classification Numbers (ECCN), Harmonized System (HS) Codes, of our products can be found below. ### ECCN [Section titled “ECCN”](#eccn) All Binho products and accessories are classified as **EAR99.** ### HS Codes [Section titled “HS Codes”](#hs-codes) | **SKU** | **Product** | **HS Code** | | ------- | ------------------------------------- | ------------- | | BIN002 | Binho Multi-Protocol USB Host Adapter | 8543.20.00.00 | | BIN003 | Total Retrofitter | 8543.90.68.00 | | BIN004 | Breadboard Breakout | 8543.90.68.00 | | BIN005 | Qwiic Interface Board | 8543.90.68.00 | | BIN008 | Feather Interface Board | 8543.90.68.00 | | BIN010 | Socket Station | 8543.90.68.00 | ### Country of Origin [Section titled “Country of Origin”](#country-of-origin) | SKU | Product | Country of Origin | | ------ | ------------------------------------- | ----------------- | | BIN002 | Binho Multi-Protocol USB Host Adapter | China (Mainland) | | BIN003 | Total Retrofitter | USA | | BIN004 | Breadboard Breakout | China (Mainland) | | BIN005 | Qwiic Interface Board | China (Mainland) | | BIN008 | Feather Interface Board | China (Mainland) | | BIN010 | Socket Station | USA | # Place an Order ### Buying Online [Section titled “Buying Online”](#buying-online) The easiest way to place an order is from our online store. While we feature the device prominently on our homepage, it’s even easier to add it to the shopping cart from its dedicated product page. 1. Navigate to the Binho Host Adapter [products page](https://binho.io/collections/host-adapters). 2. Select what host adapter you want to order. 3. Click the **Add to Cart** button. This action will take you to the Shopping Cart page. 4. On the Shopping Cart page, you can modify the quantity if you’d like to purchase multiple devices. After adjusting the quantity, be sure to click the **Update** button. 5. To add any other product to your cart, you may click the **Continue Shopping** button. 6. You can complete the purchase online by clicking the **Check Out** button. We accept payment by credit card, Apple Pay, & Google Pay in our online store. ### Requesting a Quotation [Section titled “Requesting a Quotation”](#requesting-a-quotation) The purchasing and procurement policies of many companies are not compatible with purchasing with a credit card online, and require a formal quotation. Please see the page below to request a quote: [requesting-a-quotation.md](/orders-and-shipping/requesting-a-quotation/) ### Placing a Purchase Order [Section titled “Placing a Purchase Order”](#placing-a-purchase-order) We are happy to support our customers who cannot place orders directly thought our website by credit card. Please see the page below for all the details about placing a PO: [placing-a-purchase-order.md](/orders-and-shipping/placing-a-purchase-order/) # Placing a Purchase Order Purchase Orders are the recommended method for companies who cannot place orders with credit card directly on our website. In order to ensure a smooth order process, please make sure the PO includes the following information: * Billing Address * Shipping Address * Purchase Order Number * Phone Number * Product Name(s) and Quantities * Prices in US Dollars * Shipping Method: * Please include your FedEx/UPS Account Number if shipping will be on your account * Please indicate “Binho to Prepay Shipping - Add to Invoice” if not using your shipping account * Email Address and contact information for Accounts Payable department ### Payment Terms[](#payment-terms) [Section titled “Payment Terms ”](#payment-terms-) Net 30 payment terms are offered to customers with a history of timely payments. For your first order, we will generate a Proforma Invoice which must be pre-paid. We will then ship the order on the first business day after the payment has been received. ### Requesting A Quotation[](#requesting-a-quotation) [Section titled “Requesting A Quotation ”](#requesting-a-quotation-) [requesting-a-quotation.md](/orders-and-shipping/requesting-a-quotation/) # Requesting a Quotation To receive an official quotation, please send an email to **** with the required information. ### Required Information[](#required-information) [Section titled “Required Information ”](#required-information-) * Full Name * E-mail address * Telephone Number * How you prefer to pay for your order: * Wire Transfer * Credit Card * Products and Quantity * Shipping Address * Shipping Method * Use your own shipping account (only possible with orders placed via PO) * Shipping costs will be added to the quote * Shipping Carrier and Account Number if placing a PO to ship on your own account We’ll process your request as soon as possible and follow up with you by email, typically on the same day. If you’ll be placing a Purchase Order to complete the transaction, please have a look at the following page: [placing-a-purchase-order.md](/orders-and-shipping/placing-a-purchase-order/) # Shipping Policy ### In-Stock Items [Section titled “In-Stock Items”](#in-stock-items) Normally, orders placed before 12pm PST on business days are shipped the same day. The stock status (in-stock / out-of-stock) is displayed under each item in your cart. Orders after the 12pm PST cut-off time will ship on the next business day. ### Out-of-Stock Items [Section titled “Out-of-Stock Items”](#out-of-stock-items) We do our best to ensure our products are in-stock and ready to ship, however there are some rare occasions when this is regrettably not possible. If an item is out of stock, it will be indicated as such on its product page, as well as in your shopping cart. In the case that any item on your order is out of stock, we will hold your entire order until it can be shipped in full. Please contact us if you’d like to make other arrangements. ### Shipping Methods[](#shipping-methods) [Section titled “Shipping Methods ”](#shipping-methods-) To check the shipping methods available for your location, simply add an item to the shopping cart and select your country. Then click the Checkout button and enter your shipping information. This will then allow you to view the available shipping options and their costs. ### Shipping Origin[](#shipping-origin) [Section titled “Shipping Origin ”](#shipping-origin-) All orders placed on [www.binho.io](http://www.binho.io) as well as orders placed via PO are shipped from Pacifica, California. ### No Shipping Days[](#no-shipping-days) [Section titled “No Shipping Days ”](#no-shipping-days-) There are few national holidays in the USA on which Binho will not be shipping any orders: * New Years Day (January 1) * Memorial Day (last Monday in May) * Independence Day (July 4) * Labor Day (first Monday in September) * Thanksgiving Day (fourth Thursday in November) * Christmas Day (December 25) ### International Shipping - Duties and Taxes[](#international-shipping-duties-and-taxes) [Section titled “International Shipping - Duties and Taxes ”](#international-shipping---duties-and-taxes-) If you are having your order shipped outside of the USA, there will likely be additional charges for duties and taxes due upon receipt in the destination country. Binho does not pay the customs fees associated with any orders for any destination. ### Order Confirmation & Tracking Numbers[](#order-confirmation-and-tracking-numbers) [Section titled “Order Confirmation & Tracking Numbers ”](#order-confirmation--tracking-numbers-) You’ll receive an order confirmation email as soon as your order is placed. If you find that you need to make any changes to your order, please contact us as soon as possible. After your order has been shipped, you will receive a second email with tracking information for your purchase. Please note that tracking information may not appear in the system for up to 24 hours. # Tax Exemption If your company is exempt from paying taxes and our product will ship within the United States, please provide us with your tax exemption certificate in advance of placing your order. Contact us at **** and include an attachment of your tax exemption certificate. We’ll follow up with confirmation after approval, and then your future orders will be tax-free. ### Refund of Tax Charges[](#refund-of-tax-charges) [Section titled “Refund of Tax Charges ”](#refund-of-tax-charges-) If your order has already been shipped, then the sales tax has already been collected. We’ll do our best to refund the tax charges after you provide us with your certificate of exemption. Note that we can only process tax refunds for orders placed directly on our website. # Returns & Warranty The 2-year warranty always applies, regardless of where you purchased the product. All warranty replacements and repairs are handled directly by us. There is no need to contact the distributor where you purchased it. Also, you don’t need the original receipt. As long as you have the unit, we can repair or replace it under warranty. Also, if you can’t remember when you purchased the unit or if the 2-year window has already closed, please contact us anyway in case we can help. # 2-Year Warranty The 2-year warranty always applies, regardless of where you purchased the product. All warranty replacements and repairs are handled directly by us. There is no need to contact the distributor where you purchased it. Also, you don’t need the original receipt. As long as you have the unit, we can repair or replace it under warranty. Also, if you can’t remember when you purchased the unit or if the 2-year window has already closed, please contact us anyway in case we can help. # 90-Day Return Policy The 90-Day return policy only applies to products purchased directly from Binho, either from our website, [www.binho.io](https://www.binho.io/), or on a purchase order directly with Binho. # Troubleshooting This section provides solutions to common issues you may encounter when using Binho products. If you’re experiencing problems, follow the guides below to resolve them quickly. ## Common Issues [Section titled “Common Issues”](#common-issues) ### USB Connection Issues on Linux [Section titled “USB Connection Issues on Linux”](#usb-connection-issues-on-linux) If you’re having trouble connecting to Binho host adapters on Linux, this could be due to permission issues. Follow the steps outlined in the [**Solving USB Connection Issues on Linux**](/troubleshooting/solving-usb-connection-issues-on-linux/) guide to fix it. # Solving USB Connection Issues on Linux If you’re experiencing issues accessing Binho host adapters on Linux, whether using our SDKs or desktop apps, follow these steps to resolve the problem. ### Issue Description [Section titled “Issue Description”](#issue-description) You may encounter an error when trying to access a Binho device, which could look something like: ```plaintext Open connection failed. Exception type: . Exception message: open failed. ``` ### Solution [Section titled “Solution”](#solution) Follow these steps to set up proper permissions and resolve the issue: #### 1. Create a user group for Binho devices [Section titled “1. Create a user group for Binho devices”](#1-create-a-user-group-for-binho-devices) ```sh sudo groupadd binho sudo usermod -a -G binho $USER ``` #### 2. Refresh your session [Section titled “2. Refresh your session”](#2-refresh-your-session) ```sh su - $USER ``` #### 3. Verify your user belongs to the `binho` group [Section titled “3. Verify your user belongs to the binho group”](#3-verify-your-user-belongs-to-the-binho-group) ```sh groups ``` #### 4. Set proper permissions for Binho devices [Section titled “4. Set proper permissions for Binho devices”](#4-set-proper-permissions-for-binho-devices) Create a new rules file for `udev` to handle the USB permissions: ```sh sudo nano /etc/udev/rules.d/99-binho.rules ``` Add the following rules: ```plaintext SUBSYSTEM=="usb", MODE="0666", GROUP="binho" SUBSYSTEM=="hidraw", MODE="0664", GROUP="binho" ``` #### 5. Reload `udev` rules [Section titled “5. Reload udev rules”](#5-reload-udev-rules) ```sh sudo udevadm control --reload sudo udevadm trigger ``` #### 6. Reboot if necessary [Section titled “6. Reboot if necessary”](#6-reboot-if-necessary) If the issue persists, try rebooting your system. ### Verifying Device Connection [Section titled “Verifying Device Connection”](#verifying-device-connection) To check if your device is properly connected and recognized by your system, run your preferred application or tool, verify the device is listed, and connect to the device. The output should indicate the device is successfully connected. # User Guide # Binho Nova > Multi-protocol (I2C, SPI, 1-Wire), single-port host adapter  Binho Nova Host Adapter ## Summary [Section titled “Summary”](#summary) The *Binho Nova Multi-Protocol USB Host Adapter* allows one to interface their computer directly to hardware circuits. This device is powered by the USB connection to the host PC and is also able to provide downstream power to test circuits. ## Description [Section titled “Description”](#description) The Binho Nova features 5 signal pins, 1 x 3v3 pin, 1 x VUSB pin, and 3 x GND pins on its 10-pin wire harness. The wire harness terminates with a female 1.27mm 2x5 IDC connector. In IO Mode, the 5 signal pins can be used for varying functions such as Digital Input, Digital Output, PWM Output, Digital Interrupt (on rising edge, falling edge, or change), Analog Input, or Analog Output. Additionally, the host adapter is able to utilize these pins to communicate on several digital buses: I2C, SPI, UART, (Dallas) 1-Wire, and (Atmel) Single-Wire Interface. While in these modes of operation, remaining available pins can be assigned to other related or unrelated purposes such as gpio, interrupts, chip selects, PWM signals, or analog input or outputs. The Binho Nova is ideal for manual testing during firmware development and debugging as well as a perfect way to automate hardware testing and validation. A common use-case of this product in production environments is for EEPROM/Flash Memory programming along with functional testing activities. ## Common Applications [Section titled “Common Applications”](#common-applications) * Firmware Development * Proof of Concept Development * System Debugging * Automated Hardware/Firmware Testing * EEPROM Programming * FLASH Programming * FRAM Programming ## Hardware Specifications [Section titled “Hardware Specifications”](#hardware-specifications) ### Key Features [Section titled “Key Features”](#key-features) * Support for SPI @ 12MHz max clock * Support for I2C @ 3.4MHz max clock * Support for UART @ 1000000 max baud * Support for Dallas 1-Wire * Support for Atmel Single-Wire Interface * Provides 3v3 and VUSB power rails * 1 x DAC Output, 5 x ADC Inputs * GPIO / Interrupt / PWM Support * Programmable RGB Status LED * Field-Upgradeable Device Firmware * Cross-platform Support for Windows, Mac, Linux * Robust, low-profile Aluminum Enclosure * USB Type-C Connector ### Power Requirements [Section titled “Power Requirements”](#power-requirements) * Power Source: USB Type-C * Voltage & Current: 200 mA @ 5 V * Max Power Consumption: 1 W ### Interfaces [Section titled “Interfaces”](#interfaces) * USB-C: Serves as both power input and data interface. * Wire harness which terminates with a female 1.27mm 2x5 IDC connector composed by 5 signal pins, 1 x 3v3 pin, 1 x VUSB pin, and 3 x GND pins. ### Included Components [Section titled “Included Components”](#included-components) Every Binho Nova Multi-Protocol USB Host Adapter comes with a convenient [breadboard breakout adapter](https://binho.io/collections/accessories/products/breadboard-breakout). Also included is a 1-foot USB Type-C to Type-A cable, all packed neatly in a soft-shell zippered case. ## Pinout Guide [Section titled “Pinout Guide”](#pinout-guide) .png) # Binho Supernova > Multi-protocol (I3C, I2C, SPI, UART), multi-port host adapter  Binho Supernova host adapter from top and bottom. ## Summary [Section titled “Summary”](#summary) The *Binho Supernova Multi-Protocol Host Adapter* joins the Binho family of USB host adapters as an all-in-one solution that supports I3C, I2C, UART, and SPI protocols in controller mode, plus I3C in target mode and GPIO. Paired with *Binho Mission Control*, our multi-platform desktop app, or our Python or C++ SDKs, the Supernova dramatically simplifies device orchestration during embedded system development and testing. ## Description [Section titled “Description”](#description) The Supernova is a USB 2.0 Full Speed HID device that provides an array of connectors including an I2C qwiic 4-pin port, a versatile 2x15 pins connector for I2C/UART/SPI/GPIO functions, and a duo of I3C dedicated 10-pin ports segmented for low and high voltage. In combination with our desktop app Binho Mission Control, the Supernova enables Windows, Linux, and Mac users to quickly and easily start interacting with their testing devices through various protocols and GPIO. When used alongside the C++ and Python SDKs, users can write programs and scripts to create automations. ## Common Applications [Section titled “Common Applications”](#common-applications) * **Testing and debugging:** Streamlined testing and debugging of embedded systems. * **Hardware and firmware design:** Reduces the code-build-test cycle, increasing the speed of analysis and solution design. * **Research and hands-on experimentation:** Facilitates rapid trials with new devices such as sensors, accelerometers, microcontrollers, and more, across various protocols, without the need to write a single line of code. * **Learning purposes:** Eases the learning curve when mastering new protocols or devices. ## Features [Section titled “Features”](#features) ### Device Management [Section titled “Device Management”](#device-management) * **Retrieve System Information:** Easily access comprehensive device information. * **Voltage Configuration:** Flexibly adapt bus voltages to various device requirements. * **Device Control:** Provides straightforward mechanisms to reset the device or initiate boot mode. ### I2C Communication Protocol [Section titled “I2C Communication Protocol”](#i2c-communication-protocol) * **Roles:** Comprehensive support for I2C Controller role. * **Bus Voltage:** Versatile voltage adjustment ranging from 1.2 V to 3.3 V. * **Frequency Range:** Adjustable SCL clock frequency to suit different communication needs, ranging from 10 KHz to 1 MHz. * **Write and Read Operations:** Streamlined operations to facilitate both writing to and reading from devices. * **Register Address Setting:** Offers the capability to set specific register addresses. * **Non-Stop Transactions:** Supports “non-stop” or “repeated start” conditions. * **Parameter Setting:** Simplified parameter configuration for optimal communication. ### I3C Communication Protocol [Section titled “I3C Communication Protocol”](#i3c-communication-protocol) * **Roles:** I3C Controller in both SDR and HDR-DDR modes, I3C Target in both SDR and HDR-DDR modes, and I3C Target with Secondary Controller capability. I3C Basic v1.1.1 (backwards-compatible with I3C Basic v1.0). * **Bus Voltage:** Wide voltage range from 0.8 V to 3.3 V. * **Working Frequencies:** * Push-Pull Modes: 3.75 MHz to 12.5 MHz. * Open-Drain Modes: 100 KHz to 4.17 MHz. * **Enhanced Features:** * Dynamic Address Assignments for flexible device communication. * Comprehensive transaction types including I3C Private Write and Read, and Common Command Code (CCC) transactions. * Legacy I2C backward compatibility for seamless integration. * Advanced features like In-Band Interrupts (IBIs), Hot-Join, and Controller role handoff. * Efficient data operations with expansive write and read capabilities. * Dynamic Target Devices Table that’s user-configurable and automatically updated. ### UART Communication Protocol [Section titled “UART Communication Protocol”](#uart-communication-protocol) * **Bus Voltage**: Ample voltage range from 1.2 V up to 3.3 V. * **Baudrate**: Up to 115200 bps. (And even higher in the future). * **Wide Bandwidth**: With a maximum transfer length of 1024 bytes. * **Personalizable Set Up**: * **Parity**: Even, Odd, or no parity set up. * **Configurable Datasize**: Data in 7 or 8 bits. * **Assignable Stop Bits Quantity**: With 1 or 2 stop bits. * **Flow Control**: With Optional RTS/CTS handshake. ### SPI Communication Protocol [Section titled “SPI Communication Protocol”](#spi-communication-protocol) * **Roles:** Controller role fully supported. Peripheral role will be supported in a future release. * **Bus Voltage**: Ample voltage range from 1.2 V up to 3.3 V. * **High Frequency Support**: Clock frequencies of up to 50 MHz. * **Highly Customizable**: * **Configurable Bit Order**: Set up standard MSB and LSB bit orders. * **Mode Support:** Modes 0, 1, 2, and 3 are supported. * **Support for Varying Polarity**: Set up Low and High polarity in the CS Pins. * **Multi-Target Support**: Connect multiple targets in the 4 available Chip Select Pins. * **Wide Bandwidth**: With a maximum transfer length of 1024 bytes. ### GPIO [Section titled “GPIO”](#gpio) > GPIOs work differently depending on what revision of Supernova you are using, so please be mindful of their differences * **Configurable GPIOs:** All GPIO pins can be configured to be either Digital Input (DIN) or Digital Output (DOUT) * **Configurable Interrupts**: All DIN-configured pins support triggering interrupts on falling, rising and both edges * For Rev. B Supernovas, GPIO3 cannot have interruptions configured * **Wide Voltage Range**: * For Rev. B Supernovas * GPIO1 and GPIO2 share power domain with I3C from 1.2 V to 3.3 V * GPIO3 to GPIO6 work at a fixed 3.3 V * For Rev. C Supernovas * GPIOs share power domain with I2C, SPI and UART, from 1.2 V to 3.3 V ## Hardware Specification [Section titled “Hardware Specification”](#hardware-specification) ### Power Requirements [Section titled “Power Requirements”](#power-requirements) * Power Source: USB Type-C * Max. Voltage & Current: 500 mA @ 5 V * Max Power Consumption: 2.5 W ### Interfaces [Section titled “Interfaces”](#interfaces) * USB-C HID Class: Serves as both power input and data interface. * Unified Interface: Consolidates I2C, UART, SPI, and GPIO functions. * I3C Interfaces: * Low Voltage Interface: Supports I3C bus voltages ranging from 0.800 V to 1.199 V. * High Voltage Interface: Supports I3C bus voltages ranging from 1.200 V to 3.300 V. ### Indicators [Section titled “Indicators”](#indicators) * MCU Operation Indicators: * RGB Neopixels: * Normal Operation: Cycles between green and blue in a sinusoidal pattern when the device is in a resting state. * Command Reception: Pauses for 30 seconds upon receiving a command. * USB Communication: * Fourth Neopixel: Illuminates when the Supernova receives a message via USB. * Fifth Neopixel: Lights up upon sending a response back to the USB host. ## Pinout Guide [Section titled “Pinout Guide”](#pinout-guide) .jpg) Supernova's ports .png) ### QWIIC I2C Port [Section titled “QWIIC I2C Port”](#qwiic-i2c-port) | 1 - GND | 2 - VTARGET | 3 - SDA | 4 - SCL | | ------- | ----------- | ------- | ------- | ### I2C / UART / SPI / GPIO Port [Section titled “I2C / UART / SPI / GPIO Port”](#i2c--uart--spi--gpio-port) #### I2C [Section titled “I2C”](#i2c) | 1 - SCL | 2 - GND | 3 - SDA | 4 - GND | | ------- | ------- | ------- | ------- | #### UART [Section titled “UART”](#uart) | 5 - RX | 6 - GND | 7 - TX | 8 - GND | | ------- | -------- | -------- | -------- | | 9 - RTS | 10 - GND | 11 - CTS | 12 - GND | #### SPI [Section titled “SPI”](#spi) | 13 - MOSI (SDO) | 14 - GND | 15 - MISO (SDI) | 16 - GND | | --------------- | --------- | --------------- | --------- | | 17 - CLK | 18 - GND | 19 - CS 0 | 20 - CS 1 | | 21 - CS 2 | 22 - CS 3 | | | #### GPIO [Section titled “GPIO”](#gpio-1) | 23 - GPIO 1 | 24 - GPIO 2 | 25 - GPIO 3 | 26 - GPIO 4 | | ----------- | ----------- | ------------ | ----------- | | 27 - GPIO 5 | 28 - GPIO 6 | 29 - VTARGET | 30 - AIN | ### Low Voltage I3C Port [Section titled “Low Voltage I3C Port”](#low-voltage-i3c-port) | 1 - VTARGET | 2 - DETECT | 3 - VTARGET | 4 - GND | | ----------- | ---------- | ----------- | ------- | | 5 - VTARGET | 6 - GND | 7 - SCL | 8 - GND | | 9 - SDA | 10 - GND | | | ### High Voltage I3C Port [Section titled “High Voltage I3C Port”](#high-voltage-i3c-port) | 1 - VTARGET | 2 - DETECT | 3 - VTARGET | 4 - GND | | ----------- | ---------- | ----------- | ------- | | 5 - VTARGET | 6 - GND | 7 - SCL | 8 - GND | | 9 - SDA | 10 - GND | | | ## Unboxing the Supernova [Section titled “Unboxing the Supernova”](#unboxing-the-supernova)  Binho Supernova kit * 1 USB A to USB Type-C cable * 1 2x15 pin 1.27 mm pitch Flat Ribbon Cable. * 3 Qwiic JSH cables: * Qwiic JST SH 4-Pin Cable - 50mm Long. * Qwiic JST SH 4-pin to Premium Female Sockets Cable - 150mm Long. * Qwiic JST SH 4-pin to Premium Male Headers Cable - 150mm Long * Wire color reference: * Red = VTARG * Blue = SDA * Black = GND * Yellow = SCL * 1 I3C High-Quality Harness. * Connector pair 1: Black=GND, Red=VTARG * Connector pair 2: Black=GND, Blue=SDA * Connector pair 3: Black=GND, Yellow=SCL * 1 I3C Port connector to Qwiic Adapter board * 1 Binho Supernova Breakout Board for 2x15 1.27 mm pitch to 2x15 2.54 mm pitch male pin header adaptation. # Compliance & Legal ### RoHS Certificate of Conformance [Section titled “RoHS Certificate of Conformance”](#rohs-certificate-of-conformance) #### Download [Binho RoHS Certificate of Conformance](https://cdn.binho.io/doc/nova/compliance/Binho%20LLC%20RoHS%20Certificate%20of%20Conformance.pdf) \[pdf] [Section titled “Download Binho RoHS Certificate of Conformance \[pdf\]”](#download-binho-rohs-certificate-of-conformance-pdf) ### EU Declaration of Conformity [Section titled “EU Declaration of Conformity”](#eu-declaration-of-conformity) #### Download [Binho EU Declaration of Conformity](https://cdn.binho.io/doc/nova/compliance/Binho%20LLC%20EU%20Declaration%20of%20Conformity.pdf) \[pdf] [Section titled “Download Binho EU Declaration of Conformity \[pdf\]”](#download-binho-eu-declaration-of-conformity-pdf) ### California Proposition 65 Warning [Section titled “California Proposition 65 Warning”](#california-proposition-65-warning) THIS PRODUCT CONTAINS CHEMICALS KNOWN TO THE STATE OF CALIFORNIA TO CAUSE CANCER AND BIRTH DEFECTS OR OTHER REPRODUCTIVE HARM. ### Import / Export Compliance [Section titled “Import / Export Compliance”](#import--export-compliance) Please see our International Shipping page for information regarding ECCN and HS Codes for Binho products: [international-shipping.md](/orders-and-shipping/international-shipping/) # Hardware Comparison Table | Feature/Accessory | Binho Nova | Binho Supernova | | ----------------------- | --------------------------------- | ---------------------------------------------------- | | Signal Pins | 1 port, 5 pins | 4 ports, 54 pins | | USB Class | CDC | HID | | IO Mode Capabilities | Digital I/O, PWM, Analog I/O | Digital I/O, PWM, Analog I/O, Interrupts | | Communication Protocols | I2C, SPI, 1-Wire | I3C, I2C, SPI, UART | | Device Roles | I2C Controller | I2C Controller, I3C Controller and Peripheral | | Ports | 1 port for GPIO, SPI, I2C, 1-Wire | 1 QWIIC I2C, 1 I2C/UART/SPI/GPIO, 1 LV I3C, 1 HV I3C | | GUI Desktop App | Binho Mission Control | Binho Mission Control | | SDKs | Nova SDK (Python) | Supernova SDK (Python and C/C++) |  Binho Nova (top) and Binho Supernova (bottom) # Protocols and Interfaces # 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 [Section titled “Introduction”](#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 [Section titled “Architecture Overview”](#architecture-overview) ### 1. **Bridge Service Layer** [Section titled “1. Bridge Service Layer”](#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** [Section titled “2. Command Adaptors”](#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** [Section titled “3. Command and Response Structure”](#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 [Section titled “Getting Started”](#getting-started) To launch the Bridge for the Supernova host adapter: ```shell python bridge.py BinhoSupernova ``` ## Command Structure [Section titled “Command Structure”](#command-structure) Commands are structured as JSON objects. Each command request requires a `transaction_id`, `command`, and `params`: ```json { "transaction_id": "", "command": "", "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: ```json { "transaction_id": "", "status": "", "type": "", "is_promise": "", "data": "" } ``` ## Device Management Commands [Section titled “Device Management Commands”](#device-management-commands) ### Open a Connection [Section titled “Open a Connection”](#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: ``` { "transaction_id": "2450", "status": "success", "type": "command_response", "is_promise": false, "data": { "command": "open", "id": "", "port": "", "productName": "", "vendorId": "", "productId": "", "firmwareVersion": "", "hardwareVersion": "", "mode": "" } } ``` ### Close a Connection [Section titled “Close a Connection”](#close-a-connection) * Command Request: ```json { "transaction_id": "123", "command": "close" } ``` * Response: ```json { "transaction_id": "123", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "close", "status": "success", "result": "Supernova closed successfully" } } ``` ### Exit [Section titled “Exit”](#exit) * Command Request: ```json { "transaction_id": "421", "command": "exit" } ``` * Response: ```json { "transaction_id": "421", "status": "exit", "type": "command_response", "is_promise": false, "data": null } ``` ## Error Handling [Section titled “Error Handling”](#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”](#error-message-structure) Every error message returned by the Bridge service has the following structure: ```json { "transaction_id": "", "status": "failure", "type": null, "is_promise": false, "data": { "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”](#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 [Section titled “Protocol-Specific Commands”](#protocol-specific-commands) [bridge-1.1-api-basic-i3c-commands.md](/user-guide/protocols-and-interfaces/bridge-11-api/bridge-11-api-basic-i3c-commands/) [bridge-1.1-api-i3c-common-command-codes.md](/user-guide/protocols-and-interfaces/bridge-11-api/bridge-11-api-i3c-common-command-codes/) [bridge-1.1-api-i2c-commands.md](/user-guide/protocols-and-interfaces/bridge-11-api/bridge-11-api-i2c-commands/) [bridge-1.1-api-uart-commands.md](/user-guide/protocols-and-interfaces/bridge-11-api/bridge-11-api-uart-commands/) [bridge-1.1-api-spi-commands.md](/user-guide/protocols-and-interfaces/bridge-11-api/bridge-11-api-spi-commands/) [bridge-1.1-api-gpio-commands.md](/user-guide/protocols-and-interfaces/bridge-11-api/bridge-11-api-gpio-commands/) # Bridge 1.1 API - Basic I3C Commands ### I3C Bus Initialization [Section titled “I3C Bus Initialization”](#i3c-bus-initialization) * **Command Request:** ```json { "transaction_id": "1", "command": "i3c_init_bus", "params": { "busVoltageInV": "3.3" } } ``` * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i3c_init_bus" } } ``` * Final Response to Setting Bus Voltage: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_set_bus_voltage", "status": "success", "result": {} } } ``` * Final Response to Bus Initialization: ```json { "transaction_id": "2", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_init_bus", "status": "success", "result": {} } } ``` * Response to Get Target Device Table: ```json { "transaction_id": "3", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_get_target_device_table", "status": "success", "result": { "payload": [ {"static_address": "50", "dynamic_address": "08", "bcr": "10", "dcr": "C3", "pid": ["65", "64", "00", "00", "00", "00"]}, {"static_address": "51", "dynamic_address": "09", "bcr": "10", "dcr": "C3", "pid": ["65", "64", "00", "00", "00", "00"]}, {"static_address": "52", "dynamic_address": "0A", "bcr": "10", "dcr": "C3", "pid": ["65", "64", "00", "00", "00", "00"]}, {"static_address": "53", "dynamic_address": "0B", "bcr": "03", "dcr": "63", "pid": ["5A", "00", "1D", "0F", "17", "02"]} ] } } } ``` ### Reset I3C Bus [Section titled “Reset I3C Bus”](#reset-i3c-bus) * **Command Request:** ```json { "transaction_id": "2", "command": "i3c_reset_bus", "params": {} } ``` * **Responses:** 1. Initial promise indicating the command is queued: ```json { "transaction_id": "2", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i3c_reset_bus" } } ``` 2. Final response indicating the outcome of the reset command: ```json { "transaction_id": "2", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_reset_bus", "status": "success", "result": {} } } ``` 3. Response indicating the state of the target device table after reset: ```json { "transaction_id": "2", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_get_target_device_table", "status": "success", "result": { "payload": [] } } } ``` ### Set Bus Voltage [Section titled “Set Bus Voltage”](#set-bus-voltage) Set the bus voltage for the connected device. * **Command Request:** ```json { "transaction_id": 4, "command": "i3c_set_bus_voltage", "params": { "busVoltageInV": "3.3" } } ``` * **Responses:** Immediate promise response: ```json { "transaction_id": "4", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i3c_set_bus_voltage" } } ``` Final response: ```json { "transaction_id": "4", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_set_bus_voltage", "status": "success", "result": {} } } ``` ### I3C Get Target Device Table [Section titled “I3C Get Target Device Table”](#i3c-get-target-device-table) * **Command Request:** ```json { "transaction_id": "6", "command": "i3c_get_target_device_table", "params": {} } ``` * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "6", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i3c_get_target_device_table" } } ``` * Final Response: ```json { "transaction_id": "6", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_get_target_device_table", "status": "success", "result": { "payload": [ {"static_address": "50", "dynamic_address": "08", "bcr": "10", "dcr": "C3", "pid": ["65", "64", "00", "00", "00", "00"]}, {"static_address": "51", "dynamic_address": "09", "bcr": "10", "dcr": "C3", "pid": ["65", "64", "00", "00", "00", "00"]}, {"static_address": "52", "dynamic_address": "0A", "bcr": "10", "dcr": "C3", "pid": ["65", "64", "00", "00", "00", "00"]}, {"static_address": "53", "dynamic_address": "0B", "bcr": "03", "dcr": "63", "pid": ["5A", "00", "1D", "0F", "17", "02"]} ] } } } ``` ### I3C Write [Section titled “I3C Write”](#i3c-write) #### Write Using Subaddress [Section titled “Write Using Subaddress”](#write-using-subaddress) * **Command Request:** ```json { "transaction_id": "5", "command": "i3c_write_using_subaddress", "params": { "address": "08", "subaddress": "0000", "mode": "SDR", "pushPullClockFrequencyInMHz": "5", "openDrainClockFrequencyInKHz": "2500", "writeBuffer": "DEADBEEF" } } ``` * **Responses:** * Immediate Promise: ```json { "transaction_id": "5", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i3c_write_using_subaddress" } } ``` * Final Response: ```json { "transaction_id": "5", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_write_using_subaddress", "status": "success", "result": { "payload": [], "payload_size": 0 } } } ``` #### Direct Write [Section titled “Direct Write”](#direct-write) * **Command Request:** ```json { "transaction_id": "6", "command": "i3c_write", "params": { "address": "08", "mode": "SDR", "pushPullClockFrequencyInMHz": "5", "openDrainClockFrequencyInKHz": "2500", "writeBuffer": "0000" } } ``` * **Responses:** * Immediate Promise: ```json { "transaction_id": "6", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i3c_write" } } ``` * Final Response: ```json { "transaction_id": "6", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_write", "status": "success", "result": { "payload": [], "payload_size": 0 } } } ``` ### I3C Read [Section titled “I3C Read”](#i3c-read) #### Basic Read [Section titled “Basic Read”](#basic-read) * **Command Request:** ```json { "transaction_id": 7, "command": "i3c_read", "params": { "address": "08", "mode": "SDR", "pushPullClockFrequencyInMHz": "5", "openDrainClockFrequencyInKHz": "2500", "bytesToRead": "5" } } ``` * **Responses:** ```json { "transaction_id": "7", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i3c_read" } } ``` ```json { "transaction_id": "7", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_read", "status": "success", "result": { "payload": ["DE", "AD", "BE", "EF", "00"], "payload_size": 5 } } } ``` #### Read using Subaddress [Section titled “Read using Subaddress”](#read-using-subaddress) * **Command Request:** ```json { "transaction_id": 8, "command": "i3c_read_using_subaddress", "params": { "address": "08", "mode": "SDR", "pushPullClockFrequencyInMHz": "5", "openDrainClockFrequencyInKHz": "2500", "subaddress": "0000", "bytesToRead": "5" } } ``` * **Responses:** ```json { "transaction_id": "8", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i3c_read_using_subaddress" } } ``` ```json { "transaction_id": "8", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_read_using_subaddress", "status": "success", "result": { "payload": ["DE", "AD", "BE", "EF", "00"], "payload_size": 5 } } } ``` # Bridge 1.1 API - GPIO Commands ### Set Voltage [Section titled “Set Voltage”](#set-voltage) See [#set-bus-voltage](/user-guide/protocols-and-interfaces/bridge-11-api/bridge-11-api-i2c-commands/#set-bus-voltage "mention"). ### GPIO Configuration [Section titled “GPIO Configuration”](#gpio-configuration) * **Command Request:** ```json { "transaction_id": "1", "command": "gpio_config_pin", "params": { "pinNumber": "<1..6>", "functionality": "" } } ``` * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "gpio_config_pin" } } ``` * Final Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "gpio_config_pin", "status": "success" } } ``` ### GPIO Read [Section titled “GPIO Read”](#gpio-read) * **Command Request:** ```json { "transaction_id": "1", "command": "gpio_digital_read", "params": { "pinNumber": "1..6" } } ``` * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "gpio_digital_read" } } ``` * Final Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "gpio_digital_read", "status": "success", "logic_level": "" } } ``` ### GPIO Write [Section titled “GPIO Write”](#gpio-write) * **Command Request:** ```json { "transaction_id": "1", "command": "gpio_digital_write", "params": { "pinNumber": "<1..6>", "logicLevel": "<0|1>" } } ``` * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "gpio_digital_write" } } ``` * Final Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "gpio_digital_write", "status": "success" } } ``` ### Configure GPIO Interruptions [Section titled “Configure GPIO Interruptions”](#configure-gpio-interruptions) * **Command Request:** ```json { "transaction_id": "1", "command": "gpio_set_interrupt", "params": { "pinNumber": "<1..6>", "edgeTrigger": "" } } ``` * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "gpio_set_interrupt" } } ``` * Final Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "gpio_set_interrupt", "status": "success" } } ``` ### GPIO Interruption Notification Message [Section titled “GPIO Interruption Notification Message”](#gpio-interruption-notification-message) ```json { "transaction_id": "0", "status": "success", "type": "notification", "is_promise": false, "data": { "payload": { "pin": "<1..6>" } } } ``` # Bridge 1.1 API - I2C Commands ### Set Bus Voltage [Section titled “Set Bus Voltage”](#set-bus-voltage) * **Command Request:** ```json { "transaction_id": "1", "command": "i2c_spi_uart_set_bus_voltage", "params": { "busVoltageInV": "" } } ``` * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i2c_spi_uart_set_bus_voltage" } } ``` * Final Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i2c_spi_uart_set_bus_voltage", "status": "success" } } ``` ### I2C Set Parameters [Section titled “I2C Set Parameters”](#i2c-set-parameters) * **Command Request:** ```json { "transaction_id": "1", "command": "i2c_set_parameters", "params": { "clockFrequencyInKHz": "" } } ``` * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i2c_set_parameters" } } ``` * Final Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i2c_set_parameters", "status": "success" } } ``` ### I2C Read [Section titled “I2C Read”](#i2c-read) * **Command Request:** ```json { "transaction_id": "1", "command": "i2c_read", "params": { "address": "<2-Digit Hexadecimal (E.g. 0A)>", "bytesToRead": "", "busVoltageInV": "" } } } ``` * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i2c_read" } } ``` * Final Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i2c_read", "status": "success", "data": } } ``` ### I2C Write [Section titled “I2C Write”](#i2c-write) * **Command Request:** ```json { "transaction_id": "1", "command": "i2c_write", "params": { "address": "<2-Digit Hexadecimal (E.g. 0A)>", "writeBuffer": "", "clockFrequencyInKHz": "Unsigned Integer" } } ``` * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i2c_write" } } ``` * Final Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i2c_write", "status": "success" } } ``` ### I2C Read Using Subaddress [Section titled “I2C Read Using Subaddress”](#i2c-read-using-subaddress) * **Command Request:** ```json { "transaction_id": "1", "command": "i2c_read_using_subaddress", "params": { "address": "<2-Digit Hexadecimal (E.g. 0A)>", "subaddress": "", "bytesToRead": "", "busVoltageInV": "" } } } ``` * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i2c_read_using_subaddress" } } ``` * Final Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i2c_read_using_subaddress", "status": "success", "data": } } ``` ### I2C Write Using Subaddress [Section titled “I2C Write Using Subaddress”](#i2c-write-using-subaddress) * **Command Request:** ```json { "transaction_id": "1", "command": "i2c_write_using_subaddress", "params": { "address": "<2-Digit Hexadecimal (E.g. 0A)>", "subaddress": "", "writeBuffer": "", "clockFrequencyInKHz": "Unsigned Integer" } } ``` * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i2c_write_using_subaddress" } } ``` * Final Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i2c_write_using_subaddress", "status": "success" } } ``` # Bridge 1.1 API - I3C Common Command Codes ### CCC (Common Command Codes) [Section titled “CCC (Common Command Codes)”](#ccc-common-command-codes) 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. For more information on this topic see [I3C Common Command Codes](/user-guide/protocols-and-interfaces/i3c-common-command-codes/#what-are-common-command-codes) section. #### GETPID [Section titled “GETPID”](#getpid) * **Command Request:** ```json { "transaction_id": 9, "command": "i3c_ccc_send", "params": { "cccName": "GETPID", "address": "08", "pushPullClockFrequencyInMHz": "5", "openDrainClockFrequencyInKHz": "2500", "cccParams": {} } } ``` * **Responses:** 1. Immediate promise: ```json { "transaction_id": "9", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i3c_ccc_getpid" } } ``` 2. Command result: ```json { "transaction_id": "9", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_ccc_getpid", "status": "success", "result": { "payload": ["0", "0", "0", "0", "64", "65"], "payload_size": 6 } } } ``` #### DIRECTSETMRL [Section titled “DIRECTSETMRL”](#directsetmrl) * **Command Request:** ```json { "transaction_id": 10, "command": "i3c_ccc_send", "params": { "cccName": "DIRECTSETMRL", "address": "08", "pushPullClockFrequencyInMHz": "5", "openDrainClockFrequencyInKHz": "2500", "cccParams": { "cccDataBuffer": "10" } } } ``` * **Responses:** 1. Immediate promise: ```json { "transaction_id": "10", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i3c_ccc_direct_setmrl" } } ``` 2. Command result: ```json { "transaction_id": "10", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_ccc_direct_setmrl", "status": "success", "result": { "payload": ["00", "00"], "payload_size": 2 } } } ``` #### DIRECTENEC [Section titled “DIRECTENEC”](#directenec) * **Command Request:** ```json { "transaction_id": 11, "command": "i3c_ccc_send", "params": { "cccName": "DIRECTENEC", "address": "08", "pushPullClockFrequencyInMHz": "5", "openDrainClockFrequencyInKHz": "2500", "cccParams": { "events": ["ENINT", "ENCR", "ENHJ"] } } } ``` * **Responses:** 1. Immediate promise: ```json { "transaction_id": "10", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i3c_ccc_direct_enec" } } ``` 2. Command result: ```json { "transaction_id": "10", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_ccc_direct_enec", "status": "success" } } ``` **Note:** For `DIRECTDISEC` the response’s format is very similar, except that the accepted events are \[“DISINT”, “DISCR”, “DISHJ”]. For `BROADCASTENEC` and `BROADCASTDISEC` is also similar but address parameter is not required. #### SETAASA [Section titled “SETAASA”](#setaasa) * **Command Request:** ```json { "transaction_id": 12, "command": "i3c_ccc_send", "params": { "cccName": "SETAASA", "pushPullClockFrequencyInMHz": "5", "openDrainClockFrequencyInKHz": "2500", "cccParams": { "staticAddresses": ["08", "09", "0A"] } } } ``` * **Responses:** 1. Immediate promise: ```json { "transaction_id": "12", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i3c_ccc_setaasa" } } ``` 2. Command result: ```json { "transaction_id": "12", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_ccc_setaasa", "status": "success" } } ``` #### ENTDAA [Section titled “ENTDAA”](#entdaa) * **Command Request:** ```json { "transaction_id": 13, "command": "i3c_ccc_send", "params": { "cccName": "ENTDAA", "pushPullClockFrequencyInMHz": "5", "openDrainClockFrequencyInKHz": "2500", "cccParams": { "targetDeviceTable": { "BMM350": { "staticAddress": "0x14", "dynamicAddress": "0x0C", "i3cFeatures": "0x0B", "maxIbiPayloadLength": "0xE9", "bcr": "0x26", "dcr": "0x43", "pid": ["0x07", "0x70", "0x10", "0x33", "0x00", "0x00"] } } } } } ``` * **Responses:** 1. Immediate promise: ```json { "transaction_id": "13", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i3c_ccc_entdaa" } } ``` 2. Command result: ```json { "transaction_id": "13", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_ccc_entdaa", "status": "success" } } ``` **Note:** When using this command is necessary to previously run `i3c_init_bus` followed by`i3c_reset_bus`. #### BROADCASTRSTACT [Section titled “BROADCASTRSTACT”](#broadcastrstact) * **Command Request:** ```json { "transaction_id": 14, "command": "i3c_ccc_send", "params": { "cccName": "BROADCASTRSTACT", "pushPullClockFrequencyInMHz": "5", "openDrainClockFrequencyInKHz": "2500", "cccParams": { "definingByte": "02" } } } ``` * **Responses:** 1. Immediate promise: ```json { "transaction_id": "14", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i3c_ccc_broadcast_rstact" } } ``` 2. Command result: ```json { "transaction_id": "14", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_ccc_broadcast_rstact", "status": "success" } } ``` **Note:** Similar to `DIRECTRSTACT` but does not require an address parameter. #### DIRECTENDXFER [Section titled “DIRECTENDXFER”](#directendxfer) * **Command Request:** ```json { "transaction_id": 15, "command": "i3c_ccc_send", "params": { "cccName": "DIRECTENDXFER", "address": "08", "pushPullClockFrequencyInMHz": "5", "openDrainClockFrequencyInKHz": "2500", "cccParams": { "definingByte": "AA", "data": "20" } } } ``` * **Responses:** 1. Immediate promise: ```json { "transaction_id": "15", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i3c_ccc_direct_endxfer" } } ``` 2. Command result: ```json { "transaction_id": "15", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_ccc_direct_endxfer", "status": "success", "result": { "payload": [0], "payload_size": 1 } } } ``` **Note:** Similar to `BROADCASTENDXFER`, but requires an address parameter. #### BROADCASTSETXTIME [Section titled “BROADCASTSETXTIME”](#broadcastsetxtime) * **Command Request:** ```json { "transaction_id": 16, "command": "i3c_ccc_send", "params": { "cccName": "BROADCASTSETXTIME", "pushPullClockFrequencyInMHz": "5", "openDrainClockFrequencyInKHz": "2500", "cccParams": { "definingByte": "3F", "data": ["DE", "AD", "BE", "EF"] } } } ``` * **Responses:** 1. Immediate promise: ```json { "transaction_id": "16", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "i3c_ccc_broadcast_setxtime" } } ``` 2. Command result: ```json { "transaction_id": "16", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "i3c_ccc_broadcast_setxtime", "status": "success", "result": { "payload": [0, 0, 0, 0, 0], "payload_size": 5 } } } ``` **Note:** Similar to `DIRECTSETXTIME`, but does not require an address parameter. #### Currently Supported CCCs: [Section titled “Currently Supported CCCs:”](#currently-supported-cccs) Refer to [this table](/user-guide/protocols-and-interfaces/i3c-common-command-codes/#supported-cccs) for current support status (see Bridge column). # Bridge 1.1 API - SPI Commands ### Set Voltage [Section titled “Set Voltage”](#set-voltage) See [#set-bus-voltage](/user-guide/protocols-and-interfaces/bridge-11-api/bridge-11-api-i2c-commands/#set-bus-voltage "mention"). ### SPI Initialization [Section titled “SPI Initialization”](#spi-initialization) * **Command Request:** ```json { "transaction_id": "1", "command": "spi_init", "params": { { "mode": "<0..3>", "clockFrequencyInKHz": "", "bitOrder": "", "bitsPerTransfer": "<8|16>", "chipSelect": "<0..3>", "chipSelectPol": "<0,1>" } } } ``` * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "spi_init" } } ``` * Final Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "spi_init", "status": "success" } } ``` ### SPI Configuration [Section titled “SPI Configuration”](#spi-configuration) * **Command Request:** ```json { "transaction_id": "1", "command": "spi_config", "params": { { "mode": "<0..3>", "clockFrequencyInKHz": "", "bitOrder": "", "bitsPerTransfer": "<8|16>", "chipSelect": "<0..3>", "chipSelectPol": "<0,1>" } } } ``` * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "spi_config" } } ``` * Final Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "spi_config", "status": "success" } } ``` ### SPI Transfer [Section titled “SPI Transfer”](#spi-transfer) * **Command Request:** ```json { "transaction_id": "1", "command": "spi_transfer", "params": { "bytesToRead": "", "writeBuffer": "" } } } ``` * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "spi_transfer" } } ``` * Final Response: ```json { "transaction_id": "1", "status": "success", "is_promise": false, "data": { "is_response_to": "spi_transfer", "status": "success", "payload_length": , "data": } } } ``` # Bridge 1.1 API - UART Commands ### Set Voltage [Section titled “Set Voltage”](#set-voltage) See [#set-bus-voltage](/user-guide/protocols-and-interfaces/bridge-11-api/bridge-11-api-i2c-commands/#set-bus-voltage "mention"). ### UART Initialization [Section titled “UART Initialization”](#uart-initialization) * **Command Request:** ```json { "transaction_id": "1", "command": "uart_init", "params": { "baudRate": "<600|1200|2400|4800|9600|14400|19200|38400|56000|57600|115200>", "hardwareHandShake": , "parity": "<0|1|2>", "dataSize": "<0|1>", "stopBit": "1" } } ``` * **Field Descriptions**: * **`parity`**\ Sets the UART parity mode:\ `0` = No parity, `1` = Even parity, `2` = Odd parity. * **`dataSize`**\ Defines the number of data bits per frame:\ `0` = 7-bit, `1` = 8-bit. * **`stopBit`**\ Selects the number of stop bits:\ `0` = 1 stop bit, `1` = 2 stop bits. * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "uart_init" } } ``` * Final Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "uart_init", "status": "success" } } ``` ### UART Configuration [Section titled “UART Configuration”](#uart-configuration) * **Command Request:** ```json { "transaction_id": "1", "command": "uart_config", "params": { "baudRate": "<600|1200|2400|4800|9600|14400|19200|38400|56000|57600|115200>", "hardwareHandShake": , "parity": "<0|1|2>", "dataSize": "<0|1>", "stopBit": "1" } } ``` * **Field Descriptions**: * **`parity`**\ Sets the UART parity mode:\ `0` = No parity, `1` = Even parity, `2` = Odd parity. * **`dataSize`**\ Defines the number of data bits per frame:\ `0` = 7-bit, `1` = 8-bit. * **`stopBit`**\ Selects the number of stop bits:\ `0` = 1 stop bit, `1` = 2 stop bits. * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "uart_config" } } ``` * Final Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "uart_config", "status": "success" } } ``` ### UART Send [Section titled “UART Send”](#uart-send) * **Command Request:** ```json { "transaction_id": "1", "command": "uart_send", "params": { "writeBuffer": "" } } ``` * **Responses:** * Immediate Promise Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": true, "data": { "command": "uart_send" } } ``` * Final Response: ```json { "transaction_id": "1", "status": "success", "type": "command_response", "is_promise": false, "data": { "is_response_to": "uart_send", "status": "success" } } ``` ### UART Interruption Notification Message [Section titled “UART Interruption Notification Message”](#uart-interruption-notification-message) ```json { "transaction_id": "0", "status": "success", "type": "notification", "is_promise": false, "data": { "type": "UART_MESSAGE_RECEIVED", "payload": , "payload_length": 4 } } ``` # I3C Common Command Codes > This page provides an overview of CCCs, their functions, and the ones currently supported in the Binho family of products. ## What are Common Command Codes? [Section titled “What are Common Command Codes? ”](#what-are-common-command-codes-) Common Command Codes (CCCs) are I3C’s standardized command set enabling access to various standard functions. Support for CCCs depends ultimately on the targets. CCCs are classified as BROADCAST or DIRECT: * Broadcast CCCs: * Addressed to all I3C target devices on the I3C bus. * All Broadcast CCCs are write operations. * Direct CCCs: * Typically directed to a single target device (e.g., DUT) on the I3C bus, identified by its dynamic address. * Some direct write CCCs can use a group address. * If a response is required, only the specifically addressed target device will reply. * Direct CCCs can be classified as read, write, or read/write. ### Brief Descriptions and References [Section titled “Brief Descriptions and References”](#brief-descriptions-and-references) #### DISEC and ENEC (Enable/Disable Events Command) [Section titled “DISEC and ENEC (Enable/Disable Events Command) ”](#disec-and-enec-enabledisable-events-command--) *Available BOTH as DIRECT and BROADCAST* Allows the Controller to control target-initiated traffic on the I3C bus. ENEC enables traffic, DISEC disables traffic. This CCC controls: * Target In-Band Interrupts (ENINT/DISINT) `*` * Requests for the Controller Role (ENCR/DISCR) * Hot Join Signaling (ENHJ/DISHJ) `*` * These commands can prevent the target from making Dynamic Address Assignment requests. `*` Enabled by Default **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=89) \[PDF] | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=153) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C Basic v1.0 | ✅ | 5.1.9.3.1 | | I3C Basic v1.1.1 | ✅ | 5.1.9.3.1 | #### ENDXFER (Data Transfer Ending Procedure Control) [Section titled “ENDXFER (Data Transfer Ending Procedure Control) ”](#endxfer-data-transfer-ending-procedure-control--) *Available BOTH as DIRECT and BROADCAST* Allows the Controller and Target devices to exchange setup parameters for terminating data transfers in supported HDR modes. **Reference**: **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | I3C Basic v1.0 | ❌ | *Unsupported* | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=214) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ❌ | *Unsupported* | | I3C v1.1.1 | ✅ | 5.1.9.3.25 | #### ENTASX (Enter Activity State X) [Section titled “ENTASX (Enter Activity State X) ”](#entasx-enter-activity-state-x--) *Available BOTH as DIRECT and BROADCAST* Allows the Controller to inform Targets of inactivity periods on the bus, allowing them to enter lower power states. Activity States: * Activity State 0: 1 microsecond (latency-free operation) * Activity State 1: 100 microseconds * Activity State 2: 2 milliseconds * Activity State 3: 50 milliseconds (lowest-activity operation) **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=90) \[PDF] | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=155) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ✅ | *5.1.9.3.2* | | I3C v1.1.1 | ✅ | 5.1.9.3.2 | #### GETACCCR (Get Accept Controller Role) [Section titled “GETACCCR (Get Accept Controller Role) ”](#getacccr-get-accept-controller-role--) *Available ONLY as DIRECT* Enables the verification of a Controller Role request and enables the Active Controller to transfer the role to a Secondary Controller. If the Second Controller accepts the role, it responds with its Dynamic Address (matching the target’s address). If it NACKs or returns an invalid address, the Secondary Controller will not assume the Controller Role. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=98) \[PDF] (as GETACCMST) | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=178) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ✅ | 5.1.9.3.16 | | I3C v1.1.1 | ✅ | 5.1.9.3.16 | #### GETBCR (Get Bus Characteristics Register) [Section titled “GETBCR (Get Bus Characteristics Register) ”](#getbcr-get-bus-characteristics-register--) *Available ONLY as DIRECT* Allows the Controller to get the Bus Characteristics Register of a target. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=96) \[PDF] | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=170) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ✅ | *5.1.9.3.13* | | I3C v1.1.1 | ✅ | 5.1.9.3.13 | #### GETCAPS (Get Optional Feature Capabilities) [Section titled “GETCAPS (Get Optional Feature Capabilities) ”](#getcaps-get-optional-feature-capabilities--) *Available ONLY as DIRECT* Allows the Controller to check which optional I3C features a Target supports. Responses are 2 to 4 bytes. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | I3C Basic v1.0 | ❌ | *Unsupported* | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=191) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ❌ | *Unsupported* | | I3C v1.1.1 | ✅ | 5.1.9.3.19 | #### GETDCR (Get Device Characteristics Register) [Section titled “GETDCR (Get Device Characteristics Register) ”](#getdcr-get-device-characteristics-register--) *Available ONLY as DIRECT* Enables the Controller to retrieve the Device Characteristics Register from a Target device. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=96) \[PDF] | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=171) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ✅ | 5.1.9.3.14 | | I3C v1.1.1 | ✅ | 5.1.9.3.14 | #### GETMRL / SETMRL (Get/Set Max Read Length) [Section titled “GETMRL / SETMRL (Get/Set Max Read Length)”](#getmrl--setmrl-getset-max-read-length) *SETMRL is available both in DIRECT and BROADCAST, GETMRL is DIRECT ONLY* Allows the Controller to set or get a maximum data read length in bytes, and optionally, a maximum IBI payload size. The first 2 bytes indicate the Max Read Length, with a minimum of 16 bytes. A response of 0 means the Max Read Length is less than 16 bytes; otherwise, it shows the length in bytes. If the device’s BCR bit 2 is set, a third byte for Max IBI payload size is included. A value of 0 means unlimited, and the minimum depends on Timing Control (4 or 5 bytes if used, or 1 byte if not used). **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=92) \[PDF] | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=160) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ✅ | 5.1.9.3.6 | | I3C v1.1.1 | ✅ | 5.1.9.3.6 | #### GETMWL / SETMWL (Get/Set Max Write Length) [Section titled “GETMWL / SETMWL (Get/Set Max Write Length)”](#getmwl--setmwl-getset-max-write-length) *SETMWL is available both in DIRECT and BROADCAST, GETMWL is DIRECT ONLY* Allows the Controller to set or get the maximum data write length in bytes. This limit does not apply to BROADCAST CCCs as their data sizes are fixed. The minimum value you can set is 16 bytes. If a Target responds with 0, it means the Max Write length is less than 16 bytes. Any other response indicates the number of bytes. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=91) \[PDF] | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=158) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ✅ | 5.1.9.3.5 | | I3C v1.1.1 | ✅ | 5.1.9.3.5 | #### GETMXDS (Get Max Data Speed) [Section titled “GETMXDS (Get Max Data Speed) ”](#getmxds-get-max-data-speed--) *Available ONLY as DIRECT* Allows the controller to determine a Target’s SDR mode data speed limitations. The response is provided in one of two possible formats, indicated by the number of bytes returned: * **FORMAT 1:** 2 bytes containing Maximum Write Speed and Maximum Read Speed. * **FORMAT 2:** 5 bytes, including 2 bytes for Maximum Write Speed and Maximum Read Speed, plus 3 bytes for Maximum Read Turnaround Time. The format used depends on whether the target needs to communicate its Maximum Read Turnaround Time. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=100) \[PDF] | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=182) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ✅ | 5.1.9.3.18 | | I3C v1.1.1 | ✅ | 5.1.9.3.18 | #### GETPID (Get Provisioned ID) [Section titled “GETPID (Get Provisioned ID) ”](#getpid-get-provisioned-id--) *Available ONLY as DIRECT* Allows the controller to get the 48-bit (6-byte) Provisioned ID of a target. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=96) \[PDF] | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=169) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ✅ | 5.1.9.3.12 | | I3C v1.1.1 | ✅ | 5.1.9.3.12 | #### GETXTIME (Get Exchange Timing Information) [Section titled “GETXTIME (Get Exchange Timing Information) ”](#getxtime-get-exchange-timing-information--) *Available ONLY as DIRECT* Allows the controller to query the exchange timing capabilities of a Target. The response contains four bytes that provide key information on supported Timing Control modes, current state, internal clock frequency, and accuracy. The response bytes are interpreted as follows: **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=102) \[PDF] | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=211) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ✅ | 5.1.9.3.21 | | I3C v1.1.1 | ✅ | 5.1.9.3.22 | #### RSTDAA (Reset Dynamic Address Assignment) [Section titled “RSTDAA (Reset Dynamic Address Assignment) ”](#rstdaa-reset-dynamic-address-assignment--) *Available ONLY as BROADCAST* This CCC indicates all Targets to clear their assigned Dynamic and Group Addresses (if applicable). After clearing, all Target devices should be ready to participate in Dynamic Address Assignment, SETDASA or SETAASA, or communicate via I2C. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=90) \[PDF] | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=157) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ✅ | 5.1.9.3.3 | | I3C v1.1.1 | ✅ | 5.1.9.3.3 | #### ENTDAA (Enter Dynamic Address Assignment) [Section titled “ENTDAA (Enter Dynamic Address Assignment) ”](#entdaa-enter-dynamic-address-assignment--) *Available ONLY as BROADCAST* Allows the Controller to indicate all targets to enter the Dynamic Address Assignment procedure. Target devices with an already assigned Dynamic Address do not respond to this command. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=91) \[PDF] | | I3C v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=157) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ✅ | 5.1.9.3.4 | | I3C v1.1.1 | ✅ | 5.1.9.3.4 | #### SETAASA (Set All Addresses to Static Addresses) [Section titled “SETAASA (Set All Addresses to Static Addresses) ”](#setaasa-set-all-addresses-to-static-addresses--) *Available ONLY as BROADCAST* Allows the Controller to request that all Targets that have an I2C Static Address set it as their Dynamic Address. This is the fastest way to assign Dynamic Addresses. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=103) \[PDF] | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=213) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ❌ | *Unsupported* | | I3C v1.1.1 | ✅ | 5.1.9.3.23 | #### SETBUSCON (Set Bus Context) [Section titled “SETBUSCON (Set Bus Context) ”](#setbuscon-set-bus-context--) *Available ONLY as BROADCAST* Enables the Controller to specify a particular context on the I3C bus, either a higher-level protocol developed by a standards-developing organization or the version of I3C Basic in use. Targets respond only to contexts they recognize. This command can be used multiple times to set and support a layered protocol context. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | I3C Basic v1.0 | ❌ | *Unsupported* | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=232) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ❌ | *Unsupported* | | I3C v1.1.1 | ✅ | 5.1.9.3.31 | #### SETDASA (Set Dynamic Address from Static Address) [Section titled “SETDASA (Set Dynamic Address from Static Address) ”](#setdasa-set-dynamic-address-from-static-address--) *Available ONLY as DIRECT* Allows the Controller to assign a Dynamic Address to a Target via its Static Address (therefore, the target must have an I2C Static Address). This CCC is faster than the Dynamic Address Assignment Procedure (ENTDAA) and should be used beforehand. SETDASA is particularly useful for simple point-to-point communication in an I3C minimal bus, consisting of a single Controller and Target. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=95) \[PDF] | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=166) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ✅ | 5.1.9.3.10 | | I3C v1.1.1 | ✅ | 5.1.9.3.10 | #### SETNEWDA (Set New Dynamic Address) [Section titled “SETNEWDA (Set New Dynamic Address) ”](#setnewda-set-new-dynamic-address--) *Available ONLY as DIRECT* Allows the Controller to assign a new Dynamic Address to a Target that already has an existing Dynamic Address. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=96) \[PDF] | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=168) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ✅ | 5.1.9.3.11 | | I3C v1.1.1 | ✅ | 5.1.9.3.11 | #### SETXTIME (Set Exchange Timing Information) [Section titled “SETXTIME (Set Exchange Timing Information) ”](#setxtime-set-exchange-timing-information--) *Available BOTH as DIRECT and BROADCAST* Allows the Controller and Targets to exchange event timing information for synchronizing controls, collecting or reconstructing timestamps, and specifying the timing data procedure. A defining byte is required to specify a sub-command, and while some sub-commands may require additional data, none that do so are currently supported. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=102) \[PDF] | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=209) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ✅ | 5.1.9.3.20 | | I3C v1.1.1 | ✅ | 5.1.9.3.21 | #### SETGRPA (Set Group Address) [Section titled “SETGRPA (Set Group Address)”](#setgrpa-set-group-address) *Available ONLY as DIRECT* Allows the Controller to assign a Group Address to an I3C Target that supports the Group Address feature. The Target will then respond to both the assigned Group and Dynamic addresses. If multiple I3C Targets share the same Group Address, a single message sent by the Controller to that Group Address will be received by all of those I3C Targets simultaneously. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | I3C Basic v1.0 | ❌ | *Unsupported* | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=221) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ❌ | *Unsupported* | | I3C v1.1.1 | ✅ | 5.1.9.3.27 | #### RSTACT (Target Reset Action) [Section titled “RSTACT (Target Reset Action)”](#rstact-target-reset-action) *Available BOTH as DIRECT and BROADCAST* This CCC, available as both Broadcast (WRITE) and Direct (READ/WRITE), configures the next Target Reset action and can be used to retrieve the Target’s reset recovery timing. It is used alongside the Target Reset Pattern to initiate a reset on the Target. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | I3C Basic v1.0 | ❌ | *Unsupported* | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=217) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ❌ | *Unsupported* | | I3C v1.1.1 | ✅ | 5.1.9.3.26 | #### GETSTATUS (Get Device Status) [Section titled “GETSTATUS (Get Device Status)”](#getstatus-get-device-status) *Available ONLY as DIRECT* Allows the controller to get the current status from the Target. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=97) \[PDF] | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=172) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ----------------- | | I3C v1.0 | ✅ | 5.1.9.3.15 | | I3C v1.1.1 | ✅ | 5.1.9.3.15 | #### DEFTGTS (Define List of Targets) [Section titled “DEFTGTS (Define List of Targets)”](#deftgts-define-list-of-targets) *Available ONLY as BROADCAST* Allows the Main Controller to tell the Secondary Controllers what Targets (and Groups) are on the I3C Bus. **I3C Basic** | Specification Version | Included | Reference Section | | --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | I3C Basic v1.0 | ✅ | [Link to Spec](https://2384176.fs1.hubspotusercontent-na1.net/hubfs/2384176/Public-I3C-Basic-Debug-Touch/mipi_I3C-Basic_specification_v1-0.pdf#page=93) \[PDF] (as DEFSLVS) | | I3C Basic v1.1.1 | ✅ | [Link to Spec](https://f.hubspotusercontent20.net/hubfs/2384176/mipi_I3C-Basic_specification_v1-1-1.pdf#page=162) \[PDF] | **I3C** | Specification Version | Included | Reference Section | | --------------------- | -------- | ---------------------- | | I3C v1.0 | ✅ | 5.1.9.3.7 (as DEFSLVS) | | I3C v1.1.1 | ✅ | 5.1.9.3.7 | ### Supported CCCs [Section titled “Supported CCCs”](#supported-cccs) Here is a table showing the current CCC support in Supernova for I3C Targets and Controllers, alongside their Software Platforms: | CCC | Type | Supernova | SDK (Python) | S. Controller | Bridge | BMC | Notes | | --------- | ---------------- | :-------: | :----------: | :-----------: | :----: | :-: | -------------------------------------------------------------------------- | | ENEC | DIRECT/BROADCAST | ✅ | ✅ | ✅ | ✅ | ✅ | | | DISEC | DIRECT/BROADCAST | ✅ | ✅ | ✅ | ✅ | ✅ | | | ENTASX | BROADCAST | ✅ | ✅ | ✅ | ✅ | ✅ | | | RSTDAA | BROADCAST | ✅ | ✅ | ✅ | ✅ | ✅ | | | ENTDAA | BROADCAST | ✅ | ✅ | ❌ | ✅ | ❌ | | | SETMWL | DIRECT/BROADCAST | ✅ | ✅ | ✅ | ✅ | ✅ | | | SETMRL | DIRECT/BROADCAST | ✅ | ✅ | ✅ | ✅ | ✅ | | | SETBUSCON | BROADCAST | ✅ | ✅ | ✅ | ✅ | ✅ | | | ENDXFER | DIRECT/BROADCAST | ✅ | ✅ | ✅ | ✅ | ❌ | | | SETXTIME | DIRECT/BROADCAST | ✅ | ✅ | ✅ | ✅ | ✅ | | | SETAASA | BROADCAST | ✅ | ✅ | ✅ | ✅ | ✅ | Not supported in Supernova in target mode. | | RSTACT | DIRECT/BROADCAST | ✅ | ✅ | ✅ | ✅ | ✅ | | | RSTGRPA | DIRECT/BROADCAST | ✅ | ✅ | ✅ | ❌ | ❌ | | | SETDASA | DIRECT | ✅ | ✅ | ✅ | ✅ | ✅ | | | SETNEWDA | DIRECT | ✅ | ✅ | ✅ | ✅ | ✅ | | | GETMWL | DIRECT | ✅ | ✅ | ✅ | ✅ | ✅ | | | GETMRL | DIRECT | ✅ | ✅ | ✅ | ✅ | ✅ | | | GETPID | DIRECT | ✅ | ✅ | ✅ | ✅ | ✅ | | | GETBCR | DIRECT | ✅ | ✅ | ✅ | ✅ | ✅ | | | GETDCR | DIRECT | ✅ | ✅ | ✅ | ✅ | ✅ | | | GETSTATUS | DIRECT | ✅ | ✅ | ✅ | ❌ | ❌ | | | GETACCCR | DIRECT | ✅ | ✅ | ✅ | ✅ | ✅ | Supernova as a target does not support I3C Secondary Controller Role (yet) | | GETMXDS | DIRECT | ✅ | ✅ | ✅ | ✅ | ✅ | | | GETCAPS | DIRECT | ✅ | ✅ | ✅ | ✅ | ✅ | Currently a Defining Byte for GETCAPS is NOT supported. | | GETXTIME | DIRECT | ✅ | ✅ | ✅ | ✅ | ✅ | | | SETGRPA | DIRECT | ✅ | ✅ | ✅ | ❌ | ❌ | | CCCs or their types outside of this reference table are NOT supported at the moment. These include: * **BROADCAST DEFTGTS:** This will be supported when I3C Secondary Controller mode is supported * **BROADCAST ENTTM** * **BROADCAST DEFGRPA:** This will be supported when I3C Secondary Controller mode is supported * **DIRECT ENTASX** * **DIRECT SETBRGTGT** * **DIRECT SETROUTE** * **BROADCAST/DIRECT ENTHDR0:** This will be supported when HDR-DDR mode is supported * **BROADCAST/DIRECT ENTHDR1:** The Supernova does not support HDR - TSP mode * **BROADCAST/DIRECT ENTHDR2:** The Supernova does not support HDR - TSL mode * **BROADCAST/DIRECT ENTHDR3:** The Supernova does not support HDR - BT mode * **BROADCAST/DIRECT MLANE:** The Supernova does not support multi-lane # Safety Notice Before using your *Host Adapter* (be it the Binho Nova, the Binho Supernova, or another host adapter), let’s review some basic safety information to keep in mind while working with electronics in order to avoid injury or damage. In the case of *Binho Nova* and *Binho Supernova* *Host Adapters,* they are **not** electrically isolated from the PC. Caution should be taken when using the host adapter in the presence of a ground loop. Ground loops can easily occur in test bench setups when the host adapter is not the only ground path between your test circuit and the host computer. This is not necessarily bad, but requires an additional awareness. **Common Ways a Ground Loop Can Exist:** * Other USB devices (such as programmers) are connected to the test circuit, or the test circuit itself is plugged into the USB port on your computer. In addition to the host adapter’s ground connection, the test circuit’s ground is also connected to the PC’s ground through another USB port. * Non-isolated power supplies. Most AC power supplies with 3-prong plugs will short the MAINS earth ground pin to the power supply ground output. That includes your PC’s ground. If your test circuit is powered from a 3-prong wall power supply and your PC is also plugged in, that will form another ground path. Keep in mind that if you’re using a laptop that’s not plugged in, even an attached external monitor or printer will create a ground loop. **Common Ways Damage Can Occur:** * When connecting or disconnecting wires, one of the ground signals from the host adapter is accidentally brushed against a power supply pin on the test circuit, such as +5V. If there are no other ground paths between the test circuit and the computer, nothing will happen. However, if there is a ground path, then current will flow from that voltage supply through the host adapter’s ground pin, through the USB cable and the host PC, and then through the secondary ground connection—either MAINS earth ground or another USB port, back to the ground on the test circuit. Basically, that is the same as shorting out the voltage supply on your test circuit, but it uses the host adapter and your host PC as the short circuit, which could damage all components in the loop. * What if the test circuit’s ground reference isn’t at the same voltage as the ground loop connection? For instance, if your circuit is powered by a bipolar power supply used to produce +10 volts and -10 volts, and then your circuit uses the -10 volt rail as its ground voltage, but there exists a ground loop through MAINS earth ground to the power supply’s 0 volt output, then effectively the ground on your test circuit is actually -10 volts relative to the host PC. Connecting your *Host Adapter* will immediately short out the test circuit’s power supply and potentially damage all devices present in the loop. #### **Identifying if a Ground Loop is Present**[](#identifying-if-a-ground-loop-is-present) [Section titled “Identifying if a Ground Loop is Present ”](#identifying-if-a-ground-loop-is-present-) To identify a potential ground loop between the host adapter and the test circuit, you could check the resistance between the test circuit ground and the host adapter’s ground. While the host adapter is connected to the PC, if the resistance reads infinite on a multi-meter, then the grounds are isolated. Otherwise, they are connected, and a ground loop exists. If a ground loop is present, extra care should be taken, as highlighted below, before connecting the host adapter ground to the test circuit ground. If you believe there is a ground loop between the test circuit and the host PC but you are uncertain if the grounds on both sides you plan to use are at the same potential, there is a quick test you can perform with a multi-meter. If you happen to have a large resistor (> 10K ohm), there is an additional test you can perform. 1. Connect the host adapter to the PC but not the test circuit. 2. Measure the voltage between the ground pin on the host adapter and the ground pin on the test circuit. 3. If there is a ground loop and you measure a voltage greater than about +/- 100mV, then a common mode ground current may occur when they are connected, damaging your equipment. 4. If there is a ground loop and you measure a voltage smaller than about +/- 100mV, then it is safe to connect the ground pins. 5. If there is not a ground loop or you are not sure there is a ground loop, then the voltage may drift significantly. If you are SURE there is no ground loop, then it is safe to connect the grounds. If you are not sure there is a ground loop or would like to perform another test anyway, connect the resistor (\~10K) between the two grounds and then measure the voltage across the resistor. * If you see a voltage that indicates a noticeable current, then there is a ground loop between devices and you should not connect the grounds together. * If you see an insignificant voltage across the resistor, then either there is no ground loop or there is a ground loop, but both grounds are at the same reference. It is safe to connect the host adapter. #### **Identifying If Your Test Circuit Is Isolated From The PC**[](#identifying-if-your-test-circuit-is-isolated-from-the-pc) [Section titled “Identifying If Your Test Circuit Is Isolated From The PC ”](#identifying-if-your-test-circuit-is-isolated-from-the-pc-) The test circuit’s local ground is isolated from the host PC when one of the following is true: * The test circuit is battery-powered and has no other electrical connections to the host PC or devices powered from MAINS power. * The test circuit is powered from an isolated power supply that does NOT short MAINS earth ground to the output ground. Bench top supplies with a separate green earth ground terminal do this. USB wall adapters also do this. Common AC power adapters (chargers, “wall warts”) with 2-prong plugs are also isolated. Most power supplies do have transformers that can provide isolation if implemented properly. * The Host PC is a laptop running from a battery or is plugged into an instrumentation isolation transformer. Note that normal isolation transformers connect earth ground for human safety reasons. *Warning:* When working in an electrically isolated state, keep in mind that floating grounds can be dangerous to the operator. When operating equipment with a floating ground, please review and follow appropriate safety measures. #### **Using an Isolated Wall Adapter to Power the Test Circuit**[](#using-an-isolated-wall-adapter-to-power-the-test-circuit) [Section titled “Using an Isolated Wall Adapter to Power the Test Circuit ”](#using-an-isolated-wall-adapter-to-power-the-test-circuit-) Using isolated wall adapters such as USB wall adapters to power the test circuit will isolate its ground from MAINS ground, although that does not always eliminate ground loops. For example, if the test circuit was connected to the same computer that the host adapter is connected to, then a ground loop is formed. #### **Are Binho Host Adapters Safe to Use in the Presence of Ground Loops?**[](#is-the-binho-host-adapter-safe-to-use-in-the-presence-of-ground-loops) [Section titled “Are Binho Host Adapters Safe to Use in the Presence of Ground Loops? ”](#are-binho-host-adapters-safe-to-use-in-the-presence-of-ground-loops-) Yes, they are completely safe to use as long as both grounds are at the same voltage level and as long as you only connect the host adapter ground to the ground of the test circuit. # System Requirements **System Requirements** Both the *Binho Nova* and *Binho Supernova Multi-Protocol USB Host Adapters* have been meticulously designed to ensure compatibility with a wide range of systems. **Common Features**: * **USB Compatibility**: Each device is structured to work with systems possessing a USB 2.0 port or higher. * **USB Cable**: While the supplied USB cable comes with a Type-A male connector, owing to its ubiquity, users have the flexibility to employ other USB cables that better match their host device’s mating connector. * **Broad OS Support**: Leveraging the USB Communications Device Class standard driver, these host adapters are capable of interfacing with any operating system that extends support for this USB device category. This encompasses all modern versions of Windows (starting with Windows Vista), macOS, Ubuntu, and even Android-based mobile platforms. * **Single-board Computer Compatibility**: Given the universal nature of their design, both the Binho Nova and Binho Supernova Multi-Protocol USB Host Adapters are readily compatible with numerous single-board computers, including but not limited to the Raspberry Pi. **Binho Nova Specifics**: * **USB Class**: Utilizes the CDC (USB Communications Device Class) standard, ensuring compatibility across a variety of systems. **Binho Supernova Specifics**: * **USB Class**: Operates based on the HID (Human Interface Devices) standard, offering a wider array of interfacing opportunities. * **Interface Ports**: Apart from the general USB connectivity, the Supernova features multiple protocol-specific ports including Qwiic for I2C and dedicated ports for I3C. This advanced design promotes flexibility in connection options, catering to a broader spectrum of use-cases. By endorsing such broad compatibility and flexibility, both the Binho Nova and Binho Supernova ensure that users, irrespective of their system preferences, can harness the full potential of these devices for their embedded system needs. # Updating Firmware **Auto Firmware Update via Binho Mission Control (for installing the latest supported firmware)** If you intend to have the most plug-and-play experience with the Binho Host Adapters, this process allows you to prepare them for use with Mission Control with just a few clicks. 1. **Launch Binho Mission Control**: Start up the application after ensuring it’s properly installed. 2. **Connect the Host Adapter**: Plug in your Binho Nova, Supernova or Pulsar host adapter to your computer. 3. **Navigate to the Connection**: Access the Connection menu within the application. 4. **Mount the Host Adapter**: Choose your connected device from the list and initialize the connection. You should see the incompatibility firmware or the recommended update dialogs from here. (If your device connects without any warning, you already have the latest firmware!) You should see a button in both dialogs prompting “Update Firmware”. Click it to initiate the autoinstall of the latest firmware update: .png) Incompatible firmware dialog > Important Note: > > For the autoupdate to be successful, you must ensure you > > * Maintain the host adapter connected via USB. > * Have a stable internet connection. > * Ensure the PC remains powered on. The app should guide you in the installation process, and once it is done, click “OK” to close the dialog. In some cases, if your firmware version is not the latest, you may still be able to use it within the app, although you will be prompted to update to the newest version. Suppose you decide to keep using the app nonetheless. In that case, you may update to the latest firmware version later by using the “Update Firmware” button below the device data table of the connected device: .png) Device Info for an older supported firmware version **Manual Firmware Update via Binho Mission Control (for specific firmware versions)** Ensuring your Binho host adapter operates with the latest capabilities is crucial. With Binho Mission Control, updating your firmware is streamlined, and here’s how: 1. **Launch Binho Mission Control**: Start up the application after ensuring it’s properly installed. 2. **Connect the Host Adapter**: Plug in your Binho Nova, Supernova or Pulsar host adapter to your computer. 3. **Navigate to the Connection**: Access the Connection menu within the application. 4. **Mount the Host Adapter**: Choose your connected device from the list and initialize connection. 5. **Access Bootloader Mode**: On the right side of the interface, click the “ENTER BOOTLOADER MODE” button. The host adapter will transition to a mode that’s ready to receive new firmware. 6. **Transfer the Firmware**: Drag and drop or copy/paste the firmware file onto the device, just as you would with a standard USB storage device. 7. **Firmware Verification**: Post-update, it’s good practice to ensure the firmware version on the host adapter reflects the recent update. This can usually be checked within the device information section.  Remember, regular updates equip your device with the newest functionalities and security patches. Make it a habit! ## **Supernova Firmware Update via script** [Section titled “Supernova Firmware Update via script”](#supernova-firmware-update-via-script) Danger IMPORTANT. Never load Pulsar firmware on a Supernova. Never load Supernova firmware on a Pulsar. Mixing them will cause severe malfunction that may require factory recovery. Stay very alert during this step. This guide explains how to enter boot mode on a Supernova device and manually update its firmware using Python. The process varies slightly depending on the firmware version and corresponding SDK version. Tip To avoid version conflicts between different SDKs, we strongly recommend using a Python virtual environment when performing these operations: ```bash python -m venv env source env/bin/activate # on Linux/macOS env\Scripts\activate # on Windows ``` Once the environment is activated, install the required SDK version. ### If Your Supernova Is Running Firmware v4.x [Section titled “If Your Supernova Is Running Firmware v4.x”](#if-your-supernova-is-running-firmware-v4x) To control a Supernova device running firmware v4.x, you must use **SupernovaSDK v4.2.0**. 1. Install the SDK: ```plaintext pip install binhosupernova==4.2.0 ``` 2. Run the following script to enter boot mode: ```python from binhosupernova.supernova import Supernova device = Supernova() device.onEvent(lambda response, system_message: print(f"Event: {response} {system_message}")) device.open() print("Entering boot mode...") print("If it takes too long, verify the firmware version.") print("Press ^C to exit the program.") device.enterBootMode(1) ``` 3. The Supernova LEDs should turn red. 4. The device will mount as a USB storage drive. 5. Drag and drop the desired `.gfi` firmware file into the drive. Example: * [supernova-app-crp-3.2.0.gfi](https://cdn.binho.io/fw/supernova/3.2.0/supernova-app-crp-3.2.0.gfi) (e.g. if you want to downgrade to v3) 6. LEDs should return to blue once flashing completes. ### If Your Supernova Is Running Firmware v3.x [Section titled “If Your Supernova Is Running Firmware v3.x”](#if-your-supernova-is-running-firmware-v3x) To control a Supernova device running firmware v3.x, you must use **SupernovaSDK v3.2.0**. 1. Install the SDK: ```plaintext pip install binhosupernova==3.2.0 ``` 2. Run the following script to enter boot mode: ```python from BinhoSupernova.Supernova import Supernova device = Supernova() device.open() device.onEvent(lambda response, system_message: print(f"Event: {response} {system_message}")) print("Entering boot mode...") print("If it takes too long, verify the firmware version.") print("Press ^C to exit the program.") device.enterBootMode(1) ``` 3. The Supernova LEDs should turn red. 4. The device will mount as a USB storage drive. 5. Drag and drop the desired `.gfi` firmware file into the drive. Example: * [supernova-app-crp-4.2.1.gfi](https://cdn.binho.io/fw/supernova/4.2.1/supernova-app-crp-4.2.1.gfi) (e.g. if you want to upgrade to v4) 6. LEDs should return to blue once flashing completes. ### Final Notes [Section titled “Final Notes”](#final-notes) * Boot mode may take a few seconds to activate. If nothing happens, confirm you’re using the appropriate SDK version for the currently installed firmware. ## **Pulsar Firmware Update via script** [Section titled “Pulsar Firmware Update via script”](#pulsar-firmware-update-via-script) Danger IMPORTANT. Never load Pulsar firmware on a Supernova. Never load Supernova firmware on a Pulsar. Mixing them will cause severe malfunction that may require factory recovery. Stay very alert during this step. This guide explains how to manually update the firmware on a Pulsar device using Python. The update process involves placing the device into boot mode, then flashing the appropriate `.gfi` firmware file by dragging and dropping it onto the device’s storage interface. Tip To avoid version conflicts between different SDKs, we strongly recommend using a Python virtual environment when performing these operations: ```bash python -m venv env source env/bin/activate # on Linux/macOS env\Scripts\activate # on Windows ``` Once the environment is activated, install the required SDK version. ### If Your Pulsar Is Running Firmware v4.x [Section titled “If Your Pulsar Is Running Firmware v4.x”](#if-your-pulsar-is-running-firmware-v4x) To control a Pulsar device running firmware v4.x, you must use **PulsarSDK v1.2.0**. 1. Install the SDK: ```plaintext pip install binhopulsar==1.2.0 ``` 2. Run the following script to enter boot mode: ```python from binhopulsar.pulsar import Pulsar device = Pulsar() device.onEvent(lambda response, system_message: print(f"Event: {response} {system_message}")) device.open() print("Entering boot mode...") print("If it takes too long, verify the firmware version.") print("Press ^C to exit the program.") device.enterBootMode(1) ``` 3. The Pulsar LEDs should turn red. 4. The device will mount as a USB storage drive. 5. Drag and drop the desired `.gfi` firmware file into the drive. Example: * [pulsar-app-3.2.0.gfi](https://cdn.binho.io/fw/pulsar/3.2.0/pulsar-app-3.2.0.gfi) (e.g. if you want to downgrade to v3) 6. LEDs should return to blue once flashing completes. ### If Your Pulsar Is Running Firmware v3.x [Section titled “If Your Pulsar Is Running Firmware v3.x”](#if-your-pulsar-is-running-firmware-v3x) To control a Pulsar device running firmware v3.x, you must use **PulsarSDK v0.3.0**. 1. Install the SDK: ```plaintext pip install binhopulsar==0.3.0 ``` 2. Run the following script to enter boot mode: ```python from BinhoPulsar.Pulsar import Pulsar device = Pulsar() device.onEvent(lambda response, system_message: print(f"Event: {response} {system_message}")) device.open() print("Entering boot mode...") print("If it takes too long, verify the firmware version.") print("Press ^C to exit the program.") device.enterBootMode(1) ``` 3. The Pulsar LEDs should turn red. 4. The device will mount as a USB storage drive. 5. Drag and drop the desired `.gfi` firmware file into the drive. Example: * [pulsar-app-4.2.1.gfi](https://cdn.binho.io/fw/pulsar/4.2.1/pulsar-app-4.2.1.gfi) (e.g. if you want to upgrade to v4) 6. LEDs should return to blue once flashing completes. ### Final Notes [Section titled “Final Notes”](#final-notes-1) * Boot mode may take a few seconds to activate. If nothing happens, confirm you’re using the appropriate SDK version for the currently installed firmware. ## Firmware Releases [Section titled “Firmware Releases”](#firmware-releases) ### Binho Supernova [Section titled “Binho Supernova”](#binho-supernova) #### Version 4.2.1 [Section titled “Version 4.2.1”](#version-421) Danger Note: this version is not compatible with Binho Mission Control 2.16.1 or older versions. Please, follow the instructions on [#if-your-supernova-is-running-firmware-v4.x](#if-your-supernova-is-running-firmware-v4.x "mention") if you want to downgrade to v3.2.0. #### Version 3.2.0 (Compatible with Binho Mission Control 2.16.1) [Section titled “Version 3.2.0 (Compatible with Binho Mission Control 2.16.1)”](#version-320-compatible-with-binho-mission-control-2161) ### Binho Pulsar [Section titled “Binho Pulsar”](#binho-pulsar) #### Version 4.2.1 [Section titled “Version 4.2.1”](#version-421-1) Danger Note: this version is not compatible with Binho Mission Control 2.16.1 or older versions. Please, follow the instructions on [#if-your-pulsar-is-running-firmware-v4.x](#if-your-pulsar-is-running-firmware-v4.x "mention") if you want to downgrade to v3.2.0. #### Version 3.2.0 (Compatible with Binho Mission Control 2.16.1) [Section titled “Version 3.2.0 (Compatible with Binho Mission Control 2.16.1)”](#version-320-compatible-with-binho-mission-control-2161-1) ### Binho Nova [Section titled “Binho Nova”](#binho-nova) #### Version 0.2.8 - Stable [Section titled “Version 0.2.8 - Stable”](#version-028---stable)