djsundog
/
circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Add initial draft documentation for the WiPy. 

This makes all common files "port-aware" using the .. only directive.
This commit is contained in:
Daniel Campora 2015-06-10 23:29:56 +02:00
parent b630de1103
commit cfcf47c064
33 changed files with 2155 additions and 835 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -121,6 +121,8 @@ preferably in a virtualenv:
In `micropython/docs`, build the docs:
make html
make MICROPY_PORT=<port_name> BUILDDIR=<port_name>/build html
You'll find the index page at `micropython/docs/build/html/index.html`.
Where ``<port_name>`` can be ``port_unix``, ``port_pyboard``, ``port_wipy`` or ``port_esp8266``.
You'll find the index page at `micropython/docs/<port_name>/build/html/index.html`.

8
docs/conf.py
View File

@ -47,7 +47,7 @@ source_suffix = '.rst'
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
#master_doc = 'index'
# General information about the project.
project = 'MicroPython'
@ -297,3 +297,9 @@ html_context = {
'port_name':ports[micropy_port],
'all_ports':[(n, url_prefix + p) for p, n in ports.items()],
}
# Append the other ports' specific folders/files to the exclude pattern
exclude_patterns.extend([port + '*' for port in ports if port != micropy_port])
# Specify a custom master document based on the port name
master_doc = micropy_port + '_' + 'index'

20
docs/contents.rst
View File

@ -1,20 +0,0 @@
MicroPython documentation contents
==================================
.. only:: port_pyboard
.. toctree::
pyboard/quickref.rst
pyboard/general.rst
pyboard/tutorial/index.rst
library/index.rst
pyboard/hardware/index.rst
license.rst
.. only:: port_esp8266
.. toctree::
library/index.rst
license.rst

7
docs/esp8266_contents.rst Normal file
View File

@ -0,0 +1,7 @@
MicroPython documentation contents
==================================
.. toctree::
library/index.rst
license.rst

15
docs/esp8266_index.rst Normal file
View File

@ -0,0 +1,15 @@
MicroPython documentation and references
========================================
.. toctree::
library/index.rst
license.rst
esp8266_contents.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

29
docs/index.rst
View File

@ -1,29 +0,0 @@
MicroPython documentation and references
========================================
.. only:: port_pyboard
.. toctree::
pyboard/quickref.rst
pyboard/general.rst
pyboard/tutorial/index.rst
library/index.rst
pyboard/hardware/index.rst
license.rst
contents.rst
.. only:: port_esp8266
.. toctree::
library/index.rst
license.rst
contents.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

110
docs/library/index.rst
View File

@ -17,17 +17,30 @@ The following standard Python libraries are built in to MicroPython.
For additional libraries, please download them from the `micropython-lib repository
<https://github.com/micropython/micropython-lib>`_.
.. toctree::
:maxdepth: 1
.. only:: port_pyboard
cmath.rst
gc.rst
math.rst
os.rst
select.rst
struct.rst
sys.rst
time.rst
.. toctree::
:maxdepth: 1
cmath.rst
gc.rst
math.rst
os.rst
select.rst
struct.rst
sys.rst
time.rst
.. only:: port_wipy
.. toctree::
:maxdepth: 1
gc.rst
os.rst
select.rst
sys.rst
time.rst
Python micro-libraries
----------------------
@ -43,37 +56,68 @@ For example, ``import json`` will first search for a file ``json.py`` or
directory ``json`` and load that package if it is found. If nothing is found,
it will fallback to loading the built-in ``ujson`` module.
.. toctree::
:maxdepth: 1
.. only:: port_pyboard
ubinascii.rst
uctypes.rst
uhashlib.rst
uheapq.rst
ujson.rst
ure.rst
usocket.rst
uzlib.rst
.. toctree::
:maxdepth: 1
ubinascii.rst
uctypes.rst
uhashlib.rst
uheapq.rst
ujson.rst
ure.rst
usocket.rst
uzlib.rst
Libraries specific to the pyboard
---------------------------------
.. only:: port_pyboard
The following libraries are specific to the pyboard.
Libraries specific to the pyboard
---------------------------------
The following libraries are specific to the pyboard.
.. toctree::
:maxdepth: 2
pyb.rst
network.rst
.. toctree::
:maxdepth: 2
.. only:: port_wipy
.. toctree::
:maxdepth: 1
ubinascii.rst
uhashlib.rst
uheapq.rst
ujson.rst
ure.rst
usocket.rst
.. only:: port_wipy
Libraries specific to the WiPy
---------------------------------
The following libraries are specific to the WiPy.
.. toctree::
:maxdepth: 2
pyb.rst
network.rst
pyb.rst
network.rst
.. only:: port_esp8266
Libraries specific to the ESP8266
---------------------------------
Libraries specific to the ESP8266
---------------------------------
The following libraries are specific to the ESP8266.
The following libraries are specific to the ESP8266.
.. toctree::
:maxdepth: 2
.. toctree::
:maxdepth: 2
esp.rst
pyb.rst
esp.rst

34
docs/library/micropython.rst
View File

@ -7,23 +7,25 @@
Functions
---------
.. function:: mem_info([verbose])
.. only:: port_pyboard or port_unix
Print information about currently used memory. If the ``verbose`` argument
is given then extra information is printed.
The information that is printed is implementation dependent, but currently
includes the amount of stack and heap used. In verbose mode it prints out
the entire heap indicating which blocks are used and which are free.
.. function:: qstr_info([verbose])
Print information about currently interned strings. If the ``verbose``
argument is given then extra information is printed.
The information that is printed is implementation dependent, but currently
includes the number of interned strings and the amount of RAM they use. In
verbose mode it prints out the names of all RAM-interned strings.
.. function:: mem_info([verbose])
Print information about currently used memory. If the ``verbose`` argument
is given then extra information is printed.
The information that is printed is implementation dependent, but currently
includes the amount of stack and heap used. In verbose mode it prints out
the entire heap indicating which blocks are used and which are free.
.. function:: qstr_info([verbose])
Print information about currently interned strings. If the ``verbose``
argument is given then extra information is printed.
The information that is printed is implementation dependent, but currently
includes the number of interned strings and the amount of RAM they use. In
verbose mode it prints out the names of all RAM-interned strings.
.. function:: alloc_emergency_exception_buf(size)

404
docs/library/network.rst
View File

@ -27,151 +27,297 @@ For example::
data = s.recv(1000)
s.close()
class CC3K
==========
.. only:: port_pyboard
This class provides a driver for CC3000 wifi modules. Example usage::
class CC3K
==========
This class provides a driver for CC3000 wifi modules. Example usage::
import network
nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3)
nic.connect('your-ssid', 'your-password')
while not nic.isconnected():
pyb.delay(50)
print(nic.ifconfig())
# now use socket as usual
...
For this example to work the CC3000 module must have the following connections:
- MOSI connected to Y8
- MISO connected to Y7
- CLK connected to Y6
- CS connected to Y5
- VBEN connected to Y4
- IRQ connected to Y3
It is possible to use other SPI busses and other pins for CS, VBEN and IRQ.
Constructors
------------
.. class:: CC3K(spi, pin_cs, pin_en, pin_irq)
Create a CC3K driver object, initialise the CC3000 module using the given SPI bus
and pins, and return the CC3K object.
Arguments are:
- ``spi`` is an :ref:`SPI object <pyb.SPI>` which is the SPI bus that the CC3000 is
connected to (the MOSI, MISO and CLK pins).
- ``pin_cs`` is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 CS pin.
- ``pin_en`` is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 VBEN pin.
- ``pin_irq`` is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 IRQ pin.
All of these objects will be initialised by the driver, so there is no need to
initialise them yourself. For example, you can use::
nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3)
Methods
-------
.. method:: cc3k.connect(ssid, key=None, \*, security=WPA2, bssid=None)
Connect to a wifi access point using the given SSID, and other security
parameters.
.. method:: cc3k.disconnect()
Disconnect from the wifi access point.
.. method:: cc3k.isconnected()
Returns True if connected to a wifi access point and has a valid IP address,
False otherwise.
.. method:: cc3k.ifconfig()
Returns a 7-tuple with (ip, subnet mask, gateway, DNS server, DHCP server,
MAC address, SSID).
.. method:: cc3k.patch_version()
Return the version of the patch program (firmware) on the CC3000.
.. method:: cc3k.patch_program('pgm')
Upload the current firmware to the CC3000. You must pass 'pgm' as the first
argument in order for the upload to proceed.
Constants
---------
.. data:: CC3K.WEP
.. data:: CC3K.WPA
.. data:: CC3K.WPA2
security type to use
class WIZNET5K
==============
This class allows you to control WIZnet5x00 Ethernet adaptors based on
the W5200 and W5500 chipsets (only W5200 tested).
Example usage::
import network
nic = network.WIZNET5K(pyb.SPI(1), pyb.Pin.board.X5, pyb.Pin.board.X4)
print(nic.ifconfig())
# now use socket as usual
...
For this example to work the WIZnet5x00 module must have the following connections:
- MOSI connected to X8
- MISO connected to X7
- SCLK connected to X6
- nSS connected to X5
- nRESET connected to X4
It is possible to use other SPI busses and other pins for nSS and nRESET.
Constructors
------------
.. class:: WIZNET5K(spi, pin_cs, pin_rst)
Create a WIZNET5K driver object, initialise the WIZnet5x00 module using the given
SPI bus and pins, and return the WIZNET5K object.
Arguments are:
- ``spi`` is an :ref:`SPI object <pyb.SPI>` which is the SPI bus that the WIZnet5x00 is
connected to (the MOSI, MISO and SCLK pins).
- ``pin_cs`` is a :ref:`Pin object <pyb.Pin>` which is connected to the WIZnet5x00 nSS pin.
- ``pin_rst`` is a :ref:`Pin object <pyb.Pin>` which is connected to the WIZnet5x00 nRESET pin.
All of these objects will be initialised by the driver, so there is no need to
initialise them yourself. For example, you can use::
nic = network.WIZNET5K(pyb.SPI(1), pyb.Pin.board.X5, pyb.Pin.board.X4)
Methods
-------
.. method:: wiznet5k.ifconfig([(ip, subnet, gateway, dns)])
Get/set IP address, subnet mask, gateway and DNS.
When called with no arguments, this method returns a 4-tuple with the above information.
To set the above values, pass a 4-tuple with the required information. For example::
nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
.. method:: wiznet5k.regs()
Dump the WIZnet5x00 registers. Useful for debugging.
import network
nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3)
nic.connect('your-ssid', 'your-password')
while not nic.isconnected():
pyb.delay(50)
print(nic.ifconfig())
.. only:: port_wipy
# now use socket as usual
...
class WLAN
==========
For this example to work the CC3000 module must have the following connections:
.. _network.WLAN:
- MOSI connected to Y8
- MISO connected to Y7
- CLK connected to Y6
- CS connected to Y5
- VBEN connected to Y4
- IRQ connected to Y3
This class provides a driver for WiFi network processor in the WiPy. Example usage::
import network
# setup as a station
nic = network.WLAN(WLAN.STA)
nic.connect('your-ssid', security=WLAN.WPA_WPA2, key='your-key')
while not nic.isconnected():
pyb.delay(50)
print(nic.ifconfig())
It is possible to use other SPI busses and other pins for CS, VBEN and IRQ.
# now use socket as usual
...
Constructors
------------
Constructors
------------
.. class:: WLAN(mode, ssid, \*, security=WLAN.OPEN, key=None, channel=5)
Create a WLAN driver object, initialise the WLAN engine in station or AP mode.
Arguments are:
- ``mode`` can be either ``WLAN.STA`` or ``WLAN.AP``.
- ``ssid`` is a string with the ssid name. Only needed when mode is ``WLAN.AP``.
- ``security`` can be ``WLAN.OPEN``, ``WLAN.WEP`` or ``WLAN.WPA_WPA2``.
Only needed when mode is ``WLAN.AP``.
- ``key`` is a string with the ``WLAN.WPA_WPA2`` key or a byte array with the
``WLAN.WEP`` key. Not needed when mode is ``WLAN.STA`` or security is ``WLAN.OPEN``.
- ``channel`` a number in the range 1-11. Only needed when mode is ``WLAN.AP``.
For example, you can use::
.. class:: CC3K(spi, pin_cs, pin_en, pin_irq)
# configure as an access point
nic = network.WLAN(WLAN.AP, 'wipy-wlan', security=WLAN.WPA_WPA2, key='www.wipy.io', channel=7)
Create a CC3K driver object, initialise the CC3000 module using the given SPI bus
and pins, and return the CC3K object.
or::
Arguments are:
# configure as an station
nic = network.WLAN(WLAN.STA)
Methods
-------
.. method:: wlan.connect(ssid, \*, security=WLAN.OPEN, key=None, bssid=None, timeout=5000)
Connect to a wifi access point using the given SSID, and other security
parameters.
- ``bssid`` is the MAC address of the AP to connect to. Useful when there are several APs
with the same ssid.
- ``timeout`` is the maximum time in milliseconds to wait for the connection to succeed.
.. method:: wlan.scan()
Performs a network scan and returns a list of named tuples with (ssid, bssid, security, channel, rssi).
Note that channel is always ``None`` since this info is not provided by the WiPy.
.. method:: wlan.disconnect()
Disconnect from the wifi access point.
.. method:: wlan.isconnected()
Returns True if connected to a wifi access point and has a valid IP address,
False otherwise.
.. method:: wlan.ifconfig(['dhcp' or configtuple])
With no parameters given eturns a 4-tuple of ``(ip, subnet mask, gateway, DNS server)``.
if ``'dhcp'`` is passed as a parameter then the DHCP client is enabled and the IP params
are negotiated with the AP.
if the 4-tuple config is given then a static IP is configured. For example::
nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
.. method:: wlan.info()
Provides information about the current WLAN configuration. Returns a named tuple
of (mode, ssid, security, mac)
- ``mode`` can be either ``WLAN.STA`` or ``WLAN.AP``.
- ``ssid`` is a string with our ssid if in AP mode, ``None`` oterwise.
- ``security`` security type currently used.
- ``mac`` our MAC address.
.. method:: wlan.connections()
Returns a list of the devices currently connected. Each item in the list is a
tuple of ``(ssid, mac)``.
.. method:: wlan.antenna(antenna_type)
Selects the antenna type to be used. Must be either ``WLAN.INT_ANTENNA`` or
``WLAN.EXT_ANTENNA``.
- ``spi`` is an :ref:`SPI object <pyb.SPI>` which is the SPI bus that the CC3000 is
connected to (the MOSI, MISO and CLK pins).
- ``pin_cs`` is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 CS pin.
- ``pin_en`` is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 VBEN pin.
- ``pin_irq`` is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 IRQ pin.
.. method:: wlan.callback(wakes)
All of these objects will be initialised by the driver, so there is no need to
initialise them yourself. For example, you can use::
Create a callback to be triggered when a WLAN event occurs during ``pyb.Sleep.SUSPENDED``
mode. Events are triggered by socket activity or by WLAN connection/disconnection.
nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3)
- ``wakes`` can only be ``pyb.Sleep.SUSPENDED``.
Methods
-------
Returns a callback object.
.. method:: cc3k.connect(ssid, key=None, \*, security=WPA2, bssid=None)
Constants
---------
.. data:: WLAN.STA
WiFi station mode
.. data:: WLAN.AP
Connect to a wifi access point using the given SSID, and other security
parameters.
WiFi access point mode
.. method:: cc3k.disconnect()
.. data:: WLAN.OPEN
open network (no security)
.. data:: WLAN.WEP
WEP network security
.. data:: WLAN.WPA_WPA2
WPA/WPA2 network security
Disconnect from the wifi access point.
.. data:: WLAN.INT_ANTENNA
selects the internal antenna
.. data:: WLAN.EXT_ANTENNA
.. method:: cc3k.isconnected()
Returns True if connected to a wifi access point and has a valid IP address,
False otherwise.
.. method:: cc3k.ifconfig()
Returns a 7-tuple with (ip, subnet mask, gateway, DNS server, DHCP server,
MAC address, SSID).
.. method:: cc3k.patch_version()
Return the version of the patch program (firmware) on the CC3000.
.. method:: cc3k.patch_program('pgm')
Upload the current firmware to the CC3000. You must pass 'pgm' as the first
argument in order for the upload to proceed.
Constants
---------
.. data:: CC3K.WEP
.. data:: CC3K.WPA
.. data:: CC3K.WPA2
security type to use
class WIZNET5K
==============
This class allows you to control WIZnet5x00 Ethernet adaptors based on
the W5200 and W5500 chipsets (only W5200 tested).
Example usage::
import network
nic = network.WIZNET5K(pyb.SPI(1), pyb.Pin.board.X5, pyb.Pin.board.X4)
print(nic.ifconfig())
# now use socket as usual
...
For this example to work the WIZnet5x00 module must have the following connections:
- MOSI connected to X8
- MISO connected to X7
- SCLK connected to X6
- nSS connected to X5
- nRESET connected to X4
It is possible to use other SPI busses and other pins for nSS and nRESET.
Constructors
------------
.. class:: WIZNET5K(spi, pin_cs, pin_rst)
Create a WIZNET5K driver object, initialise the WIZnet5x00 module using the given
SPI bus and pins, and return the WIZNET5K object.
Arguments are:
- ``spi`` is an :ref:`SPI object <pyb.SPI>` which is the SPI bus that the WIZnet5x00 is
connected to (the MOSI, MISO and SCLK pins).
- ``pin_cs`` is a :ref:`Pin object <pyb.Pin>` which is connected to the WIZnet5x00 nSS pin.
- ``pin_rst`` is a :ref:`Pin object <pyb.Pin>` which is connected to the WIZnet5x00 nRESET pin.
All of these objects will be initialised by the driver, so there is no need to
initialise them yourself. For example, you can use::
nic = network.WIZNET5K(pyb.SPI(1), pyb.Pin.board.X5, pyb.Pin.board.X4)
Methods
-------
.. method:: wiznet5k.ifconfig([(ip, subnet, gateway, dns)])
Get/set IP address, subnet mask, gateway and DNS.
When called with no arguments, this method returns a 4-tuple with the above information.
To set the above values, pass a 4-tuple with the required information. For example::
nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
.. method:: wiznet5k.regs()
Dump the WIZnet5x00 registers. Useful for debugging.
selects the external antenna

16
docs/library/os.rst
View File

@ -16,8 +16,14 @@ available physical drives are accessible from here. They are currently:
``/sd`` -- the SD card (if it exists)
On boot up, the current directory is ``/flash`` if no SD card is inserted,
otherwise it is ``/sd``.
.. only:: port_pyboard
On boot up, the current directory is ``/flash`` if no SD card is inserted,
otherwise it is ``/sd``.
.. only:: port_wipy
On boot up, the current directory is ``/flash``.
Functions
---------
@ -63,6 +69,12 @@ Functions
Return a bytes object with n random bytes, generated by the hardware
random number generator.
.. only:: port_wipy
.. function:: mkfs(drive)
Formats the specified drive, must be either ``/flash`` or ``/sd``.
Constants
---------

93
docs/library/pyb.ADC.rst
View File

@ -3,28 +3,55 @@
class ADC -- analog to digital conversion: read analog values on a pin
======================================================================
Usage::
.. only:: port_pyboard
import pyb
Usage::
import pyb
adc = pyb.ADC(pin) # create an analog object from a pin
val = adc.read() # read an analog value
adc = pyb.ADCAll(resolution) # creale an ADCAll object
val = adc.read_channel(channel) # read the given channel
val = adc.read_core_temp() # read MCU temperature
val = adc.read_core_vbat() # read MCU VBAT
val = adc.read_core_vref() # read MCU VREF
adc = pyb.ADC(pin) # create an analog object from a pin
val = adc.read() # read an analog value
.. only:: port_wipy
adc = pyb.ADCAll(resolution) # creale an ADCAll object
val = adc.read_channel(channel) # read the given channel
val = adc.read_core_temp() # read MCU temperature
val = adc.read_core_vbat() # read MCU VBAT
val = adc.read_core_vref() # read MCU VREF
Usage::
import pyb
adc = pyb.ADC(channel) # create an analog object on one of the 4 ADC channels
val = adc.read() # read an analog value
Constructors
------------
.. class:: pyb.ADC(pin)
.. only:: port_pyboard
Create an ADC object associated with the given pin.
This allows you to then read analog values on that pin.
.. class:: pyb.ADC(pin)
Create an ADC object associated with the given pin.
This allows you to then read analog values on that pin.
.. only:: port_wipy
.. class:: pyb.ADC(channel)
Create an ADC object on the given channel. Each channel is associated
to a specific pin. For more info check the `pinout and alternate functions
table. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_
This allows you to then read analog values on that pin.
.. warning::
ADC pin input range is 0-1.4V (being 1.8V the absolute maximum that it
can withstand). When GPIO2, GPIO3, GPIO4 or GPIO5 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.
Methods
-------
@ -34,19 +61,31 @@ Methods
Read the value on the analog pin and return it. The returned value
will be between 0 and 4095.
.. method:: adc.read_timed(buf, freq)
.. only:: port_pyboard
Read analog values into the given buffer at the given frequency. Buffer
can be bytearray or array.array for example. If a buffer with 8-bit elements
is used, sample resolution will be reduced to 8 bits.
Example::
adc = pyb.ADC(pyb.Pin.board.X19) # create an ADC on pin X19
buf = bytearray(100) # create a buffer of 100 bytes
adc.read_timed(buf, 10) # read analog values into buf at 10Hz
# this will take 10 seconds to finish
for val in buf: # loop over all values
print(val) # print the value out
This function does not allocate any memory.
.. method:: adc.read_timed(buf, freq)
Read analog values into the given buffer at the given frequency. Buffer
can be bytearray or array.array for example. If a buffer with 8-bit elements
is used, sample resolution will be reduced to 8 bits.
Example::
adc = pyb.ADC(pyb.Pin.board.X19) # create an ADC on pin X19
buf = bytearray(100) # create a buffer of 100 bytes
adc.read_timed(buf, 10) # read analog values into buf at 10Hz
# this will take 10 seconds to finish
for val in buf: # loop over all values
print(val) # print the value out
This function does not allocate any memory.
.. only:: port_wipy
.. method:: adc.enable()
Enable the ADC channel.
.. method:: adc.disable()
Disable the ADC channel.

46
docs/library/pyb.HeartBeat.rst Normal file
View File

@ -0,0 +1,46 @@
.. _pyb.HeartBeat:
class HeartBeat -- heart beat LED
=================================
The HeartBeat class controls the heart beat led which by default
flashes once every 5s. The user can disable the HeartBeat and then
is free to control this LED manually through GPIO25 using the Pin
class. The GPIO25 can also be remapped as a PWM output, an this
can be used to control the light intesity of the heart beat LED.
Example usage::
hb = pyb.HeartBeat()
hb.disable() # disable the heart beat
hb.enable() # enable the heart beat
Constructors
------------
.. class:: pyb.HeartBeat()
Create a HeartBeat object.
Methods
-------
.. method:: heartbeat.enable()
Enable the heart beat. The LED will flash once every 5 seconds.
.. method:: heartbeat.disable()
Disable the heart beat. The LED can then be controlled manually.
Example::
import pyb
# disable the heart beat
pyb.HeartBeat().disable()
# get the GPIO25 pin object
hbl = pyb.Pin('GPIO25')
# toggle the led
hbl.toggle()
...

269
docs/library/pyb.I2C.rst
View File

@ -7,19 +7,34 @@ 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::
when created, or initialised later on.
from pyb import I2C
.. only:: port_pyboard
i2c = I2C(1) # create on bus 1
i2c = I2C(1, I2C.MASTER) # create and init as a master
i2c.init(I2C.MASTER, baudrate=20000) # init as a master
i2c.init(I2C.SLAVE, addr=0x42) # init as a slave with given address
i2c.deinit() # turn off the peripheral
Example::
from pyb import I2C
i2c = I2C(1) # create on bus 1
i2c = I2C(1, I2C.MASTER) # create and init as a master
i2c.init(I2C.MASTER, baudrate=20000) # init as a master
i2c.init(I2C.SLAVE, addr=0x42) # init as a slave with given address
i2c.deinit() # turn off the peripheral
.. only:: port_wipy
Example::
from pyb import I2C
i2c = I2C(1) # create on bus 1
i2c = I2C(1, 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.
Basic methods for slave are send and recv::
The basic methods are send and recv::
i2c.send('abc') # send 3 bytes
i2c.send(0x42) # send a single byte, given by the number
@ -30,9 +45,11 @@ To receive inplace, first create a bytearray::
data = bytearray(3) # create a buffer
i2c.recv(data) # receive 3 bytes, writing them into data
You can specify a timeout (in ms)::
.. only:: port_pyboard
i2c.send(b'123', timeout=2000) # timout after 2 seconds
You can specify a timeout (in ms)::
i2c.send(b'123', timeout=2000) # timout after 2 seconds
A master must specify the recipient's address::
@ -40,31 +57,57 @@ A master must specify the recipient's address::
i2c.send('123', 0x42) # send 3 bytes to slave with address 0x42
i2c.send(b'456', addr=0x42) # keyword for address
Master also has other methods::
.. only:: port_pyboard
i2c.is_ready(0x42) # check if slave 0x42 is ready
i2c.scan() # scan for slaves on the bus, returning
# a list of valid addresses
i2c.mem_read(3, 0x42, 2) # read 3 bytes from memory of slave 0x42,
# starting at address 2 in the slave
i2c.mem_write('abc', 0x42, 2, timeout=1000)
Master also has other methods::
i2c.is_ready(0x42) # check if slave 0x42 is ready
i2c.scan() # scan for slaves on the bus, returning
# a list of valid addresses
i2c.mem_read(3, 0x42, 2) # read 3 bytes from memory of slave 0x42,
# starting at address 2 in the slave
i2c.mem_write('abc', 0x42, 2, timeout=1000)
.. only:: port_wipy
There are also other methods::
i2c.is_ready(0x42) # check if slave 0x42 is ready
i2c.scan() # scan for slaves on the bus, returning
# a list of valid addresses
i2c.mem_read(3, 0x42, 2) # read 3 bytes from memory of slave 0x42,
# starting at address 2 in the slave
i2c.mem_write('abc', 0x42, 2) # write 'abc' (3 bytes) to memory of slave 0x42
# starting at address 2 in the slave
Constructors
------------
.. class:: pyb.I2C(bus, ...)
.. only:: port_pyboard
Construct an I2C object on the given bus. ``bus`` can be 1 or 2.
With no additional parameters, the I2C object is created but not
initialised (it has the settings from the last initialisation of
the bus, if any). If extra arguments are given, the bus is initialised.
See ``init`` for parameters of initialisation.
The physical pins of the I2C busses are:
- ``I2C(1)`` is on the X position: ``(SCL, SDA) = (X9, X10) = (PB6, PB7)``
- ``I2C(2)`` is on the Y position: ``(SCL, SDA) = (Y9, Y10) = (PB10, PB11)``
.. class:: pyb.I2C(bus, ...)
Construct an I2C object on the given bus. ``bus`` can be 1 or 2.
With no additional parameters, the I2C object is created but not
initialised (it has the settings from the last initialisation of
the bus, if any). If extra arguments are given, the bus is initialised.
See ``init`` for parameters of initialisation.
The physical pins of the I2C busses are:
- ``I2C(1)`` is on the X position: ``(SCL, SDA) = (X9, X10) = (PB6, PB7)``
- ``I2C(2)`` is on the Y position: ``(SCL, SDA) = (Y9, Y10) = (PB10, PB11)``
.. only:: port_wipy
.. class:: pyb.I2C(bus, ...)
Construct an I2C object on the given bus. `bus` can only be 1.
With no additional parameters, the I2C object is created but not
initialised (it has the settings from the last initialisation of
the bus, if any). If extra arguments are given, the bus is initialised.
See `init` for parameters of initialisation.
Methods
@ -74,72 +117,142 @@ Methods
Turn off the I2C bus.
.. method:: i2c.init(mode, \*, addr=0x12, baudrate=400000, gencall=False)
.. only:: port_pyboard
Initialise the I2C bus with the given parameters:
- ``mode`` must be either ``I2C.MASTER`` or ``I2C.SLAVE``
- ``addr`` is the 7-bit address (only sensible for a slave)
- ``baudrate`` is the SCL clock rate (only sensible for a master)
- ``gencall`` is whether to support general call mode
.. method:: i2c.init(mode, \*, addr=0x12, baudrate=400000, gencall=False)
Initialise the I2C bus with the given parameters:
- ``mode`` must be either ``I2C.MASTER`` or ``I2C.SLAVE``
- ``addr`` is the 7-bit address (only sensible for a slave)
- ``baudrate`` is the SCL clock rate (only sensible for a master)
- ``gencall`` is whether to support general call mode
.. only:: port_wipy
.. method:: i2c.init(mode, \*, baudrate=100000)
Initialise the I2C bus with the given parameters:
- ``mode`` must be ``I2C.MASTER``
- ``baudrate`` is the SCL clock rate
.. method:: i2c.is_ready(addr)
Check if an I2C device responds to the given address. Only valid when in master mode.
.. method:: i2c.mem_read(data, addr, memaddr, timeout=5000, addr_size=8)
.. only:: port_pyboard
Read from the memory of an I2C device:
- ``data`` can be an integer (number of bytes to read) or a buffer to read into
- ``addr`` is the I2C device address
- ``memaddr`` is the memory location within the I2C device
- ``timeout`` is the timeout in milliseconds to wait for the read
- ``addr_size`` selects width of memaddr: 8 or 16 bits
Returns the read data.
This is only valid in master mode.
.. method:: i2c.mem_read(data, addr, memaddr, timeout=5000, addr_size=8)
Read from the memory of an I2C device:
- ``data`` can be an integer (number of bytes to read) or a buffer to read into
- ``addr`` is the I2C device address
- ``memaddr`` is the memory location within the I2C device
- ``timeout`` is the timeout in milliseconds to wait for the read
- ``addr_size`` selects width of memaddr: 8 or 16 bits
.. method:: i2c.mem_write(data, addr, memaddr, timeout=5000, addr_size=8)
Returns the read data.
This is only valid in master mode.
Write to the memory of an I2C device:
- ``data`` can be an integer or a buffer to write from
- ``addr`` is the I2C device address
- ``memaddr`` is the memory location within the I2C device
- ``timeout`` is the timeout in milliseconds to wait for the write
- ``addr_size`` selects width of memaddr: 8 or 16 bits
Returns ``None``.
This is only valid in master mode.
.. only:: port_wipy
.. method:: i2c.recv(recv, addr=0x00, timeout=5000)
.. method:: i2c.mem_read(data, addr, memaddr, addr_size=8)
Read from the memory of an I2C device:
- ``data`` can be an integer (number of bytes to read) or a buffer to read into
- ``addr`` is the I2C device address
- ``memaddr`` is the memory location within the I2C device
- ``addr_size`` selects width of memaddr: 8 or 16 bits
Receive data on the bus:
- ``recv`` can be an integer, which is the number of bytes to receive,
or a mutable buffer, which will be filled with received bytes
- ``addr`` is the address to receive from (only required in master mode)
- ``timeout`` is the timeout in milliseconds to wait for the receive
Return value: if ``recv`` is an integer then a new buffer of the bytes received,
otherwise the same buffer that was passed in to ``recv``.
Returns the read data.
This is only valid in master mode.
.. only:: port_pyboard
.. method:: i2c.mem_write(data, addr, memaddr, timeout=5000, addr_size=8)
Write to the memory of an I2C device:
- ``data`` can be an integer or a buffer to write from
- ``addr`` is the I2C device address
- ``memaddr`` is the memory location within the I2C device
- ``timeout`` is the timeout in milliseconds to wait for the write
- ``addr_size`` selects width of memaddr: 8 or 16 bits
Returns ``None``.
This is only valid in master mode.
.. only:: port_wipy
.. method:: i2c.mem_write(data, addr, memaddr, timeout=5000, addr_size=8)
Write to the memory of an I2C device:
- ``data`` can be an integer or a buffer to write from
- ``addr`` is the I2C device address
- ``memaddr`` is the memory location within the I2C device
- ``addr_size`` selects width of memaddr: 8 or 16 bits
Returns ``None``.
This is only valid in master mode.
.. only:: port_pyboard
.. method:: i2c.recv(recv, addr=0x00, timeout=5000)
Receive data on the bus:
- ``recv`` can be an integer, which is the number of bytes to receive,
or a mutable buffer, which will be filled with received bytes
- ``addr`` is the address to receive from (only required in master mode)
- ``timeout`` is the timeout in milliseconds to wait for the receive
Return value: if ``recv`` is an integer then a new buffer of the bytes received,
otherwise the same buffer that was passed in to ``recv``.
.. only:: port_wipy
.. method:: i2c.recv(recv, addr=0x00)
Receive data on the bus:
- ``recv`` can be an integer, which is the number of bytes to receive,
or a mutable buffer, which will be filled with received bytes
- ``addr`` is the address to receive from (only required in master mode)
Return value: if ``recv`` is an integer then a new buffer of the bytes received,
otherwise the same buffer that was passed in to ``recv``.
.. 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.
.. method:: i2c.send(send, addr=0x00, timeout=5000)
.. only:: port_pyboard
Send data on the bus:
- ``send`` is the data to send (an integer to send, or a buffer object)
- ``addr`` is the address to send to (only required in master mode)
- ``timeout`` is the timeout in milliseconds to wait for the send
Return value: ``None``.
.. method:: i2c.send(send, addr=0x00, timeout=5000)
Send data on the bus:
- ``send`` is the data to send (an integer to send, or a buffer object)
- ``addr`` is the address to send to (only required in master mode)
- ``timeout`` is the timeout in milliseconds to wait for the send
Return value: ``None``.
.. only:: port_wipy
.. method:: i2c.send(send, addr=0x00)
Send data on the bus:
- ``send`` is the data to send (an integer to send, or a buffer object)
- ``addr`` is the address to send to (only required in master mode)
Return value: ``None``.
Constants
---------
@ -148,6 +261,8 @@ Constants
for initialising the bus to master mode
.. data:: I2C.SLAVE
.. only:: port_pyboard
for initialising the bus to slave mode
.. data:: I2C.SLAVE
for initialising the bus to slave mode

565
docs/library/pyb.Pin.rst
View File

@ -5,113 +5,190 @@ 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.
digital logic level. For analog control of a pin, see the ADC class.
Usage Model:
All Board Pins are predefined as pyb.Pin.board.Name ::
.. only:: port_pyboard
x1_pin = pyb.Pin.board.X1
All Board Pins are predefined as pyb.Pin.board.Name::
x1_pin = pyb.Pin.board.X1
g = pyb.Pin(pyb.Pin.board.X1, pyb.Pin.IN)
CPU pins which correspond to the board pins are available
as ``pyb.cpu.Name``. For the CPU pins, the names are the port letter
followed by the pin number. On the PYBv1.0, ``pyb.Pin.board.X1`` and
``pyb.Pin.cpu.B6`` are the same pin.
You can also use strings::
g = pyb.Pin('X1', pyb.Pin.OUT_PP)
Users can add their own names::
MyMapperDict = { 'LeftMotorDir' : pyb.Pin.cpu.C12 }
pyb.Pin.dict(MyMapperDict)
g = pyb.Pin("LeftMotorDir", pyb.Pin.OUT_OD)
and can query mappings::
pin = pyb.Pin("LeftMotorDir")
Users can also add their own mapping function::
def MyMapper(pin_name):
if pin_name == "LeftMotorDir":
return pyb.Pin.cpu.A0
pyb.Pin.mapper(MyMapper)
So, if you were to call: ``pyb.Pin("LeftMotorDir", pyb.Pin.OUT_PP)``
then ``"LeftMotorDir"`` is passed directly to the mapper function.
To summarise, the following order determines how things get mapped into
an ordinal pin number:
1. Directly specify a pin object
2. User supplied mapping function
3. User supplied mapping (object must be usable as a dictionary key)
4. Supply a string which matches a board pin
5. Supply a string which matches a CPU port/pin
You can set ``pyb.Pin.debug(True)`` to get some debug information about
how a particular object gets mapped to a pin.
When a pin has the ``Pin.PULL_UP`` or ``Pin.PULL_DOWN`` pull-mode enabled,
that pin has an effective 40k Ohm resistor pulling it to 3V3 or GND
respectively (except pin Y5 which has 11k Ohm resistors).
g = pyb.Pin(pyb.Pin.board.X1, pyb.Pin.IN)
.. only:: port_wipy
CPU pins which correspond to the board pins are available
as ``pyb.cpu.Name``. For the CPU pins, the names are the port letter
followed by the pin number. On the PYBv1.0, ``pyb.Pin.board.X1`` and
``pyb.Pin.cpu.B6`` are the same pin.
Board pins are identified by their string name::
You can also use strings::
g = pyb.Pin('GPIO9', af=0, mode=pyb.Pin.IN, type=pyb.Pin.STD, strength=pyb.Pin.S2MA)
g = pyb.Pin('X1', pyb.Pin.OUT_PP)
You can also configure the Pin to generate interrupts. For instance::
Users can add their own names::
def pincb(pin):
print(pin.info().name)
MyMapperDict = { 'LeftMotorDir' : pyb.Pin.cpu.C12 }
pyb.Pin.dict(MyMapperDict)
g = pyb.Pin("LeftMotorDir", pyb.Pin.OUT_OD)
pin_int = pyb.Pin('GPIO10', af=0, mode=Pin.IN, type=pyb.Pin.STD_PD, strength=pyb.Pin.S2MA)
pin_int.callback (mode=pyb.Pin.INT_RISING, handler=pincb)
# the callback can be triggered manually
pin_int.callback()()
# to disable the callback
pin_int.callback().disable()
and can query mappings ::
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: http://www.eng.utah.edu/~cs5780/debouncing.pdf for a detailed
explanation, along with various techniques for debouncing.
pin = pyb.Pin("LeftMotorDir")
Users can also add their own mapping function::
def MyMapper(pin_name):
if pin_name == "LeftMotorDir":
return pyb.Pin.cpu.A0
pyb.Pin.mapper(MyMapper)
So, if you were to call: ``pyb.Pin("LeftMotorDir", pyb.Pin.OUT_PP)``
then ``"LeftMotorDir"`` is passed directly to the mapper function.
To summarise, the following order determines how things get mapped into
an ordinal pin number:
1. Directly specify a pin object
2. User supplied mapping function
3. User supplied mapping (object must be usable as a dictionary key)
4. Supply a string which matches a board pin
5. Supply a string which matches a CPU port/pin
You can set ``pyb.Pin.debug(True)`` to get some debug information about
how a particular object gets mapped to a pin.
When a pin has the ``Pin.PULL_UP`` or ``Pin.PULL_DOWN`` pull-mode enabled,
that pin has an effective 40k Ohm resistor pulling it to 3V3 or GND
respectively (except pin Y5 which has 11k Ohm resistors).
All pin objects go through the pin mapper to come up with one of the
gpio pins.
Constructors
------------
.. class:: pyb.Pin(id, ...)
.. only:: port_pyboard
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`.
.. class:: pyb.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`.
Class methods
-------------
.. only:: port_wipy
.. method:: Pin.af_list()
.. class:: pyb.Pin(name, ...)
Returns an array of alternate functions available for this pin.
Create a new Pin object associated with the name. If additional arguments are given,
they are used to initialise the pin. See :meth:`pin.init`.
.. method:: Pin.debug([state])
.. only:: port_pyboard
Get or set the debugging state (``True`` or ``False`` for on or off).
.. method:: Pin.dict([dict])
Get or set the pin mapper dictionary.
.. method:: Pin.mapper([fun])
Get or set the pin mapper function.
Class methods
-------------
.. method:: Pin.af_list()
Returns an array of alternate functions available for this pin.
.. method:: Pin.debug([state])
Get or set the debugging state (``True`` or ``False`` for on or off).
.. method:: Pin.dict([dict])
Get or set the pin mapper dictionary.
.. method:: Pin.mapper([fun])
Get or set the pin mapper function.
Methods
-------
.. method:: pin.init(mode, pull=Pin.PULL_NONE, af=-1)
.. only:: port_pyboard
Initialise the pin:
- ``mode`` can be one of:
- ``Pin.IN`` - configure the pin for input;
- ``Pin.OUT_PP`` - configure the pin for output, with push-pull control;
- ``Pin.OUT_OD`` - configure the pin for output, with open-drain control;
- ``Pin.AF_PP`` - configure the pin for alternate function, pull-pull;
- ``Pin.AF_OD`` - configure the pin for alternate function, open-drain;
- ``Pin.ANALOG`` - configure the pin for analog.
- ``pull`` can be one of:
- ``Pin.PULL_NONE`` - no pull up or down resistors;
- ``Pin.PULL_UP`` - enable the pull-up resistor;
- ``Pin.PULL_DOWN`` - enable the pull-down resistor.
- when mode is Pin.AF_PP or Pin.AF_OD, then af can be the index or name
of one of the alternate functions associated with a pin.
Returns: ``None``.
.. method:: pin.init(mode, pull=Pin.PULL_NONE, af=-1)
Initialise the pin:
- ``mode`` can be one of:
- ``Pin.IN`` - configure the pin for input;
- ``Pin.OUT_PP`` - configure the pin for output, with push-pull control;
- ``Pin.OUT_OD`` - configure the pin for output, with open-drain control;
- ``Pin.AF_PP`` - configure the pin for alternate function, pull-pull;
- ``Pin.AF_OD`` - configure the pin for alternate function, open-drain;
- ``Pin.ANALOG`` - configure the pin for analog.
- ``pull`` can be one of:
- ``Pin.PULL_NONE`` - no pull up or down resistors;
- ``Pin.PULL_UP`` - enable the pull-up resistor;
- ``Pin.PULL_DOWN`` - enable the pull-down resistor.
- when mode is ``Pin.AF_PP`` or ``Pin.AF_OD``, then af can be the index or name
of one of the alternate functions associated with a pin.
Returns: ``None``.
.. only:: port_wipy
.. method:: pin.init(af, mode, type, strength)
Initialise the pin:
- ``af`` is the number of the alternate function. Please refer to the
`pinout and alternate functions table. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_
for the specific alternate functions that each pin supports.
- ``mode`` can be one of:
- ``Pin.OUT`` - no pull up or down resistors.
- ``Pin.IN`` - enable the pull-up resistor.
- ``type`` can be one of:
- ``Pin.STD`` - push-pull pin.
- ``Pin.STD_PU`` - push-pull pin with pull-up resistor.
- ``Pin.STD_PD`` - push-pull pin with pull-down resistor.
- ``Pin.OD`` - open drain pin.
- ``Pin.OD_PU`` - open drain pin with pull-up resistor.
- ``Pin.OD_PD`` - open drain pin with pull-down resistor.
- ``strength`` can be one of:
- ``Pin.S2MA`` - 2mA drive capability.
- ``Pin.S4MA`` - 4mA drive capability.
- ``Pin.S6MA`` - 6mA drive capability.
Returns: ``None``.
.. method:: pin.high()
@ -130,137 +207,249 @@ Methods
anything that converts to a boolean. If it converts to ``True``, the pin
is set high, otherwise it is set low.
.. method:: pin.__str__()
.. only:: port_pyboard
Return a string describing the pin object.
.. method:: pin.__str__()
Return a string describing the pin object.
.. method:: pin.af()
Returns the currently configured alternate-function of the pin. The
integer returned will match one of the allowed constants for the af
argument to the init function.
.. method:: pin.gpio()
Returns the base address of the GPIO block associated with this pin.
.. method:: pin.mode()
Returns the currently configured mode of the pin. The integer returned
will match one of the allowed constants for the mode argument to the init
function.
.. method:: pin.name()
Get the pin name.
.. method:: pin.names()
Returns the cpu and board names for this pin.
.. method:: pin.pin()
Get the pin number.
.. method:: pin.port()
Get the pin port.
.. method:: pin.pull()
Returns the currently configured pull of the pin. The integer returned
will match one of the allowed constants for the pull argument to the init
function.
.. method:: pin.af()
.. only:: port_wipy
Returns the currently configured alternate-function of the pin. The
integer returned will match one of the allowed constants for the af
argument to the init function.
.. method:: pin.toggle()
.. method:: pin.gpio()
Toggle the value of the pin.
Returns the base address of the GPIO block associated with this pin.
.. method:: pin.info()
.. method:: pin.mode()
Return a 5-tuple with the configuration of the pin:
``(name, alternate-function, mode, type, strength)``
Returns the currently configured mode of the pin. The integer returned
will match one of the allowed constants for the mode argument to the init
function.
.. method:: pin.callback(mode, priority=1, handler=None, wakes=pyb.Sleep.ACTIVE)
.. method:: pin.name()
Create a callback to be triggered when data is received on the UART.
Get the pin name.
- ``mode`` configures the pin level which can generate an interrupt. Possible values are:
.. method:: pin.names()
- ``Pin.INT_FALLING`` interrupt on falling edge.
- ``Pin.INT_RISING`` interrupt on rising edge.
- ``Pin.INT_RISING_FALLING`` interrupt on rising and falling edge.
- ``Pin.INT_LOW_LEVEL`` interrupt on low level.
- ``Pin.INT_HIGH_LEVEL`` interrupt on high level.
Returns the cpu and board names for this pin.
- ``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:
.. method:: pin.pin()
- If ``wakes=pyb.Sleep.ACTIVE`` any pin can wake the board.
- If ``wakes=pyb.Sleep.SUSPENDED`` pins ``GPIO2``, ``GPIO4``, ``GPIO10``,
``GPIO11``, GPIO17`` or ``GPIO24`` 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 ``pyb.Sleep.SUSPENDED`` wake source will have effect.
- If ``wakes=pyb.Sleep.SUSPENDED`` pins ``GPIO2``, ``GPIO4``, ``GPIO10``,
``GPIO11``, GPIO17`` and ``GPIO24`` can wake the board. In this case all this 6
pins can be enabled as a ``pyb.Sleep.HIBERNATE`` wake source at the same time.
- Values can be ORed to make a pin generate interrupts in more than one power
mode.
Get the pin number.
.. method:: pin.port()
Get the pin port.
.. method:: pin.pull()
Returns the currently configured pull of the pin. The integer returned
will match one of the allowed constants for the pull argument to the init
function.
Returns a callback object.
Constants
---------
.. data:: Pin.AF_OD
.. only:: port_pyboard
initialise the pin to alternate-function mode with an open-drain drive
.. data:: Pin.AF_OD
initialise the pin to alternate-function mode with an open-drain drive
.. data:: Pin.AF_PP
initialise the pin to alternate-function mode with a push-pull drive
.. data:: Pin.ANALOG
initialise the pin to analog mode
.. data:: Pin.IN
initialise the pin to input mode
.. data:: Pin.OUT_OD
initialise the pin to output mode with an open-drain drive
.. data:: Pin.OUT_PP
initialise the pin to output mode with a push-pull drive
.. data:: Pin.PULL_DOWN
enable the pull-down resistor on the pin
.. data:: Pin.PULL_NONE
don't enable any pull up or down resistors on the pin
.. data:: Pin.PULL_UP
enable the pull-up resistor on the pin
.. data:: Pin.AF_PP
.. only:: port_wipy
initialise the pin to alternate-function mode with a push-pull drive
.. data:: Pin.IN
input pin mode
.. data:: Pin.OUT
output pin mode
.. data:: Pin.STD
push-pull pin type
.. data:: Pin.STD_PU
push-pull pin with internall pull-up resistor
.. data:: Pin.STD_PD
push-pull pin with internall pull-down resistor
.. data:: Pin.OD
open-drain pin
.. data:: Pin.OD_PU
open-drain pin with pull-up resistor
.. data:: Pin.OD_PD
open-drain pin with pull-down resistor
.. data:: Pin.INT_FALLING
interrupt on falling edge
.. data:: Pin.INT_RISING
interrupt on rising edge
.. data:: Pin.INT_RISING_FALLING
interrupt on rising and falling edge
.. data:: Pin.INT_LOW_LEVEL
interrupt on low level
.. data:: Pin.INT_HIGH_LEVEL
interrupt on high level
.. data:: Pin.S2MA
2mA drive strength
.. data:: Pin.S4MA
4mA drive strength
.. data:: Pin.S6MA
6mA drive strength
.. data:: Pin.ANALOG
.. only:: port_pyboard
initialise the pin to analog mode
class PinAF -- Pin Alternate Functions
======================================
A Pin represents a physical pin on the microcprocessor. Each pin
can have a variety of functions (GPIO, I2C SDA, etc). Each PinAF
object represents a particular function for a pin.
Usage Model::
x3 = pyb.Pin.board.X3
x3_af = x3.af_list()
x3_af will now contain an array of PinAF objects which are availble on
pin X3.
For the pyboard, x3_af would contain:
[Pin.AF1_TIM2, Pin.AF2_TIM5, Pin.AF3_TIM9, Pin.AF7_USART2]
Normally, each peripheral would configure the af automatically, but sometimes
the same function is available on multiple pins, and having more control
is desired.
To configure X3 to expose TIM2_CH3, you could use::
pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=pyb.Pin.AF1_TIM2)
or::
pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=1)
.. data:: Pin.IN
initialise the pin to input mode
.. data:: Pin.OUT_OD
initialise the pin to output mode with an open-drain drive
.. data:: Pin.OUT_PP
initialise the pin to output mode with a push-pull drive
.. data:: Pin.PULL_DOWN
enable the pull-down resistor on the pin
.. data:: Pin.PULL_NONE
don't enable any pull up or down resistors on the pin
.. data:: Pin.PULL_UP
enable the pull-up resistor on the pin
class PinAF -- Pin Alternate Functions
======================================
A Pin represents a physical pin on the microcprocessor. Each pin
can have a variety of functions (GPIO, I2C SDA, etc). Each PinAF
object represents a particular function for a pin.
Usage Model::
x3 = pyb.Pin.board.X3
x3_af = x3.af_list()
x3_af will now contain an array of PinAF objects which are availble on
pin X3.
For the pyboard, x3_af would contain:
[Pin.AF1_TIM2, Pin.AF2_TIM5, Pin.AF3_TIM9, Pin.AF7_USART2]
Normally, each peripheral would configure the af automatically, but sometimes
the same function is available on multiple pins, and having more control
is desired.
To configure X3 to expose TIM2_CH3, you could use::
pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=pyb.Pin.AF1_TIM2)
or::
pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=1)
Methods
-------
.. method:: pinaf.__str__()
Return a string describing the alternate function.
.. method:: pinaf.index()
Return the alternate function index.
.. method:: pinaf.name()
Return the name of the alternate function.
.. method:: pinaf.reg()
Return the base register associated with the peripheral assigned to this
alternate function. For example, if the alternate function were TIM2_CH3
this would return stm.TIM2
Methods
-------
.. method:: pinaf.__str__()
Return a string describing the alternate function.
.. method:: pinaf.index()
Return the alternate function index.
.. method:: pinaf.name()
Return the name of the alternate function.
.. method:: pinaf.reg()
Return the base register associated with the peripheral assigned to this
alternate function. For example, if the alternate function were TIM2_CH3
this would return stm.TIM2

78
docs/library/pyb.RTC.rst
View File

@ -1,3 +1,5 @@
.. _pyb.RTC:
class RTC -- real time clock
============================
@ -38,38 +40,52 @@ Methods
``subseconds`` counts down from 255 to 0
.. method:: rtc.wakeup(timeout, callback=None)
.. only:: port_pyboard
Set the RTC wakeup timer to trigger repeatedly at every ``timeout``
milliseconds. This trigger can wake the pyboard from both the sleep
states: :meth:`pyb.stop` and :meth:`pyb.standby`.
.. method:: rtc.wakeup(timeout, callback=None)
Set the RTC wakeup timer to trigger repeatedly at every ``timeout``
milliseconds. This trigger can wake the pyboard from both the sleep
states: :meth:`pyb.stop` and :meth:`pyb.standby`.
If ``timeout`` is ``None`` then the wakeup timer is disabled.
If ``callback`` is given then it is executed at every trigger of the
wakeup timer. ``callback`` must take exactly one argument.
.. method:: rtc.info()
Get information about the startup time and reset source.
- The lower 0xffff are the number of milliseconds the RTC took to
start up.
- Bit 0x10000 is set if a power-on reset occurred.
- Bit 0x20000 is set if an external reset occurred
.. method:: rtc.calibration(cal)
Get or set RTC calibration.
With no arguments, ``calibration()`` returns the current calibration
value, which is an integer in the range [-511 : 512]. With one
argument it sets the RTC calibration.
The RTC Smooth Calibration mechanism addjusts the RTC clock rate by
adding or subtracting the given number of ticks from the 32768 Hz
clock over a 32 second period (corresponding to 2^20 clock ticks.)
Each tick added will speed up the clock by 1 part in 2^20, or 0.954
ppm; likewise the RTC clock it slowed by negative values. The
usable calibration range is:
(-511 * 0.954) ~= -487.5 ppm up to (512 * 0.954) ~= 488.5 ppm
If ``timeout`` is ``None`` then the wakeup timer is disabled.
.. only:: port_wipy
If ``callback`` is given then it is executed at every trigger of the
wakeup timer. ``callback`` must take exactly one argument.
.. method:: rtc.callback(\*, value, handler=None, wakes=pyb.Sleep.ACTIVE)
Create a callback object triggered by a real time clock alarm.
- ``value`` is the alarm timeout in milliseconds. This parameter is required.
- ``handler`` is the function to be called when the callback is triggered.
- ``wakes`` specifies the power mode from where this interrupt can wake
up the system.
.. method:: rtc.info()
Get information about the startup time and reset source.
- The lower 0xffff are the number of milliseconds the RTC took to
start up.
- Bit 0x10000 is set if a power-on reset occurred.
- Bit 0x20000 is set if an external reset occurred
.. method:: rtc.calibration(cal)
Get or set RTC calibration.
With no arguments, ``calibration()`` returns the current calibration
value, which is an integer in the range [-511 : 512]. With one
argument it sets the RTC calibration.
The RTC Smooth Calibration mechanism addjusts the RTC clock rate by
adding or subtracting the given number of ticks from the 32768 Hz
clock over a 32 second period (corresponding to 2^20 clock ticks.)
Each tick added will speed up the clock by 1 part in 2^20, or 0.954
ppm; likewise the RTC clock it slowed by negative values. The
usable calibration range is:
(-511 * 0.954) ~= -487.5 ppm up to (512 * 0.954) ~= 488.5 ppm

39
docs/library/pyb.SD.rst Normal file
View File

@ -0,0 +1,39 @@
.. _pyb.SD:
class SD -- secure digital memory card
======================================
The SD card class allows to configure and enable the memory card
module of the WiPy and automatically mount it as ``/sd`` as part
of the file system. There are several pin combinations that can be
used to wire the SD card socket to the WiPy and the pins used can
be specified in the constructor. Please check the `pinout and alternate functions
table. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_ for
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
# their respective alternate functions
sd = pyb.SD('GPIO15', 8, 'GPIO16', 8, 'GPIO17', 8)
sd.enable() # enable and mount the SD card
sd.disable() # disable and unmount it
Constructors
------------
.. class:: pyb.SD(dat_pin, dat_pin_af, clk_pin, clk_pin_af, cmd_pin, cmd_pin_af)
Create a SD card object. Data, clock and cmd pins must be passed along with
their respective alternate functions.
Methods
-------
.. method:: sd.enable()
Enable the SD card and mount it on the file system. Accesible as ``/sd``.
.. method:: sd.disable()
Disable the SD card and remove it from the file system.

251
docs/library/pyb.SPI.rst
View File

@ -6,18 +6,32 @@ class SPI -- a master-driven serial protocol
SPI is a serial protocol that is driven by a master. At the physical level
there are 3 lines: SCK, MOSI, MISO.
See usage model of I2C; SPI is very similar. Main difference is
parameters to init the SPI bus::
.. only:: port_pyboard
from pyb import SPI
spi = SPI(1, SPI.MASTER, baudrate=600000, polarity=1, phase=0, crc=0x7)
See usage model of I2C; SPI is very similar. Main difference is
parameters to init the SPI bus::
from pyb import SPI
spi = SPI(1, SPI.MASTER, baudrate=600000, polarity=1, phase=0, crc=0x7)
Only required parameter is mode, SPI.MASTER or SPI.SLAVE. Polarity can be
0 or 1, and is the level the idle clock line sits at. Phase can be 0 or 1
to sample data on the first or second clock edge respectively. Crc can be
None for no CRC, or a polynomial specifier.
Only required parameter is mode, SPI.MASTER or SPI.SLAVE. Polarity can be
0 or 1, and is the level the idle clock line sits at. Phase can be 0 or 1
to sample data on the first or second clock edge respectively. Crc can be
None for no CRC, or a polynomial specifier.
Additional method for SPI::
.. only:: port_wipy
See usage model of I2C; SPI is very similar. Main difference is
parameters to init the SPI bus::
from pyb import SPI
spi = SPI(1, SPI.MASTER, baudrate=600000, polarity=1, phase=0)
Only required parameter is mode, must be SPI.MASTER. Polarity can be 0 or
1, and is the level the idle clock line sits at. Phase can be 0 or 1 to
sample data on the first or second clock edge respectively.
Additional methods for SPI::
data = spi.send_recv(b'1234') # send 4 bytes and receive 4 bytes
buf = bytearray(4)
@ -28,22 +42,33 @@ Additional method for SPI::
Constructors
------------
.. class:: pyb.SPI(bus, ...)
.. only:: port_pyboard
Construct an SPI object on the given bus. ``bus`` can be 1 or 2.
With no additional parameters, the SPI object is created but not
initialised (it has the settings from the last initialisation of
the bus, if any). If extra arguments are given, the bus is initialised.
See ``init`` for parameters of initialisation.
The physical pins of the SPI busses are:
- ``SPI(1)`` is on the X position: ``(NSS, SCK, MISO, MOSI) = (X5, X6, X7, X8) = (PA4, PA5, PA6, PA7)``
- ``SPI(2)`` is on the Y position: ``(NSS, SCK, MISO, MOSI) = (Y5, Y6, Y7, Y8) = (PB12, PB13, PB14, PB15)``
At the moment, the NSS pin is not used by the SPI driver and is free
for other use.
.. class:: pyb.SPI(bus, ...)
Construct an SPI object on the given bus. ``bus`` can be 1 or 2.
With no additional parameters, the SPI object is created but not
initialised (it has the settings from the last initialisation of
the bus, if any). If extra arguments are given, the bus is initialised.
See ``init`` for parameters of initialisation.
The physical pins of the SPI busses are:
- ``SPI(1)`` is on the X position: ``(NSS, SCK, MISO, MOSI) = (X5, X6, X7, X8) = (PA4, PA5, PA6, PA7)``
- ``SPI(2)`` is on the Y position: ``(NSS, SCK, MISO, MOSI) = (Y5, Y6, Y7, Y8) = (PB12, PB13, PB14, PB15)``
At the moment, the NSS pin is not used by the SPI driver and is free
for other use.
.. only:: port_wipy
.. class:: pyb.SPI(bus, ...)
Construct an SPI object on the given bus. ``bus`` can be only 1.
With no additional parameters, the SPI object is created but not
initialised (it has the settings from the last initialisation of
the bus, if any). If extra arguments are given, the bus is initialised.
See ``init`` for parameters of initialisation.
Methods
-------
@ -51,73 +76,147 @@ Methods
.. method:: spi.deinit()
Turn off the SPI bus.
.. method:: spi.init(mode, baudrate=328125, \*, prescaler, polarity=1, phase=0, bits=8, firstbit=SPI.MSB, ti=False, crc=None)
Initialise the SPI bus with the given parameters:
- ``mode`` must be either ``SPI.MASTER`` or ``SPI.SLAVE``.
- ``baudrate`` is the SCK clock rate (only sensible for a master).
- ``prescaler`` is the prescaler to use to derive SCK from the APB bus frequency;
use of ``prescaler`` overrides ``baudrate``.
- ``polarity`` can be 0 or 1, and is the level the idle clock line sits at.
- ``phase`` can be 0 or 1 to sample data on the first or second clock edge
respectively.
- ``firstbit`` can be ``SPI.MSB`` or ``SPI.LSB``.
- ``crc`` can be None for no CRC, or a polynomial specifier.
.. only:: port_pyboard
Note that the SPI clock frequency will not always be the requested baudrate.
The hardware only supports baudrates that are the APB bus frequency
(see :meth:`pyb.freq`) divided by a prescaler, which can be 2, 4, 8, 16, 32,
64, 128 or 256. SPI(1) is on AHB2, and SPI(2) is on AHB1. For precise
control over the SPI clock frequency, specify ``prescaler`` instead of
``baudrate``.
.. method:: spi.init(mode, baudrate=328125, \*, prescaler, polarity=1, phase=0, bits=8, firstbit=SPI.MSB, ti=False, crc=None)
Initialise the SPI bus with the given parameters:
- ``mode`` must be either ``SPI.MASTER`` or ``SPI.SLAVE``.
- ``baudrate`` is the SCK clock rate (only sensible for a master).
- ``prescaler`` is the prescaler to use to derive SCK from the APB bus frequency;
use of ``prescaler`` overrides ``baudrate``.
- ``polarity`` can be 0 or 1, and is the level the idle clock line sits at.
- ``phase`` can be 0 or 1 to sample data on the first or second clock edge
respectively.
- ``firstbit`` can be ``SPI.MSB`` or ``SPI.LSB``.
- ``crc`` can be None for no CRC, or a polynomial specifier.
Note that the SPI clock frequency will not always be the requested baudrate.
The hardware only supports baudrates that are the APB bus frequency
(see :meth:`pyb.freq`) divided by a prescaler, which can be 2, 4, 8, 16, 32,
64, 128 or 256. SPI(1) is on AHB2, and SPI(2) is on AHB1. For precise
control over the SPI clock frequency, specify ``prescaler`` instead of
``baudrate``.
Printing the SPI object will show you the computed baudrate and the chosen
prescaler.
Printing the SPI object will show you the computed baudrate and the chosen
prescaler.
.. only:: port_wipy
.. method:: spi.recv(recv, \*, timeout=5000)
.. method:: spi.init(mode, baudrate=328125, \*, polarity=1, phase=0, bits=8, nss=SPI.ACTIVE_LOW)
Initialise the SPI bus with the given parameters:
- ``mode`` must be ``SPI.MASTER``.
- ``baudrate`` is the SCK clock rate.
- ``polarity`` can be 0 or 1, and is the level the idle clock line sits at.
- ``phase`` can be 0 or 1 to sample data on the first or second clock edge
respectively.
- ``bits`` is the width of each transfer, accepted values are 8, 16 and 32.
- ``nss`` is the polarity of the slave select line. Can be ``SPI.ACTIVE_LOW``
or ``SPI.ACTIVE_HIGH``.
Note that the SPI clock frequency will not always be the requested baudrate.
Printing the SPI object will show you the computed baudrate and the chosen
prescaler.
Receive data on the bus:
- ``recv`` can be an integer, which is the number of bytes to receive,
or a mutable buffer, which will be filled with received bytes.
- ``timeout`` is the timeout in milliseconds to wait for the receive.
Return value: if ``recv`` is an integer then a new buffer of the bytes received,
otherwise the same buffer that was passed in to ``recv``.
.. only:: port_pyboard
.. method:: spi.send(send, \*, timeout=5000)
.. method:: spi.recv(recv, \*, timeout=5000)
Receive data on the bus:
- ``recv`` can be an integer, which is the number of bytes to receive,
or a mutable buffer, which will be filled with received bytes.
- ``timeout`` is the timeout in milliseconds to wait for the receive.
Return value: if ``recv`` is an integer then a new buffer of the bytes received,
otherwise the same buffer that was passed in to ``recv``.
Send data on the bus:
- ``send`` is the data to send (an integer to send, or a buffer object).
- ``timeout`` is the timeout in milliseconds to wait for the send.
Return value: ``None``.
.. only:: port_wipy
.. method:: spi.send_recv(send, recv=None, \*, timeout=5000)
.. method:: spi.recv(recv)
Receive data on the bus:
- ``recv`` can be an integer, which is the number of bytes to receive,
or a mutable buffer, which will be filled with received bytes.
Return value: if ``recv`` is an integer then a new buffer of the bytes received,
otherwise the same buffer that was passed in to ``recv``.
Send and receive data on the bus at the same time:
- ``send`` is the data to send (an integer to send, or a buffer object).
- ``recv`` is a mutable buffer which will be filled with received bytes.
It can be the same as ``send``, or omitted. If omitted, a new buffer will
be created.
- ``timeout`` is the timeout in milliseconds to wait for the receive.
Return value: the buffer with the received bytes.
.. only:: port_pyboard
.. method:: spi.send(send, \*, timeout=5000)
Send data on the bus:
- ``send`` is the data to send (an integer to send, or a buffer object).
- ``timeout`` is the timeout in milliseconds to wait for the send.
Return value: ``None``.
.. only:: port_wipy
.. method:: spi.send(send)
Send data on the bus:
- ``send`` is the data to send (an integer to send, or a buffer object).
Return value: ``None``.
.. only:: port_pyboard
.. method:: spi.send_recv(send, recv=None, \*, timeout=5000)
Send and receive data on the bus at the same time:
- ``send`` is the data to send (an integer to send, or a buffer object).
- ``recv`` is a mutable buffer which will be filled with received bytes.
It can be the same as ``send``, or omitted. If omitted, a new buffer will
be created.
- ``timeout`` is the timeout in milliseconds to wait for the receive.
Return value: the buffer with the received bytes.
.. only:: port_wipy
.. method:: spi.send_recv(send, recv=None)
Send and receive data on the bus at the same time:
- ``send`` is the data to send (an integer to send, or a buffer object).
- ``recv`` is a mutable buffer which will be filled with received bytes.
It can be the same as ``send``, or omitted. If omitted, a new buffer will
be created.
Return value: the buffer with the received bytes.
Constants
---------
.. data:: SPI.MASTER
.. data:: SPI.SLAVE
.. only:: port_pyboard
for initialising the SPI bus to master or slave mode
.. data:: SPI.MASTER
.. data:: SPI.SLAVE
for initialising the SPI bus to master or slave mode
.. data:: SPI.LSB
.. data:: SPI.MSB
set the first bit to be the least or most significant bit
.. data:: SPI.LSB
.. data:: SPI.MSB
.. only:: port_wipy
set the first bit to be the least or most significant bit
.. data:: SPI.MASTER
for initialising the SPI bus to master
.. data:: SPI.ACTIVE_LOW
.. data:: SPI.ACTIVE_HIGH
decides the polarity of the NSS pin

170
docs/library/pyb.UART.rst
View File

@ -15,10 +15,17 @@ UART objects can be created and initialised using::
uart = UART(1, 9600) # init with given baudrate
uart.init(9600, bits=8, parity=None, stop=1) # init with given parameters
Bits can be 7, 8 or 9. Parity can be None, 0 (even) or 1 (odd). Stop can be 1 or 2.
.. only:: port_pyboard
Bits can be 7, 8 or 9. Parity can be None, 0 (even) or 1 (odd). Stop can be 1 or 2.
*Note:* with parity=None, only 8 and 9 bits are supported. With parity enabled,
only 7 and 8 bits are supported.
.. only:: port_wipy
Bits can be 5, 6, 7, 8. Parity can be None, 0 (even) or 1 (odd). Stop can be 1 or 2.
*Note:* with parity=None, only 8 and 9 bits are supported. With parity enabled,
only 7 and 8 bits are supported.
A UART object acts like a stream object and reading and writing is done
using the standard stream methods::
@ -44,46 +51,77 @@ Earlier versions use ``uart.send`` and ``uart.recv``.
Constructors
------------
.. class:: pyb.UART(bus, ...)
.. only:: port_pyboard
Construct a UART object on the given bus. ``bus`` can be 1-6, or 'XA', 'XB', 'YA', or 'YB'.
With no additional parameters, the UART object is created but not
initialised (it has the settings from the last initialisation of
the bus, if any). If extra arguments are given, the bus is initialised.
See ``init`` for parameters of initialisation.
.. class:: pyb.UART(bus, ...)
Construct a UART object on the given bus. ``bus`` can be 1-6, or 'XA', 'XB', 'YA', or 'YB'.
With no additional parameters, the UART object is created but not
initialised (it has the settings from the last initialisation of
the bus, if any). If extra arguments are given, the bus is initialised.
See ``init`` for parameters of initialisation.
The physical pins of the UART busses are:
- ``UART(4)`` is on ``XA``: ``(TX, RX) = (X1, X2) = (PA0, PA1)``
- ``UART(1)`` is on ``XB``: ``(TX, RX) = (X9, X10) = (PB6, PB7)``
- ``UART(6)`` is on ``YA``: ``(TX, RX) = (Y1, Y2) = (PC6, PC7)``
- ``UART(3)`` is on ``YB``: ``(TX, RX) = (Y9, Y10) = (PB10, PB11)``
- ``UART(2)`` is on: ``(TX, RX) = (X3, X4) = (PA2, PA3)``
The physical pins of the UART busses are:
.. only:: port_wipy
- ``UART(4)`` is on ``XA``: ``(TX, RX) = (X1, X2) = (PA0, PA1)``
- ``UART(1)`` is on ``XB``: ``(TX, RX) = (X9, X10) = (PB6, PB7)``
- ``UART(6)`` is on ``YA``: ``(TX, RX) = (Y1, Y2) = (PC6, PC7)``
- ``UART(3)`` is on ``YB``: ``(TX, RX) = (Y9, Y10) = (PB10, PB11)``
- ``UART(2)`` is on: ``(TX, RX) = (X3, X4) = (PA2, PA3)``
.. class:: pyb.UART(bus, ...)
Construct a UART object on the given bus. ``bus`` can be 1 or 2.
With no additional parameters, the UART object is created but not
initialised (it has the settings from the last initialisation of
the bus, if any). If extra arguments are given, the bus is initialised.
See ``init`` for parameters of initialisation.
Methods
-------
.. method:: uart.init(baudrate, bits=8, parity=None, stop=1, \*, timeout=1000, timeout_char=0, read_buf_len=64)
.. only:: port_pyboard
Initialise the UART bus with the given parameters:
.. method:: uart.init(baudrate, bits=8, parity=None, stop=1, \*, timeout=1000, flow=None, timeout_char=0, read_buf_len=64)
Initialise the UART bus with the given parameters:
- ``baudrate`` is the clock rate.
- ``bits`` is the number of bits per character, 7, 8 or 9.
- ``parity`` is the parity, ``None``, 0 (even) or 1 (odd).
- ``stop`` is the number of stop bits, 1 or 2.
- ``flow`` sets the flow control type. Can be None, ``UART.RTS``, ``UART.CTS``
or ``UART.RTS | UART.CTS``.
- ``timeout`` is the timeout in milliseconds to wait for the first character.
- ``timeout_char`` is the timeout in milliseconds to wait between characters.
- ``read_buf_len`` is the character length of the read buffer (0 to disable).
This method will raise an exception if the baudrate could not be set within
5% of the desired value. The minimum baudrate is dictated by the frequency
of the bus that the UART is on; UART(1) and UART(6) are APB2, the rest are on
APB1. The default bus frequencies give a minimum baudrate of 1300 for
UART(1) and UART(6) and 650 for the others. Use :func:`pyb.freq <pyb.freq>`
to reduce the bus frequencies to get lower baudrates.
*Note:* with parity=None, only 8 and 9 bits are supported. With parity enabled,
only 7 and 8 bits are supported.
- ``baudrate`` is the clock rate.
- ``bits`` is the number of bits per character, 7, 8 or 9.
- ``parity`` is the parity, ``None``, 0 (even) or 1 (odd).
- ``stop`` is the number of stop bits, 1 or 2.
- ``timeout`` is the timeout in milliseconds to wait for the first character.
- ``timeout_char`` is the timeout in milliseconds to wait between characters.
- ``read_buf_len`` is the character length of the read buffer (0 to disable).
.. only:: port_wipy
This method will raise an exception if the baudrate could not be set within
5% of the desired value. The minimum baudrate is dictated by the frequency
of the bus that the UART is on; UART(1) and UART(6) are APB2, the rest are on
APB1. The default bus frequencies give a minimum baudrate of 1300 for
UART(1) and UART(6) and 650 for the others. Use :func:`pyb.freq <pyb.freq>`
to reduce the bus frequencies to get lower baudrates.
*Note:* with parity=None, only 8 and 9 bits are supported. With parity enabled,
only 7 and 8 bits are supported.
.. method:: uart.init(baudrate, bits=8, parity=None, stop=1, \*, timeout=1000, flow=None, timeout_char=0)
Initialise the UART bus with the given parameters:
- ``baudrate`` is the clock rate.
- ``bits`` is the number of bits per character, 7, 8 or 9.
- ``parity`` is the parity, ``None``, 0 (even) or 1 (odd).
- ``stop`` is the number of stop bits, 1 or 2.
- ``flow`` sets the flow control type. Can be None, ``UART.RTS``, ``UART.CTS``
or ``UART.RTS | UART.CTS``.
- ``timeout`` is the timeout in milliseconds to wait for the first character.
- ``timeout_char`` is the timeout in milliseconds to wait between characters.
.. method:: uart.deinit()
@ -97,11 +135,18 @@ Methods
Read characters. If ``nbytes`` is specified then read at most that many bytes.
*Note:* for 9 bit characters each character takes two bytes, ``nbytes`` must
be even, and the number of characters is ``nbytes/2``.
.. only:: port_pyboard
Return value: a bytes object containing the bytes read in. Returns ``b''``
on timeout.
*Note:* for 9 bit characters each character takes two bytes, ``nbytes`` must
be even, and the number of characters is ``nbytes/2``.
Return value: a bytes object containing the bytes read in. Returns ``b''``
on timeout.
.. only:: port_wipy
Return value: a bytes object containing the bytes read in. Returns ``b''``
on timeout.
.. method:: uart.readall()
@ -130,12 +175,20 @@ Methods
.. method:: uart.write(buf)
Write the buffer of bytes to the bus. If characters are 7 or 8 bits wide
then each byte is one character. If characters are 9 bits wide then two
bytes are used for each character (little endian), and ``buf`` must contain
an even number of bytes.
.. only:: port_pyboard
Return value: number of bytes written.
Write the buffer of bytes to the bus. If characters are 7 or 8 bits wide
then each byte is one character. If characters are 9 bits wide then two
bytes are used for each character (little endian), and ``buf`` must contain
an even number of bytes.
Return value: number of bytes written.
.. only:: port_wipy
Write the buffer of bytes to the bus.
Return value: number of bytes written.
.. method:: uart.writechar(char)
@ -147,3 +200,36 @@ Methods
Send a break condition on the bus. This drives the bus low for a duration
of 13 bits.
Return value: ``None``.
.. only:: port_wipy
.. method:: uart.callback(value, priority=1, handler=None)
Create a callback to be triggered when data is received on the UART.
- ``value`` sets the size in bytes of the Rx buffer. Every character
received is put into this buffer as long as there's space free.
- ``priority`` level of the interrupt. Can take values in the range 1-7.
Higher values represent higher priorities.
- ``handler`` an optional function to be called when new characters arrive.
.. note::
The handler will be called whenever any of the following two conditions are met:
- 4 new characters have been received.
- At least 1 new character is waiting in the Rx buffer and the Rx line has been
silent for the duration of 1 complete frame.
This means that when the handler function is called there might be 1, 2, 3 or 4
characters waiting.
Return a callback object.
Constants
---------
.. data:: UART.RTS
.. data:: UART.CTS
to select the flow control type

33
docs/library/pyb.WDT.rst Normal file
View File

@ -0,0 +1,33 @@
.. _pyb.WDT:
class WDT -- watchdog timer
===========================
The WDT is used to restart the system when the application crashes and ends
up into a non recoverable state. Once started it cannot be stopped or
reconfigured in any way. After enabling, the application must "kick" the
watchdog periodically to prevent it from expiring and resetting the system.
Example usage::
wdt = pyb.WDT(5000) # enable with a timeout of 5s
wdt.kick()
Constructors
------------
.. class:: pyb.WDT([timeout])
Create a WDT object. If the timeout is specified the WDT is started.
The timeout must be given in seconds and 1s the minimum value that
is accepted. Once it is running the timeout cannot be changed and
the WDT cannot be stopped either.
Methods
-------
.. method:: wdt.kick()
Kick the WDT to prevent it from resetting the system. The application
should place this call in a sensible place ensuring that the WDT is
only kicked after verifying that everything is functioning correctly.

335
docs/library/pyb.rst
View File

@ -1,10 +1,10 @@
:mod:`pyb` --- functions related to the pyboard
===============================================
:mod:`pyb` --- functions related to the board
=============================================
.. module:: pyb
:synopsis: functions related to the pyboard
:synopsis: functions related to the board
The ``pyb`` module contains specific functions related to the pyboard.
The ``pyb`` module contains specific functions related to the board.
Time related functions
----------------------
@ -63,14 +63,25 @@ Time related functions
Reset related functions
-----------------------
.. function:: hard_reset()
.. only:: port_pyboard
Resets the pyboard in a manner similar to pushing the external RESET
button.
.. function:: hard_reset()
Resets the pyboard in a manner similar to pushing the external RESET
button.
.. function:: bootloader()
.. only:: port_wipy
Activate the bootloader without BOOT\* pins.
.. function:: reset()
Resets the WiPy in a manner similar to pushing the external RESET
button.
.. only:: port_pyboard
.. function:: bootloader()
Activate the bootloader without BOOT\* pins.
Interrupt related functions
---------------------------
@ -93,93 +104,106 @@ Interrupt related functions
Power related functions
-----------------------
.. function:: freq([sysclk[, hclk[, pclk1[, pclk2]]]])
.. only:: port_pyboard
If given no arguments, returns a tuple of clock frequencies:
(sysclk, hclk, pclk1, pclk2).
These correspond to:
.. function:: freq([sysclk[, hclk[, pclk1[, pclk2]]]])
If given no arguments, returns a tuple of clock frequencies:
(sysclk, hclk, pclk1, pclk2).
These correspond to:
- sysclk: frequency of the CPU
- hclk: frequency of the AHB bus, core memory and DMA
- pclk1: frequency of the APB1 bus
- pclk2: frequency of the APB2 bus
If given any arguments then the function sets the frequency of the CPU,
and the busses if additional arguments are given. Frequencies are given in
Hz. Eg freq(120000000) sets sysclk (the CPU frequency) to 120MHz. Note that
not all values are supported and the largest supported frequency not greater
than the given value will be selected.
Supported sysclk frequencies are (in MHz): 8, 16, 24, 30, 32, 36, 40, 42, 48,
54, 56, 60, 64, 72, 84, 96, 108, 120, 144, 168.
The maximum frequency of hclk is 168MHz, of pclk1 is 42MHz, and of pclk2 is
84MHz. Be sure not to set frequencies above these values.
The hclk, pclk1 and pclk2 frequencies are derived from the sysclk frequency
using a prescaler (divider). Supported prescalers for hclk are: 1, 2, 4, 8,
16, 64, 128, 256, 512. Supported prescalers for pclk1 and pclk2 are: 1, 2,
4, 8. A prescaler will be chosen to best match the requested frequency.
A sysclk frequency of
8MHz uses the HSE (external crystal) directly and 16MHz uses the HSI
(internal oscillator) directly. The higher frequencies use the HSE to
drive the PLL (phase locked loop), and then use the output of the PLL.
Note that if you change the frequency while the USB is enabled then
the USB may become unreliable. It is best to change the frequency
in boot.py, before the USB peripheral is started. Also note that sysclk
frequencies below 36MHz do not allow the USB to function correctly.
.. function:: wfi()
Wait for an internal or external interrupt.
This executes a ``wfi`` instruction which reduces power consumption
of the MCU until any interrupt occurs (be it internal or external),
at which point execution continues. Note that the system-tick interrupt
occurs once every millisecond (1000Hz) so this function will block for
at most 1ms.
.. function:: stop()
Put the pyboard in a "sleeping" state.
This reduces power consumption to less than 500 uA. To wake from this
sleep state requires an external interrupt or a real-time-clock event.
Upon waking execution continues where it left off.
See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event.
.. function:: standby()
Put the pyboard into a "deep sleep" state.
This reduces power consumption to less than 50 uA. To wake from this
sleep state requires an external interrupt or a real-time-clock event.
Upon waking the system undergoes a hard reset.
See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event.
- sysclk: frequency of the CPU
- hclk: frequency of the AHB bus, core memory and DMA
- pclk1: frequency of the APB1 bus
- pclk2: frequency of the APB2 bus
.. only:: port_wipy
If given any arguments then the function sets the frequency of the CPU,
and the busses if additional arguments are given. Frequencies are given in
Hz. Eg freq(120000000) sets sysclk (the CPU frequency) to 120MHz. Note that
not all values are supported and the largest supported frequency not greater
than the given value will be selected.
.. function:: freq([sysclk])
Supported sysclk frequencies are (in MHz): 8, 16, 24, 30, 32, 36, 40, 42, 48,
54, 56, 60, 64, 72, 84, 96, 108, 120, 144, 168.
Returns a tuple of clock frequencies: ``(sysclk)``
These correspond to:
The maximum frequency of hclk is 168MHz, of pclk1 is 42MHz, and of pclk2 is
84MHz. Be sure not to set frequencies above these values.
The hclk, pclk1 and pclk2 frequencies are derived from the sysclk frequency
using a prescaler (divider). Supported prescalers for hclk are: 1, 2, 4, 8,
16, 64, 128, 256, 512. Supported prescalers for pclk1 and pclk2 are: 1, 2,
4, 8. A prescaler will be chosen to best match the requested frequency.
A sysclk frequency of
8MHz uses the HSE (external crystal) directly and 16MHz uses the HSI
(internal oscillator) directly. The higher frequencies use the HSE to
drive the PLL (phase locked loop), and then use the output of the PLL.
Note that if you change the frequency while the USB is enabled then
the USB may become unreliable. It is best to change the frequency
in boot.py, before the USB peripheral is started. Also note that sysclk
frequencies below 36MHz do not allow the USB to function correctly.
.. function:: wfi()
Wait for an internal or external interrupt.
This executes a ``wfi`` instruction which reduces power consumption
of the MCU until any interrupt occurs (be it internal or external),
at which point execution continues. Note that the system-tick interrupt
occurs once every millisecond (1000Hz) so this function will block for
at most 1ms.
.. function:: stop()
Put the pyboard in a "sleeping" state.
This reduces power consumption to less than 500 uA. To wake from this
sleep state requires an external interrupt or a real-time-clock event.
Upon waking execution continues where it left off.
See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event.
.. function:: standby()
Put the pyboard into a "deep sleep" state.
This reduces power consumption to less than 50 uA. To wake from this
sleep state requires an external interrupt or a real-time-clock event.
Upon waking the system undergoes a hard reset.
See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event.
- sysclk: frequency of the CPU
Miscellaneous functions
-----------------------
.. function:: have_cdc()
.. only:: port_pyboard
Return True if USB is connected as a serial device, False otherwise.
.. note:: This function is deprecated. Use pyb.USB_VCP().isconnected() instead.
.. function:: hid((buttons, x, y, z))
Takes a 4-tuple (or list) and sends it to the USB host (the PC) to
signal a HID mouse-motion event.
.. note:: This function is deprecated. Use pyb.USB_HID().send(...) instead.
.. function:: info([dump_alloc_table])
Print out lots of information about the board.
.. function:: have_cdc()
Return True if USB is connected as a serial device, False otherwise.
.. note:: This function is deprecated. Use pyb.USB_VCP().isconnected() instead.
.. function:: hid((buttons, x, y, z))
Takes a 4-tuple (or list) and sends it to the USB host (the PC) to
signal a HID mouse-motion event.
.. note:: This function is deprecated. Use pyb.USB_HID().send(...) instead.
.. function:: info([dump_alloc_table])
Print out lots of information about the board.
.. function:: main(filename)
@ -188,72 +212,109 @@ Miscellaneous functions
It only makes sense to call this function from within boot.py.
.. function:: mount(device, mountpoint, \*, readonly=False, mkfs=False)
.. only:: port_pyboard
Mount a block device and make it available as part of the filesystem.
``device`` must be an object that provides the block protocol:
- ``readblocks(self, blocknum, buf)``
- ``writeblocks(self, blocknum, buf)`` (optional)
- ``count(self)``
- ``sync(self)`` (optional)
``readblocks`` and ``writeblocks`` should copy data between ``buf`` and
the block device, starting from block number ``blocknum`` on the device.
``buf`` will be a bytearray with length a multiple of 512. If
``writeblocks`` is not defined then the device is mounted read-only.
The return value of these two functions is ignored.
``count`` should return the number of blocks available on the device.
``sync``, if implemented, should sync the data on the device.
The parameter ``mountpoint`` is the location in the root of the filesystem
to mount the device. It must begin with a forward-slash.
If ``readonly`` is ``True``, then the device is mounted read-only,
otherwise it is mounted read-write.
If ``mkfs`` is ``True``, then a new filesystem is created if one does not
already exist.
To unmount a device, pass ``None`` as the device and the mount location
as ``mountpoint``.
.. function:: mount(device, mountpoint, \*, readonly=False, mkfs=False)
Mount a block device and make it available as part of the filesystem.
``device`` must be an object that provides the block protocol:
- ``readblocks(self, blocknum, buf)``
- ``writeblocks(self, blocknum, buf)`` (optional)
- ``count(self)``
- ``sync(self)`` (optional)
``readblocks`` and ``writeblocks`` should copy data between ``buf`` and
the block device, starting from block number ``blocknum`` on the device.
``buf`` will be a bytearray with length a multiple of 512. If
``writeblocks`` is not defined then the device is mounted read-only.
The return value of these two functions is ignored.
``count`` should return the number of blocks available on the device.
``sync``, if implemented, should sync the data on the device.
The parameter ``mountpoint`` is the location in the root of the filesystem
to mount the device. It must begin with a forward-slash.
If ``readonly`` is ``True``, then the device is mounted read-only,
otherwise it is mounted read-write.
If ``mkfs`` is ``True``, then a new filesystem is created if one does not
already exist.
To unmount a device, pass ``None`` as the device and the mount location
as ``mountpoint``.
.. function:: repl_uart(uart)
Get or set the UART object that the REPL is repeated on.
.. function:: rng()
.. only:: port_pyboard
Return a 30-bit hardware generated random number.
.. function:: rng()
Return a 30-bit hardware generated random number.
.. only:: port_wipy
.. function:: rng()
Return a 24-bit software generated random number.
.. function:: sync()
Sync all file systems.
.. function:: unique_id()
.. only:: port_pyboard
Returns a string of 12 bytes (96 bits), which is the unique ID for the MCU.
.. function:: unique_id()
Returns a string of 12 bytes (96 bits), which is the unique ID for the MCU.
.. only:: port_wipy
.. function:: unique_id()
Returns a string of 6 bytes (48 bits), which is the unique ID for the MCU.
This also corresponds to the ``MAC address`` of the WiPy.
Classes
-------
.. toctree::
:maxdepth: 1
.. only:: port_pyboard
pyb.Accel.rst
pyb.ADC.rst
pyb.CAN.rst
pyb.DAC.rst
pyb.ExtInt.rst
pyb.I2C.rst
pyb.LCD.rst
pyb.LED.rst
pyb.Pin.rst
pyb.RTC.rst
pyb.Servo.rst
pyb.SPI.rst
pyb.Switch.rst
pyb.Timer.rst
pyb.UART.rst
pyb.USB_VCP.rst
.. toctree::
:maxdepth: 1
pyb.Accel.rst
pyb.ADC.rst
pyb.CAN.rst
pyb.DAC.rst
pyb.ExtInt.rst
pyb.I2C.rst
pyb.LCD.rst
pyb.LED.rst
pyb.Pin.rst
pyb.RTC.rst
pyb.Servo.rst
pyb.SPI.rst
pyb.Switch.rst
pyb.Timer.rst
pyb.UART.rst
pyb.USB_VCP.rst
.. only:: port_wipy
.. toctree::
:maxdepth: 1
pyb.ADC.rst
pyb.HeartBeat.rst
pyb.I2C.rst
pyb.Pin.rst
pyb.RTC.rst
pyb.SD.rst
pyb.SPI.rst
pyb.Timer.rst
pyb.UART.rst
pyb.WDT.rst

20
docs/library/time.rst
View File

@ -31,10 +31,24 @@ Functions
which expresses a time as per localtime. It returns an integer which is
the number of seconds since Jan 1, 2000.
.. function:: sleep(seconds)
.. only:: port_pyboard
Sleep for the given number of seconds. Seconds can be a floating-point number to
sleep for a fractional number of seconds.
.. function:: sleep(seconds)
Sleep for the given number of seconds. Seconds can be a floating-point number to
sleep for a fractional number of seconds.
.. only:: port_esp8266
.. function:: sleep(seconds)
Sleep for the given number of seconds.
.. only:: port_wipy
.. function:: sleep(milliseconds)
Sleep for the given number of milliseconds.
.. function:: time()

2
docs/library/uctypes.rst
View File

@ -141,7 +141,7 @@ Module contents
at the given memory address.
Structure descriptors and instantiating structure objects
-----------------------------------------------------
---------------------------------------------------------
Given a structure descriptor dictionary and its layout type, you can
instantiate a specific structure instance at a given memory address

70
docs/library/uhashlib.rst
View File

@ -4,34 +4,78 @@
.. module:: uhashlib
:synopsis: hashing algorithm
This module implements binary data hashing algorithms. Currently, it
implements SHA256 algorithm. Choosing SHA256 was a deliberate choice,
as a modern, cryptographically secure algorithm. This means that a
single algorithm can cover both usecases of "any hash algorithm" and
security-related usage, and thus save space omitting legacy algorithms
like MD5 or SHA1.
.. only:: port_pyboard
This module implements binary data hashing algorithms. Currently, it
implements SHA256 algorithm. Choosing SHA256 was a deliberate choice,
as a modern, cryptographically secure algorithm. This means that a
single algorithm can cover both usecases of "any hash algorithm" and
security-related usage, and thus save space omitting legacy algorithms
like MD5 or SHA1.
.. only:: port_wipy
This module implements binary data hashing algorithms. Currently, it
implements SHA1 and SHA256 algorithms only. These two algorithms are
more than enough for today's web applications.
Constructors
------------
.. class:: uhashlib.sha256([data])
.. only:: port_pyboard
Create a hasher object and optionally feed ``data`` into it.
.. class:: uhashlib.sha256([data])
Create a hasher object and optionally feed ``data`` into it.
.. only:: port_wipy
.. class:: uhashlib.sha1([data[, block_size]])
Create a sha1 hasher object and optionally feed ``data`` or ``data and block_size`` into it.
.. class:: uhashlib.sha256([data[, block_size]])
Create a sha256 hasher object and optionally feed ``data`` or ``data and block_size`` into it.
.. admonition:: CPython extension
:class: attention
Due to hardware implementation details of the WiPy, data must be buffered before being
digested, which would make impossible to calculate the hash of big blocks of data that
do not fit in RAM. In this case, since most likely the total size of the data is known
in advance, the size can be passed to the constructor and hence the HASH hardware engine
of the WiPy can be properly initialized without needing buffering. If ``block_size`` is
to be given, an initial chunk of ``data`` must be passed as well. **When using this extension,
care must be taken to make sure that the length of all intermediate chunks (including the
initial one) is a multiple of 4 bytes.** The last chunk may be of any length.
Example::
hash = uhashlib.sha1('abcd1234', 1001) # lenght of the initial piece is multiple of 4 bytes
hash.update('1234') # also multiple of 4 bytes
...
hash.update('12345') # last chunk may be of any length
hash.digest()
Methods
-------
.. method:: sha256.update(data)
.. method:: hash.update(data)
Feed more binary data into hash.
.. method:: sha256.digest()
.. method:: hash.digest()
Return hash for all data passed thru hash, as a bytes object. After this
method is called, more data cannot be fed into hash any longer.
.. method:: sha256.hexdigest()
.. only:: port_wipy
SHA1 hashes are 20-byte long. SHA256 hashes are 32-byte long.
This method is NOT implemented. Use ``ubinascii.hexlify(sha256.digest())``
to achieve similar effect.
.. method:: hash.hexdigest()
This method is NOT implemented. Use ``ubinascii.hexlify(hash.digest())``
to achieve a similar effect.

4
docs/pyboard/quickref.rst
View File

@ -1,4 +1,6 @@
.. _quickref:
.. only:: port_pyboard
.. _quickref:
Quick reference for the pyboard
===============================

4
docs/pyboard/tutorial/amp_skin.rst
View File

@ -53,8 +53,8 @@ For example::
dac.write_timed(buf, 400 * len(buf), mode=DAC.CIRCULAR)
You can also play WAV files using the Python ``wave`` module. You can get
the wave module `here <http://micropython.org/resources/examples/wave.py>`_ and you will also need
the chunk module available `here <http://micropython.org/resources/examples/chunk.py>`_. Put these
the wave module `here <http://micropython.org/resources/examples/wave.py>`__ and you will also need
the chunk module available `here <http://micropython.org/resources/examples/chunk.py>`__. Put these
on your pyboard (either on the flash or the SD card in the top-level directory). You will need an
8-bit WAV file to play, such as `this one <http://micropython.org/resources/examples/test.wav>`_,
or to convert any file you have with the command::

4
docs/pyboard/tutorial/lcd_skin.rst
View File

@ -60,7 +60,7 @@ enables the 4 touch sensors. The third line reads the touch
status and the ``touch`` variable holds the state of the 4 touch
buttons (A, B, X, Y).
There is a simple driver `here <http://micropython.org/resources/examples/mpr121.py>`_
There is a simple driver `here <http://micropython.org/resources/examples/mpr121.py>`__
which allows you to set the threshold and debounce parameters, and
easily read the touch status and electrode voltage levels. Copy
this script to your pyboard (either flash or SD card, in the top
@ -83,4 +83,4 @@ initialise the I2C bus using::
>>> m = mpr121.MPR121(pyb.I2C(2, pyb.I2C.MASTER))
There is also a demo which uses the LCD and the touch sensors together,
and can be found `here <http://micropython.org/resources/examples/lcddemo.py>`_.
and can be found `here <http://micropython.org/resources/examples/lcddemo.py>`__.

12
docs/pyboard_contents.rst Normal file
View File

@ -0,0 +1,12 @@
MicroPython documentation contents
==================================
.. toctree::
pyboard/quickref.rst
pyboard/general.rst
pyboard/tutorial/index.rst
library/index.rst
pyboard/hardware/index.rst
license.rst

19
docs/pyboard_index.rst Normal file
View File

@ -0,0 +1,19 @@
MicroPython documentation and references
========================================
.. toctree::
pyboard/quickref.rst
pyboard/general.rst
pyboard/tutorial/index.rst
library/index.rst
pyboard/hardware/index.rst
license.rst
pyboard_contents.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

14
docs/topindex.html
View File

@ -21,11 +21,11 @@
{% endfor %}.
</p-->
<p><strong>Documentation for MicroPython and the pyboard:</strong></p>
<p><strong>Documentation for MicroPython and {{ port_name }}:</strong></p>
<table class="contentstable"><tr>
<td width="40%" style="padding-left:2em;">
{% if port == "pyboard" %}
{% if port == "pyboard" or port == "wipy" %}
<p class="biglink">
<a class="biglink" href="{{ pathto(port + "/quickref") }}">Quick reference for {{ port_name }}</a><br/>
<span class="linkdescr">pinout for {{ port_name }} and snippets of useful code</span>
@ -34,6 +34,8 @@
<a class="biglink" href="{{ pathto(port + "/general") }}">General information about {{ port_name }}</a><br/>
<span class="linkdescr">read this first for a quick overview</span>
</p>
{% endif %}
{% if port == "pyboard" %}
<p class="biglink">
<a class="biglink" href="{{ pathto(port + "/tutorial/index") }}">Tutorials and code examples</a><br/>
<span class="linkdescr">start here</span>
@ -76,7 +78,7 @@
</td>
<td width="40%" style="padding-left:2em;">
<p class="biglink">
<a class="biglink" href="{{ pathto("contents") }}">Table of contents</a><br/>
<a class="biglink" href="{{ pathto(port + "_contents") }}">Table of contents</a><br/>
<span class="linkdescr">a list of all sections and subsections</span>
</p>
</td></tr>
@ -100,6 +102,12 @@
<a class="biglink" href="https://github.com/micropython">MicroPython on GitHub</a><br/>
<span class="linkdescr">contribute to the source code on GitHub</span>
</p>
{% if port == "wipy" %}
<p class="biglink">
<a class="biglink" href="http://wipy.io">The WiPy homepage</a><br/>
<span class="linkdescr">the official WiPy site</span>
</p>
{% endif %}
</td>
</tr></table>

59
docs/wipy/general.rst Normal file
View File

@ -0,0 +1,59 @@
General information about the WiPy
==================================
WLAN default behaviour
----------------------
When the WiPy boots with the default factory configuration starts in Access Point
mode with ``ssid: wipy-wlan`` and ``key: www.wipy.io``.
Connect to this network and the WiPy will be reachable at ``192.168.1.1``. In order
to gain access to the interactive prompt, open a telnet session to that IP address on
the default port (23). You will be asked for credentials:
``login: micro`` ``password: python``
Local file system and SD card
-----------------------------
There is a small internal file system (a drive) on the WiPy, called ``/flash``,
which is stored within the external serial flash memory. If a micro SD card
is hooked-up and enabled, it is available as ``/sd``.
When the WiPy boots up, it always boots from the ``boot.py`` located in the
``/flash`` file system. If during the boot process the SD card is enabled and
it's selected as the current drive then the WiPy will try to execute ``main.py``
that should be located in the SD card.
The file system is accessible via the native FTP server running in the WiPy.
Open your FTP client of choice and connect to:
``ftp://192.168.1.1`` ``user: micro`` ``password: python``
Boot modes
----------
If you power up normally, or press the reset button, the WiPy will boot
into standard mode: the ``boot.py`` file will be executed first, then
``main.py`` will run.
You can override this boot sequence by pulling ``GPIO28`` **up** during reset.
The heart beat LED will flash slowly 3 times to signal that safe boot is being
requested, and then 3 more times quickly to let you know that safe boot is
going to be performed. While safe booting, the WiPy runs the factory firmware
and skips the execution of ``boot.py`` and ``main.py``. This is useful to
recover from any crash situation.
The heart beat LED
------------------
By default the heart beat LED flashes once every 5s to signal that the system is
alive. This can be overridden through the HeartBeat class:
``pyb.HeartBeat().disable()``
There are currently 2 kinds of errors that you might see:
1. If the heart beat LED flashes quickly, then a Python script(eg ``main.py``)
has an error. Use the REPL to debug it.
2. If the heart beat LED stays on, then there was a hard fault, you cannot
recover from this, the only way out is by pressing the reset switch.

228
docs/wipy/quickref.rst Normal file
View File

@ -0,0 +1,228 @@
.. only:: port_wipy
.. _quickref_:
Quick reference for the WiPy
============================
.. image:: https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png
:alt: WiPy pinout and alternate functions table
:width: 800px
General board control
---------------------
See :mod:`pyb`. ::
import pyb
help(pyb) # display all members from the pyb module
pyb.delay(50) # wait 50 milliseconds
pyb.millis() # number of milliseconds since boot-up
pyb.freq() # get the CPU frequency
pyb.unique_id() # return the 6-byte unique id of the board (it's MAC address)
Pins and GPIO
-------------
See :ref:`pyb.Pin <pyb.Pin>`. ::
from pyb import Pin
# initialize GPIO2 in gpio mode (af=0) and make it an output
p_out = Pin('GPIO2', af=0, mode=Pin.OUT)
p_out.high()
p_out.low()
p_out.toggle()
# make GPIO1 an input with the pull-up enabled
p_in = Pin('GPIO1', af = 0, mode=Pin.IN, type = Pin.STD_PU)
p_in.value() # get value, 0 or 1
Timers
------
See :ref:`pyb.Timer <pyb.Timer>` and :ref:`pyb.Pin <pyb.Pin>`. ::
from pyb import Timer
from pyb import Pin
tim = Timer(1, mode=Timer.PERIODIC)
tim_a = tim.channel(Timer.A, freq=1000)
tim_a.time() # get the value in microseconds
tim_a.freq(1) # 1 Hz
p_out = Pin('GPIO2', af=0, mode=Pin.OUT)
tim_a.callback(handler=lambda t: p_out.toggle())
PWM (pulse width modulation)
----------------------------
See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.Timer <pyb.Timer>`. ::
from pyb import Timer
from pyb import Pin
# assign GPIO25 to alternate function 5 (PWM)
p_out = Pin('GPIO25', af=9, type=Pin.STD)
# timer 2 in PWM mode and width must be 16 buts
tim = Timer(2, mode=Timer.PWM, width=16)
# enable channel A @1KHz with a 50% duty cycle
tim_a = tim.channel(Timer.A, freq=1000, duty_cycle=50)
ADC (analog to digital conversion)
----------------------------------
See :ref:`pyb.ADC <pyb.ADC>`. ::
from pyb import ADC
adc = ADC(1)
adc.read() # read value, 0-4095
UART (serial bus)
-----------------
See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.UART <pyb.UART>`. ::
from pyb import Pin, UART
# first assign TX and RX to the correct pins
Pin('GPIO1', af=3, mode=Pin.STD_PU) # TX
Pin('GPIO2', af=3, mode=Pin.STD_PU) # RX
uart = UART(1, 9600)
uart.write('hello')
uart.read(5) # read up to 5 bytes
SPI bus
-------
See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.SPI <pyb.SPI>`. ::
from pyb import Pin, SPI
# first assign CLK, MISO, MOSI, CS to the correct pins
Pin('GPIO14', af=7, mode=Pin.STD) # CLK
Pin('GPIO15', af=7, mode=Pin.STD) # MISO
Pin('GPIO16', af=7, mode=Pin.STD) # MOSI
Pin('GPIO17', af=7, mode=Pin.STD) # NSS/CS
# configure the SPI master @ 2MHz
spi = SPI(1, SPI.MASTER, baudrate=200000, polarity=0, phase=0)
spi.send('hello')
spi.recv(5) # receive 5 bytes on the bus
spi.send_recv('hello') # send a receive 5 bytes
I2C bus
-------
See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.I2C <pyb.I2C>`. ::
from pyb import Pin, I2C
# first assign SCL and SDA to the correct pins
Pin('GPIO23', af=9, mode=Pin.STD_PU) # SCL
Pin('GPIO24', af=9, mode=Pin.STD_PU) # SDA
# configure the I2C bus
i2c = I2C(1, I2C.MASTER, baudrate=100000)
i2c.scan() # returns list of slave addresses
i2c.send('hello', 0x42) # send 5 bytes to slave with address 0x42
i2c.recv(5, 0x42) # receive 5 bytes from slave
i2c.mem_read(2, 0x42, 0x10) # read 2 bytes from slave 0x42, slave memory 0x10
i2c.mem_write('xy', 0x42, 0x10) # write 2 bytes to slave 0x42, slave memory 0x10
Watchdog timer (WDT)
--------------------
See :ref:`pyb.WDT <pyb.WDT>`. ::
from pyb import WDT
# enable the WDT with a timeout of 5s (1s is the minimum)
wdt = WDT(5000)
wdt.kick()
Real time clock (RTC)
---------------------
See :ref:`pyb.RTC <pyb.RTC>` and ``pyb.Sleep``. ::
from pyb import RTC, Sleep
rtc = pyb.RTC()
rtc.datetime((2014, 5, 1, 4, 13, 0, 0, 0))
print(rtc.datetime())
def some_handler (rtc_obj):
# trigger the callback again in 30s
rtc_obj.callback(value=30000, handler=some_handler)
# create a RTC alarm that expires in 30s
rtc.callback(value=30000, handler=some_handler, wakes=Sleep.SUSPENDED)
# go into suspended mode waiting for the RTC alarm to expire and wake us up
Sleep.suspend()
SD card
-------
See :ref:`pyb.SD <pyb.SD>`. ::
from pyb import SD
# SD card pins need special configuration so we pass 'em to the constructor
# data pin, data af, clock pin, clock af, cmd pin, cmd af
sd = SD('GPIO15', 8, 'GPIO16', 8, 'GPIO17', 8)
sd.enable()
WLAN (WiFi)
-----------
See :ref:`network.WLAN <network.WLAN>` and ``pyb.Sleep``. ::
from network import WLAN
from pyb import Sleep
# configure the WLAN subsystem in station mode (the default is AP)
wifi = WLAN(WLAN.STA)
# go for fixed IP settings
wifi.ifconfig('192.168.0.107', '255.255.255.0', '192.168.0.1', '8.8.8.8')
wifi.scan() # scan for available netrworks
wifi.connect(ssid='mynetwork', security=2, key='mynetworkkey')
while not wifi.isconnected():
pass
print(wifi.ifconfig())
# enable wake on WLAN
wifi.callback(wakes=Sleep.SUSPENDED)
# go to sleep
Sleep.suspend()
# now, connect to the FTP or the Telnet server and the WiPy will wake-up
Sleep and power modes control
-----------------------------
See ``pyb.Sleep``. ::
from pyb import Sleep
Sleep.idle() # lowest sleep mode (~12mA), any interrupts wakes it up
Sleep.suspend() # everything except for WLAN is powered down (~950uA)
# wakes from Pin, RTC or WLAN
Sleep.hibernate() # deepest sleep mode, mcu starts from reset. Wakes from Pin and RTC.
Heart beat LED
-----------------------------
See :ref:`pyb.HeartBeat <pyb.HeartBeat>`. ::
from pyb import HeartBeat
# disable the heart beat indication (you are free to use this led connected to GPIO25)
HeartBeat.disable()
# enable the heart beat again
HeartBeat.enable()

9
docs/wipy_contents.rst Normal file
View File

@ -0,0 +1,9 @@
MicroPython documentation contents
==================================
.. toctree::
wipy/quickref.rst
wipy/general.rst
library/index.rst
license.rst

17
docs/wipy_index.rst Normal file
View File

@ -0,0 +1,17 @@
MicroPython documentation and references
========================================
.. toctree::
wipy/quickref.rst
wipy/general.rst
library/index.rst
license.rst
wipy_contents.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`