Machine (machine)

The modules described in this chapter provide the interface to the hardware interfaces in the machine module.

class machine.ADC(id: any)

The ADC class provides an interface to analog-to-digital converters, and represents a single endpoint that can sample a continuous voltage and convert it to a discretised value.

Multiple instances of the class can be created for each ADC input/pin that needs to be sampled.

Parameters:

id – Identifer of the ADC input to sample. This can be either an integer ADC channel number, a Pin object, or a string representing the pin name. The exact values that can be used depend on the platform.

init(**args)

Reconfigure the ADC channel with the given parameters.

Parameters:

  • sample_ns – The sampling time in nanoseconds. Not all values are supported by all platforms. If not supported, the closest supported value will be used.

  • atten – The attenuation value to use. A value of 2 will attenuate the by half. The default value is 1 (no attenuation).

  • gain – The gain value to use. Default value is 1 (no gain). A value of 2 will amplify the singal by 2.

read_u16() → int

Take an analog reading and return an integer in the range 0 to 65535.

Returns:

An integer in the range 0 to 65535. The value represents the raw reading from the ADC, scaled such that the minmum value is 0 and the maximum value is 65535.

read_uv() → int

Take an analog reading and return an integer in units of microvolts.

Returns:

An integer representing the voltage in microvolts.

class machine.I2C(device: any, address: int)

An I2C (Inter-Integrated Circuit) object is used to interact with the I2C peripheral. The two-wire interface can can be used to communicate with multiple devices on the same bus. Device addresses may be specific to the device, selectable by input pins, or programmable.

Parameters:

  • device – [str] Device identifier

  • device – [3-tuple] (Device identifier, SDA pin name, SCL pin name)

  • address – Device address

Zephyr example: I2C(“i2c@40003000”, 0x40)

Silicon Labs (Lyra) example: I2C((“I2C0”, “PD03”, “PD02”), 0x40)

0x40 is the 7-bit address of the TI HDC1010 (https://download.mikroe.com/documents/datasheets/hdc1010.pdf) that is part of the temperature and humidity click board (https://www.mikroe.com/temp-hum-4-click) that can be populated in the mikroBUS socket.

read(length: int) → any

Read from I2C device.

Parameters:

length – Number of bytes to read

set_address(address: int)

Set device address.

write(data: any) → int

Write to I2C device.

Parameters:

data – Buffer containing bytes to write

write_read(data: any, length: int) → any

Write-then-read I2C device (repeated start).

Parameters:

  • data – Buffer containing bytes to write

  • length – Number of bytes to read

class machine.Pin(port_pin: any, mode: int, pull: int = PULL_NONE)

A pin object is used to control I/O pins (also known as GPIO - general-purpose input/output). Pin objects are commonly associated with a physical pin that can drive an output voltage and read input voltages. The pin class has methods to set the mode of the pin (IN, OUT, etc) and methods to get and set the digital logic level.

Parameters:
configure_event(callback: any, type: int)

Configure GPIO pin event (interrupt).

Parameters:

  • callback – Function that is called when event occurs

  • type – Pin.EVENT_* type

high()

Set a pin to ‘1’.

low()

Set a pin to ‘0’.

off()

Set a pin to off (‘0’).

on()

Set a pin to on (‘1’).

reconfigure(port_pin: any, mode: int, pull: int = PULL_NONE)

Delete and re-initialize pin (potentially with a different configuration).

Parameters:
toggle()

Toggle a pin’s state.

value() → int

Read an input pin. Negative on error.

ANALOG: int

Pin is configured as an analog input

EVENT_BOTH: int

Event on rising or falling edge

EVENT_FALLING: int

Event on falling edge (1 -> 0 transition)

EVENT_LEVEL_HIGH: int

Event on high level

EVENT_LEVEL_LOW: int

Event on low level

EVENT_NONE: int

No events

EVENT_RISING: int

Event on rising edge (0 -> 1 transition)

IN: int

Pin is an input

NO_CONNECT: int

Pin is disconnected internally

OPEN_DRAIN: int

Pin is an output, set to high impedance

OUT: int

Pin is an output

PULL_DOWN: int

Pin has a pull-down resistor enabled

PULL_NONE: int

Pin has no pull-up or pull-down resistor

PULL_UP: int

Pin has a pull-up resistor enabled

class machine.RTC

This object is used to interface with the real time clock peripheral. The real time clock is used to keep track of the current date and time. This class is a singleton, only one RTC can be instantiated at a time. Attempting to instantiate a second RTC will return the existing instance.

datetime(tuple=None) → any

Get or set the date and time of the RTC.

With no arguments, this method returns an 8-tuple with the current date and time. With one argument (being an 8-tuple), it sets the date and time.

The 8-tuple has the following format:

(year, month, day, weekday, hours, minutes, seconds, milliseconds)

Parameters:

tuple – Optional 8-tuple of date and time

Returns:

8-tuple of date and time

class machine.SPI(device: any, pin: any)

This object is used to interact with the SPI peripheral. It is commonly used with 3 or 4 signals (clock, data out, data in, and chip select). The chip select can be controlled by the peripheral or by the application. When controlled by the application, multiple devices can exist on the same bus.

Parameters:

  • device – [str] Device identifier

  • device – [4-tuple] (Device identifier, clock pin name, data out pin name, data in pin name)

  • pin – [None] Optional chip select pin

  • pin – [object] Pin

  • pin – [3-tuple] (Port, pin number, active state)

  • pin – [2-tuple] (Pin name, active state)

Zephyr example - SPI(“spi@40023000”, Pin(“SPI_CS”, Pin.OUT, Pin.PULL_NONE)) or SPI(“spi@40023000”, (“gpio@50000000”, 20, SPI.CS_ACTIVE_LOW))

Silicon Labs (Lyra) example - SPI((“USART0”, “PC02”, “PC04”, “PC05”), (“PC03”, SPI.CS_ACTIVE_LOW))

configure(rate: int, polarity: int, phase: int, first_bit: int)

Change configuration from default (1M, 0, 0, MSB).

The underlying Silicon Labs (Lyra) driver can only support a single configuration for hardware peripheral.

Parameters:

  • rate – SCK rate in Hz

  • polarity – Clock polarity (0 or 1)

  • phase – Clock phase (0 or 1)

  • first_bit – Bit to send first. MSB or LSB

transceive(data: any) → any

Write data to device and return equal sized buffer.

Parameters:

data – Bytes to write

CS_ACTIVE_HIGH: int

Configure the SPI bus to use an active high (‘1’) chip select

CS_ACTIVE_LOW: int

Configure the SPI bus to use an active low (‘0’) chip select

LSB: int

Configure the SPI bus to send the least significant byte first

MSB: int

Configure the SPI bus to send the most significant byte first

class machine.UART(id: int)

This object represents a UART peripheral. The constructor takes a single parameter, the device identifier. The device identifier is a unique integer representing the UART peripheral.

For Zephyr-based devices, the device identifiers map to the following UART peripherals:

  • 0 - UART0

  • 1 - UART1

  • 2 - UART2

  • 3 - UART3

  • 4 - CDC ACM (USB) UART0

  • 5 - CDC ACM (USB) UART1

Not all devices will have all of these peripherals.

The UART object acts like a stream object and reading and writing is done using the standard stream methods.

See the MicroPython documentation for more information.

Parameters:

id – The device identifier

any() → int

Returns an integer counting the number of characters available for reading.

Returns:

The number of characters available for reading, possibly 0.

deinit()

De-initialize the UART peripheral. You will not be able to call init() on the ojbect after de-initializing it. A new instance would need to be created.

init(baudrate: int = 9600, bits: int = 8, parity=None, stop: int = 1, **kwargs)

Initialize the UART peripheral with the given parameters. This method should be called before using the UART peripheral and can be called multiple times to change the configuration without de-initializing the peripheral.

Parameters:

  • baudrate – The baud rate to use

  • bits – The number of data bits to use (7 or 8)

  • parity – The parity to use (None, 0 (even), or 1 (odd))

  • stop – The number of stop bits to use (1 or 2)

Additional keyword arguments may be provided to configure other UART parameters. The following arguments are supported:

  • tx: The transmit pin

  • rx: The receive pin

  • rts: The request-to-send pin

  • cts: The clear-to-send pin

  • txbuf: The length in characters of the transmit buffer

  • rxbuf: The length in characters of the receive buffer

  • timeout: The time to wait for the first character in milliseconds

  • timeout_char: The time to wait between characters in milliseconds

resume()

Resume the UART peripheral. This will bring the UART out of the low-power state and allow data to be sent and received.

sendbreak()

Send a break character.

suspend(cb: any = None)

Suspend the UART peripheral. This will put the UART into a low-power state. Data cannot be sent or received while the UART is suspended. The UART can be resumed using the resume() method.

Parameters:

cb – A callback function to call if the UART is woken up by an external event.

txdone() → bool

Check to see if the transmit buffer is empty.

Returns:

True if the transmit buffer is empty, False otherwise.

class machine.WDT(timeout: int = 5000)

This class provides an interface to the Watchdog Timer (WDT) peripheral. The WDT is used to detect and recover from software failures. If the WDT is not fed within the timeout period, the device will reset. The WDT is disabled by default and must be enabled before use. The WDT cannot be disabled once enabled. The WDT is fed by calling the feed method.

This class supports only a single watchdog timer instance. Creating a new instance may reconfigure the watchdog timer period on platforms that suppport it. On platforms that do not support reconfiguring the watchdog timer period, creating a new instance will have no effect.

Parameters:

timeout (int) – The timeout period in milliseconds. The default is 5000 milliseconds. Not all values are supported on all devices. The actual timeout period is the nearest supported value that is greater than or equal to the requested value.

feed()

Feed the watchdog timer. This method must be called before the timeout period expires to prevent the device from resetting.

machine.console_sleep(timeout: int = 20000, cb: any = None)

Allow the console UART to go to sleep.

The console UART is the UART used for REPL input and output. This function allows the UART to go to sleep when it is not in use. This can be used to save power. The console UART will be turned off after a short period of inactivity. It can only be turned back on using the console_wake() function.

Parameters:

  • timeout – The time in milliseconds to wait before putting the UART to sleep. The default is 20000 milliseconds (20 seconds) and it works like an idle timeout. Once no input or output is detected for the specified time, the UART will go to sleep.

  • cb – A callback function to call if the UART is woken up by an external event.

machine.console_wake()

Wake up the console UART

This function will turn on the console UART immediately. It can be used to wake up the UART after it has been put to sleep using the console_sleep() function. The UART will stay on until console_sleep() is called again.