13.3.1.6. API 레퍼런스¶
openmv 패키지의 공개 인터페이스는 카메라와 통신하기 위한 Camera 클래스와 프로토콜 오류를 위한 OMVException 계층입니다. 둘 다 이 페이지에 문서화되어 있습니다.
13.3.1.6.1. Camera 클래스¶
- class openmv.Camera(port: str, *, baudrate: int = 921600, crc: bool = True, seq: bool = True, ack: bool = True, events: bool = True, timeout: float = 1.0, max_retry: int = 3, max_payload: int = 4096, drop_rate: float = 0.0)¶
USB 시리얼을 통해 연결된 OpenMV 카메라를 위한 호스트 측 프록시입니다.
- 매개변수:
port – 시리얼 장치 경로입니다. Linux에서는 USB CDC의 경우
/dev/ttyACMx, USB-to-UART 브리지의 경우/dev/ttyUSBx입니다. macOS에서는/dev/tty.usbmodem...또는/dev/cu.usbmodem...입니다. Windows에서는COMx입니다.baudrate – 시리얼 보드 레이트입니다. USB에서는
921600이 카메라를 MicroPython REPL에서 OpenMV 프로토콜로 전환하는 매직 값입니다. USB 링크에서 다른 값을 사용하면 카메라가 REPL 모드에 머무르므로 기본값을 사용해야 합니다. UART 링크에서는 이 값이 실제 회선 보드 레이트이며 양쪽 모두에서 자유롭게 설정할 수 있습니다.crc – 모든 패킷에 대해 CRC 검증을 활성화합니다.
seq – 패킷별 시퀀스 번호를 활성화합니다.
ack – 패킷 확인 응답을 요구합니다.
events – 카메라로부터의 이벤트 알림을 활성화합니다.
timeout – 작업별 타임아웃(초)입니다.
max_retry – 패킷 실패 시 예외를 발생시키기 전 재시도 횟수입니다.
max_payload – 협상되는 최대 페이로드 크기(바이트)입니다. 카메라가 더 낮은 값으로 협상할 수 있습니다.
drop_rate – 패킷을 드롭할 테스트 전용 확률로,
[0.0, 1.0]범위입니다. 운영 환경에서는0.0으로 두십시오.
이 클래스는 컨텍스트 매니저 프로토콜을 지원합니다.
with Camera(port) as cam:는 진입 시connect(), 종료 시disconnect()를 호출합니다.
13.3.1.6.2. 연결¶
- Camera.connect() None¶
시리얼 포트를 열고 프로토콜 핸드셰이크를 수행합니다. 캐시된 상태(채널 목록, 시스템 정보, 버전 정보)가 부수 효과로 채워집니다. 컨텍스트 매니저에 의해 자동으로 호출됩니다.
13.3.1.6.3. 스크립트 실행¶
13.3.1.6.4. 스트리밍¶
- Camera.streaming(enable: bool, raw: bool = False, resolution: tuple[int, int] | None = None) None¶
프레임 스트림을 켜거나 끄고 전송 포맷을 선택합니다.
- 매개변수:
enable –
True는 스트리밍을 활성화하고,False는 비활성화합니다.raw –
False(기본값)일 때 카메라는 각 프레임을 스트림 채널에 넣기 전에 JPEG으로 압축하고read_frame()이 호스트에서 압축을 해제합니다.True일 때 카메라는 캡처된 픽셀 버퍼를 압축하지 않고 전송합니다. 이는 하드웨어 JPEG 지원이 없는 카메라에서 소프트웨어 압축이 루프에서 가장 느린 단계가 될 때 올바른 선택입니다.resolution – 압축되지 않은 프레임은 JPEG으로 압축된 프레임보다 훨씬 크기 때문에, 카메라가 전송 전에 각 원본 프레임을 축소하는 대상 크기
(width, height)입니다.raw=True일 때 필수이며, 그렇지 않으면 무시됩니다.
13.3.1.6.5. 사용자 정의 채널¶
- Camera.channel_write(name: str, data: bytes) bool¶
data를 사용자 정의 채널에 씁니다. 페이로드보다 큰 쓰기는 자동으로 여러 패킷으로 분할됩니다.- 매개변수:
name – 카메라 측 스크립트가 등록한 채널 이름입니다.
data – 전송할 바이트형 페이로드입니다.
- 반환:
채널이 존재하고 쓰기가 전송되었으면
True, 그렇지 않으면False입니다.
- Camera.read_status() dict[str, bool]¶
등록된 모든 채널을 폴링합니다.
- 반환:
채널 이름을 “읽을 데이터가 준비됨”의 불리언 값에 매핑하는 딕셔너리입니다.
- Camera.update_channels() None¶
카메라로부터 캐시된 채널 목록을 갱신합니다. 채널 등록 이벤트가 도착한 후 이름으로 채널을 조회할 때 자동으로 실행됩니다. 새로 등록된 채널을 즉시 알고자 하는 애플리케이션은 이를 직접 호출할 수 있습니다.
- Camera.get_channel(name: str | None = None, channel_id: int | None = None) int | str | None¶
채널을 이름으로(숫자 ID 반환) 또는 ID로(이름 반환) 조회합니다. 채널 등록 이벤트가 대기 중이면 먼저
update_channels()를 통해 채널 캐시를 갱신합니다.- 매개변수:
name – ID로 해석할 채널 이름입니다.
channel_id – 이름으로 해석할 채널 ID입니다.
- 반환:
대응하는 ID 또는 이름이며, 채널이 존재하지 않으면
None입니다.name또는channel_id중 하나는 반드시 제공해야 합니다.
13.3.1.6.6. 장치 인트로스펙션¶
- Camera.version() dict¶
카메라의 프로토콜, 부트로더, 펌웨어 버전 트리플을 반환합니다.
connect()이후 캐시됩니다. 각 트리플은int의(major, minor, patch)튜플입니다:protocol_version– 카메라가 구현하는 OpenMV 와이어 프로토콜의 버전입니다.bootloader_version– 플래시에 상주하는 부트로더 이미지입니다.firmware_version– 현재 실행 중인 MicroPython 펌웨어입니다.
- Camera.system_info() dict¶
카메라의 하드웨어 기능 및 메모리 정보를 반환합니다.
connect()이후 캐시됩니다. 반환된 딕셔너리의 키는 네 그룹으로 나뉩니다.식별 정보
cpu_id– 32비트 CPU 식별자입니다.device_id– 32비트 워드 3개로 이루어진 튜플로, 실리콘에 새겨진 고유 장치 시리얼입니다.chip_id– 32비트 워드 3개로 이루어진 튜플로, 카메라에 연결된 이미지 센서마다 하나씩의 항목입니다.usb_vid– USB 벤더 ID입니다.usb_pid– USB 제품 ID입니다.
메모리 크기 (모두 킬로바이트 단위)
flash_size_kb– 내부 플래시 총량입니다.ram_size_kb– 총 RAM입니다.framebuffer_size_kb– 이미지 캡처를 위해 예약된 RAM입니다.stream_buffer_size_kb– 프레임을 호스트로 보내는 스트림 채널을 위해 예약된 RAM입니다.
기능 플래그 (기능당 불리언 하나, 모두
<feature>_present형식의 이름)gpu_present– 그래픽 처리 장치입니다.npu_present– 신경망 처리 장치입니다.isp_present– 이미지 신호 프로세서입니다.venc_present– 비디오 인코더입니다.jpeg_present– JPEG 하드웨어 인코더입니다.dram_present– 외부 DRAM입니다.crc_present– CRC 가속기입니다.pmu_present– 성능 모니터링 장치입니다.wifi_present– Wi-Fi 무선 모듈입니다.bt_present– Bluetooth 무선 모듈입니다.sd_present– SD 카드 슬롯입니다.eth_present– 이더넷 PHY입니다.multicore_present– 다중 CPU 코어입니다.
기타
usb_highspeed– 불리언으로, USB가 고속 모드(USB 2.0 HS, 480 Mbps)로 열거되면True입니다.pmu_eventcnt– 사용 가능한 PMU 이벤트 카운터의 수이며, PMU가 없으면0입니다.
13.3.1.6.7. 진단¶
13.3.1.6.8. 프로파일러¶
프로파일러는 계측된 펌웨어 모듈(현재 image, ml, ulab)에 대해 함수별 호출 횟수와 최소 / 최대 / 총 실행 시간을 보고합니다. 함수 진입과 종료는 컴파일 시점에 가로채집니다. 런타임은 각 시점에 단조 증가 마이크로초 카운터를 샘플링하고, 함수별로 결과를 누적하며, profile 채널을 통해 호스트에 테이블을 노출합니다.
프로파일러는 make 에 PROFILE_ENABLE=1 이 전달될 때만 펌웨어에 빌드됩니다. 기본 펌웨어 이미지에는 포함되지 않습니다. 빌드가 추적 모듈에 추가하는 -finstrument-functions 플래그는 무시할 수 없는 런타임 오버헤드를 가지므로, 프로파일링 빌드는 이를 필요로 하는 특정 디버깅 세션을 위해 소스에서 생성됩니다. 펌웨어가 이 플래그로 빌드되지 않은 경우 profile 채널은 등록되지 않으며, 이 페이지의 모든 프로파일러 메서드는 아무 작업도 하지 않고 조용히 반환됩니다.
Arm Performance Monitoring Unit (PMU)은 Cortex-M55의 하드웨어 카운터 블록으로, 사이클 수, 캐시 적중 및 실패, 분기 동작, 그 밖의 아키텍처에 정의된 이벤트를 측정 대상 코드의 속도를 저하시키지 않고 추적하는 구성 가능한 소수의 카운터 집합입니다. PMU를 갖춘 cam에서 – AE3와 N6, 즉 M55를 기반으로 만들어진 OpenMV 제품군의 두 cam – 프로파일러는 타이밍 데이터와 함께 이러한 카운터를 샘플링하며 이벤트 합계는 각 함수별 레코드에 표시됩니다. PMU가 없는 cam도 타이밍 레코드는 생성하지만, 이벤트 필드는 0으로 반환되고 profiler_event()는 아무 동작도 하지 않습니다.
- Camera.profiler_mode(exclusive: bool = False) None¶
포함적 타이밍과 배타적 타이밍을 전환합니다. 포함적 타이밍은 피호출자의 시간을 호출자에게 부과하고, 배타적 타이밍은 그렇지 않습니다.
- 매개변수:
exclusive –
True는 배타적 타이밍을,False는 포함적 타이밍을 선택합니다.
- Camera.profiler_reset(config: list | None = None) None¶
모든 프로파일 카운터를 지웁니다.
config=None이면 기본 PMU 이벤트 할당도 복원합니다.- 매개변수:
config – 향후의 카운터별 구성 재정의를 위해 예약되었습니다. 기본값을 유지하려면
None을 전달하십시오.
13.3.1.6.9. 서브클래싱 및 채널 내부 구조¶
위에 문서화된 메서드는 패키지의 모든 일반적인 사용을 다룹니다. 일부 패턴(호스트가 반응하고자 하는 카메라 측 이벤트 처리, 다단계 교환을 위한 채널 잠금, 바이트 스트림 대신 형태가 정해진 데이터를 전달하는 채널과의 통신, 또는 채널별 제어 명령 구동)에는 Camera 가 밑줄로 접두사를 붙여 유지하는 메서드가 필요합니다. 이러한 이름은 관례상 비공개이며(Python은 이름을 맹글링하지 않음), 이를 필요로 하는 애플리케이션은 Camera 를 서브클래싱하거나 메서드를 직접 호출하도록 기대됩니다.
이벤트에 반응하기 위한 서브클래싱. 카메라가 발생시키는 모든 이벤트는 Camera._handle_event() 를 통해 도착합니다. Camera 를 서브클래싱하고 이 메서드를 재정의하는 것이 애플리케이션이 카메라 측 스크립트가 발생시키는 이벤트에 반응하는 방법입니다. 이벤트 페이지에서 전체 패턴을 설명합니다.
- Camera._handle_event(channel_id: int, event: int) None¶
카메라로부터 이벤트 하나를 디스패치합니다. 이벤트 패킷이 도착할 때마다 트랜스포트 계층에 의해 호출됩니다. 애플리케이션별 처리를 추가하려면 서브클래스에서 재정의하고, 기본 동작(
CHANNEL_REGISTERED시 채널 목록 갱신,stream채널의 프레임 준비 추적,stdin채널 시작 / 중지 로깅)을 유지하려면super()._handle_event(...)를 호출하십시오.- 매개변수:
channel_id – 시스템 이벤트의 경우
0이며, 그렇지 않으면 등록된 채널 ID입니다.event – 이벤트 식별자입니다. 시스템 이벤트의 값은
EventType열거형에서 나오고, 채널 이벤트의 값은 카메라 측 채널 백엔드가 선택한 값에서 나옵니다.
자체 프로토콜 통신 메서드를 추가하는 서브클래스는 이 페이지의 모든 제공 메서드가 갖는 동일한 재동기화 및 재시도 동작을 상속하도록 retry_if_failed() 로 데코레이션해야 합니다.
- static Camera.retry_if_failed(func)¶
데코레이터입니다. 트랜스포트가
ResyncException을 발생시킬 때 한 번 재시도하도록 인스턴스 메서드를 래핑합니다._send_cmd_wait_resp()를 (직접 또는_channel_*래퍼 중 하나를 통해) 호출하는 모든 메서드는 이 데코레이터를 가져야 합니다:class MyCamera(Camera): @Camera.retry_if_failed def my_custom_command(self, payload): return self._send_cmd_wait_resp(Opcode.MY_CMD, 0, payload)
채널 잠금은 두 관련 작업 사이에 채널 상태가 변경되지 않도록 보장합니다(예를 들어 데이터를 계속 추가하는 채널에서 _channel_size() 다음에 _channel_read() 를 수행하는 경우). read_frame() 과 read_profile() 은 내부적으로 이를 사용하며, 다단계 접근으로 사용자 정의 채널을 구동하는 애플리케이션도 마찬가지입니다.
- Camera._channel_lock(channel_id: int) bool¶
채널에 대한 배타적 잠금을 획득합니다. 동일 채널에 대한 다른 호스트 작업은 잠금이 해제될 때까지 블록됩니다.
- 매개변수:
channel_id – 숫자 채널 ID이며, 일반적으로
get_channel()로 해석됩니다.- 반환:
잠금이 허용되면
True입니다.
- Camera._channel_unlock(channel_id: int) bool¶
_channel_lock()으로 이전에 획득한 잠금을 해제합니다. 항상 잠금 호출과 짝을 이룹니다. 중간의 읽기가 예외를 발생시키더라도 잠금 해제가 일어나도록try/finally를 사용하십시오.- 매개변수:
channel_id – 숫자 채널 ID이며, 일반적으로
get_channel()로 해석됩니다.
형태가 정해진 채널은 평면 바이트 스트림 대신 구조화된 레코드를 전달합니다. 프로파일러 채널이 제공되는 예입니다. 그 형태는 (record_count, record_size) 이며, 대기 중인 레코드 수를 알고자 하는 호스트는 바이트 크기 대신 형태를 읽습니다.
- Camera._channel_shape(channel_id: int) tuple[int, ...]¶
채널의 형태 디스크립터를 읽습니다.
- 매개변수:
channel_id – 숫자 채널 ID이며, 일반적으로
get_channel()로 해석됩니다.- 반환:
채널의 레이아웃을 설명하는 부호 없는 32비트 정수의 튜플입니다. 의미는 채널별로 다릅니다.
채널별 제어 명령 – 시작, 중지, 리셋, 구성 – 은 채널별 명령 번호와 선택적 struct.pack 페이로드를 갖춘 단일 opcode(CHANNEL_IOCTL)를 통해 전달됩니다. stop(), exec(), streaming() 같은 기본 제공 메서드는 stdin 및 stream 채널에 대한 _channel_ioctl() 호출을 감싼 얇은 래퍼입니다. 자체 ioctl 메뉴를 정의하는 cam 측 사용자 정의 채널도 동일한 방식으로 구동됩니다.
- Camera._channel_ioctl(channel_id: int, cmd: int, fmt: str | None = None, *args) bytes | None¶
채널에 ioctl 명령을 발행합니다.
- 매개변수:
channel_id – 숫자 채널 ID이며, 일반적으로
get_channel()로 해석됩니다.cmd – 카메라 측 채널 백엔드가 정의한 명령 번호입니다.
fmt – 인자 튜플을 위한 선택적
struct포맷 문자열입니다. 인자를 받지 않는 ioctl의 경우None을 전달하십시오.args –
fmt와 일치하는 값입니다.
- 반환:
채널이 반환한 페이로드이며, 없으면
None입니다.
공개 채널 메서드의 ID 기반 바이트 스트림 변형은 이름-ID 조회를 생략하고 명시적인 바이트 offset 을 받습니다. 큰 버퍼의 중간에서 일부를 읽는 데 유용합니다(예를 들어 profile 채널 레코드).
- Camera._channel_size(channel_id: int) int¶
- 매개변수:
channel_id – 숫자 채널 ID이며, 일반적으로
get_channel()로 해석됩니다.- 반환:
채널에서 현재 사용 가능한 바이트입니다.
- Camera._channel_read(channel_id: int, offset: int, length: int) bytes¶
offset에서 시작하여length바이트를 읽습니다. 다중 패킷 읽기는 자동으로 재조립됩니다.- 매개변수:
channel_id – 숫자 채널 ID이며, 일반적으로
get_channel()로 해석됩니다.offset – 읽기를 시작할 바이트 오프셋입니다.
length – 읽을 바이트 수입니다.
- Camera._channel_write(channel_id: int, data: bytes, offset: int = 0) None¶
지정된
offset에data를 씁니다. 다중 패킷 쓰기는 자동으로 여러 패킷으로 분할됩니다.- 매개변수:
channel_id – 숫자 채널 ID이며, 일반적으로
get_channel()로 해석됩니다.data – 쓸 바이트형 페이로드입니다.
offset – 쓰기를 시작할 바이트 오프셋입니다.
프로토콜 프리미티브는 클래스가 노출하는 가장 낮은 수준으로, 위의 모든 것이 결국 그 위에 구축되는 원시 명령 전송, 원시 채널 목록 가져오기, 수동 재동기화 항목입니다. 클래스가 아직 래핑하지 않은 옵코드를 보내거나 서브클래스에서 사용자 정의 복구를 구현할 때 애플리케이션이 이를 사용합니다.
- Camera._send_cmd_wait_resp(opcode: int, channel: int = 0, data: bytes = b'') bytes | None¶
프로토콜 명령을 보내고 카메라의 응답을 기다립니다. 이 섹션의 다른 모든 메서드가 구축되는 프리미티브입니다.
- 매개변수:
opcode – 명령 번호입니다. 제공되는
Opcode열거형은 펌웨어가 함께 제공하는 코드를 나열하지만, 이 매개변수는 단지 정수일 뿐이므로 사용자 정의 펌웨어 빌드가 자체 코드를 정의하고 응답할 수 있습니다.channel – 채널 ID이며, 시스템 명령의 경우
0입니다.data – 명령별 페이로드입니다.
- 반환:
응답 페이로드이며, 연결을 끊는
Opcode.SYS_RESET및Opcode.SYS_BOOT같은 명령의 경우None입니다.
- Camera._channel_list() dict¶
update_channels()가 채우는 캐시된channels_by_id및channels_by_name딕셔너리를 건드리지 않고 카메라로부터 현재 채널 목록을 가져옵니다. 카메라의 채널 상태를 직접 검사하고자 하는 서브클래스에 유용합니다.- 반환:
채널 ID를
{'name': str, 'flags': int}에 매핑하는 딕셔너리입니다.
- Camera._resync() None¶
프로토콜 핸드셰이크를 처음부터 다시 실행합니다. 초기 연결 시
connect()에 의해, 그리고 트랜스포트로부터OMVException을 잡는 모든 공개 메서드에 의해 자동으로 호출됩니다. 서브클래스에서 자체 복구 루프를 구현하는 애플리케이션은 기저 오류를 처리한 후 이를 직접 호출할 수 있습니다.
13.3.1.6.10. 예외¶
- exception openmv.OMVException¶
모든 프로토콜 수준 오류의 기반 클래스입니다. 아래의 세 서브클래스가 모두 이를 상속하므로, 단일
except OMVException으로 전체 오류 영역을 다룰 수 있습니다.
- exception openmv.TimeoutException¶
카메라가 구성된 타임아웃 내에 응답하지 않았습니다.
OMVException의 서브클래스입니다.
- exception openmv.ChecksumException¶
패킷의 CRC가 일치하지 않았습니다. 프로토콜이 재시도 예산을 소진한 후 발생합니다.
OMVException의 서브클래스입니다.
- exception openmv.SequenceException¶
재시도 후에도 예상치 못한 시퀀스 번호의 패킷이 도착했습니다.
OMVException의 서브클래스입니다.