Commit 45426430 authored by danicampora's avatar danicampora
Browse files

docs: Update all WiPy docs to reflect the new API.

parent fca3308c
......@@ -40,18 +40,13 @@
#include "rom_map.h"
#include "prcm.h"
#include "pyexec.h"
#include "ff.h"
#include "diskio.h"
#include "sflash_diskio.h"
#include "pybuart.h"
#include "pybpin.h"
#include "pybrtc.h"
#include "mpsystick.h"
#include "simplelink.h"
#include "modnetwork.h"
#include "modwlan.h"
#include "moduos.h"
#include "telnet.h"
#include "FreeRTOS.h"
#include "portable.h"
#include "task.h"
......@@ -67,7 +62,6 @@
#include "utils.h"
#include "gccollect.h"
#include "mperror.h"
#include "genhdr/mpversion.h"
#ifdef DEBUG
......@@ -558,7 +558,7 @@ STATIC mp_obj_t pyb_uart_irq (mp_uint_t n_args, const mp_obj_t *pos_args, mp_map
nlr_raise(mp_obj_new_exception_msg(&mp_type_ValueError, mpexception_value_invalid_arguments));
STATIC MP_DEFINE_CONST_FUN_OBJ_KW(pyb_uart_callback_obj, 1, pyb_uart_irq);
STATIC MP_DEFINE_CONST_FUN_OBJ_KW(pyb_uart_irq_obj, 1, pyb_uart_irq);
STATIC const mp_map_elem_t pyb_uart_locals_dict_table[] = {
// instance methods
......@@ -566,7 +566,7 @@ STATIC const mp_map_elem_t pyb_uart_locals_dict_table[] = {
{ MP_OBJ_NEW_QSTR(MP_QSTR_deinit), (mp_obj_t)&pyb_uart_deinit_obj },
{ MP_OBJ_NEW_QSTR(MP_QSTR_any), (mp_obj_t)&pyb_uart_any_obj },
{ MP_OBJ_NEW_QSTR(MP_QSTR_sendbreak), (mp_obj_t)&pyb_uart_sendbreak_obj },
{ MP_OBJ_NEW_QSTR(MP_QSTR_irq), (mp_obj_t)&pyb_uart_callback_obj },
{ MP_OBJ_NEW_QSTR(MP_QSTR_irq), (mp_obj_t)&pyb_uart_irq_obj },
/// \method read([nbytes])
{ MP_OBJ_NEW_QSTR(MP_QSTR_read), (mp_obj_t)&mp_stream_read_obj },
......@@ -300,6 +300,11 @@ html_context = {
# Append the other ports' specific folders/files to the exclude pattern
exclude_patterns.extend([port + '*' for port in ports if port != micropy_port])
# Exclude pyb module if the port is the WiPy
if micropy_port == 'wipy':
else: # exclude machine
# Specify a custom master document based on the port name
master_doc = micropy_port + '_' + 'index'
......@@ -74,12 +74,12 @@ it will fallback to loading the built-in ``ujson`` module.
Libraries specific to the pyboard
The following libraries are specific to the pyboard.
.. toctree::
:maxdepth: 2
......@@ -87,10 +87,8 @@ it will fallback to loading the built-in ``ujson`` module.
.. toctree::
:maxdepth: 1
......@@ -105,7 +103,7 @@ it will fallback to loading the built-in ``ujson`` module.
.. toctree::
:maxdepth: 2
.. _machine.ADC:
class ADC -- analog to digital conversion
import machine
adc = machine.ADC() # create an ADC object
apin ='GP3') # create an analog pin on GP3
val = apin() # read an analog value
.. class:: machine.ADC(id=0, \*, bits=12)
Create an ADC object associated with the given pin.
This allows you to then read analog values on that pin.
For more info check the `pinout and alternate functions
table. <>`_
.. warning::
ADC pin input range is 0-1.4V (being 1.8V the absolute maximum that it
can withstand). When GP2, GP3, GP4 or GP5 are remapped to the
ADC block, 1.8 V is the maximum. If these pins are used in digital mode,
then the maximum allowed input is 3.6V.
.. method::, \*, pin)
Create an analog pin. If only channel ID is given, the correct pin will
be selected. Alternatively, only the pin can be passed and the correct
channel will be selected. Examples::
# all of these are equivalent and enable ADC channel 1 on GP3
apin =
apin ='GP3')
apin =, pin='GP3')
.. method:: adc.init()
Enable the ADC block.
.. method:: adc.deinit()
Disable the ADC block.
class ADCChannel --- read analog values from internal or external sources
ADC channels can be connected to internal points of the MCU or to GPIO pins.
ADC channels are created using the method.
.. method:: adcchannel()
Fast method to read the channel value.
.. method:: adcchannel.value()
Read the channel value.
.. method:: adcchannel.init()
Re-init (and effectively enable) the ADC channel.
.. method:: adcchannel.deinit()
Disable the ADC channel.
.. _pyb.HeartBeat:
.. _machine.HeartBeat:
class HeartBeat -- heart beat LED
......@@ -11,14 +11,14 @@ can be used to control the light intesity of the heart beat LED.
Example usage::
hb = pyb.HeartBeat()
hb = machine.HeartBeat()
hb.disable() # disable the heart beat
hb.enable() # enable the heart beat
.. class:: pyb.HeartBeat()
.. class:: machine.HeartBeat()
Create a HeartBeat object.
......@@ -35,12 +35,13 @@ Methods
import pyb
from machine import HeartBeat
from machine import Pin
# disable the heart beat
# get the GP25 pin object
hbl = pyb.Pin('GP25')
# init GP25 as output
led = Pin('GP25', mode=Pin.OUT)
# toggle the led
.. _machine.I2C:
class I2C -- a two-wire serial protocol
I2C is a two-wire protocol for communicating between devices. At the physical
level it consists of 2 wires: SCL and SDA, the clock and data lines respectively.
I2C objects are created attached to a specific bus. They can be initialised
when created, or initialised later on.
.. only:: port_wipy
from machine import I2C
i2c = I2C(0) # create on bus 0
i2c = I2C(0, I2C.MASTER) # create and init as a master
i2c.init(I2C.MASTER, baudrate=20000) # init as a master
i2c.deinit() # turn off the peripheral
Printing the i2c object gives you information about its configuration.
.. only:: port_wipy
A master must specify the recipient's address::
i2c.writeto(0x42, '123') # send 3 bytes to slave with address 0x42
i2c.writeto(addr=0x42, b'456') # keyword for address
Master also has other methods::
i2c.scan() # scan for slaves on the bus, returning
# a list of valid addresses
i2c.readfrom_mem(0x42, 2, 3) # read 3 bytes from memory of slave 0x42,
# starting at address 2 in the slave
i2c.writeto_mem(0x42, 2, 'abc') # write 'abc' (3 bytes) to memory of slave 0x42
# starting at address 2 in the slave, timeout after 1 second
.. only:: port_wipy
.. class:: machine.I2C(bus, ...)
Construct an I2C object on the given bus. `bus` can only be 0.
If the bus is not given, the default one will be selected (0).
.. method:: i2c.deinit()
Turn off the I2C bus.
.. only:: port_wipy
.. method:: i2c.init(mode, \*, baudrate=100000, pins=(SDA, SCL))
Initialise the I2C bus with the given parameters:
- ``mode`` must be ``I2C.MASTER``
- ``baudrate`` is the SCL clock rate
- ``pins`` is an optional tuple with the pins to assign to the I2C bus.
.. method:: i2c.readfrom(addr, nbytes)
Read ``nbytes`` from the slave specified by ``addr``.
Returns a ``bytes`` object with the data read.
.. method:: i2c.readfrom_into(addr, buf)
Read into ``buf`` from the slave specified by ``addr``.
Returns the number of bytes read.
.. method:: i2c.writeto(addr, buf, \*, stop=True)
Write ``buf`` to the slave specified by ``addr``. Set ``stop`` to ``False``
if the transfer should be continued.
Returns the number of bytes written.
.. method:: i2c.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8)
Read ``nbytes`` from the slave specified by ``addr`` starting from the memory
address specified by ``memaddr``.
Param ``addrsize`` specifies the address size in bits.
Returns a ``bytes`` object with the data read.
.. method:: i2c.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8)
Read into ``buf`` from the slave specified by ``addr`` starting from the memory
address specified by ``memaddr``.
Param ``addrsize`` specifies the address size in bits.
Returns the number of bytes read.
.. method:: i2c.writeto_mem(addr, memaddr, buf, \*, addrsize=8)
Write ``buf`` to the slave specified by ``addr`` starting from the
memory address specified by ``memaddr``. Param ``addrsize`` specifies the
address size in bits.
Set ``stop`` to ``False`` if the transfer should be continued.
Returns the number of bytes written.
.. method:: i2c.scan()
Scan all I2C addresses from 0x01 to 0x7f and return a list of those that respond.
Only valid when in master mode.
.. data:: I2C.MASTER
for initialising the bus to master mode
.. _machine.Pin:
class Pin -- control I/O pins
A pin is the basic object to control I/O pins. It has methods to set
the mode of the pin (input, output, etc) and methods to get and set the
digital logic level. For analog control of a pin, see the ADC class.
Usage Model:
.. only:: port_wipy
Board pins are identified by their string id::
g = machine.Pin('GP9', mode=machine.Pin.OUT, pull=None, drive=machine.Pin.MED_POWER, alt=-1)
You can also configure the Pin to generate interrupts. For instance::
def pincb(pin):
pin_int = machine.Pin('GP10', mode=Pin.IN, pull=machine.Pin.PULL_DOWN)
pin_int.irq(mode=machine.Pin.IRQ_RISING, handler=pincb)
# the callback can be triggered manually
# to disable the callback
Now every time a falling edge is seen on the gpio pin, the callback will be
executed. Caution: mechanical push buttons have "bounce" and pushing or
releasing a switch will often generate multiple edges.
See: for a detailed
explanation, along with various techniques for debouncing.
All pin objects go through the pin mapper to come up with one of the
gpio pins.
.. class:: machine.Pin(id, ...)
Create a new Pin object associated with the id. If additional arguments are given,
they are used to initialise the pin. See :meth:`pin.init`.
.. only:: port_wipy
.. method:: pin.init(mode, pull, \*, drive, alt)
Initialise the pin:
- ``mode`` can be one of:
- ``Pin.IN`` - input pin.
- ``Pin.OUT`` - output pin in push-pull mode.
- ``Pin.OPEN_DRAIN`` - output pin in open-drain mode.
- ``Pin.ALT`` - pin mapped to an alternate function.
- ``Pin.ALT_OPEN_DRAIN`` - pin mapped to an alternate function in open-drain mode.
- ``pull`` can be one of:
- ``None`` - no pull up or down resistor.
- ``Pin.PULL_UP`` - pull up resistor enabled.
- ``Pin.PULL_DOWN`` - pull down resitor enabled.
- ``drive`` can be one of:
- ``Pin.LOW_POWER`` - 2mA drive capability.
- ``Pin.MED_POWER`` - 4mA drive capability.
- ``Pin.HIGH_POWER`` - 6mA drive capability.
- ``alt`` is the number of the alternate function. Please refer to the
`pinout and alternate functions table. <>`_
for the specific alternate functions that each pin supports.
Returns: ``None``.
.. method::
Get the pin id.
.. method:: pin.value([value])
Get or set the digital logic level of the pin:
- With no argument, return 0 or 1 depending on the logic level of the pin.
- With ``value`` given, set the logic level of the pin. ``value`` can be
anything that converts to a boolean. If it converts to ``True``, the pin
is set high, otherwise it is set low.
.. method:: pin.alt_list()
Returns a list of the alternate functions supported by the pin. List items are
a tuple of the form: ``('ALT_FUN_NAME', ALT_FUN_INDEX)``
.. only:: port_wipy
.. method:: pin([value])
Pin objects are callable. The call method provides a (fast) shortcut to set and get the value of the pin.
See **pin.value** for more details.
.. method:: pin.toggle()
Toggle the value of the pin.
.. method:: pin.mode([mode])
Get or set the pin mode.
.. method:: pin.pull([pull])
Get or set the pin pull.
.. method::[drive])
Get or set the pin drive strength.
.. method:: pin.irq(\*, trigger, priority=1, handler=None, wake=None)
Create a callback to be triggered when the input level at the pin changes.
- ``trigger`` configures the pin level which can generate an interrupt. Possible values are:
- ``Pin.IRQ_FALLING`` interrupt on falling edge.
- ``Pin.IRQ_RISING`` interrupt on rising edge.
- ``Pin.IRQ_LOW_LEVEL`` interrupt on low level.
- ``Pin.IRQ_HIGH_LEVEL`` interrupt on high level.
The values can be *ORed* together, for instance mode=Pin.IRQ_FALLING | Pin.IRQ_RISING
- ``priority`` level of the interrupt. Can take values in the range 1-7.
Higher values represent higher priorities.
- ``handler`` is an optional function to be called when new characters arrive.
- ``wakes`` selects the power mode in which this interrupt can wake up the
board. Please note:
- If ``wake_from=machine.Sleep.ACTIVE`` any pin can wake the board.
- If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``,
``GP11``, GP17`` or ``GP24`` can wake the board. Note that only 1
of this pins can be enabled as a wake source at the same time, so, only
the last enabled pin as a ``machine.Sleep.SUSPENDED`` wake source will have effect.
- If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``,
``GP11``, ``GP17`` and ``GP24`` can wake the board. In this case all of the
6 pins can be enabled as a ``machine.Sleep.HIBERNATE`` wake source at the same time.
- Values can be ORed to make a pin generate interrupts in more than one power
Returns a callback object.
.. class:: Pin.board
Contains all ``Pin`` objects supported by the board. Examples::
led = Pin(Pin.board.GP25, mode=Pin.OUT)
.. only:: port_wipy
.. data:: Pin.IN
.. data:: Pin.OUT
.. data:: Pin.OPEN_DRAIN
.. data:: Pin.ALT
.. data:: Pin.ALT_OPEN_DRAIN
Selects the pin mode.
.. data:: Pin.PULL_UP
.. data:: Pin.PULL_DOWN
Selectes the wether there's pull up/down resistor.
.. data:: Pin.LOW_POWER
.. data:: Pin.MED_POWER
.. data:: Pin.HIGH_POWER
Selects the drive strength.
.. data:: Pin.IRQ_FALLING
.. data:: Pin.IRQ_RISING
.. data:: Pin.IRQ_LOW_LEVEL
.. data:: Pin.IRQ_HIGH_LEVEL
Selects the IRQ trigger type.
.. _machine.RTC:
class RTC -- real time clock
The RTC is and independent clock that keeps track of the date
and time.
Example usage::
rtc = machine.RTC()
rtc.datetime((2014, 5, 1, 4, 13, 0, 0, 0))
.. class:: machine.RTC(id=0, ...)
Create an RTC object. See init for parameters of initialization.
.. method:: rtc.init(id, datetime)
Initialise the RTC. Datetime is a tuple of the form:
``(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])``
.. method::
Get get the current datetime tuple.
.. method:: rtc.deinit()
Resets the RTC to the time of January 1, 2015 and starts running it again.
.. method:: rtc.alarm(id, time, /*, repeat=False)
Set the RTC alarm. Time might be either a milllisecond value to program the alarm to
current time + time_in_ms in the future, or a datetimetuple. If the time passed is in
milliseconds, repeat can be set to ``True`` to make the alarm periodic.
.. method:: rtc.alarm_left(alarm_id=0)
Get the number of milliseconds left before the alarm expires.
.. method:: rtc.cancel(alarm_id=0)
Cancel a running alarm.
.. method:: rtc.irq(\*, trigger, handler=None, wake=machine.IDLE)
Create an irq object triggered by a real time clock alarm.
- ``trigger`` must be ``RTC.ALARM0``
- ``handler`` is the function to be called when the callback is triggered.
- ``wake`` specifies the sleep mode from where this interrupt can wake
up the system.
.. data:: RTC.ALARM0
irq trigger source
.. _pyb.SD:
.. _machine.SD:
class SD -- secure digital memory card
......@@ -13,36 +13,30 @@ more info regarding the pins which can be remapped to be used with a SD card.
Example usage::
# data, clk and cmd pins must be passed along with
from machine import SD
import os
# clk cmd and dat0 pins must be passed along with
# their respective alternate functions
sd = pyb.SD(('GP15', 8, 'GP10', 6, 'GP11', 6))
sd = machine.SD(pins=('GP10', 'GP11', 'GP15'))
os.mount(sd, '/sd')
# do normal file operations
.. class:: pyb.SD([pins_tuple])
.. class:: machine.SD(id,... )
Create a SD card object. In order to initalize the card, give it a 6-tuple
``(dat_pin, dat_af, clk_pin, clk_af, cmd_pin, cmd_af)`` with the data, clock
and cmd pins together their respective alternate functions.
Create a SD card object. See init for parameters if initialization.
.. method:: sd.init([pins_tuple])
.. method:: sd.init(id, pins=('GP10', 'GP11', 'GP15'))
Enable the SD card.
In order to initalize the card, give it a 3-tuple ``(clk_pin, cmd_pin, dat0_pin)``
ID defaults to zero.
.. method:: sd.deinit()