Raspberry Pi (자체 호스팅)

Revka는 Raspberry Pi에서 직접 실행되며, 시리얼 링크·펌웨어 플래싱·mpremote 없이 보드의 GPIO 핀을 제어할 수 있습니다. Pi에서 Revka를 시작하면 모델을 감지하고 시스템 정보를 읽은 뒤, 에이전트의 시스템 프롬프트를 재작성하여 모델이 디바이스 위에서 실행 중임을 인식하게 합니다. 그런 다음 rppal을 통해 /dev/gpiomem에 접근하는 소규모 네이티브 GPIO 도구 세트를 노출합니다.

Pi 자체가 호스트인 경우 이 페이지를 참조하십시오. USB로 Mac 또는 Linux 호스트에 연결된 보드를 제어하려면 하드웨어 퀵스타트와 GPIO 도구를 참조하십시오. Pi에서 Revka 런타임 자체(바인딩, 서비스, 채널)를 배포하려면 네트워크 배포, Raspberry Pi & 프록시를 참조하십시오.

주의

네이티브 Raspberry Pi GPIO는 peripheral-rpi Cargo 피처 뒤에 위치하며 Linux 전용입니다 — macOS 또는 Windows에서는 컴파일되지 않습니다. gpio_rpi_* 및 rpi_system_info 도구는 해당 피처로 바이너리가 빌드되었고, 부팅 시 /proc/device-tree/model이 Pi임을 식별한 경우에만 나타납니다. Cargo 피처 플래그 & ADR을 참조하십시오.

Pi용 빌드

hardware 피처와 함께 빌드하고, 네이티브 GPIO를 위해 peripheral-rpi를 추가하십시오:

cargo build --release --features hardware,peripheral-rpi

메모리가 제한된 Pi에서는 소스 빌드보다 사전 빌드된 바이너리를 권장합니다(소스 빌드에는 약 2GB RAM과 6GB 디스크가 필요합니다). 사전 빌드 타겟은 armv7-unknown-linux-gnueabihf(Pi 2/3, 32비트)와 aarch64-unknown-linux-gnu(Pi 4/5, 64비트)를 지원합니다:

# Raspberry Pi OS 64-bit (Pi 4 / Pi 5)
cargo build --release --features hardware,peripheral-rpi --target aarch64-unknown-linux-gnu

# Raspberry Pi OS 32-bit (Pi 2 / Pi 3)
cargo build --release --features hardware,peripheral-rpi --target armv7-unknown-linux-gnueabihf

그런 다음 런타임을 시작합니다. Telegram과 같은 폴링 채널은 인바운드 포트가 필요 없으므로, LAN에 연결된 Pi는 터널 없이도 동작합니다:

revka daemon --host 127.0.0.1 --port 42617

참고

연결된 보드와 달리, 네이티브 GPIO에는 [[peripherals.boards]] 항목이 필요 없습니다. Pi는 부팅 시 자동으로 검색되며 도구가 자동으로 등록됩니다. (revka peripheral add rpi-gpio native를 통해 board = "rpi-gpio", transport = "native" 항목을 설정 기반 주변기기 서브시스템에 추가할 수는 있지만, 네이티브 gpio_rpi_* 도구는 이에 의존하지 않습니다.)

자동 검색 및 시스템 프롬프트 주입

부팅 시 Revka는 /proc/device-tree/model을 읽어(실패 시 /proc/cpuinfo의 Model 행으로 폴백) Pi에서 실행 중인지 감지를 시도합니다. 감지되는 모델은 Pi 3B, 3B+, 4B, 5, Zero 2 W입니다. Pi가 확인되면 Revka는 사용자 작업 없이 자동으로 두 가지를 수행합니다:

1. 시스템 프롬프트 섹션을 주입하여 디바이스를 설명하고, 에이전트가 현재 위치와 사용할 도구를 인식하게 합니다.
2. 디바이스 프로파일을 ~/.revka/hardware/devices/rpi0.md에 작성합니다. 이 파일은 부팅할 때마다 재작성되어 휘발성 필드(IP, 온도)가 최신 상태를 유지합니다. 다른 하드웨어 컨텍스트 파일과 동일하게 프롬프트에 로드됩니다.

주입되는 프롬프트 섹션은 다음과 같습니다:

## Running On Device (Raspberry Pi)

- Board: Raspberry Pi 4 Model B
- Hostname: mypi
- IP Address: 192.168.1.42
- WiFi interface: wlan0
- RAM: 3921MB total, 2847MB available
- CPU Temperature: 47.2°C
- Onboard ACT LED: BCM GPIO 42
- GPIO: available via rppal (/dev/gpiomem)

Use `gpio_rpi_write`, `gpio_rpi_read`, and `gpio_rpi_blink` for all GPIO
operations — they access /dev/gpiomem directly, no serial port or mpremote needed.

생성된 rpi0.md 프로파일에는 BCM 핀 규약(I2C는 GPIO 2/3, SPI는 GPIO 7–11)과 일반 GPIO 동작을 재정의하는 도구 사용 규칙이 추가로 기록됩니다 — 에이전트가 시리얼-JSON 방식의 gpio_write 대신 gpio_rpi_write를 사용하도록 유도하며, 자체 호스팅 Pi에는 존재하지 않는 device_exec나 mpremote는 사용하지 않도록 명시합니다.

팁

~/.revka/hardware/HARDWARE.md 또는 ~/.revka/hardware/devices/에 Markdown을 추가하여 디바이스별 메모를 작성할 수 있습니다. Revka는 부팅할 때마다 rpi0.md를 재생성하므로, 커스터마이즈 내용은 rpi0.md를 직접 편집하지 말고 별도 파일에 작성하십시오.

BCM 핀 번호 및 온보드 ACT LED

네이티브 Raspberry Pi 도구는 물리적 헤더 핀 번호가 아닌 BCM(Broadcom) GPIO 번호를 사용합니다. 일반 GPIO 핀은 rppal(/dev/gpiomem)을 통해 직접 제어됩니다.

온보드 녹색 액티비티(ACT) LED는 특수한 경우입니다. Pi 3B/4B/5 및 Zero 2 W에서는 rppal로 직접 접근할 수 없고 커널 LED 드라이버를 통해 연결되어 있으므로, Revka는 sysfs(/sys/class/leds/ACT/brightness, 실패 시 led0으로 폴백)를 통해 제어하며, 제어권을 가져오기 위해 LED 트리거를 먼저 none으로 설정합니다. ACT LED의 BCM 번호는 모델에 따라 다릅니다:

모델	온보드 ACT LED (BCM GPIO)
Raspberry Pi 3B / 3B+	47
Raspberry Pi 4B	42
Raspberry Pi 5	9
Raspberry Pi Zero 2 W	29

gpio_rpi_* 도구에 이 번호 중 하나를 전달하면 온보드 LED를 제어하고, 다른 BCM 번호를 전달하면 일반 핀을 제어합니다. ACT LED에 대한 읽기/쓰기는 "source":"sysfs"를 보고하며, 일반 핀은 rppal을 통해 처리됩니다.

네이티브 GPIO 도구

다음 네 가지 도구는 부팅 시 Pi가 감지되면 자동으로 등록됩니다. 에이전트는 자연어에 응답하여 도구를 호출하며, CLI에서 revka agent -m "…"으로 직접 실행할 수도 있습니다.

핀 쓰기 — gpio_rpi_write

Pi에서 BCM GPIO 핀을 HIGH 또는 LOW로 직접 설정합니다.

파라미터	타입	필수 여부	설명
pin	integer	예	BCM GPIO 번호.
value	integer	예	1 = HIGH, 0 = LOW.

# Turn on the onboard ACT LED of a Pi 4B (BCM 42)
revka agent -m "Turn on the onboard LED"
# Agent calls: gpio_rpi_write(pin=42, value=1)

# Drive a regular pin
# Agent calls: gpio_rpi_write(pin=17, value=1)

주의

Revka를 Pi에서 네이티브로 실행하는 경우, 연결된 보드용 시리얼-JSON 도구인 gpio_write를 사용하지 마십시오 — gpio_rpi_write를 사용하십시오. 주입된 rpi0.md 규칙이 에이전트를 올바른 도구로 자동 안내합니다.

핀 읽기 — gpio_rpi_read

BCM GPIO 핀의 현재 상태를 읽습니다(rppal 사용, 온보드 LED는 sysfs 사용).

파라미터	타입	필수 여부	설명
pin	integer	예	BCM GPIO 번호.

이 도구는 pin, value, state가 포함된 JSON 객체를 반환합니다:

{ "pin": 17, "value": 0, "state": "LOW" }

ACT LED 핀을 읽으면 출력에 "source":"sysfs"가 포함됩니다.

핀 점멸 — gpio_rpi_blink

BCM GPIO 핀을 설정 가능한 ON/OFF 타이밍으로 지정된 횟수만큼 점멸합니다. 온보드 ACT LED(sysfs 경유)와 일반 핀(rppal을 통한 백그라운드 블로킹 태스크) 모두에서 동작합니다.

파라미터	타입	기본값	최대값	설명
pin	integer	—	—	BCM GPIO 번호 (필수).
times	integer	3	100	점멸 횟수.
on_ms	integer	500	10000	사이클당 HIGH 유지 시간(밀리초).
off_ms	integer	500	10000	사이클 사이의 LOW 유지 시간(밀리초).

revka agent -m "Blink the onboard LED 5 times, fast"
# Agent calls: gpio_rpi_blink(pin=42, times=5, on_ms=300, off_ms=200)

상한(100사이클, 단계당 10초)은 제어 불능 점멸 루프를 방지합니다.

참고

gpio_rpi_blink는 네이티브 Pi 점멸에 적합한 도구입니다. 온디바이스 루프를 위한 device_exec 방식은 자체 호스팅 Pi가 아닌 연결된 보드(USB를 통한 Pico/Arduino)에 적용됩니다.

시스템 정보 — rpi_system_info

Pi의 JSON 스냅샷을 반환합니다: 보드 모델, 호스트명, IP 주소, WiFi 인터페이스, RAM(MB), CPU 온도(°C), GPIO 가용성, 온보드 LED의 BCM 번호. 파라미터는 없습니다.

revka agent -m "What Pi am I running on and how hot is it?"
# Agent calls: rpi_system_info()

{
  "model": "Raspberry Pi 4 Model B",
  "hostname": "mypi",
  "ip_address": "192.168.1.42",
  "wifi_interface": "wlan0",
  "ram_total_mb": 3921,
  "ram_free_mb": 2847,
  "cpu_temp_celsius": 47.2,
  "gpio_available": true,
  "onboard_led_gpio": 42
}

IP 주소는 UDP 라우팅 기법으로 확인됩니다(실제 패킷은 전송되지 않으며, Revka가 OS에 아웃바운드 경로에 사용할 인터페이스를 질의합니다). RAM은 /proc/meminfo(MemTotal / MemAvailable)에서, 온도는 /sys/class/thermal/thermal_zone0/temp에서 읽습니다. Pi에서 실제로 실행 중이지 않으면 오류를 반환합니다.

온보드 LED 점멸 실습

1. Pi에서 네이티브 GPIO 지원으로 빌드합니다.

   cargo build --release --features hardware,peripheral-rpi

2. 데몬을 시작합니다. 자동 검색이 자동으로 실행됩니다 — 설정 항목이나 플래싱이 필요 없습니다.

   revka daemon --host 127.0.0.1 --port 42617

3. Revka가 Pi를 인식하는지 확인합니다. 시스템 정보를 요청하면 rpi_system_info에서 응답이 반환됩니다.

   revka agent -m "What board am I running on?"

4. 온보드 LED를 점멸합니다. 에이전트는 주입된 컨텍스트에서 모델에 맞는 올바른 BCM 핀을 선택합니다.

   revka agent -m "Blink the onboard LED 5 times"

   Pi 4B에서는 sysfs를 통해 gpio_rpi_blink(pin=42, times=5)로 실행됩니다.

peripheral-rpi 피처

네이티브 Pi GPIO는 hardware 위에서 동작하는 peripheral-rpi Cargo 피처로 제한됩니다:

항목	내용
빌드 플래그	--features hardware,peripheral-rpi
플랫폼	Linux 전용 (macOS / Windows에서는 컴파일 안 됨)
백엔드	/dev/gpiomem을 통한 rppal; 온보드 ACT LED는 sysfs
활성화되는 도구	gpio_rpi_write, gpio_rpi_read, gpio_rpi_blink, rpi_system_info
등록	부팅 시 /proc/device-tree/model이 Pi를 식별하면 자동 등록 — 설정 항목 불필요

피처 없이는 gpio_rpi_* 도구와 자동 검색 프롬프트 주입이 존재하지 않습니다. 전체 피처 플래그 매트릭스(hardware, peripheral-rpi, probe, rag-pdf, safety)는 Cargo 피처 플래그 & ADR을 참조하십시오.

Android / Termux 타겟

Revka는 Android용 사전 빌드 바이너리도 제공하여, Termux를 통해 휴대폰이나 태블릿에서 에이전트를 실행할 수 있습니다. 이는 런타임 타겟이며 GPIO 타겟이 아닙니다 — Android에는 gpio_rpi_*에 해당하는 기능이 없습니다.

타겟 트리플	Android 버전	디바이스
aarch64-linux-android	Android 5.0+ (API 21+)	최신 64비트 휴대폰
armv7-linux-androideabi	Android 4.1+ (API 16+)	구형 32비트 휴대폰

# In Termux — install from F-Droid, not the Play Store (the Play build is outdated)
uname -m   # aarch64 = 64-bit; armv7l/armv8l = 32-bit

# 64-bit
curl -LO https://github.com/KumihoIO/Revka/releases/latest/download/revka-aarch64-linux-android.tar.gz
tar xzf revka-aarch64-linux-android.tar.gz

chmod +x revka
mv revka $PREFIX/bin/
revka --version
revka onboard

참고

Android에는 systemd가 없습니다 — 데몬 모드에는 Termux의 termux-services를 사용하고, 파일시스템 접근 권한을 부여하려면 termux-setup-storage를 실행하십시오. 일부 로컬 바인딩 기능에는 Android VPN 권한이 필요할 수 있습니다. 고급 사용자는 adb push로 바이너리를 직접 푸시할 수 있지만, Termux 외부에서 실행하려면 루팅된 디바이스나 특정 권한이 필요합니다.

다음 단계

GPIO 도구 gpio_rpi_write / read / blink와 시리얼 GPIO 및 Aardvark 비트마스크 GPIO.

하드웨어 퀵스타트 부팅 서브시스템, 자동 검색, 하드웨어 컨텍스트 파일.

네트워크 배포 & Raspberry Pi Pi 호스트의 바인드 주소, LAN 접근, 서비스, 채널.

Cargo 피처 플래그 & ADR hardware, peripheral-rpi, probe, safety 각각의 활성화 내용.