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

docs/library: Remove "only" directive from all pyb module docs.

Browse Source 
By virtue of its name, the pyb module would only be available on a pyboard
and so does not need to have conditional "only" directives throughout its
documentation.

These conditionals were added mostly in
cfcf47c0644952358e1a260db159e807872a37e6 in the initial development of the
cc3200 port, which had the pyb module before it switched to the machine
module.  And wipy only conditionals were removed from the pyb module
documentation in 4542643025c77a7272bde348b89d5039aea28d23, so there's no
need to retain any more conditionals.
This commit is contained in:
Damien George 2018-07-18 15:47:44 +10:00
parent 419eb86074
commit 805fd0cfe6
8 changed files with 966 additions and 1066 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -4,9 +4,7 @@
class ADC -- analog to digital conversion class ADC -- analog to digital conversion
========================================= =========================================
.. only:: port_pyboard Usage::
Usage::
import pyb import pyb
@ -25,10 +23,7 @@ class ADC -- analog to digital conversion
Constructors Constructors
------------ ------------
.. class:: pyb.ADC(pin)
.. only:: port_pyboard
.. class:: pyb.ADC(pin)
Create an ADC object associated with the given pin. Create an ADC object associated with the given pin.
This allows you to then read analog values on that pin. This allows you to then read analog values on that pin.
@ -36,14 +31,12 @@ Constructors
Methods Methods
------- -------
.. only:: port_pyboard .. method:: ADC.read()
.. method:: ADC.read()
Read the value on the analog pin and return it. The returned value Read the value on the analog pin and return it. The returned value
will be between 0 and 4095. will be between 0 and 4095.
.. method:: ADC.read_timed(buf, timer) .. method:: ADC.read_timed(buf, timer)
Read analog values into ``buf`` at a rate set by the ``timer`` object. Read analog values into ``buf`` at a rate set by the ``timer`` object.
@ -79,7 +72,7 @@ Methods
This function does not allocate any heap memory. It has blocking behaviour: This function does not allocate any heap memory. It has blocking behaviour:
it does not return to the calling program until the buffer is full. it does not return to the calling program until the buffer is full.
.. method:: ADC.read_timed_multi((adcx, adcy, ...), (bufx, bufy, ...), timer) .. method:: ADC.read_timed_multi((adcx, adcy, ...), (bufx, bufy, ...), timer)
This is a static method. It can be used to extract relative timing or This is a static method. It can be used to extract relative timing or
phase data from multiple ADC's. phase data from multiple ADC's.
@ -133,44 +126,42 @@ Methods
The ADCAll Object The ADCAll Object
----------------- -----------------
.. only:: port_pyboard Instantiating this changes all masked ADC pins to analog inputs. The preprocessed MCU temperature,
VREF and VBAT data can be accessed on ADC channels 16, 17 and 18 respectively.
Appropriate scaling is handled according to reference voltage used (usually 3.3V).
The temperature sensor on the chip is factory calibrated and allows to read the die temperature
to +/- 1 degree centigrade. Although this sounds pretty accurate, don't forget that the MCU's internal
temperature is measured. Depending on processing loads and I/O subsystems active the die temperature
may easily be tens of degrees above ambient temperature. On the other hand a pyboard woken up after a
long standby period will show correct ambient temperature within limits mentioned above.
Instantiating this changes all masked ADC pins to analog inputs. The preprocessed MCU temperature, The ``ADCAll`` ``read_core_vbat()``, ``read_vref()`` and ``read_core_vref()`` methods read
VREF and VBAT data can be accessed on ADC channels 16, 17 and 18 respectively. the backup battery voltage, reference voltage and the (1.21V nominal) reference voltage using the
Appropriate scaling is handled according to reference voltage used (usually 3.3V). actual supply as a reference. All results are floating point numbers giving direct voltage values.
The temperature sensor on the chip is factory calibrated and allows to read the die temperature
to +/- 1 degree centigrade. Although this sounds pretty accurate, don't forget that the MCU's internal
temperature is measured. Depending on processing loads and I/O subsystems active the die temperature
may easily be tens of degrees above ambient temperature. On the other hand a pyboard woken up after a
long standby period will show correct ambient temperature within limits mentioned above.
The ``ADCAll`` ``read_core_vbat()``, ``read_vref()`` and ``read_core_vref()`` methods read ``read_core_vbat()`` returns the voltage of the backup battery. This voltage is also adjusted according
the backup battery voltage, reference voltage and the (1.21V nominal) reference voltage using the to the actual supply voltage. To avoid analog input overload the battery voltage is measured
actual supply as a reference. All results are floating point numbers giving direct voltage values. via a voltage divider and scaled according to the divider value. To prevent excessive loads
to the backup battery, the voltage divider is only active during ADC conversion.
``read_core_vbat()`` returns the voltage of the backup battery. This voltage is also adjusted according ``read_vref()`` is evaluated by measuring the internal voltage reference and backscale it using
to the actual supply voltage. To avoid analog input overload the battery voltage is measured factory calibration value of the internal voltage reference. In most cases the reading would be close
via a voltage divider and scaled according to the divider value. To prevent excessive loads to 3.3V. If the pyboard is operated from a battery, the supply voltage may drop to values below 3.3V.
to the backup battery, the voltage divider is only active during ADC conversion. The pyboard will still operate fine as long as the operating conditions are met. With proper settings
of MCU clock, flash access speed and programming mode it is possible to run the pyboard down to
2 V and still get useful ADC conversion.
``read_vref()`` is evaluated by measuring the internal voltage reference and backscale it using It is very important to make sure analog input voltages never exceed actual supply voltage.
factory calibration value of the internal voltage reference. In most cases the reading would be close
to 3.3V. If the pyboard is operated from a battery, the supply voltage may drop to values below 3.3V.
The pyboard will still operate fine as long as the operating conditions are met. With proper settings
of MCU clock, flash access speed and programming mode it is possible to run the pyboard down to
2 V and still get useful ADC conversion.
It is very important to make sure analog input voltages never exceed actual supply voltage. Other analog input channels (0..15) will return unscaled integer values according to the selected
precision.
Other analog input channels (0..15) will return unscaled integer values according to the selected To avoid unwanted activation of analog inputs (channel 0..15) a second parameter can be specified.
precision. This parameter is a binary pattern where each requested analog input has the corresponding bit set.
The default value is 0xffffffff which means all analog inputs are active. If just the internal
channels (16..18) are required, the mask value should be 0x70000.
To avoid unwanted activation of analog inputs (channel 0..15) a second parameter can be specified. Example::
This parameter is a binary pattern where each requested analog input has the corresponding bit set.
The default value is 0xffffffff which means all analog inputs are active. If just the internal
channels (16..18) are required, the mask value should be 0x70000.
Example::
adcall = pyb.ADCAll(12, 0x70000) # 12 bit resolution, internal channels adcall = pyb.ADCAll(12, 0x70000) # 12 bit resolution, internal channels
temp = adcall.read_core_temp() temp = adcall.read_core_temp()

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

@ -10,9 +10,7 @@ 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 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.
.. only:: port_pyboard Example::
Example::
from pyb import I2C from pyb import I2C
@ -24,30 +22,28 @@ when created, or initialised later on.
Printing the i2c object gives you information about its configuration. Printing the i2c object gives you information about its configuration.
.. only:: port_pyboard The basic methods are send and recv::
The basic methods are send and recv::
i2c.send('abc') # send 3 bytes i2c.send('abc') # send 3 bytes
i2c.send(0x42) # send a single byte, given by the number i2c.send(0x42) # send a single byte, given by the number
data = i2c.recv(3) # receive 3 bytes data = i2c.recv(3) # receive 3 bytes
To receive inplace, first create a bytearray:: To receive inplace, first create a bytearray::
data = bytearray(3) # create a buffer data = bytearray(3) # create a buffer
i2c.recv(data) # receive 3 bytes, writing them into data i2c.recv(data) # receive 3 bytes, writing them into data
You can specify a timeout (in ms):: You can specify a timeout (in ms)::
i2c.send(b'123', timeout=2000) # timeout after 2 seconds i2c.send(b'123', timeout=2000) # timeout after 2 seconds
A master must specify the recipient's address:: A master must specify the recipient's address::
i2c.init(I2C.MASTER) i2c.init(I2C.MASTER)
i2c.send('123', 0x42) # send 3 bytes to slave with address 0x42 i2c.send('123', 0x42) # send 3 bytes to slave with address 0x42
i2c.send(b'456', addr=0x42) # keyword for address i2c.send(b'456', addr=0x42) # keyword for address
Master also has other methods:: Master also has other methods::
i2c.is_ready(0x42) # check if slave 0x42 is ready i2c.is_ready(0x42) # check if slave 0x42 is ready
i2c.scan() # scan for slaves on the bus, returning i2c.scan() # scan for slaves on the bus, returning
@ -60,9 +56,7 @@ Printing the i2c object gives you information about its configuration.
Constructors Constructors
------------ ------------
.. only:: port_pyboard .. class:: pyb.I2C(bus, ...)
.. class:: pyb.I2C(bus, ...)
Construct an I2C object on the given bus. ``bus`` can be 1 or 2, 'X' or Construct an I2C object on the given bus. ``bus`` can be 1 or 2, 'X' or
'Y'. With no additional parameters, the I2C object is created but not 'Y'. With no additional parameters, the I2C object is created but not
@ -90,9 +84,7 @@ Methods
Turn off the I2C bus. Turn off the I2C bus.
.. only:: port_pyboard .. method:: I2C.init(mode, \*, addr=0x12, baudrate=400000, gencall=False, dma=False)
.. method:: I2C.init(mode, \*, addr=0x12, baudrate=400000, gencall=False, dma=False)
Initialise the I2C bus with the given parameters: Initialise the I2C bus with the given parameters:
@ -104,11 +96,11 @@ Methods
that DMA transfers have more precise timing but currently do not handle bus that DMA transfers have more precise timing but currently do not handle bus
errors properly) errors properly)
.. method:: I2C.is_ready(addr) .. method:: I2C.is_ready(addr)
Check if an I2C device responds to the given address. Only valid when in master mode. 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) .. method:: I2C.mem_read(data, addr, memaddr, \*, timeout=5000, addr_size=8)
Read from the memory of an I2C device: Read from the memory of an I2C device:
@ -121,7 +113,7 @@ Methods
Returns the read data. Returns the read data.
This is only valid in master mode. This is only valid in master mode.
.. method:: I2C.mem_write(data, addr, memaddr, \*, timeout=5000, addr_size=8) .. method:: I2C.mem_write(data, addr, memaddr, \*, timeout=5000, addr_size=8)
Write to the memory of an I2C device: Write to the memory of an I2C device:
@ -134,7 +126,7 @@ Methods
Returns ``None``. Returns ``None``.
This is only valid in master mode. This is only valid in master mode.
.. method:: I2C.recv(recv, addr=0x00, \*, timeout=5000) .. method:: I2C.recv(recv, addr=0x00, \*, timeout=5000)
Receive data on the bus: Receive data on the bus:
@ -146,7 +138,7 @@ Methods
Return value: if ``recv`` is an integer then a new buffer of the bytes received, 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``. otherwise the same buffer that was passed in to ``recv``.
.. method:: I2C.send(send, addr=0x00, \*, timeout=5000) .. method:: I2C.send(send, addr=0x00, \*, timeout=5000)
Send data on the bus: Send data on the bus:
@ -168,8 +160,6 @@ Constants
for initialising the bus to master mode for initialising the bus to master mode
.. only:: port_pyboard .. data:: I2C.SLAVE
.. data:: I2C.SLAVE
for initialising the bus to slave mode for initialising the bus to slave mode

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

@ -10,34 +10,32 @@ digital logic level. For analog control of a pin, see the ADC class.
Usage Model: Usage Model:
.. only:: port_pyboard All Board Pins are predefined as pyb.Pin.board.Name::
All Board Pins are predefined as pyb.Pin.board.Name::
x1_pin = pyb.Pin.board.X1 x1_pin = pyb.Pin.board.X1
g = pyb.Pin(pyb.Pin.board.X1, pyb.Pin.IN) g = pyb.Pin(pyb.Pin.board.X1, pyb.Pin.IN)
CPU pins which correspond to the board pins are available CPU pins which correspond to the board pins are available
as ``pyb.cpu.Name``. For the CPU pins, the names are the port letter 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 followed by the pin number. On the PYBv1.0, ``pyb.Pin.board.X1`` and
``pyb.Pin.cpu.A0`` are the same pin. ``pyb.Pin.cpu.A0`` are the same pin.
You can also use strings:: You can also use strings::
g = pyb.Pin('X1', pyb.Pin.OUT_PP) g = pyb.Pin('X1', pyb.Pin.OUT_PP)
Users can add their own names:: Users can add their own names::
MyMapperDict = { 'LeftMotorDir' : pyb.Pin.cpu.C12 } MyMapperDict = { 'LeftMotorDir' : pyb.Pin.cpu.C12 }
pyb.Pin.dict(MyMapperDict) pyb.Pin.dict(MyMapperDict)
g = pyb.Pin("LeftMotorDir", pyb.Pin.OUT_OD) g = pyb.Pin("LeftMotorDir", pyb.Pin.OUT_OD)
and can query mappings:: and can query mappings::
pin = pyb.Pin("LeftMotorDir") pin = pyb.Pin("LeftMotorDir")
Users can also add their own mapping function:: Users can also add their own mapping function::
def MyMapper(pin_name): def MyMapper(pin_name):
if pin_name == "LeftMotorDir": if pin_name == "LeftMotorDir":
@ -45,33 +43,33 @@ Usage Model:
pyb.Pin.mapper(MyMapper) pyb.Pin.mapper(MyMapper)
So, if you were to call: ``pyb.Pin("LeftMotorDir", pyb.Pin.OUT_PP)`` So, if you were to call: ``pyb.Pin("LeftMotorDir", pyb.Pin.OUT_PP)``
then ``"LeftMotorDir"`` is passed directly to the mapper function. then ``"LeftMotorDir"`` is passed directly to the mapper function.
To summarise, the following order determines how things get mapped into To summarise, the following order determines how things get mapped into
an ordinal pin number: an ordinal pin number:
1. Directly specify a pin object 1. Directly specify a pin object
2. User supplied mapping function 2. User supplied mapping function
3. User supplied mapping (object must be usable as a dictionary key) 3. User supplied mapping (object must be usable as a dictionary key)
4. Supply a string which matches a board pin 4. Supply a string which matches a board pin
5. Supply a string which matches a CPU port/pin 5. Supply a string which matches a CPU port/pin
You can set ``pyb.Pin.debug(True)`` to get some debug information about You can set ``pyb.Pin.debug(True)`` to get some debug information about
how a particular object gets mapped to a pin. how a particular object gets mapped to a pin.
When a pin has the ``Pin.PULL_UP`` or ``Pin.PULL_DOWN`` pull-mode enabled, 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 that pin has an effective 40k Ohm resistor pulling it to 3V3 or GND
respectively (except pin Y5 which has 11k Ohm resistors). respectively (except pin Y5 which has 11k Ohm resistors).
Now every time a falling edge is seen on the gpio pin, the callback will be 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 executed. Caution: mechanical push buttons have "bounce" and pushing or
releasing a switch will often generate multiple edges. releasing a switch will often generate multiple edges.
See: http://www.eng.utah.edu/~cs5780/debouncing.pdf for a detailed See: http://www.eng.utah.edu/~cs5780/debouncing.pdf for a detailed
explanation, along with various techniques for debouncing. explanation, along with various techniques for debouncing.
All pin objects go through the pin mapper to come up with one of the All pin objects go through the pin mapper to come up with one of the
gpio pins. gpio pins.
Constructors Constructors
------------ ------------
@ -81,20 +79,18 @@ Constructors
Create a new Pin object associated with the id. If additional arguments are given, 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`. they are used to initialise the pin. See :meth:`pin.init`.
.. only:: port_pyboard Class methods
-------------
Class methods .. classmethod:: Pin.debug([state])
-------------
.. classmethod:: Pin.debug([state])
Get or set the debugging state (``True`` or ``False`` for on or off). Get or set the debugging state (``True`` or ``False`` for on or off).
.. classmethod:: Pin.dict([dict]) .. classmethod:: Pin.dict([dict])
Get or set the pin mapper dictionary. Get or set the pin mapper dictionary.
.. classmethod:: Pin.mapper([fun]) .. classmethod:: Pin.mapper([fun])
Get or set the pin mapper function. Get or set the pin mapper function.
@ -102,9 +98,7 @@ Constructors
Methods Methods
------- -------
.. only:: port_pyboard .. method:: Pin.init(mode, pull=Pin.PULL_NONE, af=-1)
.. method:: Pin.init(mode, pull=Pin.PULL_NONE, af=-1)
Initialise the pin: Initialise the pin:
@ -137,45 +131,43 @@ Methods
anything that converts to a boolean. If it converts to ``True``, the pin anything that converts to a boolean. If it converts to ``True``, the pin
is set high, otherwise it is set low. is set high, otherwise it is set low.
.. only:: port_pyboard .. method:: Pin.__str__()
.. method:: Pin.__str__()
Return a string describing the pin object. Return a string describing the pin object.
.. method:: Pin.af() .. method:: Pin.af()
Returns the currently configured alternate-function of the pin. The Returns the currently configured alternate-function of the pin. The
integer returned will match one of the allowed constants for the af integer returned will match one of the allowed constants for the af
argument to the init function. argument to the init function.
.. method:: Pin.af_list() .. method:: Pin.af_list()
Returns an array of alternate functions available for this pin. Returns an array of alternate functions available for this pin.
.. method:: Pin.gpio() .. method:: Pin.gpio()
Returns the base address of the GPIO block associated with this pin. Returns the base address of the GPIO block associated with this pin.
.. method:: Pin.mode() .. method:: Pin.mode()
Returns the currently configured mode of the pin. The integer returned 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 will match one of the allowed constants for the mode argument to the init
function. function.
.. method:: Pin.name() .. method:: Pin.name()
Get the pin name. Get the pin name.
.. method:: Pin.names() .. method:: Pin.names()
Returns the cpu and board names for this pin. Returns the cpu and board names for this pin.
.. method:: Pin.pin() .. method:: Pin.pin()
Get the pin number. Get the pin number.
.. method:: Pin.port() .. method:: Pin.port()
Get the pin port. Get the pin port.
@ -188,92 +180,88 @@ Methods
Constants Constants
--------- ---------
.. only:: port_pyboard .. data:: Pin.AF_OD
.. data:: Pin.AF_OD
initialise the pin to alternate-function mode with an open-drain drive initialise the pin to alternate-function mode with an open-drain drive
.. data:: Pin.AF_PP .. data:: Pin.AF_PP
initialise the pin to alternate-function mode with a push-pull drive initialise the pin to alternate-function mode with a push-pull drive
.. data:: Pin.ANALOG .. data:: Pin.ANALOG
initialise the pin to analog mode initialise the pin to analog mode
.. data:: Pin.IN .. data:: Pin.IN
initialise the pin to input mode initialise the pin to input mode
.. data:: Pin.OUT_OD .. data:: Pin.OUT_OD
initialise the pin to output mode with an open-drain drive initialise the pin to output mode with an open-drain drive
.. data:: Pin.OUT_PP .. data:: Pin.OUT_PP
initialise the pin to output mode with a push-pull drive initialise the pin to output mode with a push-pull drive
.. data:: Pin.PULL_DOWN .. data:: Pin.PULL_DOWN
enable the pull-down resistor on the pin enable the pull-down resistor on the pin
.. data:: Pin.PULL_NONE .. data:: Pin.PULL_NONE
don't enable any pull up or down resistors on the pin don't enable any pull up or down resistors on the pin
.. data:: Pin.PULL_UP .. data:: Pin.PULL_UP
enable the pull-up resistor on the pin enable the pull-up resistor on the pin
.. only:: port_pyboard class PinAF -- Pin Alternate Functions
======================================
class PinAF -- Pin Alternate Functions A Pin represents a physical pin on the microprocessor. Each pin
====================================== can have a variety of functions (GPIO, I2C SDA, etc). Each PinAF
object represents a particular function for a pin.
A Pin represents a physical pin on the microprocessor. Each pin Usage Model::
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 = pyb.Pin.board.X3
x3_af = x3.af_list() x3_af = x3.af_list()
x3_af will now contain an array of PinAF objects which are available on x3_af will now contain an array of PinAF objects which are available on
pin X3. pin X3.
For the pyboard, x3_af would contain: For the pyboard, x3_af would contain:
[Pin.AF1_TIM2, Pin.AF2_TIM5, Pin.AF3_TIM9, Pin.AF7_USART2] [Pin.AF1_TIM2, Pin.AF2_TIM5, Pin.AF3_TIM9, Pin.AF7_USART2]
Normally, each peripheral would configure the af automatically, but sometimes Normally, each peripheral would configure the af automatically, but sometimes
the same function is available on multiple pins, and having more control the same function is available on multiple pins, and having more control
is desired. is desired.
To configure X3 to expose TIM2_CH3, you could use:: 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) pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=pyb.Pin.AF1_TIM2)
or:: or::
pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=1) pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=1)
Methods Methods
------- -------
.. method:: pinaf.__str__() .. method:: pinaf.__str__()
Return a string describing the alternate function. Return a string describing the alternate function.
.. method:: pinaf.index() .. method:: pinaf.index()
Return the alternate function index. Return the alternate function index.
.. method:: pinaf.name() .. method:: pinaf.name()
Return the name of the alternate function. Return the name of the alternate function.
.. method:: pinaf.reg() .. method:: pinaf.reg()
Return the base register associated with the peripheral assigned to this Return the base register associated with the peripheral assigned to this
alternate function. For example, if the alternate function were TIM2_CH3 alternate function. For example, if the alternate function were TIM2_CH3

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

@ -33,8 +33,6 @@ Methods
date and time. With 1 argument (being an 8-tuple) it sets the date date and time. With 1 argument (being an 8-tuple) it sets the date
and time (and ``subseconds`` is reset to 255). and time (and ``subseconds`` is reset to 255).
.. only:: port_pyboard
The 8-tuple has the following format: The 8-tuple has the following format:
(year, month, day, weekday, hours, minutes, seconds, subseconds) (year, month, day, weekday, hours, minutes, seconds, subseconds)
@ -43,9 +41,7 @@ Methods
``subseconds`` counts down from 255 to 0 ``subseconds`` counts down from 255 to 0
.. only:: port_pyboard .. method:: RTC.wakeup(timeout, callback=None)
.. method:: RTC.wakeup(timeout, callback=None)
Set the RTC wakeup timer to trigger repeatedly at every ``timeout`` Set the RTC wakeup timer to trigger repeatedly at every ``timeout``
milliseconds. This trigger can wake the pyboard from both the sleep milliseconds. This trigger can wake the pyboard from both the sleep
@ -56,7 +52,7 @@ Methods
If ``callback`` is given then it is executed at every trigger of the If ``callback`` is given then it is executed at every trigger of the
wakeup timer. ``callback`` must take exactly one argument. wakeup timer. ``callback`` must take exactly one argument.
.. method:: RTC.info() .. method:: RTC.info()
Get information about the startup time and reset source. Get information about the startup time and reset source.
@ -65,7 +61,7 @@ Methods
- Bit 0x10000 is set if a power-on reset occurred. - Bit 0x10000 is set if a power-on reset occurred.
- Bit 0x20000 is set if an external reset occurred - Bit 0x20000 is set if an external reset occurred
.. method:: RTC.calibration(cal) .. method:: RTC.calibration(cal)
Get or set RTC calibration. Get or set RTC calibration.
@ -80,4 +76,3 @@ Methods
ppm; likewise the RTC clock it slowed by negative values. The ppm; likewise the RTC clock it slowed by negative values. The
usable calibration range is: usable calibration range is:
(-511 * 0.954) ~= -487.5 ppm up to (512 * 0.954) ~= 488.5 ppm (-511 * 0.954) ~= -487.5 ppm up to (512 * 0.954) ~= 488.5 ppm

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

@ -7,20 +7,18 @@ class SPI -- a master-driven serial protocol
SPI is a serial protocol that is driven by a master. At the physical level SPI is a serial protocol that is driven by a master. At the physical level
there are 3 lines: SCK, MOSI, MISO. there are 3 lines: SCK, MOSI, MISO.
.. only:: port_pyboard See usage model of I2C; SPI is very similar. Main difference is
parameters to init the SPI bus::
See usage model of I2C; SPI is very similar. Main difference is
parameters to init the SPI bus::
from pyb import SPI from pyb import SPI
spi = SPI(1, SPI.MASTER, baudrate=600000, polarity=1, phase=0, crc=0x7) 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 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 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 to sample data on the first or second clock edge respectively. Crc can be
None for no CRC, or a polynomial specifier. None for no CRC, or a polynomial specifier.
Additional methods for SPI:: Additional methods for SPI::
data = spi.send_recv(b'1234') # send 4 bytes and receive 4 bytes data = spi.send_recv(b'1234') # send 4 bytes and receive 4 bytes
buf = bytearray(4) buf = bytearray(4)
@ -30,9 +28,7 @@ there are 3 lines: SCK, MOSI, MISO.
Constructors Constructors
------------ ------------
.. only:: port_pyboard .. class:: pyb.SPI(bus, ...)
.. class:: pyb.SPI(bus, ...)
Construct an SPI object on the given bus. ``bus`` can be 1 or 2, or Construct an SPI object on the given bus. ``bus`` can be 1 or 2, or
'X' or 'Y'. With no additional parameters, the SPI object is created but 'X' or 'Y'. With no additional parameters, the SPI object is created but
@ -55,9 +51,7 @@ Methods
Turn off the SPI bus. Turn off the SPI bus.
.. only:: port_pyboard .. method:: SPI.init(mode, baudrate=328125, \*, prescaler, polarity=1, phase=0, bits=8, firstbit=SPI.MSB, ti=False, crc=None)
.. 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: Initialise the SPI bus with the given parameters:
@ -82,9 +76,7 @@ Methods
Printing the SPI object will show you the computed baudrate and the chosen Printing the SPI object will show you the computed baudrate and the chosen
prescaler. prescaler.
.. only:: port_pyboard .. method:: SPI.recv(recv, \*, timeout=5000)
.. method:: SPI.recv(recv, \*, timeout=5000)
Receive data on the bus: Receive data on the bus:
@ -95,7 +87,7 @@ Methods
Return value: if ``recv`` is an integer then a new buffer of the bytes received, 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``. otherwise the same buffer that was passed in to ``recv``.
.. method:: SPI.send(send, \*, timeout=5000) .. method:: SPI.send(send, \*, timeout=5000)
Send data on the bus: Send data on the bus:
@ -104,7 +96,7 @@ Methods
Return value: ``None``. Return value: ``None``.
.. method:: SPI.send_recv(send, recv=None, \*, timeout=5000) .. method:: SPI.send_recv(send, recv=None, \*, timeout=5000)
Send and receive data on the bus at the same time: Send and receive data on the bus at the same time:
@ -119,14 +111,12 @@ Methods
Constants Constants
--------- ---------
.. only:: port_pyboard .. data:: SPI.MASTER
.. data:: SPI.SLAVE
.. data:: SPI.MASTER
.. data:: SPI.SLAVE
for initialising the SPI bus to master or slave mode for initialising the SPI bus to master or slave mode
.. data:: SPI.LSB .. data:: SPI.LSB
.. data:: SPI.MSB .. data:: SPI.MSB
set the first bit to be the least or most significant bit set the first bit to be the least or most significant bit

82
docs/library/pyb.Timer.rst
View File

@ -4,31 +4,29 @@
class Timer -- control internal timers class Timer -- control internal timers
====================================== ======================================
.. only:: port_pyboard Timers can be used for a great variety of tasks. At the moment, only
the simplest case is implemented: that of calling a function periodically.
Timers can be used for a great variety of tasks. At the moment, only Each timer consists of a counter that counts up at a certain rate. The rate
the simplest case is implemented: that of calling a function periodically. at which it counts is the peripheral clock frequency (in Hz) divided by the
timer prescaler. When the counter reaches the timer period it triggers an
event, and the counter resets back to zero. By using the callback method,
the timer event can call a Python function.
Each timer consists of a counter that counts up at a certain rate. The rate Example usage to toggle an LED at a fixed frequency::
at which it counts is the peripheral clock frequency (in Hz) divided by the
timer prescaler. When the counter reaches the timer period it triggers an
event, and the counter resets back to zero. By using the callback method,
the timer event can call a Python function.
Example usage to toggle an LED at a fixed frequency::
tim = pyb.Timer(4) # create a timer object using timer 4 tim = pyb.Timer(4) # create a timer object using timer 4
tim.init(freq=2) # trigger at 2Hz tim.init(freq=2) # trigger at 2Hz
tim.callback(lambda t:pyb.LED(1).toggle()) tim.callback(lambda t:pyb.LED(1).toggle())
Example using named function for the callback:: Example using named function for the callback::
def tick(timer): # we will receive the timer object when being called def tick(timer): # we will receive the timer object when being called
print(timer.counter()) # show current timer's counter value print(timer.counter()) # show current timer's counter value
tim = pyb.Timer(4, freq=1) # create a timer object using timer 4 - trigger at 1Hz tim = pyb.Timer(4, freq=1) # create a timer object using timer 4 - trigger at 1Hz
tim.callback(tick) # set the callback to our tick function tim.callback(tick) # set the callback to our tick function
Further examples:: Further examples::
tim = pyb.Timer(4, freq=100) # freq in Hz tim = pyb.Timer(4, freq=100) # freq in Hz
tim = pyb.Timer(4, prescaler=0, period=99) tim = pyb.Timer(4, prescaler=0, period=99)
@ -38,13 +36,13 @@ class Timer -- control internal timers
tim.callback(lambda t: ...) # set callback for update interrupt (t=tim instance) tim.callback(lambda t: ...) # set callback for update interrupt (t=tim instance)
tim.callback(None) # clear callback tim.callback(None) # clear callback
*Note:* Timer(2) and Timer(3) are used for PWM to set the intensity of LED(3) *Note:* Timer(2) and Timer(3) are used for PWM to set the intensity of LED(3)
and LED(4) respectively. But these timers are only configured for PWM if and LED(4) respectively. But these timers are only configured for PWM if
the intensity of the relevant LED is set to a value between 1 and 254. If the intensity of the relevant LED is set to a value between 1 and 254. If
the intensity feature of the LEDs is not used then these timers are free for the intensity feature of the LEDs is not used then these timers are free for
general purpose use. Similarly, Timer(5) controls the servo driver, and general purpose use. Similarly, Timer(5) controls the servo driver, and
Timer(6) is used for timed ADC/DAC reading/writing. It is recommended to Timer(6) is used for timed ADC/DAC reading/writing. It is recommended to
use the other timers in your programs. use the other timers in your programs.
*Note:* Memory can't be allocated during a callback (an interrupt) and so *Note:* Memory can't be allocated during a callback (an interrupt) and so
exceptions raised within a callback don't give much information. See exceptions raised within a callback don't give much information. See
@ -57,8 +55,6 @@ Constructors
.. class:: pyb.Timer(id, ...) .. class:: pyb.Timer(id, ...)
.. only:: port_pyboard
Construct a new timer object of the given id. If additional Construct a new timer object of the given id. If additional
arguments are given, then the timer is initialised by ``init(...)``. arguments are given, then the timer is initialised by ``init(...)``.
``id`` can be 1 to 14. ``id`` can be 1 to 14.
@ -66,9 +62,7 @@ Constructors
Methods Methods
------- -------
.. only:: port_pyboard .. method:: Timer.init(\*, freq, prescaler, period)
.. method:: Timer.init(\*, freq, prescaler, period)
Initialise the timer. Initialisation must be either by frequency (in Hz) Initialise the timer. Initialisation must be either by frequency (in Hz)
or by prescaler and period:: or by prescaler and period::
@ -119,24 +113,18 @@ Methods
Deinitialises the timer. Deinitialises the timer.
.. only:: port_pyboard
Disables the callback (and the associated irq). Disables the callback (and the associated irq).
Disables any channel callbacks (and the associated irq). Disables any channel callbacks (and the associated irq).
Stops the timer, and disables the timer peripheral. Stops the timer, and disables the timer peripheral.
.. only:: port_pyboard .. method:: Timer.callback(fun)
.. method:: Timer.callback(fun)
Set the function to be called when the timer triggers. Set the function to be called when the timer triggers.
``fun`` is passed 1 argument, the timer object. ``fun`` is passed 1 argument, the timer object.
If ``fun`` is ``None`` then the callback will be disabled. If ``fun`` is ``None`` then the callback will be disabled.
.. only:: port_pyboard .. method:: Timer.channel(channel, mode, ...)
.. method:: Timer.channel(channel, mode, ...)
If only a channel number is passed, then a previously initialized channel If only a channel number is passed, then a previously initialized channel
object is returned (or ``None`` if there is no previous channel). object is returned (or ``None`` if there is no previous channel).
@ -210,29 +198,23 @@ Methods
ch2 = timer.channel(2, pyb.Timer.PWM, pin=pyb.Pin.board.X2, pulse_width=8000) ch2 = timer.channel(2, pyb.Timer.PWM, pin=pyb.Pin.board.X2, pulse_width=8000)
ch3 = timer.channel(3, pyb.Timer.PWM, pin=pyb.Pin.board.X3, pulse_width=16000) ch3 = timer.channel(3, pyb.Timer.PWM, pin=pyb.Pin.board.X3, pulse_width=16000)
.. only:: port_pyboard .. method:: Timer.counter([value])
.. method:: Timer.counter([value])
Get or set the timer counter. Get or set the timer counter.
.. only:: port_pyboard .. method:: Timer.freq([value])
.. method:: Timer.freq([value])
Get or set the frequency for the timer (changes prescaler and period if set). Get or set the frequency for the timer (changes prescaler and period if set).
.. only:: port_pyboard .. method:: Timer.period([value])
.. method:: Timer.period([value])
Get or set the period of the timer. Get or set the period of the timer.
.. method:: Timer.prescaler([value]) .. method:: Timer.prescaler([value])
Get or set the prescaler for the timer. Get or set the prescaler for the timer.
.. method:: Timer.source_freq() .. method:: Timer.source_freq()
Get the frequency of the source of the timer. Get the frequency of the source of the timer.
@ -246,29 +228,25 @@ TimerChannel objects are created using the Timer.channel() method.
Methods Methods
------- -------
.. only:: port_pyboard .. method:: timerchannel.callback(fun)
.. method:: timerchannel.callback(fun)
Set the function to be called when the timer channel triggers. Set the function to be called when the timer channel triggers.
``fun`` is passed 1 argument, the timer object. ``fun`` is passed 1 argument, the timer object.
If ``fun`` is ``None`` then the callback will be disabled. If ``fun`` is ``None`` then the callback will be disabled.
.. only:: port_pyboard .. method:: timerchannel.capture([value])
.. method:: timerchannel.capture([value])
Get or set the capture value associated with a channel. Get or set the capture value associated with a channel.
capture, compare, and pulse_width are all aliases for the same function. capture, compare, and pulse_width are all aliases for the same function.
capture is the logical name to use when the channel is in input capture mode. capture is the logical name to use when the channel is in input capture mode.
.. method:: timerchannel.compare([value]) .. method:: timerchannel.compare([value])
Get or set the compare value associated with a channel. Get or set the compare value associated with a channel.
capture, compare, and pulse_width are all aliases for the same function. capture, compare, and pulse_width are all aliases for the same function.
compare is the logical name to use when the channel is in output compare mode. compare is the logical name to use when the channel is in output compare mode.
.. method:: timerchannel.pulse_width([value]) .. method:: timerchannel.pulse_width([value])
Get or set the pulse width value associated with a channel. Get or set the pulse width value associated with a channel.
capture, compare, and pulse_width are all aliases for the same function. capture, compare, and pulse_width are all aliases for the same function.
@ -277,7 +255,7 @@ Methods
In edge aligned mode, a pulse_width of ``period + 1`` corresponds to a duty cycle of 100% In edge aligned mode, a pulse_width of ``period + 1`` corresponds to a duty cycle of 100%
In center aligned mode, a pulse width of ``period`` corresponds to a duty cycle of 100% In center aligned mode, a pulse width of ``period`` corresponds to a duty cycle of 100%
.. method:: timerchannel.pulse_width_percent([value]) .. method:: timerchannel.pulse_width_percent([value])
Get or set the pulse width percentage associated with a channel. The value Get or set the pulse width percentage associated with a channel. The value
is a number between 0 and 100 and sets the percentage of the timer period is a number between 0 and 100 and sets the percentage of the timer period

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

@ -16,12 +16,10 @@ UART objects can be created and initialised using::
uart = UART(1, 9600) # init with given baudrate uart = UART(1, 9600) # init with given baudrate
uart.init(9600, bits=8, parity=None, stop=1) # init with given parameters uart.init(9600, bits=8, parity=None, stop=1) # init with given parameters
.. 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.
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.
*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 A UART object acts like a `stream` object and reading and writing is done
using the standard stream methods:: using the standard stream methods::
@ -32,27 +30,23 @@ using the standard stream methods::
uart.readinto(buf) # read and store into the given buffer uart.readinto(buf) # read and store into the given buffer
uart.write('abc') # write the 3 characters uart.write('abc') # write the 3 characters
.. only:: port_pyboard Individual characters can be read/written using::
Individual characters can be read/written using::
uart.readchar() # read 1 character and returns it as an integer uart.readchar() # read 1 character and returns it as an integer
uart.writechar(42) # write 1 character uart.writechar(42) # write 1 character
To check if there is anything to be read, use:: To check if there is anything to be read, use::
uart.any() # returns the number of characters waiting uart.any() # returns the number of characters waiting
*Note:* The stream functions ``read``, ``write``, etc. are new in MicroPython v1.3.4. *Note:* The stream functions ``read``, ``write``, etc. are new in MicroPython v1.3.4.
Earlier versions use ``uart.send`` and ``uart.recv``. Earlier versions use ``uart.send`` and ``uart.recv``.
Constructors Constructors
------------ ------------
.. only:: port_pyboard .. class:: pyb.UART(bus, ...)
.. class:: pyb.UART(bus, ...)
Construct a UART object on the given bus. ``bus`` can be 1-6, or 'XA', 'XB', 'YA', or 'YB'. 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 With no additional parameters, the UART object is created but not
@ -75,9 +69,7 @@ Constructors
Methods Methods
------- -------
.. only:: port_pyboard .. method:: UART.init(baudrate, bits=8, parity=None, stop=1, \*, timeout=1000, flow=0, timeout_char=0, read_buf_len=64)
.. method:: UART.init(baudrate, bits=8, parity=None, stop=1, \*, timeout=1000, flow=0, timeout_char=0, read_buf_len=64)
Initialise the UART bus with the given parameters: Initialise the UART bus with the given parameters:
@ -105,9 +97,7 @@ Methods
Turn off the UART bus. Turn off the UART bus.
.. only:: port_pyboard .. method:: UART.any()
.. method:: UART.any()
Returns the number of bytes waiting (may be 0). Returns the number of bytes waiting (may be 0).
@ -120,8 +110,6 @@ Methods
If ``nbytes`` is not given then the method reads as much data as possible. It If ``nbytes`` is not given then the method reads as much data as possible. It
returns after the timeout has elapsed. returns after the timeout has elapsed.
.. only:: port_pyboard
*Note:* for 9 bit characters each character takes two bytes, ``nbytes`` must *Note:* for 9 bit characters each character takes two bytes, ``nbytes`` must
be even, and the number of characters is ``nbytes/2``. be even, and the number of characters is ``nbytes/2``.
@ -152,8 +140,6 @@ Methods
.. method:: UART.write(buf) .. method:: UART.write(buf)
.. only:: port_pyboard
Write the buffer of bytes to the bus. If characters are 7 or 8 bits wide 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 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 bytes are used for each character (little endian), and ``buf`` must contain
@ -162,9 +148,7 @@ Methods
Return value: number of bytes written. If a timeout occurs and no bytes Return value: number of bytes written. If a timeout occurs and no bytes
were written returns ``None``. were written returns ``None``.
.. only:: port_pyboard .. method:: UART.writechar(char)
.. method:: UART.writechar(char)
Write a single character on the bus. ``char`` is an integer to write. Write a single character on the bus. ``char`` is an integer to write.
Return value: ``None``. See note below if CTS flow control is used. Return value: ``None``. See note below if CTS flow control is used.
@ -178,68 +162,64 @@ Methods
Constants Constants
--------- ---------
.. only:: port_pyboard .. data:: UART.RTS
UART.CTS
.. data:: UART.RTS
.. data:: UART.CTS
to select the flow control type. to select the flow control type.
Flow Control Flow Control
------------ ------------
.. only:: port_pyboard On Pyboards V1 and V1.1 ``UART(2)`` and ``UART(3)`` support RTS/CTS hardware flow control
using the following pins:
On Pyboards V1 and V1.1 ``UART(2)`` and ``UART(3)`` support RTS/CTS hardware flow control
using the following pins:
- ``UART(2)`` is on: ``(TX, RX, nRTS, nCTS) = (X3, X4, X2, X1) = (PA2, PA3, PA1, PA0)`` - ``UART(2)`` is on: ``(TX, RX, nRTS, nCTS) = (X3, X4, X2, X1) = (PA2, PA3, PA1, PA0)``
- ``UART(3)`` is on :``(TX, RX, nRTS, nCTS) = (Y9, Y10, Y7, Y6) = (PB10, PB11, PB14, PB13)`` - ``UART(3)`` is on :``(TX, RX, nRTS, nCTS) = (Y9, Y10, Y7, Y6) = (PB10, PB11, PB14, PB13)``
On the Pyboard Lite only ``UART(2)`` supports flow control on these pins: On the Pyboard Lite only ``UART(2)`` supports flow control on these pins:
``(TX, RX, nRTS, nCTS) = (X1, X2, X4, X3) = (PA2, PA3, PA1, PA0)`` ``(TX, RX, nRTS, nCTS) = (X1, X2, X4, X3) = (PA2, PA3, PA1, PA0)``
In the following paragraphs the term "target" refers to the device connected to In the following paragraphs the term "target" refers to the device connected to
the UART. the UART.
When the UART's ``init()`` method is called with ``flow`` set to one or both of When the UART's ``init()`` method is called with ``flow`` set to one or both of
``UART.RTS`` and ``UART.CTS`` the relevant flow control pins are configured. ``UART.RTS`` and ``UART.CTS`` the relevant flow control pins are configured.
``nRTS`` is an active low output, ``nCTS`` is an active low input with pullup ``nRTS`` is an active low output, ``nCTS`` is an active low input with pullup
enabled. To achieve flow control the Pyboard's ``nCTS`` signal should be connected enabled. To achieve flow control the Pyboard's ``nCTS`` signal should be connected
to the target's ``nRTS`` and the Pyboard's ``nRTS`` to the target's ``nCTS``. to the target's ``nRTS`` and the Pyboard's ``nRTS`` to the target's ``nCTS``.
CTS: target controls Pyboard transmitter CTS: target controls Pyboard transmitter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If CTS flow control is enabled the write behaviour is as follows: If CTS flow control is enabled the write behaviour is as follows:
If the Pyboard's ``UART.write(buf)`` method is called, transmission will stall for If the Pyboard's ``UART.write(buf)`` method is called, transmission will stall for
any periods when ``nCTS`` is ``False``. This will result in a timeout if the entire any periods when ``nCTS`` is ``False``. This will result in a timeout if the entire
buffer was not transmitted in the timeout period. The method returns the number of buffer was not transmitted in the timeout period. The method returns the number of
bytes written, enabling the user to write the remainder of the data if required. In bytes written, enabling the user to write the remainder of the data if required. In
the event of a timeout, a character will remain in the UART pending ``nCTS``. The the event of a timeout, a character will remain in the UART pending ``nCTS``. The
number of bytes composing this character will be included in the return value. number of bytes composing this character will be included in the return value.
If ``UART.writechar()`` is called when ``nCTS`` is ``False`` the method will time If ``UART.writechar()`` is called when ``nCTS`` is ``False`` the method will time
out unless the target asserts ``nCTS`` in time. If it times out ``OSError 116`` out unless the target asserts ``nCTS`` in time. If it times out ``OSError 116``
will be raised. The character will be transmitted as soon as the target asserts ``nCTS``. will be raised. The character will be transmitted as soon as the target asserts ``nCTS``.
RTS: Pyboard controls target's transmitter RTS: Pyboard controls target's transmitter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If RTS flow control is enabled, behaviour is as follows: If RTS flow control is enabled, behaviour is as follows:
If buffered input is used (``read_buf_len`` > 0), incoming characters are buffered. If buffered input is used (``read_buf_len`` > 0), incoming characters are buffered.
If the buffer becomes full, the next character to arrive will cause ``nRTS`` to go If the buffer becomes full, the next character to arrive will cause ``nRTS`` to go
``False``: the target should cease transmission. ``nRTS`` will go ``True`` when ``False``: the target should cease transmission. ``nRTS`` will go ``True`` when
characters are read from the buffer. characters are read from the buffer.
Note that the ``any()`` method returns the number of bytes in the buffer. Assume a Note that the ``any()`` method returns the number of bytes in the buffer. Assume a
buffer length of ``N`` bytes. If the buffer becomes full, and another character arrives, buffer length of ``N`` bytes. If the buffer becomes full, and another character arrives,
``nRTS`` will be set False, and ``any()`` will return the count ``N``. When ``nRTS`` will be set False, and ``any()`` will return the count ``N``. When
characters are read the additional character will be placed in the buffer and will characters are read the additional character will be placed in the buffer and will
be included in the result of a subsequent ``any()`` call. be included in the result of a subsequent ``any()`` call.
If buffered input is not used (``read_buf_len`` == 0) the arrival of a character will If buffered input is not used (``read_buf_len`` == 0) the arrival of a character will
cause ``nRTS`` to go ``False`` until the character is read. cause ``nRTS`` to go ``False`` until the character is read.

34
docs/library/pyb.rst
View File

@ -114,9 +114,7 @@ Interrupt related functions
Power related functions Power related functions
----------------------- -----------------------
.. only:: port_pyboard .. function:: freq([sysclk[, hclk[, pclk1[, pclk2]]]])
.. function:: freq([sysclk[, hclk[, pclk1[, pclk2]]]])
If given no arguments, returns a tuple of clock frequencies: If given no arguments, returns a tuple of clock frequencies:
(sysclk, hclk, pclk1, pclk2). (sysclk, hclk, pclk1, pclk2).
@ -154,7 +152,7 @@ Power related functions
in boot.py, before the USB peripheral is started. Also note that sysclk in boot.py, before the USB peripheral is started. Also note that sysclk
frequencies below 36MHz do not allow the USB to function correctly. frequencies below 36MHz do not allow the USB to function correctly.
.. function:: wfi() .. function:: wfi()
Wait for an internal or external interrupt. Wait for an internal or external interrupt.
@ -164,7 +162,7 @@ Power related functions
occurs once every millisecond (1000Hz) so this function will block for occurs once every millisecond (1000Hz) so this function will block for
at most 1ms. at most 1ms.
.. function:: stop() .. function:: stop()
Put the pyboard in a "sleeping" state. Put the pyboard in a "sleeping" state.
@ -174,7 +172,7 @@ Power related functions
See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event. See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event.
.. function:: standby() .. function:: standby()
Put the pyboard into a "deep sleep" state. Put the pyboard into a "deep sleep" state.
@ -188,22 +186,20 @@ Power related functions
Miscellaneous functions Miscellaneous functions
----------------------- -----------------------
.. only:: port_pyboard .. function:: have_cdc()
.. function:: have_cdc()
Return True if USB is connected as a serial device, False otherwise. Return True if USB is connected as a serial device, False otherwise.
.. note:: This function is deprecated. Use pyb.USB_VCP().isconnected() instead. .. note:: This function is deprecated. Use pyb.USB_VCP().isconnected() instead.
.. function:: hid((buttons, x, y, z)) .. function:: hid((buttons, x, y, z))
Takes a 4-tuple (or list) and sends it to the USB host (the PC) to Takes a 4-tuple (or list) and sends it to the USB host (the PC) to
signal a HID mouse-motion event. signal a HID mouse-motion event.
.. note:: This function is deprecated. Use :meth:`pyb.USB_HID.send()` instead. .. note:: This function is deprecated. Use :meth:`pyb.USB_HID.send()` instead.
.. function:: info([dump_alloc_table]) .. function:: info([dump_alloc_table])
Print out lots of information about the board. Print out lots of information about the board.
@ -214,9 +210,7 @@ Miscellaneous functions
It only makes sense to call this function from within boot.py. It only makes sense to call this function from within boot.py.
.. only:: port_pyboard .. function:: mount(device, mountpoint, \*, readonly=False, mkfs=False)
.. function:: mount(device, mountpoint, \*, readonly=False, mkfs=False)
Mount a block device and make it available as part of the filesystem. Mount a block device and make it available as part of the filesystem.
``device`` must be an object that provides the block protocol: ``device`` must be an object that provides the block protocol:
@ -251,9 +245,7 @@ Miscellaneous functions
Get or set the UART object where the REPL is repeated on. Get or set the UART object where the REPL is repeated on.
.. only:: port_pyboard .. function:: rng()
.. function:: rng()
Return a 30-bit hardware generated random number. Return a 30-bit hardware generated random number.
@ -261,9 +253,7 @@ Miscellaneous functions
Sync all file systems. Sync all file systems.
.. only:: port_pyboard .. function:: unique_id()
.. function:: unique_id()
Returns a string of 12 bytes (96 bits), which is the unique ID of the MCU. Returns a string of 12 bytes (96 bits), which is the unique ID of the MCU.
@ -298,9 +288,7 @@ Miscellaneous functions
Classes Classes
------- -------
.. only:: port_pyboard .. toctree::
.. toctree::
:maxdepth: 1 :maxdepth: 1
pyb.Accel.rst pyb.Accel.rst