# USB-Relay Mac

This guide provides the workflow for setting up the **Bitfocus Buttons USB-Relay** on a macOS machine. We will use the **Global LaunchAgent** method, which ensures the relay starts for any user who logs in and has the necessary permissions to access physical Stream Deck hardware.

---

### Phase 1: Enable Automatic Login

Since a LaunchAgent requires an active user session to access USB hardware, your Mac must bypass the login screen after a reboot.

- Open **System Settings** > **Users & Groups**.
- Locate **"Automatically log in as"** and select your primary account.
- **Troubleshooting:** If the option is greyed out:
    - Go to **Privacy & Security > FileVault** and turn it **OFF**. Automatic login is incompatible with FileVault.
    - Ensure the account uses a "Local Password" rather than just an iCloud login.

---

### Phase 2: Create the Global LaunchAgent

This configuration tells macOS to run the relay as a background service for any active user.

**Open Terminal** (Applications > Utilities).

**Create the configuration file:**


```bash
sudo nano /Library/LaunchAgents/com.bitfocus.usb-relay.plist

```

**Paste this exact XML:  T**o run USB relay in server mode it will announce it self with mdns

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.bitfocus.usb-relay</string>

    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/bitfocus-buttons-usb-relay-headless</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>StandardErrorPath</key>
    <string>/tmp/bitfocus-usb.err</string>

    <key>StandardOutPath</key>
    <string>/tmp/bitfocus-usb.out</string>
</dict>
</plist>
```

**Save and Exit:** Press `Ctrl+O`, `Enter`, then `Ctrl+X`.


**Or use this XML:** if you want to run the USB relay as a client you need to point it to your Buttons server (edit the ip and port in the XML) 

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.bitfocus.usb-relay</string>

    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/bitfocus-buttons-usb-relay-headless</string>
        <string>-buttonsAddress</string>
        <string>'your buttons server ip':'your server port'</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>StandardErrorPath</key>
    <string>/tmp/bitfocus-usb.err</string>

    <key>StandardOutPath</key>
    <string>/tmp/bitfocus-usb.out</string>
</dict>
</plist>

```

---

### Phase 3: Permissions & Security

Global services require specific ownership to be trusted by macOS.

**Set System Ownership**
 

```bash
sudo chown root:wheel/lLbrary/LaunchAgents/com.bitfocus.usb-relay.plist
```

```bash
sudo chmod 644 /Library/LaunchAgents/com.bitfocus.usb-relay.plist
```

**Grant Hardware Access (Crucial):**

Go to **System Settings > Privacy & Security > Input Monitoring**.

Click the **+** button.

Press `Cmd + Shift + G`, type `/usr/local/bin/`, and hit **Enter**.

Select `bitfocus-buttons-usb-relay-headless` and click **Open**.

**Ensure the toggle is ON.**

---

### Phase 4: Activation

Start the service in your current session.

**Load the relay:**

```bash
launchctl bootstrap gui/$(id -u) /Library/LaunchAgents/com.bitfocus.usb-relay.plist
```

---

### Phase 5: The Maintenance Toolkit

Use these commands to monitor and troubleshoot your relay station.

#### 1. The Health Check

Verify the process is alive. A number in the first column is the **PID** (Process ID), which confirms it is running:

```bash
launchctl list | grep bitfocus
```

#### 2. Live Log Monitoring

Watch the relay's internal messages. This will show you when Stream Decks are connected or if there is a network error:

```bash
tail -f /tmp/bitfocus-usb.out
```

#### 3. The "Hardware Kick"

If the relay stops responding to button presses or you've plugged in a new device, force a restart without rebooting the Mac:


```bash
launchctl kickstart -k gui/$(id -u)/com.bitfocus.usb-relay
```

#### 4. Verify Privacy Status

If the logs show "Permission Denied" but the program is running, run this to see if macOS is "quarantining" the binary:

```bash
xattr -d com.apple.quarantine /usr/local/bin/bitfocus-buttons-usb-relay-headless
```

#### 5. Full Service Removal

To completely remove the autostart configuration:

```bash
sudo launchctl bootout gui/$(id -u) /Library/LaunchAgents/com.bitfocus.usb-relay.plist
```

```bash
sudo rm /Library/LaunchAgents/com.bitfocus.usb-relay.plist
```

**Pro Tip:** If you are running this on a headless Mac Mini, it is highly recommended to use a "HDMI Dummy Plug" or "Ghost Adapter." This forces macOS to fully initialize the WindowServer and Graphics drivers, which leads to much more stable USB performance for Stream Decks.
