pyb — functions related to the board

Warning

The pyb module is deprecated. Use the cross-port machine module for new code – it provides the same functionality on every OpenMV Cam regardless of MCU family, whereas pyb exists only on the STM32-based boards. pyb is retained for backwards compatibility with older scripts, no new features will be added, and it may be removed in a future release.

The pyb module contains STM32-specific functions related to the board.

Time related functions

pyb.delay(ms: int) → None

Delay for the given number of milliseconds.

pyb.udelay(us: int) → None

Delay for the given number of microseconds.

pyb.millis() → int

Returns the number of milliseconds since the board was last reset.

The result is always a MicroPython smallint (31-bit signed number), so after 2^30 milliseconds (about 12.4 days) this will start to return negative numbers.

Note that if pyb.stop() is issued the hardware counter supporting this function will pause for the duration of the “sleeping” state. This will affect the outcome of pyb.elapsed_millis().

pyb.micros() → int

Returns the number of microseconds since the board was last reset.

The result is always a MicroPython smallint (31-bit signed number), so after 2^30 microseconds (about 17.8 minutes) this will start to return negative numbers.

Note that if pyb.stop() is issued the hardware counter supporting this function will pause for the duration of the “sleeping” state. This will affect the outcome of pyb.elapsed_micros().

pyb.elapsed_millis(start: int) → int

Returns the number of milliseconds which have elapsed since start.

This function takes care of counter wrap, and always returns a positive number. This means it can be used to measure periods up to about 12.4 days.

Example:

start = pyb.millis()
while pyb.elapsed_millis(start) < 1000:
    # Perform some operation

pyb.elapsed_micros(start: int) → int

Returns the number of microseconds which have elapsed since start.

This function takes care of counter wrap, and always returns a positive number. This means it can be used to measure periods up to about 17.8 minutes.

Example:

start = pyb.micros()
while pyb.elapsed_micros(start) < 1000:
    # Perform some operation
    pass

Reset related functions

pyb.hard_reset() → None

Resets the OpenMV Cam in a manner similar to pushing the external RESET button.

pyb.bootloader() → None

Reset into OpenMV’s own USB DFU bootloader, ready for a firmware update. This is the recommended way to invoke DFU from running code – no BOOT pin needs to be asserted at reset.

Not available on the OpenMV Cam N6 (the pyb legacy compatibility layer is disabled on that board); use machine.bootloader() instead.

pyb.fault_debug(value: bool) → None

Enable or disable hard-fault debugging. A hard-fault is when there is a fatal error in the underlying system, like an invalid memory access.

If the value argument is False then the board will automatically reset if there is a hard fault.

If value is True then, when the board has a hard fault, it will print the registers and the stack trace, and then cycle the LEDs indefinitely.

The default value is disabled, i.e. to automatically reset.

Interrupt related functions

pyb.disable_irq() → bool

Disable interrupt requests. Returns the previous IRQ state: False/True for disabled/enabled IRQs respectively. This return value can be passed to enable_irq to restore the IRQ to its original state.

pyb.enable_irq(state: bool = True) → None

Enable interrupt requests. If state is True (the default value) then IRQs are enabled. If state is False then IRQs are disabled. The most common use of this function is to pass it the value returned by disable_irq to exit a critical section.

pyb.freq(sysclk: int | None = None, hclk: int | None = None, pclk1: int | None = None, pclk2: int | None = None) → Tuple[int, int, int, int] | None

If given no arguments, returns a tuple of clock frequencies (sysclk, hclk, pclk1, pclk2) in hertz:

Field	Meaning
sysclk	CPU frequency
hclk	AHB bus, core memory and DMA frequency
pclk1	APB1 bus frequency
pclk2	APB2 bus frequency

If given any arguments then the function sets the CPU frequency (and bus frequencies if additional arguments are supplied). Frequencies are in hertz; the largest supported frequency not greater than the given value is selected. The set of valid sysclk frequencies and the maximum hclk / pclk1 / pclk2 values depend on the MCU – refer to the relevant STM32 reference manual for the OpenMV Cam in use. The bus frequencies are derived from sysclk via prescalers the driver picks to best match the requested values.

Warning

Changing the frequency while USB is enabled may make USB unreliable. Change it from boot.py, before the USB peripheral is started, and do not select a sysclk value too low for the USB clock requirements of the MCU.

Power related functions

pyb.wfi() → None

Wait for an internal or external interrupt.

This executes a wfi instruction which reduces power consumption of the MCU until any interrupt occurs (be it internal or external), at which point execution continues. Note that the system-tick interrupt occurs once every millisecond (1000Hz) so this function will block for at most 1ms.

pyb.stop() → None

Put the OpenMV Cam into the STM32 stop low-power state. Execution continues from this point on wake-up. Wake-up requires an external interrupt or a real-time-clock event; see pyb.RTC.wakeup() to configure one. The exact achievable current draw depends on the board and on which peripherals are left clocked.

pyb.standby() → None

Put the OpenMV Cam into the STM32 standby deep-sleep state. This is the lowest power-down level; the device exits via a hard reset when woken, so execution does not resume in place. Wake-up requires a real-time-clock event; see pyb.RTC.wakeup() to configure one. The exact achievable current draw depends on the board.

Miscellaneous functions

pyb.have_cdc() → bool

Return True if USB is connected as a serial device, False otherwise.

Note

This function is deprecated. Use pyb.USB_VCP().isconnected() instead.

pyb.hid(data: Tuple[int, int, int, int]) → None

Takes a 4-tuple (or list) and sends it to the USB host (the PC) to signal a HID mouse-motion event.

Note

This function is deprecated. Use pyb.USB_HID.send() instead.

pyb.info(dump_alloc_table: bool | None = None) → None

Print out lots of information about the board.

pyb.main(filename: str) → None

Set the filename of the main script to run after boot.py is finished. If this function is not called then the default file main.py will be executed.

It only makes sense to call this function from within boot.py.

pyb.mount(device: Any, mountpoint: str, *, readonly: bool = False, mkfs: bool = False) → None

Note

This function is deprecated. Use vfs.mount() / vfs.umount() and a vfs.AbstractBlockDev-derived block device instead.

Mount a block device under mountpoint. device must implement the legacy pyb block-device protocol (also deprecated – see vfs.AbstractBlockDev for the modern interface):

Method	Purpose
readblocks(self, blocknum, buf)	Copy buf worth of bytes from the device starting at block blocknum. buf length is a multiple of 512.
writeblocks(self, blocknum, buf) (optional)	Write buf to the device starting at block blocknum. If omitted, the device is mounted read-only.
count(self)	Return the number of 512-byte blocks on the device.
sync(self) (optional)	Flush any cached writes.

mountpoint is the path in the root of the filesystem to mount the device at; it must begin with a forward slash. readonly forces a read-only mount. mkfs creates a new filesystem if none is present.

pyb.repl_uart(uart: UART | None = None) → UART | None

Get or set the UART object where the REPL is repeated on.

pyb.rng() → int

Return a 30-bit hardware generated random number.

pyb.sync() → None

Sync all file systems.

pyb.unique_id() → bytes

Returns a string of 12 bytes (96 bits), which is the unique ID of the MCU.

pyb.usb_mode(modestr: str | None = None, port: int = -1, vid: int = 0xf055, pid: int = -1, msc: Tuple = (), hid: Tuple = pyb.hid_mouse, high_speed: bool = False) → str | None

If called with no arguments, return the current USB mode as a string.

If called with modestr provided, attempts to configure the USB mode. The following values of modestr are understood:

modestr	Configures
None	Disables USB.
'VCP'	VCP (Virtual COM Port) only.
'MSC'	MSC (USB mass storage class) only.
'VCP+MSC'	VCP and MSC.
'VCP+HID'	VCP and HID (human interface device).
'VCP+MSC+HID'	VCP, MSC and HID together. Not supported on every OpenMV Cam.

For backwards compatibility, 'CDC' is understood to mean 'VCP' (and similarly for 'CDC+MSC' and 'CDC+HID').

The port parameter should be an integer (0, 1, …) and selects which USB port to use if the board supports multiple ports. A value of -1 uses the default or automatically selected port.

The vid and pid parameters allow you to specify the VID (vendor id) and PID (product id). A pid value of -1 will select a PID based on the value of modestr.

If enabling MSC mode, the msc parameter can be used to specify a list of SCSI LUNs to expose on the mass storage interface. For example msc=(pyb.Flash(), pyb.SDCard()).

If enabling HID mode, you may also specify the HID details by passing the hid keyword parameter. It takes a tuple of (subclass, protocol, max packet length, polling interval, report descriptor). By default it will set appropriate values for a USB mouse. There is also a pyb.hid_keyboard constant, which is an appropriate tuple for a USB keyboard.

The high_speed parameter, when set to True, enables USB HS mode if it is supported by the hardware.

Constants

Both of the constants below are ready-made 5-tuples in the form

(subclass, protocol, max_packet_size, polling_interval_ms, report_descriptor)

suitable for passing as the hid argument of usb_mode() to make the OpenMV Cam appear to the host as a USB HID device. subclass = 1 means “boot interface” and protocol selects the boot device class (1 = keyboard, 2 = mouse). The fifth element is a bytes object holding the HID report descriptor used when the host enumerates the device.

pyb.hid_mouse: tuple

Pre-built HID descriptor for a 3-button boot mouse with relative X/Y movement. The tuple is (1, 2, 4, 8, <mouse report descriptor>): boot subclass, mouse protocol, 4-byte input reports (button mask + X + Y + wheel), polled every 8 ms. The built-in report descriptor is the one used by pyb.USB_HID().send((buttons, dx, dy, wheel)).

pyb.hid_keyboard: tuple

Pre-built HID descriptor for a USB boot keyboard. The tuple is (1, 1, 8, 8, <keyboard report descriptor>): boot subclass, keyboard protocol, 8-byte input reports (modifier byte, one reserved byte, six concurrent key codes), polled every 8 ms. The built-in report descriptor matches the standard 8-byte HID boot-keyboard layout, so the report sent via USB_HID.send() should be a bytes of the form (modifiers, 0, key1, key2, key3, key4, key5, key6).

Classes

• class ADC – analog to digital conversion
• class ADCAll – access all ADC channels
• class CAN – controller area network communication bus
• class DAC – digital to analog conversion
• class ExtInt – configure I/O pins to interrupt on external events
• class Flash – access to built-in flash storage
• class I2C – a two-wire serial protocol
• class LED – on-board LED
• class Pin – control I/O pins
• class PinAF – pin alternate functions
• class RTC – real time clock
• class Servo – 3-wire hobby servo driver
• class SPI – a controller-driven serial protocol
• class Timer – control internal timers
• class TimerChannel – setup a channel for a timer
• class UART – duplex serial communication bus
• class USB_HID – USB Human Interface Device (HID)
• class USB_VCP – USB virtual comm port