diff options
Diffstat (limited to 'docs')
28 files changed, 202 insertions, 139 deletions
diff --git a/docs/library/cmath.rst b/docs/library/cmath.rst index d729561d65..e45efee303 100644 --- a/docs/library/cmath.rst +++ b/docs/library/cmath.rst @@ -1,5 +1,5 @@ -:mod:`cmath` --- mathematical functions for complex numbers -=========================================================== +:mod:`cmath` -- mathematical functions for complex numbers +========================================================== .. module:: cmath :synopsis: mathematical functions for complex numbers @@ -7,7 +7,6 @@ The ``cmath`` module provides some basic mathematical funtions for working with complex numbers. - Functions --------- @@ -47,7 +46,6 @@ Functions Return the square-root of ``z``. - Constants --------- diff --git a/docs/library/gc.rst b/docs/library/gc.rst index 3e9160f98d..01e63ae51e 100644 --- a/docs/library/gc.rst +++ b/docs/library/gc.rst @@ -1,5 +1,5 @@ -:mod:`gc` --- control the garbage collector -=========================================== +:mod:`gc` -- control the garbage collector +========================================== .. module:: gc :synopsis: control the garbage collector diff --git a/docs/library/math.rst b/docs/library/math.rst index 53427ea557..988a8c2843 100644 --- a/docs/library/math.rst +++ b/docs/library/math.rst @@ -1,5 +1,5 @@ -:mod:`math` --- mathematical functions -====================================== +:mod:`math` -- mathematical functions +===================================== .. module:: math :synopsis: mathematical functions @@ -7,45 +7,58 @@ The ``math`` module provides some basic mathematical funtions for working with floating-point numbers. +*Note:* On the pyboard, floating-point numbers have 32-bit precision. Functions --------- .. function:: acos(x) + Return the inverse cosine of ``x``. .. function:: acosh(x) + Return the inverse hyperbolic cosine of ``x``. .. function:: asin(x) + Return the inverse sine of ``x``. .. function:: asinh(x) + Return the inverse hyperbolic sine of ``x``. .. function:: atan(x) + Return the inverse tangent of ``x``. .. function:: atan2(y, x) + Return the principal value of the inverse tangent of ``y/x``. .. function:: atanh(x) + Return the inverse hyperbolic tangent of ``x``. .. function:: ceil(x) + Return an integer, being ``x`` rounded towards positive infinity. .. function:: copysign(x, y) + Return ``x`` with the sign of ``y``. .. function:: cos(x) + Return the cosine of ``x``. .. function:: cosh(x) + Return the hyperbolic cosine of ``x``. .. function:: degrees(x) + Return radians ``x`` converted to degrees. .. function:: erf(x) @@ -57,18 +70,23 @@ Functions .. function:: exp(x) + Return the exponential of ``x``. .. function:: expm1(x) + Return ``exp(x) - 1``. .. function:: fabs(x) + Return the absolute value of ``x``. .. function:: floor(x) + Return an integer, being ``x`` rounded towards negative infinity. .. function:: fmod(x, y) + Return the remainder of ``x/y``. .. function:: frexp(x) @@ -80,31 +98,40 @@ Functions .. function:: isfinite(x) + Return ``True`` if ``x`` is finite. .. function:: isinf(x) + Return ``True`` if ``x`` is infinite. .. function:: isnan(x) + Return ``True`` if ``x`` is not-a-number .. function:: ldexp(x, exp) + Return ``x * (2**exp)``. .. function:: lgamma(x) - return the natural logarithm of the gamma function of ``x``. + Return the natural logarithm of the gamma function of ``x``. .. function:: log(x) + Return the natural logarithm of ``x``. .. function:: log10(x) + Return the base-10 logarithm of ``x``. .. function:: log2(x) + Return the base-2 logarithm of ``x``. .. function:: modf(x) + Return a tuple of two floats, being the fractional and integral parts of + ``x``. Both return values have the same sign as ``x``. .. function:: pow(x, y) @@ -112,26 +139,31 @@ Functions .. function:: radians(x) + Return degrees ``x`` converted to radians. .. function:: sin(x) + Return the sine of ``x``. .. function:: sinh(x) + Return the hyperbolic sine of ``x``. .. function:: sqrt(x) - Returns the square root of ``x``. + Return the square root of ``x``. .. function:: tan(x) + Return the tangent of ``x``. .. function:: tanh(x) + Return the hyperbolic tangent of ``x``. .. function:: trunc(x) - + Return an integer, being ``x`` rounded towards 0. Constants --------- diff --git a/docs/library/os.rst b/docs/library/os.rst index f6b20dca6f..df5ade3277 100644 --- a/docs/library/os.rst +++ b/docs/library/os.rst @@ -1,21 +1,24 @@ -:mod:`os` --- basic "operating system" services -=============================================== +: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: +Pyboard specifics +----------------- - /flash -- the internal flash filesystem - /sd -- the SD card (if it exists) +The filesystem on the pyboard 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 --------- @@ -56,7 +59,6 @@ Functions Return a bytes object with n random bytes, generated by the hardware random number generator. - Constants --------- diff --git a/docs/library/pyb.ADC.rst b/docs/library/pyb.ADC.rst index 8de6428baf..33e587f3fa 100644 --- a/docs/library/pyb.ADC.rst +++ b/docs/library/pyb.ADC.rst @@ -1,5 +1,5 @@ -class ADC =-- analog to digital conversion: read analog values on a pin -======================================================================= +class ADC -- analog to digital conversion: read analog values on a pin +====================================================================== Usage:: diff --git a/docs/library/pyb.Accel.rst b/docs/library/pyb.Accel.rst index 69340af9f9..f2e107920e 100644 --- a/docs/library/pyb.Accel.rst +++ b/docs/library/pyb.Accel.rst @@ -1,5 +1,5 @@ -class Accel --- accelerometer control -===================================== +class Accel -- accelerometer control +==================================== Accel is an object that controls the accelerometer. Example usage:: diff --git a/docs/library/pyb.CAN.rst b/docs/library/pyb.CAN.rst index c03a9a551e..9ee5a0a695 100644 --- a/docs/library/pyb.CAN.rst +++ b/docs/library/pyb.CAN.rst @@ -1,5 +1,5 @@ -class CAN --- controller area network communication bus -======================================================= +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 diff --git a/docs/library/pyb.DAC.rst b/docs/library/pyb.DAC.rst index 7c1fe8ae64..00be855d5a 100644 --- a/docs/library/pyb.DAC.rst +++ b/docs/library/pyb.DAC.rst @@ -1,5 +1,5 @@ -class DAC --- digital to analog conversion -========================================== +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. diff --git a/docs/library/pyb.ExtInt.rst b/docs/library/pyb.ExtInt.rst index c9f547d76f..ac31aebb40 100644 --- a/docs/library/pyb.ExtInt.rst +++ b/docs/library/pyb.ExtInt.rst @@ -1,5 +1,5 @@ -class ExtInt --- configure I/O pins to interrupt on external events -=================================================================== +class ExtInt -- configure I/O pins to interrupt on external events +================================================================== There are a total of 22 interrupt lines. 16 of these can come from GPIO pins and the remaining 6 are from internal sources. diff --git a/docs/library/pyb.I2C.rst b/docs/library/pyb.I2C.rst index 6f49f614a6..e85bcef866 100644 --- a/docs/library/pyb.I2C.rst +++ b/docs/library/pyb.I2C.rst @@ -1,5 +1,5 @@ -class I2C --- a two-wire serial protocol -======================================== +class I2C -- a two-wire serial protocol +======================================= I2C is a two-wire protocol for communicating between devices. At the physical level it consists of 2 wires: SCL and SDA, the clock and data lines respectively. diff --git a/docs/library/pyb.LCD.rst b/docs/library/pyb.LCD.rst index 2cbba80417..7555b6fb09 100644 --- a/docs/library/pyb.LCD.rst +++ b/docs/library/pyb.LCD.rst @@ -1,5 +1,5 @@ -class LCD --- LCD control for the LCD touch-sensor pyskin -========================================================= +class LCD -- LCD control for the LCD touch-sensor pyskin +======================================================== The LCD class is used to control the LCD on the LCD touch-sensor pyskin, LCD32MKv1.0. The LCD is a 128x32 pixel monochrome screen, part NHD-C12832A1Z. diff --git a/docs/library/pyb.LED.rst b/docs/library/pyb.LED.rst index 7bd98092ae..227450f482 100644 --- a/docs/library/pyb.LED.rst +++ b/docs/library/pyb.LED.rst @@ -1,5 +1,5 @@ -class LED --- LED object -======================== +class LED -- LED object +======================= The LED object controls an individual LED (Light Emitting Diode). diff --git a/docs/library/pyb.Pin.rst b/docs/library/pyb.Pin.rst index ad47d587ae..576268172d 100644 --- a/docs/library/pyb.Pin.rst +++ b/docs/library/pyb.Pin.rst @@ -1,5 +1,5 @@ -class Pin --- control I/O pins -============================== +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 @@ -206,3 +206,56 @@ Constants .. 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 diff --git a/docs/library/pyb.PinAF.rst b/docs/library/pyb.PinAF.rst deleted file mode 100644 index f0b6711696..0000000000 --- a/docs/library/pyb.PinAF.rst +++ /dev/null @@ -1,51 +0,0 @@ -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 diff --git a/docs/library/pyb.RTC.rst b/docs/library/pyb.RTC.rst index a43f335c95..2f9114ac2b 100644 --- a/docs/library/pyb.RTC.rst +++ b/docs/library/pyb.RTC.rst @@ -1,5 +1,5 @@ -class RTC --- real time clock -============================= +class RTC -- real time clock +============================ The RTC is and independent clock that keeps track of the date and time. diff --git a/docs/library/pyb.SPI.rst b/docs/library/pyb.SPI.rst index db77083064..7ad3a90e2d 100644 --- a/docs/library/pyb.SPI.rst +++ b/docs/library/pyb.SPI.rst @@ -1,5 +1,5 @@ -class SPI --- a master-driven serial protocol -============================================= +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. diff --git a/docs/library/pyb.Servo.rst b/docs/library/pyb.Servo.rst index d75ed8a2d7..486e7a057a 100644 --- a/docs/library/pyb.Servo.rst +++ b/docs/library/pyb.Servo.rst @@ -1,5 +1,5 @@ -class Servo --- 3-wire hobby servo driver -========================================= +class Servo -- 3-wire hobby servo driver +======================================== Servo controls standard hobby servos with 3-wires (ground, power, signal). diff --git a/docs/library/pyb.Switch.rst b/docs/library/pyb.Switch.rst index 347c2615ea..daaed19420 100644 --- a/docs/library/pyb.Switch.rst +++ b/docs/library/pyb.Switch.rst @@ -1,5 +1,5 @@ -class Switch --- switch object -============================== +class Switch -- switch object +============================= A Switch object is used to control a push-button switch. diff --git a/docs/library/pyb.Timer.rst b/docs/library/pyb.Timer.rst index 5d657e871a..96ea48f0dc 100644 --- a/docs/library/pyb.Timer.rst +++ b/docs/library/pyb.Timer.rst @@ -1,5 +1,5 @@ -class Timer --- control internal timers -======================================= +class Timer -- control internal timers +====================================== 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. diff --git a/docs/library/pyb.UART.rst b/docs/library/pyb.UART.rst index f9760734bc..66f5cc5da2 100644 --- a/docs/library/pyb.UART.rst +++ b/docs/library/pyb.UART.rst @@ -1,5 +1,5 @@ -class UART --- duplex serial communication bus -============================================== +class UART -- duplex serial communication bus +============================================= UART implements the standard UART/USART duplex serial communications protocol. At the physical level it consists of 2 lines: RX and TX. The unit of communication @@ -36,6 +36,8 @@ To check if there is anything to be read, use:: uart.any() # returns True if any characters waiting +*Note:* The stream functions ``read``, ``write`` etc Are new in Micro Python since v1.3.4. +Earlier versions use ``uart.send`` and ``uart.recv``. Constructors ------------ @@ -56,7 +58,6 @@ Constructors - ``UART(3)`` is on ``YB``: ``(TX, RX) = (Y9, Y10) = (PB10, PB11)`` - ``UART(2)`` is on: ``(TX, RX) = (X3, X4) = (PA2, PA3)`` - Methods ------- @@ -87,13 +88,18 @@ Methods Read characters. If ``nbytes`` is specified then read at most that many bytes. - *Note:* for 9 bit characters each character takes 2 bytes, ``nbytes`` must be even, - and the number of characters is ``nbytes/2``. + *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. .. method:: uart.readall() Read as much data as possible. + Return value: a bytes object. + .. method:: uart.readchar() Receive a single character on the bus. @@ -102,12 +108,25 @@ Methods .. method:: uart.readinto(buf[, nbytes]) + Read bytes into the ``buf``. If ``nbytes`` is specified then read at most + that many bytes. Otherwise, read at most ``len(buf)`` bytes. + + Return value: number of bytes read and stored into ``buf``. .. method:: uart.readline() + Read a line, ending in a newline character. + + Return value: the line read. .. 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. + + Return value: number of bytes written. .. method:: uart.writechar(char) diff --git a/docs/library/pyb.USB_VCP.rst b/docs/library/pyb.USB_VCP.rst index dad2ab4a52..7330640728 100644 --- a/docs/library/pyb.USB_VCP.rst +++ b/docs/library/pyb.USB_VCP.rst @@ -1,5 +1,5 @@ -class USB_VCP --- USB virtual comm port -======================================= +class USB_VCP -- USB virtual comm port +====================================== The USB_VCP class allows creation of an object representing the USB virtual comm port. It can be used to read and write data over USB to diff --git a/docs/library/pyb.rst b/docs/library/pyb.rst index d78dac4254..d221e9720c 100644 --- a/docs/library/pyb.rst +++ b/docs/library/pyb.rst @@ -160,7 +160,6 @@ Classes pyb.I2C.rst pyb.LCD.rst pyb.LED.rst - pyb.PinAF.rst pyb.Pin.rst pyb.RTC.rst pyb.Servo.rst diff --git a/docs/library/select.rst b/docs/library/select.rst index aceb190720..22e4c2097b 100644 --- a/docs/library/select.rst +++ b/docs/library/select.rst @@ -1,37 +1,52 @@ -:mod:`select` --- Provides select function to wait for events on a stream -========================================================================= +:mod:`select` -- Provides select function to wait for events on a stream +======================================================================== .. module:: select :synopsis: Provides select function to wait for events on a stream This module provides the select function. +Pyboard specifics +----------------- + +Polling is an efficient way of waiting for read/write activity on multiple +objects. Current objects that support polling are: :class:`pyb.UART`, +:class:`pyb.USB_VCP`. Functions --------- .. function:: poll() + Create an instance of the Poll class. .. function:: select(rlist, wlist, xlist[, timeout]) + Wait for activity on a set of objects. -class Poll ----------- +.. _class: Poll +class ``Poll`` +-------------- Methods -------- +~~~~~~~ -.. method:: poll.modify(obj, eventmask) +.. method:: poll.register(obj[, eventmask]) + Register ``obj`` for polling. ``eventmask`` is 1 for read, 2 for + write, 3 for read-write. -.. method:: poll.poll([timeout]) +.. method:: poll.unregister(obj) - Timeout is in milliseconds. + Unregister ``obj`` from polling. -.. method:: poll.register(obj[, eventmask]) +.. method:: poll.modify(obj, eventmask) + Modify the ``eventmask`` for ``obj``. -.. method:: poll.unregister(obj) +.. method:: poll.poll([timeout]) + + Wait for one of the registered objects to become ready. + Timeout is in milliseconds. diff --git a/docs/library/sys.rst b/docs/library/sys.rst index b46be4d0de..8e05ac23f1 100644 --- a/docs/library/sys.rst +++ b/docs/library/sys.rst @@ -1,11 +1,9 @@ -:mod:`sys` --- system specific functions -======================================== +:mod:`sys` -- system specific functions +======================================= .. module:: sys :synopsis: system specific functions - - Functions --------- @@ -14,7 +12,6 @@ Functions Raise a ``SystemExit`` exception. If an argument is given, it is the value given to ``SystemExit``. - Constants --------- diff --git a/docs/library/time.rst b/docs/library/time.rst index a12eab3b23..1ffce7c247 100644 --- a/docs/library/time.rst +++ b/docs/library/time.rst @@ -1,5 +1,5 @@ -:mod:`time` --- time related functions -====================================== +:mod:`time` -- time related functions +===================================== .. module:: time :synopsis: time related functions @@ -7,7 +7,6 @@ The ``time`` module provides functions for getting the current time and date, and for sleeping. - Functions --------- @@ -16,14 +15,15 @@ Functions Convert a time expressed in seconds since Jan 1, 2000 into an 8-tuple which contains: (year, month, mday, hour, minute, second, weekday, yearday) If secs is not provided or None, then the current time from the RTC is used. - year includes the century (for example 2014) - month is 1-12 - mday is 1-31 - hour is 0-23 - minute is 0-59 - second is 0-59 - weekday is 0-6 for Mon-Sun. - yearday is 1-366 + year includes the century (for example 2014). + + * month is 1-12 + * mday is 1-31 + * hour is 0-23 + * minute is 0-59 + * second is 0-59 + * weekday is 0-6 for Mon-Sun + * yearday is 1-366 .. function:: mktime() diff --git a/docs/library/uheapq.rst b/docs/library/uheapq.rst index 05c8ad1759..59b52e5521 100644 --- a/docs/library/uheapq.rst +++ b/docs/library/uheapq.rst @@ -1,5 +1,5 @@ -:mod:`uheapq` --- heap queue algorithm -====================================== +:mod:`uheapq` -- heap queue algorithm +===================================== .. module:: uheapq :synopsis: heap queue algorithm diff --git a/docs/library/ujson.rst b/docs/library/ujson.rst index 188fb2d392..724bc90ee1 100644 --- a/docs/library/ujson.rst +++ b/docs/library/ujson.rst @@ -1,5 +1,5 @@ -:mod:`ujson` --- JSON encoding and decoding -=========================================== +:mod:`ujson` -- JSON encoding and decoding +========================================== .. module:: ujson :synopsis: JSON encoding and decoding diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index 271e83da8c..cf79973f17 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -1,12 +1,11 @@ -:mod:`usocket` --- socket module -================================ +:mod:`usocket` -- socket module +=============================== .. module:: usocket :synopsis: socket module Socket functionality. - Functions --------- |