revka hardware 및 peripheral

Revka는 물리적 마이크로컨트롤러와 싱글보드 컴퓨터를 에이전트 도구로 구동할 수 있습니다. 두 가지 CLI 커맨드 그룹이 해당 하드웨어를 관리합니다.

• revka hardware — USB로 연결된 보드(Pico, Arduino, ESP32, Nucleo)를 읽기 전용으로 검색·식별하고, probe-rs를 통해 칩 정보를 조회합니다.
• revka peripheral — config.toml에 보드를 등록하고, Revka 펌웨어를 플래싱하며, 더 복잡한 보드(Arduino Uno Q 브리지, STM32 Nucleo)를 설정합니다.

새 보드를 연결했을 때, 에이전트가 보드와 통신하기 전에 펌웨어를 플래싱해야 할 때, 또는 어떤 장치가 어느 시리얼 포트에 연결되어 있는지 확인하고 싶을 때 이 명령어를 사용하십시오. 보드가 등록되면 에이전트는 JSON-over-serial 프로토콜을 통해 gpio_write / gpio_read 같은 도구로 보드를 호출합니다.

참고

하드웨어 지원은 hardware Cargo 기능 플래그(cargo build --release --features hardware) 뒤에 컴파일됩니다. 실시간 칩 조회는 추가로 probe 기능이 필요하고, 네이티브 Raspberry Pi GPIO는 peripheral-rpi가 필요합니다. 이 기능들 없이 빌드된 바이너리는 해당 명령어나 도구를 노출하지 않습니다. Cargo 기능 플래그 및 ADR을 참고하십시오.

하드웨어에 대한 더 자세한 내용 — 보드별 레퍼런스, GPIO 도구, 플래싱, Aardvark 어댑터 — 은 하드웨어 퀵스타트 및 지원 보드 레퍼런스를 참고하십시오. config를 수정하지 않고 단일 세션에서 보드를 연결하려면 revka agent에 설명된 --peripheral 플래그를 사용하십시오.

revka hardware

revka hardware discover                      # enumerate connected USB boards
revka hardware introspect /dev/ttyACM0       # identify the device at a path
revka hardware introspect COM3               # Windows path
revka hardware info                          # chip info via probe-rs (default chip)
revka hardware info --chip STM32F401RETx     # chip info for a specific target

서브커맨드	인수 / 플래그	설명
discover	—	모든 USB 시리얼 포트를 스캔하고, VID/PID를 내장 보드 레지스트리와 대조하여 세션 별칭을 할당합니다.
introspect	<path> (필수)	지정한 장치 경로의 상세 USB 정보를 읽고, 레지스트리와 대조하여 보드 이름과 아키텍처를 보고합니다.
info	--chip <NAME>	probe-rs를 통해 USB/SWD로 칩 이름, 아키텍처, 메모리 맵을 읽습니다. 대상 장치에 펌웨어가 없어도 됩니다. 기본 칩: STM32F401RETx.

연결된 보드 검색

revka hardware discover는 모든 USB 시리얼 포트를 스캔하고, 각 장치의 USB 벤더/제품 ID를 내장 레지스트리와 대조한 뒤, pico0, arduino0, esp0, nucleo0, device0와 같은 안정적인 세션 별칭을 할당합니다. 인식되지 않는 VID를 가진 장치는 짧은 펌웨어 핑 핸드셰이크로 탐색되며, Revka 펌웨어로 응답하는 보드만 등록되고 나머지는 자동으로 건너뜁니다.

revka hardware discover

USB devices:

  2e8a:000a  (unknown)  —  Board in FS mode
  2341:0043  arduino-uno        (unknown arch)  —

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

데몬이 시작될 때 동일한 스캔이 자동으로 실행되므로, 별도 명령 없이 검색된 보드가 등록되고 해당 도구가 로드됩니다. 별칭은 세션 동안 유지되며, 데몬을 재시작하면 초기화됩니다.

보드	USB VID	별칭 접두사
Raspberry Pi Pico	0x2E8A	pico0, pico1, …
Arduino	0x2341	arduino0
ESP32 (CP2102)	0x10C4	esp0
STM32 Nucleo	0x0483	nucleo0
Total Phase Aardvark	0x2B76	device0, device1, …

장치 경로 조회

장치 경로를 이미 알고 있다면 revka hardware introspect <path>로 해당 장치를 열어 USB 세부 정보를 읽고, 레지스트리와 대조하여 보드 이름, 아키텍처, 메모리 맵을 출력합니다.

revka hardware introspect /dev/ttyACM0

Device at /dev/ttyACM0:

  VID:PID     0483:374b
  Board       nucleo-f401re
  Architecture ARM Cortex-M4
  Memory map  Build with --features probe for live memory map via USB

probe-rs로 칩 정보 읽기 (info)

revka hardware info는 온보드 ST-Link를 통해 USB로 STM32 Nucleo에 연결하고, SWD를 통해 칩 식별 정보와 메모리 맵을 직접 읽습니다. 대상 장치에 펌웨어가 없어도 동작합니다. 공장 프로그래밍 및 칩 식별에 유용합니다.

cargo build --release --features hardware,probe
revka hardware info --chip nucleo-f401re

Connecting to nucleo-f401re via USB (ST-Link)...

Chip: STM32F401RETx
Architecture: Armv7em

Memory map:
  RAM:   0x20000000 - 0x2001FFFF (128 KB)
  Flash: 0x08000000 - 0x0807FFFF (512 KB)

Info read via USB (SWD) — no firmware on target needed.

주의

info는 hardware 외에 probe 기능도 필요합니다. 없을 경우, 명령어는 빌드 안내를 출력하고 칩을 읽는 대신 종료됩니다.

revka peripheral

revka peripheral은 에이전트가 사용할 수 있도록 보드를 등록하고, 필요한 보드에 Revka 펌웨어를 플래싱합니다. 등록된 주변 장치는 에이전트 루프에서 도구로 사용할 수 있게 됩니다.

revka peripheral list                                  # list configured boards
revka peripheral add nucleo-f401re /dev/ttyACM0        # register a serial board
revka peripheral add rpi-gpio native                   # register native GPIO (RPi)
revka peripheral add esp32 /dev/ttyUSB0
revka peripheral add arduino-uno COM3
revka peripheral flash                                 # flash Arduino (Revka firmware)
revka peripheral flash --port /dev/cu.usbmodem12345
revka peripheral flash -p COM3
revka peripheral setup-uno-q                           # deploy Uno Q bridge app
revka peripheral setup-uno-q --host 192.168.0.48
revka peripheral flash-nucleo                          # build + flash Nucleo firmware

서브커맨드	인수 / 플래그	설명
list	—	[peripherals] 아래에 현재 설정된 주변 장치 목록을 표시합니다.
add	<board> <path>	config.toml에 보드를 등록합니다. path는 시리얼 장치 경로이거나, 온보드 GPIO의 경우 native입니다.
flash	-p / --port <SERIAL_PORT>	arduino-cli를 사용하여 Arduino Uno에 Revka 펌웨어를 플래싱합니다. 포트 기본값은 config에 있는 첫 번째 arduino-uno입니다.
setup-uno-q	--host <IP>	Arduino Uno Q에 GPIO 브리지 앱을 배포합니다. Uno Q 자체에서 실행할 경우 --host를 생략합니다.
flash-nucleo	—	Embassy 펌웨어를 빌드하고 ST-Link를 통해 probe-rs로 Nucleo-F401RE에 플래싱합니다.

보드 등록 (add / list)

revka peripheral add <board> <path>는 ~/.revka/config.toml에 보드 항목을 씁니다. 데몬 시작 이후에 연결된 보드나 인식되지 않는 VID를 가진 보드처럼 자동 검색되지 않은 보드에 사용하십시오.

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

동등한 수동 config.toml 항목:

[peripherals]
enabled = true

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

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

참고

revka peripheral add는 config에 쓰고 적용을 위해 데몬 재시작이 필요합니다. Raspberry Pi와 같은 싱글보드 컴퓨터의 경우 native를 경로로 사용하십시오. 시리얼 트랜스포트는 첫 번째 명령 시 지연 개방되므로, 데몬 시작 시 포트가 존재하지 않아도 됩니다 — 보드가 분리되어 있어도 데몬은 정상적으로 시작됩니다.

Arduino Uno 펌웨어 플래싱 (flash)

revka peripheral flash는 arduino-cli를 사용하여 Arduino Uno에 Revka 펌웨어를 플래싱합니다. arduino-cli가 없으면 설치하고(macOS에서는 Homebrew를 통해), AVR 코어를 설치하며, 임베디드 펌웨어 스케치를 컴파일하고 업로드합니다. 이 펌웨어는 시리얼을 통해 capabilities, gpio_read, gpio_write 명령을 활성화합니다.

revka peripheral flash --port /dev/cu.usbmodem14301
# or, if an arduino-uno board is already in config.toml:
revka peripheral flash

• macOS에서는 arduino-cli가 없을 경우 Homebrew를 통해 자동 설치됩니다. Linux에서는 arduino-cli가 없으면 설치 안내를 출력하고 오류와 함께 종료됩니다.
• --port 값은 검증됩니다. -로 시작하거나 셸 메타문자가 포함된 포트는 거부됩니다.
• 플래싱 후 revka peripheral add arduino-uno <path>로 보드를 등록하여 GPIO 도구가 로드되도록 하십시오.

Nucleo 펌웨어 플래싱 (flash-nucleo)

revka peripheral flash-nucleo는 Nucleo-F401RE용 Embassy Rust 펌웨어를 빌드하고, 보드의 내장 ST-Link를 통해 probe-rs로 플래싱합니다. 별도의 디버그 프로브가 필요하지 않습니다. 플래싱 후 보드는 ST-Link 가상 COM 포트를 통해 Revka 시리얼 JSON 프로토콜에 응답합니다.

revka peripheral flash-nucleo

수동 동등 명령:

cd firmware/nucleo
cargo build --release --target thumbv7em-none-eabihf
probe-rs run --chip STM32F401RETx target/thumbv7em-none-eabihf/release/nucleo

참고

flash-nucleo는 probe-rs CLI가 필요합니다: cargo install probe-rs-tools --locked (크레이트 이름은 probe-rs-tools이며 probe-rs가 아닙니다). 플래싱 후 Nucleo는 /dev/cu.usbmodem* (macOS) 또는 /dev/ttyACM0 (Linux)에 나타납니다. revka peripheral add nucleo-f401re <path>로 등록하십시오.

Arduino Uno Q 설정 (setup-uno-q)

Arduino Uno Q는 Linux 사이드와 MCU를 결합합니다. revka peripheral setup-uno-q는 브리지 앱 — Python + MCU 소켓 서버 — 을 보드에 배포합니다. 이 앱은 TCP 포트 9999에서 수신 대기하며, Linux 사이드에서 MCU의 GPIO로 gpio_read / gpio_write를 노출합니다.

# From your Mac, targeting the Uno Q over the network:
revka peripheral setup-uno-q --host 192.168.0.48

# From the Uno Q itself (SSH'd in), targeting localhost:
revka peripheral setup-uno-q

설정 후 bridge 트랜스포트로 보드를 등록하십시오:

[[peripherals.boards]]
board = "arduino-uno-q"
transport = "bridge"

이 구성으로 표준 gpio_read 및 gpio_write 도구는 시리얼 포트 대신 브리지 TCP 소켓(127.0.0.1:9999)으로 투명하게 연결됩니다. 에이전트는 동일한 도구 이름을 사용합니다. 도구가 동작하려면 브리지가 실행 중이어야 합니다.

지원 보드

보드 (board 값)	트랜스포트	펌웨어 / 드라이버	플래싱 / 설정 방법
nucleo-f401re / nucleo-f411re	serial	Embassy (Rust)	revka peripheral flash-nucleo (ST-Link를 통한 probe-rs)
arduino-uno	serial	AVR 스케치	revka peripheral flash (arduino-cli)
arduino-uno-q	bridge	Linux + MCU 브리지 앱	revka peripheral setup-uno-q
esp32	serial	ESP-IDF / Embassy	외부에서 플래싱 후 add로 등록
rpi-gpio	native	rppal / sysfs (peripheral-rpi)	자동 감지 또는 add rpi-gpio native
Raspberry Pi Pico	serial	MicroPython (UF2)	pico_flash 에이전트 도구 (BOOTSEL + mpremote)
Total Phase Aardvark	—	I2C/SPI/GPIO USB 어댑터	시작 시 자동 감지

보드별 전체 레퍼런스 — VID/PID, LED 핀, 메모리 맵, 필요한 기능 플래그 — 는 지원 보드 레퍼런스를 참고하십시오. 모든 보드의 플래싱 세부 사항은 펌웨어 플래싱을 참고하십시오. Raspberry Pi Pico는 CLI 서브커맨드가 아닌 에이전트의 pico_flash 도구로 플래싱됩니다. 하드웨어 퀵스타트를 참고하십시오. Aardvark 어댑터는 자동 감지되어 I2C/SPI/GPIO 도구를 노출합니다. Aardvark I2C/SPI/GPIO 및 데이터시트를 참고하십시오.

JSON-over-serial 프로토콜

테더링된 모든 시리얼 보드(Pico, Arduino, ESP32, Nucleo)는 단일 와이어 포맷을 사용합니다: 개행 구분 JSON. 각 요청은 \n으로 끝나는 단일 JSON 라인이며, 장치도 단일 JSON 라인으로 응답합니다. 이것은 호스트와 모든 보드 펌웨어가 공유하는 펌웨어 계약입니다.

호스트 → 장치 (ZcCommand):

{"cmd":"gpio_write","params":{"pin":25,"value":1}}

장치 → 호스트 (ZcResponse):

{"ok":true,"data":{"pin":25,"value":1,"state":"HIGH"}}

필드	방향	타입	설명
cmd	요청	string	명령 이름. 예: gpio_write, gpio_read, ping, capabilities.
params	요청	object	명령 파라미터; cmd에 따라 스키마가 달라집니다. 기본값은 {}.
ok	응답	boolean	명령 성공 여부.
data	응답	object	응답 페이로드; 명령에 따라 스키마가 달라집니다.
error	응답	string	사람이 읽을 수 있는 오류 메시지. ok가 false일 때만 포함됩니다.

ping이나 capabilities처럼 파라미터가 없는 명령은 빈 params 객체를 전달합니다. 첫 연결 시 시리얼 트랜스포트는 ping을 보내고 약 300ms 내에 Revka 펌웨어 응답을 기다립니다. 이 핸드셰이크를 통해 검색 중 알 수 없는 VID 장치의 수락 여부를 결정합니다.

에이전트는 이 JSON을 직접 작성하지 않습니다. gpio_write(pin=25, value=1) 또는 gpio_read(pin=25) 같은 도구를 호출하면 Revka가 와이어 프레임을 직렬화합니다. GPIO 가능 보드가 정확히 하나 연결된 경우 device 인수는 선택적입니다. 여러 보드가 있을 때는 에이전트가 별칭을 명시해야 합니다. 예: gpio_write(device="pico0", pin=25, value=1). 네이티브 Raspberry Pi gpio_rpi_* 도구와 Aardvark 비트마스크 GPIO를 포함한 전체 GPIO 도구 세트는 GPIO 도구를 참고하십시오.

참고

위의 {"cmd":…,"params":…} / {"ok":…,"data":…} 형식이 현재 펌웨어 계약입니다. 이전 호스트 매개 설계에서는 id 필드와 args / result 키를 사용하는 레거시 프레임을 사용했습니다 ({"id":"1","cmd":"gpio_write","args":{"pin":13,"value":1}} → {"id":"1","ok":true,"result":"done"}). 새 펌웨어는 현재의 params / data 계약을 구현해야 합니다.

관련 페이지

• 하드웨어 퀵스타트 — 첫 보드를 처음부터 끝까지 연결합니다.
• 지원 보드 레퍼런스 — 보드별 VID/PID, LED 핀, 메모리 맵, 기능 플래그.
• 펌웨어 플래싱 — Pico, Arduino, Nucleo 플래싱 심층 안내.
• GPIO 도구 — gpio_write, gpio_read, 네이티브 RPi 도구, Aardvark GPIO.
• Raspberry Pi (셀프 호스팅) — peripheral-rpi로 Pi에서 Revka 네이티브 실행.
• Aardvark I2C/SPI/GPIO 및 데이터시트 — Total Phase Aardvark 어댑터와 데이터시트 도구.
• revka agent — --peripheral로 단일 세션에서 주변 장치를 연결합니다.
• Cargo 기능 플래그 및 ADR — hardware, probe, peripheral-rpi 빌드 플래그.
• CLI 개요 및 환경 — 전역 플래그와 환경 변수.