Hardware API

The aim is to make the pyb module obsolete, make all its functionality cleaner and more board-generic, and move such functionality elsewhere. Below is the current proposal, very much a work in progress.

new hardware module

The classes to control the peripherals of the board will reside in a new module called hardware, therefore, by doing:

import hardware
dir(hardware)

one can easily see what's supported on the board.

The Pin class

Create and init a pin

pin = Pin(id, mode, pull=Pin.PULL_NONE, *, value, drive, slew, ...)

• id, and mode are mandatory and positional (mode can kw).
• pull is optional and positional (also can be named).
• The rest of args are kwonly.
• Only value is required for a port to implement (initial value if given).
• The rest are optional, and a port can define them and also define others.

Besides Pin.IN and Pin.OUT, mode can also take Pin.ALT and Pin.ALT_OPEN_DRAIN, but the alternate function itself cannot be configured via the Pin class, since this will be done via the other hardware classes (UART, SPI, I2C, etc.). However, Pin.ALT and Pin.ALT_OPEN_DRAIN exist to allow custom control of the pin settings after it has been taken by another peripheral. For example:

# create and initialize UART1 with TX and RX on GP1 and GP2 respectively.
UART(1, 9600, ['GP1', 'GP2']) 
# enable the pull-ups on both UART1 pins
Pin('GP1', mode=Pin.ALT, pull=Pin.PULL_UP)
Pin('GP2', mode=Pin.ALT, pull=Pin.PULL_UP)

Methods

• pin.init(...) re init.
• pin.high() set high.
• pin.low() set low.
• pin.value() get value.
• pin.value(x) set value.
• pin() fast method to get the value of the pin.
• pin(value) fast method to set the value of the pin.
• pin.toggle()

Getters and setters

• pin.id() get only.
• pin.mode([mode])
• pin.pull([pull])
• pin.drive([drive])
• pin.slew([slew])

Constants

• for mode: Pin.IN, Pin.OUT, Pin.OPEN_DRAIN, Pin.ALT, Pin.ALT_OPEN_DRAIN
• for pull: Pin.PULL_UP, Pin.PULL_DOWN, Pin.PULL_NONE, optional: Pin.PULL_UP_STRONG, Pin.PULL_DOWN_WEAK, ...
• for drive: Pin.LOW_POWER, Pin.MED_POWER, Pin.HIGH_POWER
• for slew: Pin.FAST_RISE, Pin.SLOW_RISE
• for interrupt (callback) mode: pin.INT_RISING, pin.INT_FALLING, pin.INT_RISING_FALLING, pin.INT_HIGH_LEVEL, pin.INT_LOW_LEVEL

Attributes

• Pins list: Pin.board (mandatory) and Pin.cpu (optional).

The UART class

uart = UART(id, baudrate, bit, parity, stop, *, pins, ...)

• uart.init(...)
• uart.read([nbytes])
• uart.readinto(buf[, nbytes])
• uart.readall()
• uart.readline([max_size])
• uart.readchar()
• uart.write(buf)
• uart.writechar(char)
• uart.sendbreak()

The ADC class

adc = ADC(id, *, bits, ...)

• adc.init(...) re-init
• adc.readchannel(channel) read a specific channel
• apin = adc(pin) make an analog pin (will choose the correct channel for the pin)
• apin.read()
• apin.readtimed(buf, timer)

machine module

• machine.freq([freq, ...]) get or set CPU and/or bus frequencies
• machine.idle([... options]) idle the CPU, may require external event to leave idle mode
• machine.sleep([... options]) enter sleep mode that retains RAM and continues execution when woken
• machine.deepsleep([... options]) enter sleep mode that may not retain RAM and may reset when woken

sys module additions

The sys module has uPy specific functions:

• sys.dup_stdio([stream_obj]) get or set duplication of global stdio, so that REPL can be redirected to UART or other (note: could allow to duplicate to multiple stream objs but that's arguably overkill and could anyway be done in Python by making a stream multiplexer)

time module additions

The time module has uPy specific functions:

• time.sleep_ms(ms)
• time.sleep_us(us)
• time.ticks_ms()
• time.ticks_us()
• time.ticks_cpu()
• time.ticks_diff(t0, t1)

os module additions

The os module has uPy specific functions:

• os.mount(block_dev, mount_point, *, readonly)
• os.mkfs(device or path, *, options...)