Connecting physical USB and serial DMX interfaces requires proper operating system driver configuration. Unilighter communicates directly with hardware through browser WebUSB/WebSerial APIs or via the Unilighter Desktop app.

---

## 🪟 Windows Setup: WinUSB Driver for uDMX

Many uDMX dongles do not register automatically as generic WinUSB devices on Windows, requiring a standard driver assignment:

### Method 1: Official uDMX WinUSB Installer
1. Download the [uDMX USB Driver (WinUSB)](https://www.illutzmination.de/fileadmin/download/uDMX_Driver_WinUSB.zip).
2. Plug in your uDMX interface.
3. Extract and run the installer as Administrator.
4. Restart your browser or the Unilighter Desktop app.

### Method 2: Zadig Generic Driver Assignment
If Windows continues to flag the device with a yellow error badge in Device Manager:
1. Download and run [Zadig](https://zadig.akeo.ie/).
2. Select **Options $\rightarrow$ List All Devices**.
3. Choose your USB DMX device from the dropdown (e.g. `uDMX` or `USB DMX512`).
4. Select **WinUSB** as the target driver and click **Replace Driver** (or **Install Driver**).
5. Open Unilighter in Chrome, Edge, or Desktop and click **Connect** in [Device Patch](https://unilighter.cc/info/for-ai/docs/device-patch.md).

---

## 🐧 Linux Setup: Kernel Modules & Udev Permissions

Linux distributions typically require two configuration adjustments: releasing the kernel's automatic serial capture and granting non-root access permissions.

### 1. Releasing Kernel FTDI Capture (`ftdi_sio`)
By default, the Linux kernel automatically binds FTDI USB-to-serial chips as standard COM ports (`/dev/ttyUSB0`), preventing WebUSB from claiming direct hardware control.

- **Temporary Release**:
  ```bash
  sudo rmmod ftdi_sio
  ```
  *(Alternative command: `sudo modprobe -r ftdi_sio`)*

- **Persistent Blacklist** (if using dedicated WebUSB control):
  Create `/etc/modprobe.d/ftdi_sio.conf`:
  ```text
  blacklist ftdi_sio
  ```

### 2. Setting Up Udev Rules (Non-Root USB Access)
To access USB DMX dongles without running your browser as root:

1. Create a udev rules file:
   ```bash
   sudo nano /etc/udev/rules.d/99-unilighter-dmx.rules
   ```
2. Add the following rule matching generic uDMX / FTDI devices:
   ```text
   # uDMX
   SUBSYSTEM=="usb", ATTR{idVendor}=="16c0", ATTR{idProduct}=="05dc", MODE="0666", GROUP="plugdev"
   # FTDI USB-RS485 DMX
   SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6001", MODE="0666", GROUP="plugdev"
   ```
3. Reload udev rules and re-plug the interface:
   ```bash
   sudo udevadm control --reload-rules
   sudo udevadm trigger
   ```
4. Ensure your user is in the `plugdev` and `dialout` groups:
   ```bash
   sudo usermod -aG plugdev,dialout $USER
   ```

---

## 📱 Android USB OTG Emergency Setup

Unilighter can run a complete live show directly from an Android smartphone:

1. Connect your USB DMX dongle to your Android phone via a **USB OTG Adapter** (USB-C to USB-A).
2. Open Unilighter in **Chrome for Android**.
3. When prompted, tap **OK / Allow** on the Android system popup: *"Allow Chrome to access USB DMX512?"*
4. Select the interface in **[Device Patch](https://unilighter.cc/info/for-ai/docs/device-patch.md)**.

> [!TIP]
> Use a powered USB-C OTG hub with Power Delivery (PD) to keep your phone charged during live performances.

---

## 🍏 macOS Driver Notes

- **macOS Ventura, Sonoma & Newer**: Modern macOS versions have built-in WebUSB and WebHID drivers that recognize class-compliant USB DMX and MIDI hardware out of the box.
- **Security & Permissions**: When connecting in Google Chrome or Unilighter Desktop, accept the prompt to allow access to the USB accessory.