machine — functions related to the hardware

The machine module contains specific functions related to the hardware on a particular board. Most functions in this module allow to achieve direct and unrestricted access to and control of hardware blocks on a system (like CPU, timers, buses, etc.). Used incorrectly, this can lead to malfunction, lockups, crashes of your board, and in extreme cases, hardware damage.

Memory access

The module exposes three objects used for raw memory access.

machine.mem8

Read/write 8 bits of memory.

machine.mem16

Read/write 16 bits of memory.

machine.mem32

Read/write 32 bits of memory.

Use subscript notation [...] to index these objects with the address of interest. Note that the address is the byte address, regardless of the size of memory being accessed.

Reset related functions

machine.reset()

Hard resets the device in a manner similar to pushing the external RESET button.

machine.soft_reset()

Performs a soft reset of the interpreter, deleting all Python objects and resetting the Python heap.

machine.reset_cause()

Get the reset cause. See constants for the possible return values.

Power related functions

machine.idle()

Gates the clock to the CPU, useful to reduce power consumption at any time during short or long periods. Peripherals continue working and execution resumes as soon as any interrupt is triggered, or at most one millisecond after the CPU was paused.

It is recommended to call this function inside any tight loop that is continuously checking for an external change (i.e. polling). This will reduce power consumption without significantly impacting performance.

Miscellaneous functions

machine.bitstream(pin, encoding, timing, data, /)

Transmits data by bit-banging the specified pin. The encoding argument specifies how the bits are encoded, and timing is an encoding-specific timing specification.

The supported encodings are:

• 0 for “high low” pulse duration modulation. This will transmit 0 and 1 bits as timed pulses, starting with the most significant bit. The timing must be a four-tuple of nanoseconds in the format (high_time_0, low_time_0, high_time_1, low_time_1). For example, (400, 850, 800, 450) is the timing specification for WS2812 RGB LEDs at 800kHz.

The accuracy of the timing varies between ports. On Cortex M0 at 48MHz, it is at best +/- 120ns, however on faster MCUs (ESP8266, ESP32, STM32, Pyboard), it will be closer to +/-30ns.

Note

For controlling WS2812 / NeoPixel strips, see the neopixel module for a higher-level API.

Constants

machine.IDLE

IRQ wake values.

machine.WDT_RESET

Reset causes.

Classes

• class Pin – control I/O pins
• class Signal – control and sense external I/O devices
• class ADC – analog to digital conversion
• class DAC – digital to analog conversion
• class UART – duplex serial communication bus
• class SPI – a Serial Peripheral Interface bus protocol (controller side)
• class I2C – a two-wire serial protocol
• class RTC – real time clock
• class Timer – control internal timers
• class WDT – watchdog timer
• class Flash – access to built-in flash storage