하드웨어 빠른 시작

Revka는 물리적 마이크로컨트롤러 및 싱글 보드 컴퓨터를 에이전트 도구로 구동할 수 있습니다. 이 페이지에서는 방금 연결한 보드에서 GPIO 핀을 읽고 쓸 수 있는 에이전트를 구성하는 전 과정을 안내합니다. Revka가 부팅 시 USB 보드를 자동으로 감지하는 방법, 안정적인 별칭 할당 방식, 자동 감지되지 않은 보드를 수동으로 등록하는 방법, 그리고 이 모든 것을 제어하는 [hardware] / [peripherals] 설정을 다룹니다.

Raspberry Pi Pico, Arduino, ESP32, 또는 STM32 Nucleo를 처음 연결할 때 이 페이지를 참고하세요. 보드별 세부 정보(VID/PID, LED 핀, 메모리 맵)는 지원 보드 레퍼런스를, 펌웨어 플래싱은 펌웨어 플래싱을 참조하세요.

주의

하드웨어 지원은 hardware Cargo 기능(feature) 뒤에 컴파일됩니다. 이 기능 없이 빌드된 바이너리는 이 페이지의 명령어나 도구를 전혀 노출하지 않습니다. cargo build --release --features hardware로 빌드하고, 네이티브 Raspberry Pi GPIO를 사용하려면 peripheral-rpi를 추가하세요. Cargo 기능 플래그 & ADR을 참조하세요.

하드웨어를 두 서브시스템으로 나누는 방식

Revka는 하드웨어를 두 개의 협력 서브시스템으로 구성합니다. 보드가 어느 시스템에 속하는지 알면 등록 방법과 로드되는 도구를 파악할 수 있습니다.

서브시스템	관리 대상	보드 등록 방법	로드하는 도구
hardware	USB 수준 장치 레지스트리. 시리얼 포트를 스캔하고 VID/PID로 보드를 식별하며 별칭을 할당합니다.	부팅 시 자동 감지.	Pico GPIO/코드 도구(hardware 기능 빌드 시 항상 존재) 및 Aardvark I2C/SPI/GPIO 도구(어댑터 감지 시에만).
peripherals	설정 기반 보드 테이블. 명시적 전송 방식과 함께 config.toml에 나열된 보드.	revka peripheral add 또는 수동 [[peripherals.boards]] 항목.	시리얼/네이티브 GPIO 도구 및 설정된 보드의 보드 정보 도구.

첫 번째 보드(USB에 연결된 Pico 또는 Arduino)는 대부분 자동 감지로 처리됩니다. 부팅 후 보드를 연결했거나, USB ID가 인식되지 않거나, 비시리얼 전송 방식(네이티브 Raspberry Pi GPIO 또는 Arduino Uno Q 브리지)을 사용하는 경우에만 peripherals 테이블을 직접 편집합니다.

하드웨어 부팅 서브시스템

데몬이 시작되면(revka daemon) 하드웨어 부팅 루틴이 자동으로 실행됩니다. 별도로 호출할 명령어는 없습니다. 부팅 시 Revka는 다음을 수행합니다.

1. 스캔 — 모든 USB 시리얼 포트를 스캔하고 각 장치의 vendor/product ID를 내장 보드 레지스트리와 대조합니다.
2. 별칭 등록 — 알려진 보드에 안정적인 세션 범위 이름(pico0, arduino0, nucleo0, aardvark0 등)을 부여합니다.
3. 사전 등록 — [[peripherals.boards]] 설정에 나열된 보드를 미리 등록합니다(시리얼 전송은 첫 사용 시 지연 방식으로 열림).
4. 전송 연결 — 전송 방식을 연결하고, 존재하는 하드웨어에 따라 조건부로 도구를 로드합니다.
5. 컨텍스트 주입 — 감지된 장치 목록과 모든 하드웨어 컨텍스트 파일을 에이전트의 시스템 프롬프트에 추가하여 모델이 제어 가능한 대상을 인식하게 합니다.

별칭은 세션이 유지되는 동안 안정적으로 유지되며, 다음 데몬 재시작 시 초기화됩니다.

참고

도구 로드는 조건부입니다. Pico 도구(gpio_write, gpio_read, pico_flash, device_read_code, device_write_code, device_exec)는 hardware 기능이 컴파일되면 보드 연결 여부에 관계없이 항상 로드됩니다(보드가 없으면 “장치를 찾을 수 없음”을 반환). Aardvark 도구는 시작 시 어댑터가 감지된 경우에만 로드됩니다. 네이티브 Raspberry Pi 도구는 peripheral-rpi 기능이 빌드되고 /proc/device-tree/model이 Pi를 식별할 때만 로드됩니다.

USB 장치 자동 감지

데몬이 부팅 시 실행하는 것과 동일한 스캔을 온디맨드로 실행하여 Revka가 감지하는 내용을 정확히 확인할 수 있습니다.

revka hardware discover

USB devices:

  2e8a:000a  raspberry-pi-pico  ARM Cortex-M0+  MicroPython v1.21
  2341:0043  arduino-uno        (unknown arch)  —

Known boards: nucleo-f401re, nucleo-f411re, arduino-uno, arduino-mega, cp2102

discover는 플래그를 받지 않습니다. 각 장치의 USB vendor ID를 내장 레지스트리와 대조하며, 인식되지 않는 VID의 장치는 짧은 펌웨어 핑 핸드셰이크(약 300ms)로 프로빙되고 Revka 펌웨어로 응답한 경우에만 등록됩니다. 그 외 장치는 조용히 건너뜁니다.

보드 ID 및 별칭 접두사

보드	USB VID	별칭 접두사
Raspberry Pi Pico	0x2E8A	pico0, pico1, …
Arduino	0x2341	arduino0
ESP32 (CP2102)	0x10C4	esp0
STM32 Nucleo	0x0483	nucleo0
Total Phase Aardvark	0x2B76	aardvark0
알 수 없음 (펌웨어 핑 일치)	—	device0

장치 경로를 이미 알고 있고 해당 장치를 식별하려면 introspect를 사용하세요.

revka hardware introspect /dev/ttyACM0   # macOS/Linux
revka hardware introspect COM3           # Windows

Device at /dev/ttyACM0:

  VID:PID     0483:374b
  Board       nucleo-f401re
  Architecture ARM Cortex-M4
  Memory map  512 KB Flash, 128 KB RAM

전체 CLI 레퍼런스(타겟에 펌웨어 없이 probe-rs 칩 인트로스펙션을 수행하는 revka hardware info 포함)는 revka hardware & peripheral을 참조하세요.

첫 번째 보드 연결

USB에 연결된 Pico 또는 Arduino는 자동으로 감지됩니다. 데몬을 시작하고 에이전트에 사용을 요청하면 됩니다. 아래 안내는 보드를 연결한 시점에 관계없이 작동하도록 명시적으로 등록하는 과정입니다.

1. 하드웨어 지원으로 빌드하고 보드가 감지되는지 확인합니다.

   cargo build --release --features hardware
   revka hardware discover

   보드가 USB devices 목록에 별칭과 함께 표시되어야 합니다.

2. 보드를 등록합니다(자동 감지되지 않은 경우).

   revka peripheral add nucleo-f401re /dev/ttyACM0
   revka peripheral list

   이 명령은 ~/.revka/config.toml에 [[peripherals.boards]] 항목을 작성합니다. 온보드 Raspberry Pi GPIO의 경우 경로 대신 native를 사용하세요.

3. 새 보드를 인식하도록 데몬을 재시작합니다.

   revka daemon

   revka peripheral add는 설정을 변경하며, 이 변경 사항은 데몬 재시작 시에만 적용됩니다.

4. 에이전트에 핀 제어를 요청합니다. GPIO를 지원하는 보드가 하나만 연결된 경우 에이전트는 장치를 명시하지 않아도 gpio_write를 호출할 수 있습니다.

   revka agent -m "Turn on pin 25"

   에이전트가 gpio_write(pin=25, value=1)을 호출하면 Revka가 시리얼 프레임을 직렬화하고 보드가 응답합니다.

팁

설정을 편집하지 않고 단일 세션에 보드를 연결하려면 revka agent에 --peripheral <board>:<path>를 전달하세요. 예: revka agent --peripheral nucleo-f401re:/dev/ttyACM0. revka agent를 참조하세요.

설정을 통한 보드 등록

revka peripheral add <board> <path>는 설정 항목을 편리하게 작성하는 래퍼입니다. 동일한 내용을 ~/.revka/config.toml에 직접 작성하면 다음과 같습니다.

[peripherals]
enabled = true

[[peripherals.boards]]
board = "nucleo-f401re"
transport = "serial"
path = "/dev/ttyACM0"
baud = 115200

필드	타입	기본값	설명
board	string	—	보드 식별자: nucleo-f401re, nucleo-f411re, arduino-uno, arduino-uno-q, esp32, rpi-gpio.
transport	string	—	serial(USB/시리얼), native(로컬 GPIO, 예: Raspberry Pi), bridge(Arduino Uno Q 브리지 앱).
path	string	—	serial용 장치 경로. native의 경우 생략.
baud	integer	115200	시리얼 보드레이트.

참고

시리얼 전송은 지연 방식으로 열립니다. 포트는 시작 시가 아닌 첫 번째 명령 시점에 열립니다. 따라서 보드가 연결되지 않아도 데몬이 정상적으로 시작되며, revka peripheral add는 아직 연결되지 않은 보드에도 사용할 수 있습니다. 단, 보드의 도구를 로드하려면 데몬을 재시작해야 합니다.

[hardware] vs [peripherals]

위의 [peripherals] 섹션은 보드를 등록할 때 편집하는 보드 테이블입니다. 별도의 [hardware] 섹션은 USB 수준 서브시스템의 마스터 on/off 스위치와 전역 전송 힌트를 제공합니다.

키	타입	값	설명
[hardware].enabled	bool	true / false	USB 수준 하드웨어 서브시스템의 마스터 스위치.
[hardware].transport	string	native / serial / probe	감지된 보드의 기본 전송 모드.
[hardware].serial_port	string	예: /dev/ttyACM0	명시적 시리얼 포트 재정의.
[peripherals].enabled	bool	true / false	설정 기반 주변 장치 보드 서브시스템 활성화 여부.
[[peripherals.boards]]	table array	—	등록된 보드당 하나의 항목(위의 필드 참조).

전체 설정 키와 스키마는 revka config schema를 실행하고 설정 개요를 참조하세요.

하드웨어 감지 및 주변 장치 관리

두 CLI 그룹은 두 서브시스템에 각각 대응합니다.

• revka hardware — 읽기 전용 감지 및 식별(discover, introspect, info). USB 수준 서브시스템입니다.
• revka peripheral — 보드 등록, 플래싱, 설정(list, add, flash, flash-nucleo, setup-uno-q). 설정 기반 주변 장치 테이블을 관리합니다.

Discover & identify

revka hardware discover                  # enumerate connected USB boards
revka hardware introspect /dev/ttyACM0   # identify the device at a path
revka hardware info --chip nucleo-f401re # chip info via probe-rs (needs `probe`)

Register & flash

revka peripheral list                          # list configured boards
revka peripheral add nucleo-f401re /dev/ttyACM0
revka peripheral add rpi-gpio native           # native GPIO (Raspberry Pi)
revka peripheral flash                         # flash Arduino (arduino-cli)
revka peripheral flash-nucleo                  # build + flash Nucleo (probe-rs)
revka peripheral setup-uno-q --host 192.168.0.48

보드가 등록되면 에이전트는 도구를 통해 보드에 접근합니다. GPIO를 지원하는 보드가 정확히 하나만 연결된 경우 device 인수는 선택 사항입니다. 여러 보드가 있는 경우 별칭을 명시합니다(예: gpio_write(device="pico0", pin=25, value=1)). 네이티브 Raspberry Pi gpio_rpi_* 도구 및 Aardvark 비트마스크 GPIO를 포함한 전체 GPIO 도구 세트는 GPIO 도구를 참조하세요.

팁

Revka를 Raspberry Pi에서 직접 실행하는 것은 USB로 보드를 연결하는 것과 다릅니다. 네이티브 GPIO는 gpio_rpi_write / gpio_rpi_read(BCM 핀 번호)를 사용하며 peripheral-rpi 기능이 필요합니다. Pi는 부팅 시 자동으로 감지되므로 별도의 설정 항목이 필요 없습니다. Raspberry Pi (자체 호스팅)을 참조하세요.

하드웨어 컨텍스트 파일

자동 주입되는 장치 목록 외에도 Revka는 부팅 시 ~/.revka/hardware/의 Markdown 파일을 로드하여 에이전트의 시스템 프롬프트에 주입합니다. 이를 통해 코드를 수정하지 않고도 에이전트에 하드웨어 정보를 전달할 수 있습니다.

• ~/.revka/hardware/HARDWARE.md — 전역 하드웨어 노트.
• ~/.revka/hardware/devices/<alias>.md — 장치별 프로필(예: pico0.md).
• ~/.revka/hardware/skills/*.md — 하드웨어 스킬. 알파벳 순으로 로드됩니다.

mkdir -p ~/.revka/hardware/devices
cat > ~/.revka/hardware/devices/pico0.md <<'EOF'
# pico0 — Raspberry Pi Pico
Port: /dev/cu.usbmodem1101
Pin 25 is the onboard LED.
Use device_exec for blink loops rather than repeated gpio_write calls.
EOF

파일이 없으면 조용히 건너뜁니다. 네이티브 Raspberry Pi 감지는 부팅할 때마다 이 디렉터리에 자체 rpi0.md 프로필을 자동으로 기록합니다. 연결된 보드에서 루프나 반복적인 GPIO 작업을 수행할 경우, 호스트에서 gpio_write를 여러 번 호출하는 것보다 device_exec로 보드에서 코드를 실행하는 방식을 권장합니다.

다음 단계

지원 보드 레퍼런스 모든 보드의 VID/PID, LED 핀, 메모리 맵, 기능 플래그.

펌웨어 플래싱 Pico(UF2 + pico_flash), Arduino(arduino-cli), Nucleo(probe-rs).

GPIO 도구 gpio_write / gpio_read, 네이티브 RPi 도구, Aardvark 비트마스크 GPIO.

revka hardware & peripheral 감지, 등록, 플래싱을 위한 전체 CLI 레퍼런스.