machine — функции, связанные с аппаратным обеспечением

Модуль machine содержит специальные функции, связанные с аппаратным обеспечением конкретной платы. Большинство функций в этом модуле позволяют получить прямой и неограниченный доступ к аппаратным блокам системы (таким как ЦП, таймеры, шины и т. д.) и управление ими.

Доступ к памяти

Модуль предоставляет три индексируемых объекта, используемых для прямого доступа к памяти. Каждый ведёт себя как разреженный массив, индексируемый по адресу байта: value = memN[addr] читает, memN[addr] = value записывает. Адрес всегда является адресом байта, независимо от ширины доступа.

machine.mem8

Индексируемый 8-битный аксессор памяти. mem8[addr] читает int в диапазоне 0-255 из байта по адресу addr; mem8[addr] = value записывает младшие 8 бит value. addr должен быть выровнен по 1 байту (любой адрес).

machine.mem16

Индексируемый 16-битный (полуслово) аксессор памяти. mem16[addr] читает int в диапазоне 0-65535; mem16[addr] = value записывает младшие 16 бит. addr должен быть выровнен по 2 байтам.

machine.mem32

Индексируемый 32-битный (слово) аксессор памяти. mem32[addr] читает int в диапазоне 0-0xFFFFFFFF; mem32[addr] = value записывает младшие 32 бита. addr должен быть выровнен по 4 байтам.

Пример использования (регистры специфичны для микроконтроллера STM32H7 — на OpenMV Cam H7 / H7 Plus / Pure Thermal вывод разъёма P0 подключён к PB15):

import machine
from micropython import const

GPIOB = const(0x58020400)
GPIO_BSRR = const(0x18)
GPIO_IDR = const(0x10)

# set P0 (PB15) high via the GPIOB bit-set/reset register
machine.mem32[GPIOB + GPIO_BSRR] = 1 << 15

# read P0 (PB15) directly out of the GPIOB input-data register
value = (machine.mem32[GPIOB + GPIO_IDR] >> 15) & 1

Функции, связанные со сбросом

machine.reset() → None

Аппаратно сбрасывает устройство аналогично нажатию внешней кнопки RESET.

machine.soft_reset() → None

Выполняет программный сброс интерпретатора, удаляя все объекты Python и сбрасывая кучу Python.

machine.reset_cause() → int

Получает причину сброса. См. константы для возможных возвращаемых значений.

machine.bootloader(value: int | None = None, /) → NoReturn

Сбрасывает камеру в её загрузчик DFU / последовательной загрузки, готовый к повторной прошивке новой прошивкой. Этот вызов никогда не возвращается; плата перезагружается прямо в загрузчик.

Аргумент value принимается для совместимости между портами, но игнорируется на каждой плате, поддерживаемой OpenMV.

Функции, связанные с прерываниями

Следующие функции позволяют управлять прерываниями. Некоторые системы требуют прерываний для корректной работы, поэтому отключение их на длительные периоды может нарушить основную функциональность, например, сторожевые таймеры могут неожиданно сработать. Прерывания следует отключать только на минимально необходимое время, а затем снова включать в их предыдущее состояние. Например:

import machine

# Disable interrupts
state = machine.disable_irq()

# Do a small amount of time-critical work here

# Enable interrupts
machine.enable_irq(state)

machine.disable_irq() → int

Отключает запросы прерываний. Возвращает предыдущее состояние IRQ, которое следует считать непрозрачным значением. Это возвращаемое значение следует передать функции enable_irq(), чтобы восстановить прерывания в их исходное состояние, существовавшее до вызова disable_irq().

machine.enable_irq(state: int) → None

Снова включает запросы прерываний. Параметр state должен быть значением, которое было возвращено последним вызовом функции disable_irq().

Функции, связанные с питанием

machine.freq(hz: int | None = None, /) → int | tuple[int, ...]

Возвращает тактовые частоты MCU.

На портах STM32 (каждая OpenMV Cam M4/M7/H7/H7+/PT/N6 и варианты под брендом Arduino) возвращаемое значение является кортежем внутренних тактовых частот в Гц. На STM32N6 (OpenMV Cam N6) кортеж имеет вид (CPUCLK, SYSCLK, HCLK, PCLK1, PCLK2, PCLK4, PCLK5); на других камерах STM32 он имеет вид (SYSCLK, HCLK, PCLK1, PCLK2).

На порту mimxrt (OpenMV Cam RT1062) и порту alif (OpenMV Cam AE3) возвращаемое значение является одним целым числом — частотой ЦП в Гц.

Вызов freq(hz) для установки тактовой частоты вызывает NotImplementedError на каждой плате, поддерживаемой OpenMV.

machine.idle() → None

Останавливает тактирование ЦП, что полезно для снижения энергопотребления в любой момент в течение коротких или длительных периодов. Периферийные устройства продолжают работать, а выполнение возобновляется сразу при срабатывании любого прерывания или не позднее чем через одну миллисекунду после приостановки ЦП.

Рекомендуется вызывать эту функцию внутри любого плотного цикла, который непрерывно проверяет наличие внешних изменений (т. е. опрос). Это снизит энергопотребление без существенного влияния на производительность. Для дальнейшего снижения энергопотребления см. функции lightsleep(), time.sleep() и time.sleep_ms().

machine.sleep() → None

Примечание

Эта функция устарела, используйте вместо неё lightsleep() без аргументов.

machine.lightsleep(time_ms: int | None = None, /) → None

Останавливает выполнение и переходит в режим пониженного энергопотребления с полным сохранением RAM и периферийных устройств. Тактирование MCU прекращается; когда функция возвращается, выполнение возобновляется с того места, где была вызвана lightsleep(), при этом все подсистемы остаются работоспособными.

Если задано time_ms, это максимальная продолжительность сна в миллисекундах. С тайм-аутом или без него выполнение может возобновиться раньше, если сработает любой настроенный источник пробуждения (IRQ Pin, будильник RTC, включённое прерывание периферийного устройства, …). Источники пробуждения должны быть настроены до вызова.

Экономия энергии более скромная, чем у deepsleep(), но пробуждение мгновенное, и состояние не теряется.

machine.deepsleep(time_ms: int | None = None, /) → NoReturn

Останавливает выполнение и переходит в самый глубокий из доступных режимов пониженного энергопотребления. Содержимое RAM, состояние периферийных устройств и сетевые соединения могут быть потеряны. Когда MCU пробуждается, он загружается с начала основного скрипта, аналогично включению питания или аппаратному сбросу; reset_cause() затем вернёт DEEPSLEEP_RESET, чтобы скрипт мог отличить пробуждение из deepsleep от других причин сброса.

Если задано time_ms, MCU планирует пробуждение через указанное количество миллисекунд (или раньше, если первым сработает другой настроенный источник пробуждения). Не передавайте ничего, чтобы спать до срабатывания внешнего источника пробуждения.

Этот вызов никогда не возвращается — обрабатывайте возобновлённое выполнение в начале основного скрипта, ориентируясь на reset_cause().

Прочие функции

machine.unique_id() → bytes

Возвращает объект bytes, содержащий уникальный идентификатор этой платы. Значение считывается из аппаратного обеспечения MCU (как правило, заводской серийный номер устройства), поэтому оно стабильно между перезагрузками и различается от одной платы к другой.

Длина зависит от семейства MCU — 12 байт на STM32, 8 байт на портах mimxrt и alif. Если вашему приложению нужен идентификатор фиксированной длины, нарежьте или хешируйте возвращаемое значение.

machine.time_pulse_us(pin: Pin, pulse_level: int, timeout_us: int = 1000000, /) → int

Измеряет ширину одного импульса на pin и возвращает его длительность в микросекундах.

pin должен быть настроен как цифровой вход.

pulse_level — полярность импульса, который нужно измерить: 1 для высокого импульса, 0 для низкого импульса.

Функция работает в две фазы. Сначала, если вывод ещё не находится на уровне pulse_level, она ждёт перехода вывода на уровень pulse_level (начало импульса). Затем она измеряет время, в течение которого вывод остаётся на уровне pulse_level до обратного перехода (конец импульса). Измеренное время возвращается в микросекундах.

timeout_us ограничивает каждую фазу независимо (поэтому в худшем случае вызов длится до 2 * timeout_us). При тайм-ауте функция возвращает отрицательное значение, указывающее, в какой фазе произошёл тайм-аут:

• -2 — тайм-аут при ожидании переднего фронта (вывод так и не достиг pulse_level).

• -1 — тайм-аут при ожидании заднего фронта (импульс был длиннее timeout_us).

machine.bitstream(pin: Pin, encoding: int, timing: tuple, data: bytes, /) → None

Передаёт data, выполняя битовую манипуляцию на указанном pin. Аргумент encoding задаёт, как кодируются биты, а timing — специфичная для кодирования спецификация тайминга.

Поддерживаются следующие кодировки:

• 0 для модуляции длительности импульса по принципу «high low». Это передаёт биты 0 и 1 как тактированные импульсы, начиная со старшего значащего бита. timing должен быть кортежем из четырёх элементов в наносекундах в формате (high_time_0, low_time_0, high_time_1, low_time_1). Например, (400, 850, 800, 450) — это спецификация тайминга для RGB-светодиодов WS2812 на частоте 800 кГц.

Точность тайминга зависит от аппаратного обеспечения; более быстрые MCU дают более точные импульсы (как правило, десятки наносекунд).

Примечание

Для управления лентами WS2812 / NeoPixel см. модуль neopixel, предоставляющий более высокоуровневый API.

Константы

Приведённые ниже константы возвращаются функцией reset_cause() и указывают, почему MCU в последний раз был сброшен. Доступно на портах STM32 и mimxrt; порт alif (OpenMV Cam AE3) в настоящее время не предоставляет констант причины сброса, и его reset_cause() всегда возвращает 0.

machine.PWRON_RESET: int

Сброс, вызванный подачей питания на чип. Порты STM32 и mimxrt.

machine.WDT_RESET: int

Сброс, вызванный истечением сторожевого таймера. Порты STM32 и mimxrt.

machine.SOFT_RESET: int

Сброс, вызванный soft_reset() (интерпретатор Python был перезапущен без аппаратного сброса). Порты STM32 и mimxrt.

machine.HARD_RESET: int

Сброс, вызванный активацией вывода NRST (внешняя кнопка сброса). Только порты STM32.

machine.DEEPSLEEP_RESET: int

Сброс, вызванный пробуждением из режима deep-sleep. Только порты STM32.

Классы

• class Pin – управление вводами/выводами
• class Signal – управление и считывание внешних устройств ввода-вывода
• класс LED – переносимое управление встроенным светодиодом
• class ADC – аналого-цифровое преобразование
• класс PWM – широтно-импульсная модуляция
• class UART – дуплексная последовательная шина связи
• class SPI – протокол шины последовательного периферийного интерфейса (Serial Peripheral Interface, сторона контроллера)
• class SoftSPI – программно эмулируемая шина SPI
• class I2C – двухпроводной последовательный протокол
• class SoftI2C – программно-эмулируемая шина I2C
• class I2CTarget – целевое устройство I2C
• класс I2S – протокол шины Inter-IC Sound
• class CAN – протокол Controller Area Network
• class RTC – часы реального времени
• class Timer – виртуальный периодический / однократный таймер
• class WDT – сторожевой таймер
• class SDCard – драйвер карт SD / MMC
• class Counter – счётчик импульсов
• class Encoder – квадратурный декодер