Aardvark I2C/SPI/GPIO 및 데이터시트

Total Phase Aardvark는 USB 호스트 어댑터로, 사용 중인 머신을 8개의 보너스 GPIO 핀이 달린 I2C/SPI 마스터로 변환해 줍니다. 어댑터를 연결하면 Revka가 이를 디바이스(aardvark0)로 등록하고, 에이전트가 호출할 수 있는 여섯 가지 버스 수준 도구를 제공합니다: I2C 버스 스캔, I2C 레지스터 읽기 및 쓰기, 전이중 SPI 전송, 어댑터의 GPIO 헤더 제어, 그리고 컴포넌트 데이터시트 조회입니다.

실제 I2C 또는 SPI 버스를 통해 에이전트가 온도 센서, EEPROM, SPI 플래시, 포트 익스팬더 등 벤치 전자 장비와 통신하게 하려면 이 페이지를 참고하십시오. 다섯 가지 Aardvark 도구, datasheet 워크플로우, aardvark-sys 크레이트 및 aardvark.so 라이브러리, 그리고 REVKA_AARDVARK_LIB 오버라이드를 다룹니다. 테더드 MCU GPIO 및 네이티브 Raspberry Pi 도구는 GPIO 도구를 참고하고, 첫 번째 보드 연결은 하드웨어 빠른 시작을 참고하십시오.

주의

Aardvark 지원은 hardware Cargo 피처 플래그 뒤에 컴파일되며, 도구는 시작 시 어댑터가 감지된 경우에만 등록됩니다. hardware 없이 빌드된 바이너리나 어댑터가 연결되지 않은 상태로 시작된 바이너리는 이 페이지의 어떤 도구도 노출하지 않습니다. cargo build --release --features hardware로 빌드하십시오. Cargo 피처 플래그 & ADR을 참고하십시오.

Aardvark의 동작 방식

데몬이 시작될 때 하드웨어 부트 루틴은 aardvark-sys에 어댑터가 연결되어 있는지 확인합니다. 감지된 어댑터마다 디바이스 별칭(aardvark0, aardvark1, …, USB VID 0x2B76)을 등록하고, AardvarkTransport를 연결한 뒤, 여섯 가지 Aardvark 도구를 에이전트의 도구 레지스트리에 추가합니다. 어댑터가 없거나 aardvark.so 라이브러리를 로드할 수 없는 경우, 크레이트는 스텁 모드로 실행됩니다. 이 경우 디스커버리는 빈 목록을 반환하고, 도구는 로드되지 않으며, 데몬은 정상적으로 기동됩니다.

스택은 계층 구조로 이루어져 있습니다. 에이전트가 호출하는 각 도구는 ZcCommand로 변환되고, 트랜스포트가 이를 aardvark-sys 호출로 변환하며, aardvark-sys가 C 라이브러리를 직접 다루는 유일한 계층입니다.

계층	파일	역할
도구	src/hardware/aardvark_tools.rs	에이전트 JSON 유효성 검사, 디바이스 확인, ZcCommand 생성, 텍스트 반환.
트랜스포트	src/hardware/aardvark.rs	ZcCommand ↔ aardvark-sys 호출 변환; 명령마다 핸들을 열고 닫음.
FFI 바인딩	crates/aardvark-sys/src/lib.rs	Total Phase C 라이브러리를 런타임에 로드하는 안전한 Rust 래퍼.

참고

트랜스포트는 지연 열기 / 즉시 닫기 전략을 사용합니다. 명령마다 새로운 USB 핸들을 열고, 명령이 완료되는 즉시 (Drop을 통해 자동으로) 닫힙니다. 관리해야 할 영속적인 연결이 없습니다. Aardvark에서 I2C와 SPI 모드는 상호 배타적이므로, 트랜스포트는 명령마다 어댑터를 올바른 모드로 전환합니다. I2C와 SPI 모두 기본 버스 속도는 100 kHz이며, 트랜스포트가 생성될 때 설정됩니다(AardvarkTransport::new(port, bitrate_khz)).

I2C 도구

세 가지 I2C 도구는 선택적 device 인수를 공유합니다. 이는 대상 Aardvark 별칭을 지정합니다. 어댑터가 하나만 연결된 경우 자동으로 선택되므로 생략할 수 있으며, 여러 개인 경우 device="aardvark0"처럼 지정합니다. 주소와 바이트는 십진 정수로 입력되고 16진수로 반환됩니다.

I2C 스캔 (i2c_scan)

0x08부터 0x77까지 모든 7비트 주소에 1바이트 읽기를 시도하고, ACK를 반환하는 주소 목록을 반환합니다. 버스에 어떤 장치가 있는지 파악한 뒤 각 장치의 데이터시트를 조회하는 일반적인 첫 번째 단계입니다.

Agent call:  i2c_scan()
Output:      I2C scan found 2 device(s): 0x48, 0x68

버스가 비어 있으면 I2C scan complete — no devices found on the bus.를 반환합니다.

파라미터	타입	필수	설명
device	string	아니요	Aardvark 별칭. 어댑터가 하나만 연결된 경우 자동 선택됩니다.

I2C 읽기 (i2c_read)

I2C 디바이스에서 바이트를 읽습니다. register를 지정하면 표준 레지스터 읽기 패턴(레지스터 주소 쓰기 후 읽기)을 수행하고, 지정하지 않으면 디바이스 주소에서 단순 읽기를 수행합니다.

Agent call:  i2c_read(addr=72, register=0, len=2)
Output:      I2C read from addr 0x48: [0xAB, 0xCD]

addr=72는 0x48이고, register=0은 읽을 레지스터입니다.

파라미터	타입	필수	기본값	설명
device	string	아니요	auto	Aardvark 별칭.
addr	integer	예	—	십진수로 표현된 I2C 디바이스 주소 (예: 0x48은 72).
register	integer	아니요	—	읽을 레지스터 주소. 지정 시 쓰기-후-읽기 방식으로 동작합니다.
len	integer	아니요	1	읽을 바이트 수.

I2C 쓰기 (i2c_write)

I2C 디바이스에 바이트 시퀀스를 씁니다. 예를 들어 설정 레지스터를 쓸 때 사용합니다.

Agent call:  i2c_write(addr=72, bytes=[1, 96])
Output:      I2C write to addr 0x48: 2 byte(s) written

이 명령은 0x48 주소의 디바이스에 [0x01, 0x60]을 씁니다.

파라미터	타입	필수	설명
device	string	아니요	Aardvark 별칭.
addr	integer	예	십진수로 표현된 I2C 디바이스 주소.
bytes	array of integers	예	쓸 바이트 배열. 각 값은 유효한 u8 (0–255)이어야 합니다.

참고

범위를 벗어난 바이트 값(0–255 초과)은 파라미터 오류로 거부됩니다. I2C 버스에는 풀업 저항이 필요하지만, Aardvark는 내장 풀업을 자동으로 활성화합니다(AA_I2C_PULLUP_BOTH). 따라서 어댑터 헤더에 직접 연결한 센서는 외부 저항 없이도 대개 정상 동작합니다.

SPI 전송 (spi_transfer)

전이중 SPI 전송을 수행합니다. 전송하는 바이트가 클럭 아웃되는 동안 동일한 수의 바이트가 클럭 인되어 반환됩니다. SPI 플래시 칩에서 JEDEC ID를 읽는 것이 대표적인 사용 예입니다.

Agent call:  spi_transfer(bytes=[0x9F, 0x00, 0x00])
Output:      SPI transfer complete. Received: [0x00, 0xEF, 0x40]

파라미터	타입	필수	설명
device	string	아니요	Aardvark 별칭. 어댑터가 하나만 연결된 경우 자동 선택됩니다.
bytes	array of integers	예	전송할 바이트 배열. 수신 버퍼는 동일한 길이입니다.

참고

전송은 SPI 모드 0(클럭 극성/위상 0, MSB 우선)으로 실행됩니다. 이는 트랜스포트에서 고정된 값으로, 아직 도구 파라미터로 노출되지 않습니다. 기본 비트레이트는 100 kHz이며, Aardvark는 SPI를 최대 약 4 MHz까지 지원합니다. 어댑터에서 I2C와 SPI는 상호 배타적이므로, spi_transfer 호출 시 해당 명령 동안 어댑터가 SPI 모드로 전환됩니다.

Aardvark GPIO (gpio_aardvark)

Aardvark는 10핀 확장 헤더에 8개의 GPIO 핀을 제공합니다. 핀별로 동작하는 gpio_write/gpio_rpi_write 도구와 달리, gpio_aardvark는 1바이트 비트마스크를 사용해 8개 핀 전체를 한 번에 제어합니다. 비트 N은 핀 N에 해당합니다.

action="set"으로 핀 방향과 레벨을 설정하고, action="get"으로 현재 핀 상태를 읽습니다.

# Set pin 0 as output, drive it HIGH
Agent call:  gpio_aardvark(action="set", direction=0b00000001, value=0b00000001)
Output:      Aardvark GPIO set — direction: 0b00000001, value: 0b00000001

# Read all eight pins
Agent call:  gpio_aardvark(action="get")
Output:      Aardvark GPIO pins: 0b00000001 (0x01)

파라미터	타입	필수	설명
device	string	아니요	Aardvark 별칭.
action	string	예	set 또는 get.
direction	integer	set 시	핀 방향 비트마스크: 1 = 출력, 0 = 입력.
value	integer	set 시	출력 레벨 비트마스크: 1 = HIGH, 0 = LOW.

출력은 이진수(0b…)와 16진수로 모두 표시되어 비트마스크를 쉽게 확인할 수 있습니다.

데이터시트 관리 (datasheet)

datasheet 도구는 버스 도구를 실용적인 루프로 연결합니다. 버스를 스캔하고, 디바이스를 식별하고, 데이터시트를 가져와서, 레지스터 맵을 통해 디바이스를 프로그래밍합니다. 데이터시트는 ~/.revka/hardware/datasheets/에 PDF 형식으로 저장됩니다. 어댑터가 감지되면 다른 Aardvark 도구와 함께 등록됩니다.

네 가지 액션을 지원합니다.

액션	필수 필드	설명
search	device_name	데이터시트에 대한 웹 검색 쿼리를 반환합니다 (실제 검색을 실행하지는 않습니다).
download	device_name, url	url의 PDF를 다운로드하여 <device_name>.pdf로 저장합니다.
list	—	데이터시트 디렉토리에 캐시된 PDF 목록을 반환합니다.
read	device_name	캐시된 데이터시트의 로컬 경로(및 rag-pdf 사용 시 추출된 텍스트)를 반환합니다.

// 1. Get a search query (the agent then runs it with its web_search tool)
{ "action": "search", "device_name": "LM75" }

// 2. Download once you have the URL
{ "action": "download", "device_name": "LM75", "url": "https://www.ti.com/lit/ds/symlink/lm75.pdf" }

// 3. List what's cached
{ "action": "list" }

// 4. Get the cached file path / text
{ "action": "read", "device_name": "LM75" }

참고

search 액션은 쿼리 문자열만 반환합니다. 주요 벤더 사이트(TI, NXP, ST, Microchip, Infineon, Analog Devices)를 대상으로 하며, web_search 도구에 전달하기 위한 용도입니다. 파일은 소문자로 변환되고 공백이 밑줄로 대체된 이름으로 저장됩니다(LM75 → lm75.pdf). find_local은 대소문자를 구분하지 않으므로, LM75, lm75, LM 75 모두 동일한 파일로 연결됩니다. read 중 PDF 텍스트 추출에는 rag-pdf 빌드 피처가 필요합니다. 이 기능 없이는 read가 파일 경로만 반환하므로 에이전트가 직접 참조할 수 있습니다. 다운로드 후 도구는 ~/.revka/hardware/devices/<alias>.md에 주요 레지스터가 포함된 디바이스 프로파일을 생성하도록 제안하며, 이 파일은 시스템 프롬프트에 주입됩니다. 하드웨어 빠른 시작 → 컨텍스트 파일을 참고하십시오.

일반적인 벤치 세션

1. 버스를 스캔하여 연결된 디바이스를 확인합니다.

   i2c_scan()  →  I2C scan found 1 device(s): 0x48

2. 데이터시트를 조회합니다. 에이전트가 datasheet(action="search", device_name="LM75")를 호출하고, 반환된 쿼리를 web_search로 실행한 뒤, datasheet(action="download", …)로 PDF를 다운로드합니다.

3. 레지스터를 읽습니다. 데이터시트의 주소와 레지스터 맵을 활용합니다.

   i2c_read(addr=72, register=0, len=2)  →  I2C read from addr 0x48: [0x19, 0x00]

4. 필요한 경우 설정을 씁니다.

   i2c_write(addr=72, bytes=[1, 96])  →  I2C write to addr 0x48: 2 byte(s) written

aardvark-sys 크레이트

aardvark-sys(crates/aardvark-sys)는 Total Phase Aardvark C 라이브러리에 대한 안전한 Rust 바인딩을 제공합니다. libloading을 통해 런타임에 aardvark.so를 동적으로 로드하며, Revka에서 unsafe가 허용되는 유일한 위치입니다. 디바이스 열거(find_devices), RAII 방식의 열기/닫기 핸들, I2C 활성화/읽기/쓰기/스캔, SPI 활성화/전송, GPIO set/get을 제공합니다. 이 크레이트를 직접 호출하는 경우는 없으며, AardvarkTransport 아래에 위치합니다. 하지만 동작 방식을 이해하면 도구가 어떻게 성능 저하 및 복구되는지 파악할 수 있습니다.

주요 동작:

• 스텁 모드는 안전합니다. aardvark.so를 찾거나 로드할 수 없으면, 모든 메서드가 오류를 반환하고 find_devices()는 []를 반환합니다. 데몬은 Aardvark 도구 없이 정상적으로 시작됩니다.
• 사용 가능한 어댑터만 반환합니다. find_devices()는 사용 가능한 어댑터의 포트 번호만 반환하며, 다른 프로세스가 이미 사용 중인 포트는 제외됩니다.
• 명령별 핸들. 명령마다 새로운 핸들이 열리고, Drop 구현이 aa_close를 자동으로 호출하므로 연결이 열린 채로 남지 않습니다.

라이브러리 설정과 REVKA_AARDVARK_LIB

Aardvark 도구는 Total Phase의 독점 공유 라이브러리 aardvark.so에 의존합니다. aardvark-sys는 런타임에 다음 순서로 라이브러리를 검색합니다.

1. REVKA_AARDVARK_LIB 환경 변수에 지정된 경로 (aardvark.so의 전체 경로).
2. <workspace>/crates/aardvark-sys/vendor/aardvark.so (개발 기본 경로).
3. 실행 중인 바이너리 옆의 aardvark.so (배포용).
4. 현재 작업 디렉토리의 aardvark.so.

첫 번째로 로드에 성공한 항목이 사용됩니다. 다른 위치에 설치된 라이브러리를 사용하려면, 데몬 시작 전에 오버라이드를 설정하십시오.

macOS/Linux

export REVKA_AARDVARK_LIB=/opt/totalphase/aardvark.so
revka daemon

Windows (PowerShell)

$env:REVKA_AARDVARK_LIB = "C:\TotalPhase\aardvark.dll"
revka daemon

어떤 후보도 로드되지 않으면, aardvark-sys는 라이브러리를 찾지 못했다고 로그에 기록하고 스텁 모드로 폴백합니다. 데몬은 Aardvark 도구 없이 계속 실행됩니다.

주의

Apple Silicon: 벤더 제공 aardvark.so가 x86_64 빌드일 수 있습니다. aardvark-sys는 아키텍처 불일치(“incompatible architecture”)를 감지하여 조용히 실패하는 대신 명확하게 보고합니다. arm64에서 네이티브로 실행하려면 Total Phase 다운로드에서 해당 SDK를 받아 REVKA_AARDVARK_LIB로 지정하거나, x86_64 라이브러리에 맞춰 x86_64-apple-darwin으로 Revka를 빌드하십시오.

설정 확인

어댑터를 연결하고 데몬을 시작한 후, 도구가 정상적으로 로드되었는지 확인합니다.

curl http://127.0.0.1:42617/tools | grep -E "i2c_scan|spi_transfer|gpio_aardvark|datasheet"

해당 도구 이름이 출력되면 어댑터가 감지되고 라이브러리가 로드된 것입니다. 표시되지 않으면 바이너리가 --features hardware로 빌드되었는지, 데몬 시작 전에 어댑터가 연결되었는지, aardvark.so가 검색 경로에 있는지 확인하십시오(필요한 경우 REVKA_AARDVARK_LIB를 설정하십시오). 빠른 종단간 확인을 원하면 에이전트에게 버스 스캔을 요청합니다.

revka agent -m "Scan the I2C bus with the Aardvark"

/tools 엔드포인트는 상태, 헬스, 설정 및 도구 엔드포인트를, 진단은 revka doctor, status & self-test를 참고하십시오.

다음 단계

GPIO 도구 핀별 gpio_write / gpio_read, 네이티브 Raspberry Pi 도구, 그리고 Aardvark 비트마스크 GPIO와의 차이점.

하드웨어 빠른 시작 부트 서브시스템, 디바이스 별칭, 그리고 ~/.revka/hardware/ 컨텍스트 파일.

지원 보드 레퍼런스 Aardvark를 포함한 모든 지원 보드의 VID/PID, 별칭 접두사, 피처 플래그.

응답 캐시, 하드웨어 RAG 및 격리 rag-pdf 피처가 활성화된 후 데이터시트 PDF가 하드웨어 RAG에 공급되는 방식.