Commit 88d3054a authored by Damien George's avatar Damien George
Browse files

docs: Import documentation from source-code inline comments.

The inline docs (prefixed with /// in .c files) have been converted to
RST format and put in the docs subdirectory.
parent 7c4445af
......@@ -60,7 +60,7 @@ copyright = '2014, Damien P. George'
# The short X.Y version.
version = '1.3'
# The full version, including alpha/beta/rc tags.
release = '1.3.1'
release = '1.3.5'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
......
......@@ -14,10 +14,11 @@ Software
--------
.. toctree::
:maxdepth: 2
:maxdepth: 1
general.rst
tutorial/index.rst
library/index.rst
..
.. - Reference for the [pyb module](module/pyb/ "pyb module").
......
:mod:`cmath` --- mathematical functions for complex numbers
===========================================================
.. module:: cmath
:synopsis: mathematical functions for complex numbers
The ``cmath`` module provides some basic mathematical funtions for
working with complex numbers.
Functions
---------
.. function:: cos(z)
Return the cosine of ``z``.
.. function:: exp(z)
Return the exponential of ``z``.
.. function:: log(z)
Return the natural logarithm of ``z``. The branch cut is along the negative real axis.
.. function:: log10(z)
Return the base-10 logarithm of ``z``. The branch cut is along the negative real axis.
.. function:: phase(z)
Returns the phase of the number ``z``, in the range (-pi, +pi].
.. function:: polar(z)
Returns, as a tuple, the polar form of ``z``.
.. function:: rect(r, phi)
Returns the complex number with modulus ``r`` and phase ``phi``.
.. function:: sin(z)
Return the sine of ``z``.
.. function:: sqrt(z)
Return the square-root of ``z``.
Constants
---------
.. data:: e
base of the natural logarithm
.. data:: pi
the ratio of a circle's circumference to its diameter
:mod:`gc` --- control the garbage collector
===========================================
.. module:: gc
:synopsis: control the garbage collector
Functions
---------
.. function:: collect()
Run a garbage collection.
.. function:: disable()
Disable the garbage collector.
.. function:: enable()
Enable the garbage collector.
.. function:: mem_alloc()
Return the number of bytes of heap RAM that are allocated.
.. function:: mem_free()
Return the number of bytes of available heap RAM.
Micro Python libraries
======================
Python standard libraries
-------------------------
.. toctree::
:maxdepth: 1
cmath.rst
gc.rst
math.rst
os.rst
select.rst
sys.rst
time.rst
Micro Python reduced libraries
------------------------------
.. toctree::
:maxdepth: 1
usocket.rst
uheapq.rst
ujson.rst
Libraries specific to the pyboard
---------------------------------
.. toctree::
:maxdepth: 2
pyb.rst
network.rst
:mod:`math` --- mathematical functions
======================================
.. module:: math
:synopsis: mathematical functions
The ``math`` module provides some basic mathematical funtions for
working with floating-point numbers.
Functions
---------
.. function:: acos(x)
.. function:: acosh(x)
.. function:: asin(x)
.. function:: asinh(x)
.. function:: atan(x)
.. function:: atan2(y, x)
.. function:: atanh(x)
.. function:: ceil(x)
.. function:: copysign(x, y)
.. function:: cos(x)
.. function:: cosh(x)
.. function:: degrees(x)
.. function:: erf(x)
Return the error function of ``x``.
.. function:: erfc(x)
Return the complementary error function of ``x``.
.. function:: exp(x)
.. function:: expm1(x)
.. function:: fabs(x)
.. function:: floor(x)
.. function:: fmod(x, y)
.. function:: frexp(x)
Converts a floating-point number to fractional and integral components.
.. function:: gamma(x)
Return the gamma function of ``x``.
.. function:: isfinite(x)
.. function:: isinf(x)
.. function:: isnan(x)
.. function:: ldexp(x, exp)
.. function:: lgamma(x)
return the natural logarithm of the gamma function of ``x``.
.. function:: log(x)
.. function:: log10(x)
.. function:: log2(x)
.. function:: modf(x)
.. function:: pow(x, y)
Returns ``x`` to the power of ``y``.
.. function:: radians(x)
.. function:: sin(x)
.. function:: sinh(x)
.. function:: sqrt(x)
Returns the square root of ``x``.
.. function:: tan(x)
.. function:: tanh(x)
.. function:: trunc(x)
Constants
---------
.. data:: e
base of the natural logarithm
.. data:: pi
the ratio of a circle's circumference to its diameter
****************************************
:mod:`network` --- network configuration
****************************************
.. module:: network
:synopsis: network configuration
This module provides network drivers and routing configuration.
class CC3k
==========
Constructors
------------
.. class:: CC3k(spi, pin_cs, pin_en, pin_irq)
Initialise the CC3000 using the given SPI bus and pins and return a CC3k object.
Methods
-------
.. method:: cc3k.connect(ssid, key=None, \*, security=WPA2, bssid=None)
class WIZnet5k
==============
This class allows you to control WIZnet5x00 Ethernet adaptors based on
the W5200 and W5500 chipsets (only W5200 tested).
Example usage::
import wiznet5k
w = wiznet5k.WIZnet5k()
print(w.ipaddr())
w.gethostbyname('micropython.org')
s = w.socket()
s.connect(('192.168.0.2', 8080))
s.send('hello')
print(s.recv(10))
Constructors
------------
.. class:: WIZnet5k(spi, pin_cs, pin_rst)
Create and return a WIZnet5k object.
Methods
-------
.. method:: wiznet5k.ipaddr([(ip, subnet, gateway, dns)])
Get/set IP address, subnet mask, gateway and DNS.
.. method:: wiznet5k.regs()
Dump WIZnet5k registers.
:mod:`os` --- basic "operating system" services
===============================================
.. module:: os
:synopsis: basic "operating system" services
The ``os`` module contains functions for filesystem access and ``urandom``.
The filesystem has ``/`` as the root directory, and the available physical
drives are accessible from here. They are currently:
/flash -- the internal flash filesystem
/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``.
Functions
---------
.. function:: chdir(path)
Change current directory.
.. function:: getcwd()
Get the current directory.
.. function:: listdir([dir])
With no argument, list the current directory. Otherwise list the given directory.
.. function:: mkdir(path)
Create a new directory.
.. function:: remove(path)
Remove a file.
.. function:: rmdir(path)
Remove a directory.
.. function:: stat(path)
Get the status of a file or directory.
.. function:: sync()
Sync all filesystems.
.. function:: urandom(n)
Return a bytes object with n random bytes, generated by the hardware
random number generator.
Constants
---------
.. data:: sep
separation character used in paths
class ADC =-- analog to digital conversion: read analog values on a pin
=======================================================================
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
Constructors
------------
.. class:: pyb.ADC(pin)
Create an ADC object associated with the given pin.
This allows you to then read analog values on that pin.
Methods
-------
.. method:: adc.read()
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)
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.
class Accel --- accelerometer control
=====================================
Accel is an object that controls the accelerometer. Example usage::
accel = pyb.Accel()
for i in range(10):
print(accel.x(), accel.y(), accel.z())
Raw values are between -32 and 31.
Constructors
------------
.. class:: pyb.Accel()
Create and return an accelerometer object.
Note: if you read accelerometer values immediately after creating this object
you will get 0. It takes around 20ms for the first sample to be ready, so,
unless you have some other code between creating this object and reading its
values, you should put a ``pyb.delay(20)`` after creating it. For example::
accel = pyb.Accel()
pyb.delay(20)
print(accel.x())
Methods
-------
.. method:: accel.filtered_xyz()
Get a 3-tuple of filtered x, y and z values.
.. method:: accel.tilt()
Get the tilt register.
.. method:: accel.x()
Get the x-axis value.
.. method:: accel.y()
Get the y-axis value.
.. method:: accel.z()
Get the z-axis value.
class CAN --- controller area network communication bus
=======================================================
CAN implements the standard CAN communications protocol. At
the physical level it consists of 2 lines: RX and TX. Note that
to connect the pyboard to a CAN bus you must use a CAN transceiver
to convert the CAN logic signals from the pyboard to the correct
voltage levels on the bus.
Note that this driver does not yet support filter configuration
(it defaults to a single filter that lets through all messages),
or bus timing configuration (except for setting the prescaler).
Example usage (works without anything connected)::
from pyb import CAN
can = pyb.CAN(1, pyb.CAN.LOOPBACK)
can.send('message!', 123) # send message to id 123
can.recv(0) # receive message on FIFO 0
Constructors
------------
.. class:: pyb.CAN(bus, ...)
Construct a CAN object on the given bus. ``bus`` can be 1-2, or 'YA' or 'YB'.
With no additional parameters, the CAN 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 CAN busses are:
- ``CAN(1)`` is on ``YA``: ``(RX, TX) = (Y3, Y4) = (PB8, PB9)``
- ``CAN(2)`` is on ``YB``: ``(RX, TX) = (Y5, Y6) = (PB12, PB13)``
Methods
-------
.. method:: can.init(mode, extframe=False, prescaler=100, \*, sjw=1, bs1=6, bs2=8)
Initialise the CAN bus with the given parameters:
- ``mode`` is one of: NORMAL, LOOPBACK, SILENT, SILENT_LOOPBACK
If ``extframe`` is True then the bus uses extended identifiers in the frames (29 bits).
Otherwise it uses standard 11 bit identifiers.
.. method:: can.deinit()
Turn off the CAN bus.
.. method:: can.any(fifo)
Return ``True`` if any message waiting on the FIFO, else ``False``.
.. method:: can.recv(fifo, \*, timeout=5000)
Receive data on the bus:
- ``fifo`` is an integer, which is the FIFO to receive on
- ``timeout`` is the timeout in milliseconds to wait for the receive.
Return value: buffer of data bytes.
.. method:: can.send(send, addr, \*, timeout=5000)
Send a message on the bus:
- ``send`` is the data to send (an integer to send, or a buffer object).
- ``addr`` is the address to send to
- ``timeout`` is the timeout in milliseconds to wait for the send.
Return value: ``None``.
Constants
---------
.. data:: CAN.NORMAL
.. data:: CAN.LOOPBACK
.. data:: CAN.SILENT
.. data:: CAN.SILENT_LOOPBACK
the mode of the CAN bus
class DAC --- digital to analog conversion
==========================================
The DAC is used to output analog values (a specific voltage) on pin X5 or pin X6.
The voltage will be between 0 and 3.3V.
*This module will undergo changes to the API.*
Example usage::
from pyb import DAC
dac = DAC(1) # create DAC 1 on pin X5
dac.write(128) # write a value to the DAC (makes X5 1.65V)
To output a continuous sine-wave::
import math
from pyb import DAC
# create a buffer containing a sine-wave
buf = bytearray(100)
for i in range(len(buf)):
buf[i] = 128 + int(127 \* math.sin(2 \* math.pi \* i / len(buf)))
# output the sine-wave at 400Hz
dac = DAC(1)
dac.write_timed(buf, 400 \* len(buf), mode=DAC.CIRCULAR)
Constructors
------------