Home

Welcome to the documentation for the Pirate MIDI Device API. We've created a robust API for developers who wish to integrate Pirate MIDI devices into plugins, applications, or hardware setups, without the constraints of the MIDI protocol.

This documentation is currently undergoing work to prepare for a number of changes being introduced with Bridge OS 2.0

The API consists of two main types of communication: commands and data. A command is used to tell the device or application what type of data is about to be transferred and is used to set the internal state machine on the device. Commands are primarily sent from the host application to the device. Data is sent in response to, or after a command has been issued, and is transferred in JSON format. This data MUST be transmitted in a 'minified' format with no additional whitespaces or formatting characters.

Command Overview

CHCK

Check: This queries the device about what type of device it is, what firmware version is it running, and other essential information.

CTRL

Control: Provides control over basic device functions such as footswitch behavior, bank navigation, and reset modes.

DREQ

Data Request: Requested by the host application to the device. This prompts the device for global, bank, or configuration data.

DTXR

Data Transmit Request: Informs the device that the host application wishes to transmit new data.

RSET

Reset: Resets the communication state of the device to exit a command state if required.

---

All commands require a response packet from the device. For commands requesting data, the response is the required data packet, however, for commands such as CHCK and RSET, not data is returned. In this case, the device sends an 'ok' reply packet to indicate the reception.

The most basic command, RSET, has the following interaction:

Host appplication: RSET~

Device response: ok~

For other commands that require additional arguments, the command is sent, and the host application must wait for the 'ok' confirmation packet before sending the argument. This is demonstrated with the CTRL command:

Host appplication: CTRL~

Device response: ok~

Host appplication: bankUp~

Device response: ok~

The device will the increment to the next bank.

Some arguments also require parameters, separated by a comma:

Host appplication: CTRL~

Device response: ok~

Host appplication: goToBank,9~

Device response: ok~

The device will then jump directly to bank 9.

---

Data

Data packets may be transmitted from the device in response to a command, or by the host application as determined by the previously sent command. All data packets follow JSON formatting with the exception of the ID echo and terminating character. An example response to the CHCK command is detailed below:

Host application: CHCK~

Device response:

{
  "chckResponse": {
    "deviceModel": "Bridge6",
    "firmwareVersion": "1.0.0.1",
    "hardwareVersion": "1.0.1",
    "uId": "ffffffffffffffffffffffff",
    "deviceName": "deviceName",
    "profileId": "f9406"
  }
}