Skip to main content

OpenMV Python

Python library and CLI for communicating with OpenMV cameras.

Installation

pip install openmv

CLI Usage

Examples

# Basic usage - stream video from camera
openmv --port /dev/ttyACM0

# Run a custom script
openmv --port /dev/ttyACM0 --script my_script.py

# Adjust display scale (default is 4x)
openmv --port /dev/ttyACM0 --scale 5

# Run throughput benchmark
openmv --port /dev/ttyACM0 --bench

# Load firmware symbols for profiler function names
openmv --port /dev/ttyACM0 --firmware build/firmware.elf

# Quiet mode (suppress script output)
openmv --port /dev/ttyACM0 --quiet

# Debug mode (verbose logging)
openmv --port /dev/ttyACM0 --debug

# Preview a custom data channel
openmv --port /dev/ttyACM0 --channel ticks

Options

Option Default Description
--port PORT /dev/ttyACM0 Serial port
--script FILE None MicroPython script file to execute
--scale N 4 Display scaling factor
--poll MS 4 Poll rate in milliseconds
--bench False Run throughput benchmark mode
--raw False Enable raw streaming mode
--timeout SEC 1.0 Protocol timeout in seconds
--baudrate N 921600 Serial baudrate
--firmware FILE None Firmware ELF file for profiler symbol resolution
--channel NAME None Custom data channel to poll and print
--quiet False Suppress script output text
--debug False Enable debug logging

Protocol Options

Option Default Description
--crc BOOL true Enable CRC validation
--seq BOOL true Enable sequence number validation
--ack BOOL true Enable packet acknowledgment
--events BOOL true Enable event notifications
--max-retry N 3 Maximum number of retries
--max-payload N 4096 Maximum payload size in bytes
--drop-rate N 0.0 Packet drop simulation rate (0.0-1.0, for testing)

Keyboard Controls

Key Action
ESC Exit
P Cycle profiler overlay (Off → Performance → Events)
M Toggle profiler mode (Inclusive ↔ Exclusive)
R Reset profiler counters

Library Usage

from openmv import Camera

script = """
import csi, time

csi0 = csi.CSI()
csi0.reset()
csi0.pixformat(csi.RGB565)
csi0.framesize(csi.QVGA)
clock = time.clock()
while True:
    clock.tick()
    img = csi0.snapshot()
    print(clock.fps(), "FPS")
"""

# Connect to camera
with Camera('/dev/ttyACM0') as camera:
    # Stop running script (if any)
    camera.stop()

    # Execute script and enable streaming
    camera.exec(script)
    camera.streaming(True)

    # Read frames and output
    while True:
        if frame := camera.read_frame():
            print(f"Frame: {frame['width']}x{frame['height']}")

        if text := camera.read_stdout():
            print(text, end='')

Custom Channels

Custom channels allow bidirectional data exchange between the camera and host.

Camera-side script (MicroPython):

import time
import protocol

class TicksChannel:
    def size(self):
        return 10

    def read(self, offset, size):
        return f'{time.ticks_ms():010d}'

    def poll(self):
        return True

protocol.register(name='ticks', backend=TicksChannel())

Host-side (Python):

from openmv import Camera

with Camera('/dev/ttyACM0') as camera:
    camera.exec(script)

    while True:
        # Check if channel has data
        if camera.has_channel('ticks'):
            size = camera.channel_size('ticks')
            if size > 0:
                data = camera.channel_read('ticks', size)
                print(f"Ticks: {data.decode()}")

Quick Reference

Camera

from openmv import Camera

Camera(
    port,               # Serial port (e.g., '/dev/ttyACM0')
    baudrate=921600,    # Serial baudrate
    crc=True,           # Enable CRC validation
    seq=True,           # Enable sequence number validation
    ack=True,           # Enable packet acknowledgment
    events=True,        # Enable event notifications
    timeout=1.0,        # Protocol timeout in seconds
    max_retry=3,        # Maximum retries
    max_payload=4096,   # Maximum payload size
    drop_rate=0.0,      # Packet drop simulation (testing only)
)

Methods

Method Description
connect() / disconnect() Manage connection
is_connected() Check connection status
exec(script) Execute a MicroPython script
stop() Stop the running script
streaming(enable, raw=False, resolution=None) Enable/disable video streaming
read_frame() Read video frame → {width, height, format, depth, data, raw_size}
read_stdout() Read script output text
read_status() Poll channel status → {channel_name: bool, ...}
has_channel(name) Check if channel exists
channel_read(name, size=None) Read from custom channel
channel_write(name, data) Write to custom channel
channel_size(name) Get available data size
version() Get firmware, protocol, and bootloader versions
system_info() Get camera system information
host_stats() / device_stats() Get protocol statistics

Profiler Methods (if available)

Method Description
read_profile() Read profiler data
profiler_mode(exclusive) Set inclusive/exclusive mode
profiler_reset(config=None) Reset profiler counters
profiler_event(counter_num, event_id) Configure event counter

Exceptions

Exception Description
OMVException Base protocol exception
TimeoutException Timeout during communication
ChecksumException CRC validation failure
SequenceException Sequence number mismatch

API documentation

Full API documentation: docs/api.md

Requirements

  • Python 3.8+
  • pyserial >= 3.5
  • numpy >= 1.20.0
  • pygame >= 2.0.0
  • pyelftools

License

MIT License - Copyright (c) 2025 OpenMV, LLC.

Metadata

Release files for openmv 1.0.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for openmv 1.0.9
File Size Uploaded Provenance Actions
openmv-1.0.9.tar.gz 36.3 kB With provenance Details for openmv-1.0.9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for openmv 1.0.9
File Interpreter ABI Platform Actions
openmv-1.0.9-py3-none-any.whl Python 3 none any Details for openmv-1.0.9-py3-none-any.whl

Total release size: 67.4 kB

Release files / openmv-1.0.9.tar.gz

Download URL openmv-1.0.9.tar.gz
Size 36.3 kB
Tags Source
SHA-256 checksum
How to use checksums
1c2e31b372ba338510f4c0a280de3ef1f06a6ce6364abce60ba33727ac782b0d
BLAKE2b-256 checksum
How to use checksums
4233440e70078365c43c73dc6506e5c50392de59535a3842d222e1c3c6265e31
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

Release files / openmv-1.0.9-py3-none-any.whl

Download URL openmv-1.0.9-py3-none-any.whl
Size 31.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
17f823152ac7ae9eb409358526f4e57a499671fa56d91909ccf9dc37e87222e3
BLAKE2b-256 checksum
How to use checksums
b0fdf0828be2c95b9580a96cd42b334c78d49d9c54db3d556d15c3c3ee23b60e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

Security for openmv 1.0.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for openmv-1.0.9.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page