[RaspberryPI] 라즈베리 파이 dwc 커스텀 usb_hid_gadget 설정

라즈베리 파이를 USB 키보드/마우스로 변신시키기 (TinyPilot HID 설정 가이드)

TinyPilot과 같은 원격 KVM(Keyboard, Video, Mouse) 프로젝트를 구성할 때, 라즈베리 파이는 단순히 작은 컴퓨터가 아니라 연결된 서버를 제어하는 주변 장치 역할을 해야 합니다. 즉, 라즈베리 파이의 USB 포트가 키보드와 마우스처럼 동작해야 합니다.

이번 포스팅에서는 라즈베리 파이가 USB '호스트'가 아닌 USB '가젯(Gadget)'으로 작동하도록 설정하는 과정을 상세히 다룹니다. 이 과정은 커널 모듈을 이해하고, USB 장치의 동작 방식을 직접 구성하는 내용을 포함합니다.

---

1. 핵심 용어 이해하기

본격적인 설정에 앞서, 이 작업에 필요한 세 가지 핵심 요소(UDC, dwc2, g_ether)와 그 관계를 이해해야 합니다.

하드웨어와 소프트웨어의 계층 구조

이들의 관계는 하드웨어에서 상위 응용 프로그램으로 올라가는 계층 구조로 이해하면 쉽습니다.

• 최하위 계층: UDC (USB Device Controller)
  • USB 통신을 물리적으로 처리하는 하드웨어 컨트롤러입니다. USB 포트 자체를 관리하며, 호스트 PC와의 직접적인 데이터 통신을 담당합니다.
• 중간 계층: dwc2 (USB 컨트롤러 드라이버)
  • UDC 하드웨어를 제어하는 소프트웨어 드라이버입니다. 이 드라이버를 활성화해야 라즈베리 파이가 USB 주변 장치 모드(Gadget Mode)로 동작할 수 있습니다.
• 상위 계층: g_ether / HID (USB Gadget 드라이버)
  • dwc2 위에서 동작하며, 라즈베리 파이에게 특정 USB 장치의 '정체성'을 부여하는 드라이버입니다. 예를 들어, g_ether는 가상 네트워크 어댑터로, hid는 키보드나 마우스 같은 입력 장치로 동작하게 합니다.

핵심 문제: UDC는 한 번에 하나의 Gadget 드라이버만 지원합니다. 라즈비안 OS는 기본적으로 네트워크 연결을 위해 g_ether 모듈을 활성화하는 경우가 많습니다. g_ether가 UDC를 점유하고 있으면, 우리가 원하는 키보드/마우스(HID) Gadget을 설정할 수 없습니다. 따라서 가장 먼저 g_ether의 점유를 해제해야 합니다.

---

2. Step-by-Step: 라즈베리 파이 USB Gadget 설정

Step 1: 기존 g_ether 모듈 비활성화 및 dwc2 활성화

먼저 UDC를 점유하고 있을 수 있는 g_ether 모듈을 제거하고, USB Gadget 모드의 기반이 되는 dwc2를 활성화합니다.

#!/bin/bash



# USB Gadget 설정 디렉토리

GADGET_DIR="/sys/kernel/config/usb_gadget/g1"



# 커널 모듈 로드

sudo modprobe libcomposite



# --- 기존 설정이 있다면 깨끗하게 제거 ---

if [ -d "$GADGET_DIR" ]; then

  echo "Removing existing gadget configuration..."

  echo "" | sudo tee $GADGET_DIR/UDC > /dev/null 2>&1

  sleep 1

  # 내부 설정 파일들을 초기화하고 링크를 제거

  # ... (이 부분은 실제 구현에서 더 정교하게 처리될 수 있음)

  sudo rm -rf $GADGET_DIR

fi



echo "Creating USB Gadget configuration..."



# --- 1. 가젯 기본 정보 설정 ---

sudo mkdir -p $GADGET_DIR

cd $GADGET_DIR



echo 0x1d6b | sudo tee idVendor       # Linux Foundation

echo 0x0104 | sudo tee idProduct      # Multifunction Composite Gadget

echo 0x0100 | sudo tee bcdDevice      # v1.0.0

echo 0x0200 | sudo tee bcdUSB         # USB 2.0



sudo mkdir -p strings/0x409

echo "tinypilot-rpi" | sudo tee strings/0x409/serialnumber

echo "TinyPilot" | sudo tee strings/0x409/manufacturer

echo "TinyPilot KVM Device" | sudo tee strings/0x409/product



# --- 2. 기능(Functions) 정의: 키보드 + 마우스 ---



# 키보드 기능 설정

sudo mkdir -p functions/hid.usb0

echo 1 | sudo tee functions/hid.usb0/protocol    # 1 = Keyboard

echo 1 | sudo tee functions/hid.usb0/subclass    # 1 = Boot Interface Subclass

echo 8 | sudo tee functions/hid.usb0/report_length

echo -ne "\\x05\\x01\\x09\\x06\\xA1\\x01\\x05\\x07\\x19\\xE0\\x29\\xE7\\x15\\x00\\x25\\x01\\x95\\x08\\x75\\x01\\x81\\x02\\x95\\x01\\x75\\x08\\x81\\x03\\x95\\x05\\x75\\x01\\x05\\x08\\x19\\x01\\x29\\x05\\x91\\x02\\x95\\x01\\x75\\x03\\x91\\x03\\x95\\x06\\x75\\x08\\x15\\x00\\x25\\x65\\x05\\x07\\x19\\x00\\x29\\x65\\x81\\x00\\xC0" | sudo tee functions/hid.usb0/report_desc



# 마우스 기능 설정

sudo mkdir -p functions/hid.mouse

echo 0 | sudo tee functions/hid.mouse/protocol

echo 0 | sudo tee functions/hid.mouse/subclass

echo 5 | sudo tee functions/hid.mouse/report_length

# TinyPilot은 절대 좌표를 사용하는 특별한 마우스 리포트 디스크립터가 필요합니다.

# 출처: https://github.com/tiny-pilot/ansible-role-tinypilot

echo -ne "\\x05\\x01\\x09\\x02\\xA1\\x01\\x05\\x09\\x19\\x01\\x29\\x08\\x15\\x00\\x25\\x01\\x95\\x08\\x75\\x01\\x81\\x02\\x05\\x01\\x09\\x30\\x09\\x31\\x16\\x00\\x00\\x26\\xFF\\x7F\\x75\\x10\\x95\\x02\\x81\\x02\\x09\\x38\\x15\\x81\\x25\\x7F\\x75\\x08\\x95\\x01\\x81\\x06\\x05\\x0C\\x0A\\x38\\x02\\x15\\x81\\x25\\x7F\\x75\\x08\\x95\\x01\\x81\\x06\\xC0" | sudo tee functions/hid.mouse/report_desc



# --- 3. 구성(Configuration)에 기능들 연결 ---

sudo mkdir -p configs/c.1/strings/0x409

echo "Composite HID Config" | sudo tee configs/c.1/strings/0x409/configuration

echo 250 | sudo tee configs/c.1/MaxPower # 250mA



sudo ln -s functions/hid.usb0 configs/c.1/

sudo ln -s functions/hid.mouse configs/c.1/



# --- 4. UDC에 가젯 연결하여 활성화 ---

UDC_DEVICE=$(ls /sys/class/udc | head -n 1)

if [ -z "$UDC_DEVICE" ]; then

  echo "UDC가 발견되지 않았습니다. dwc2 설정이 올바른지 확인하십시오."

  exit 1

fi

echo $UDC_DEVICE | sudo tee UDC



echo "USB HID Gadget 설정이 완료되었습니다."

이후 추가 된 내용이 있습니다 : https://developsvai5096.tistory.com/110

Step 3: 스크립트 실행 및 자동화

1. 실행 권한 부여 및 실행
2. sudo chmod +x /usr/local/bin/setup_usb_gadget.sh sudo /usr/local/bin/setup_usb_gadget.sh
3. 부팅 시 자동 실행
   위 스크립트가 설정하는 /sys 경로는 임시 파일 시스템이므로 재부팅 시 초기화됩니다. 따라서 매 부팅 시마다 스크립트가 실행되도록 설정해야 합니다. rc.local 파일이나 systemd 서비스를 이용하는 것이 일반적입니다.

Step 4: 최종 확인

모든 설정이 완료되면, 시스템은 이 가상 HID 장치를 제어할 수 있는 디바이스 파일을 생성합니다.

ls /dev/hidg*

/dev/hidg0 (키보드), /dev/hidg1 (마우스)와 같은 파일들이 보인다면 성공입니다. 이제 TinyPilot과 같은 애플리케이션이 이 파일에 데이터를 쓰는 방식으로 원격지의 컴퓨터에 키보드 입력과 마우스 움직임을 전송할 수 있습니다.