# USB GO BOX 2

This Companion module provides full integration with the **USB GO BOX 2** from **That Little Box** when the device is running in **Companion Mode**.  
It enables Companion to receive high-speed button press and release events for triggering actions, sending OSC, controlling show playback, and more.

> **Important:**  
> This module is **only compatible with the USB GO BOX 2**.  
> It does **not** work with the original USB GO BOX.

---

## Putting the USB GO BOX 2 into Companion Mode

Before Companion can communicate with the device, the GO BOX 2 must be switched into **Companion (Serial)** mode.

Use the **GO BOX 2 Settings App** and select:

**Settings → MIDI Mode → Companion (Serial)**

When Companion Mode is applied:

- The GO BOX 2 disables all MIDI output  
- The device sends button events to Companion over USB-Serial  
- **Rapid Mode is automatically enabled** to ensure the lowest latency and most responsive operation

This mode remains active until changed again in the Settings App.

---

## What This Module Does

When the GO BOX 2 is in Companion Mode:

- Each hardware button sends **press (down)** and **release (up)** events  
- Companion receives these events in real time  
- Feedbacks and variables update immediately  
- You can trigger any Companion action (OSC, HTTP, TCP, timelines, etc.) from the hardware

This allows the GO BOX 2 to act as a reliable physical control surface for Companion.

---

## Available Feedbacks

Feedbacks can be used as **Triggers** in Companion to fire actions based on button activity.

### **Button Down**
Returns **true** while a specific GO BOX 2 button is physically pressed.

**Option:**
- Button ID (1–6)

### **Button Up**
Returns **true** when a specific button is released.

**Option:**
- Button ID (1–6)

These are ideal for firing OSC cues, controlling playback, navigating shows, or any other Companion automation.

---

## Available Variables

These variables expose the most recent button activity and the state of each button.

### **`$(gobox:last_button)`**
Human-readable identifier of the most recent button event  
(e.g. `"1 / GO"`)

### **`$(gobox:last_event)`**
Indicates whether the last event was:
- `down`
- `up`

### **`$(gobox:last_button_id)`**
Numeric ID of the last pressed or released button (1–6)

### **Per-Button State Variables**
Each button has a state variable:

- `$(gobox:button_1_state)`
- `$(gobox:button_2_state)`
- `$(gobox:button_3_state)`
- `$(gobox:button_4_state)`
- `$(gobox:button_5_state)`
- `$(gobox:button_6_state)`

Each returns:
- `pressed`
- `released`

---

## Supported GO BOX 2 Buttons

The following six hardware buttons are available:

1. **GO**  
2. **STOP**  
3. **LAST**  
4. **NEXT**  
5. **LOAD**  
6. **PAUSE**

---

## Using the GO BOX 2 in Companion

A typical setup:

1. Open the **Triggers** menu in Companion  
2. Add a new trigger  
3. Choose:  
   **When feedback becomes true → Button Down → Button ID**  
4. Add the action you want to fire (OSC, HTTP, Companion control, etc.)

The GO BOX 2 becomes a dependable physical controller for show operations, cue firing, and system automation in Companion.

