# USB-Relay Linux

Connects locally attached USB HID devices (Elgato Stream Deck, etc.) to a [Bitfocus Buttons](https://bitfocus.io/) installation over WebSocket.

By default the relay runs in **server mode**: it listens on port `3040` and announces itself via mDNS so that Buttons can discover and connect to it automatically. No configuration is needed for this mode.

## Installation

For a desktop Linux you can double-click the .Deb file to start the installation.

Or you can use the Terminal navigate to the file and use the following command.

```bash
sudo apt install ./bitfocus-buttons-usb-relay-headless_*.deb
```

The installer will:

- Install the necessary program files
- Create a dedicated `buttons` system user
- Install udev rules so USB devices are accessible without root
- Enable and start the `bitfocus-buttons-usb-relay` systemd service

Check the service status with:

```bash
systemctl status bitfocus-buttons-usb-relay
```

```bash
journalctl -u bitfocus-buttons-usb-relay -f
```

## Configuring client mode

If you cannot rely on mDNS discovery and want the relay to connect **outbound** to a specific Buttons server, edit `/etc/default/bitfocus-buttons-usb-relay`:

`EXTRA_ARGS="-buttonsAddress 192.168.1.10:3000"`

Then restart the service:

```bash
sudo systemctl restart bitfocus-buttons-usb-relay
```

## Stopping/Starting the service

Stop the service

```bash
sudo systemctl stop bitfocus-buttons-usb-relay
```

Start the service

```bash
sudo systemctl start bitfocus-buttons-usb-relay
```

 
## Autostarting the service

Disable autostart of the service

```bash
sudo systemctl disable bitfocus-buttons-usb-relay
```

Enable autostart of the service

```bash
sudo systemctl enable bitfocus-buttons-usb-relay

```

## Uninstall

```bash
sudo apt remove bitfocus-buttons-usb-relay-headless
```

To also remove the `buttons` user and all service data:

```bash
sudo apt purge bitfocus-buttons-usb-relay-headless
```

 
## License

See `EULA.txt` for the full End User License Agreement.
