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.8

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.8
File Size Uploaded Provenance Actions
openmv-1.0.8.tar.gz 36.2 kB With provenance Details for openmv-1.0.8.tar.gz

Built distribution (wheel)

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

Total release size: 67.2 kB

Release files / openmv-1.0.8.tar.gz

Download URL openmv-1.0.8.tar.gz
Size 36.2 kB
Tags Source
SHA-256 checksum
How to use checksums
4dc5b7e24ffe873867dbc4fb4d18a79be21f17b22091416648cf98755e24478f
BLAKE2b-256 checksum
How to use checksums
ccb11a72c0d39467c386556527bf97d4ebdfaaeb396385fd3396b133daaaa273
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 7, 2026.

Transparency log

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

Download URL openmv-1.0.8-py3-none-any.whl
Size 30.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5830c4407877aba0eafed413a8c45ee06f16fb232ef6ea611805a9744e22bb58
BLAKE2b-256 checksum
How to use checksums
79b14378f86e22c9db18acb14d3993232ba2b0d816edb6c2aba7b1a8f34c9301
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 7, 2026.

Transparency log

Security for openmv 1.0.8

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.8.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 7, 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