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

cc3200/mods/modmachine.c

@@ -40,18 +40,13 @@
 #include "rom_map.h"
 #include "prcm.h"
 #include "pyexec.h"
-#include "ff.h"
-#include "diskio.h"
-#include "sflash_diskio.h"
 #include "pybuart.h"
 #include "pybpin.h"
 #include "pybrtc.h"
-#include "mpsystick.h"
 #include "simplelink.h"
 #include "modnetwork.h"
 #include "modwlan.h"
 #include "moduos.h"
-#include "telnet.h"
 #include "FreeRTOS.h"
 #include "portable.h"
 #include "task.h"
@@ -67,7 +62,6 @@
 #include "utils.h"
 #include "gccollect.h"
 #include "mperror.h"
-#include "genhdr/mpversion.h"
 
 
 #ifdef DEBUG

cc3200/mods/pybuart.c

@@ -558,7 +558,7 @@ STATIC mp_obj_t pyb_uart_irq (mp_uint_t n_args, const mp_obj_t *pos_args, mp_map
 invalid_args:
     nlr_raise(mp_obj_new_exception_msg(&mp_type_ValueError, mpexception_value_invalid_arguments));
 }
-STATIC MP_DEFINE_CONST_FUN_OBJ_KW(pyb_uart_callback_obj, 1, pyb_uart_irq);
+STATIC MP_DEFINE_CONST_FUN_OBJ_KW(pyb_uart_irq_obj, 1, pyb_uart_irq);
 
 STATIC const mp_map_elem_t pyb_uart_locals_dict_table[] = {
     // instance methods
@@ -566,7 +566,7 @@ STATIC const mp_map_elem_t pyb_uart_locals_dict_table[] = {
     { MP_OBJ_NEW_QSTR(MP_QSTR_deinit),      (mp_obj_t)&pyb_uart_deinit_obj },
     { MP_OBJ_NEW_QSTR(MP_QSTR_any),         (mp_obj_t)&pyb_uart_any_obj },
     { MP_OBJ_NEW_QSTR(MP_QSTR_sendbreak),   (mp_obj_t)&pyb_uart_sendbreak_obj },
-    { MP_OBJ_NEW_QSTR(MP_QSTR_irq),         (mp_obj_t)&pyb_uart_callback_obj },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_irq),         (mp_obj_t)&pyb_uart_irq_obj },
 
     /// \method read([nbytes])
     { MP_OBJ_NEW_QSTR(MP_QSTR_read),        (mp_obj_t)&mp_stream_read_obj },

docs/conf.py

@@ -300,6 +300,11 @@ html_context = {
 
 # Append the other ports' specific folders/files to the exclude pattern
 exclude_patterns.extend([port + '*' for port in ports if port != micropy_port])
+# Exclude pyb module if the port is the WiPy
+if micropy_port == 'wipy':
+    exclude_patterns.append('library/pyb*')
+else: # exclude machine
+    exclude_patterns.append('library/machine*')
 
 # Specify a custom master document based on the port name
 master_doc = micropy_port + '_' + 'index'

docs/library/index.rst

@@ -74,12 +74,12 @@ it will fallback to loading the built-in ``ujson`` module.
 
    Libraries specific to the pyboard
    ---------------------------------
-    
+
    The following libraries are specific to the pyboard.
-    
+
    .. toctree::
       :maxdepth: 2
-    
+
       pyb.rst
       network.rst
 
@@ -87,10 +87,8 @@ it will fallback to loading the built-in ``ujson`` module.
 
    .. toctree::
       :maxdepth: 1
-    
+
       ubinascii.rst
-      uhashlib.rst
-      uheapq.rst
       ujson.rst
       ure.rst
       usocket.rst
@@ -105,7 +103,7 @@ it will fallback to loading the built-in ``ujson`` module.
    .. toctree::
       :maxdepth: 2
 
-      pyb.rst
+      machine.rst
       network.rst
 
 

docs/library/machine.ADC.rst

+.. _machine.ADC:
+
+class ADC -- analog to digital conversion
+=========================================
+
+Usage::
+
+   import machine
+
+   adc = machine.ADC()             # create an ADC object
+   apin = adc.channel(pin='GP3')   # create an analog pin on GP3
+   val = apin()                    # read an analog value
+
+Constructors
+------------
+
+.. class:: machine.ADC(id=0, \*, bits=12)
+
+   Create an ADC object associated with the given pin.
+   This allows you to then read analog values on that pin.
+   For more info check the `pinout and alternate functions
+   table. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_ 
+
+   .. warning:: 
+
+      ADC pin input range is 0-1.4V (being 1.8V the absolute maximum that it 
+      can withstand). When GP2, GP3, GP4 or GP5 are remapped to the 
+      ADC block, 1.8 V is the maximum. If these pins are used in digital mode, 
+      then the maximum allowed input is 3.6V.
+
+Methods
+-------
+
+.. method:: adc.channel(id, \*, pin)
+
+   Create an analog pin. If only channel ID is given, the correct pin will
+   be selected. Alternatively, only the pin can be passed and the correct
+   channel will be selected. Examples::
+
+      # all of these are equivalent and enable ADC channel 1 on GP3
+      apin = adc.channel(1)
+      apin = adc.channel(pin='GP3')
+      apin = adc.channel(id=1, pin='GP3')
+
+.. method:: adc.init()
+
+   Enable the ADC block.
+
+.. method:: adc.deinit()
+
+   Disable the ADC block.
+
+class ADCChannel --- read analog values from internal or external sources
+=========================================================================
+
+ADC channels can be connected to internal points of the MCU or to GPIO pins.
+ADC channels are created using the ADC.channel method.
+
+.. method:: adcchannel()
+
+   Fast method to read the channel value.
+
+.. method:: adcchannel.value()
+
+   Read the channel value.
+
+.. method:: adcchannel.init()
+
+   Re-init (and effectively enable) the ADC channel.
+
+.. method:: adcchannel.deinit()
+
+   Disable the ADC channel.

docs/library/pyb.HeartBeat.rst → docs/library/machine.HeartBeat.rst

-.. _pyb.HeartBeat:
+.. _machine.HeartBeat:
 
 class HeartBeat -- heart beat LED
 =================================
@@ -11,14 +11,14 @@ can be used to control the light intesity of the heart beat LED.
 
 Example usage::
 
-    hb = pyb.HeartBeat()
+    hb = machine.HeartBeat()
     hb.disable()    # disable the heart beat
     hb.enable()     # enable the heart beat
 
 Constructors
 ------------
 
-.. class:: pyb.HeartBeat()
+.. class:: machine.HeartBeat()
 
    Create a HeartBeat object.
 
@@ -35,12 +35,13 @@ Methods
 
    Example::
    
-      import pyb
+      from machine import HeartBeat
+      from machine import Pin
    
       # disable the heart beat
-      pyb.HeartBeat().disable()
-      # get the GP25 pin object
-      hbl = pyb.Pin('GP25')
+      HeartBeat().disable()
+      # init GP25 as output
+      led = Pin('GP25', mode=Pin.OUT)
       # toggle the led
-      hbl.toggle()
+      led.toggle()
       ...

docs/library/machine.I2C.rst

+.. _machine.I2C:
+
+class I2C -- a two-wire serial protocol
+=======================================
+
+I2C is a two-wire protocol for communicating between devices.  At the physical
+level it consists of 2 wires: SCL and SDA, the clock and data lines respectively.
+
+I2C objects are created attached to a specific bus.  They can be initialised
+when created, or initialised later on.
+
+.. only:: port_wipy
+
+    Example::
+
+        from machine import I2C
+
+        i2c = I2C(0)                         # create on bus 0
+        i2c = I2C(0, I2C.MASTER)             # create and init as a master
+        i2c.init(I2C.MASTER, baudrate=20000) # init as a master
+        i2c.deinit()                         # turn off the peripheral
+
+Printing the i2c object gives you information about its configuration.
+
+.. only:: port_wipy
+
+    A master must specify the recipient's address::
+
+        i2c.init(I2C.MASTER)
+        i2c.writeto(0x42, '123')        # send 3 bytes to slave with address 0x42
+        i2c.writeto(addr=0x42, b'456')  # keyword for address
+
+    Master also has other methods::
+
+        i2c.scan()                          # scan for slaves on the bus, returning
+                                            #   a list of valid addresses
+        i2c.readfrom_mem(0x42, 2, 3)        # read 3 bytes from memory of slave 0x42,
+                                            #   starting at address 2 in the slave
+        i2c.writeto_mem(0x42, 2, 'abc')     # write 'abc' (3 bytes) to memory of slave 0x42
+                                            # starting at address 2 in the slave, timeout after 1 second
+
+Constructors
+------------
+
+.. only:: port_wipy
+
+    .. class:: machine.I2C(bus, ...)
+
+       Construct an I2C object on the given bus.  `bus` can only be 0.
+       If the bus is not given, the default one will be selected (0).
+
+Methods
+-------
+
+.. method:: i2c.deinit()
+
+   Turn off the I2C bus.
+
+.. only:: port_wipy
+
+    .. method:: i2c.init(mode, \*, baudrate=100000, pins=(SDA, SCL))
+
+      Initialise the I2C bus with the given parameters:
+
+         - ``mode`` must be ``I2C.MASTER``
+         - ``baudrate`` is the SCL clock rate
+         - ``pins`` is an optional tuple with the pins to assign to the I2C bus.
+
+    .. method:: i2c.readfrom(addr, nbytes)
+
+        Read ``nbytes`` from the slave specified by ``addr``.
+        Returns a ``bytes`` object with the data read.
+
+    .. method:: i2c.readfrom_into(addr, buf)
+
+        Read into ``buf`` from the slave specified by ``addr``.
+        Returns the number of bytes read.
+
+    .. method:: i2c.writeto(addr, buf, \*, stop=True)
+
+        Write ``buf`` to the slave specified by ``addr``. Set ``stop`` to ``False``
+        if the transfer should be continued.
+        Returns the number of bytes written.
+
+    .. method:: i2c.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8)
+
+        Read ``nbytes`` from the slave specified by ``addr`` starting from the memory
+        address specified by ``memaddr``.
+        Param ``addrsize`` specifies the address size in bits.
+        Returns a ``bytes`` object with the data read.
+
+    .. method:: i2c.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8)
+
+        Read into ``buf`` from the slave specified by ``addr`` starting from the memory
+        address specified by ``memaddr``.
+        Param ``addrsize`` specifies the address size in bits.
+        Returns the number of bytes read.
+
+    .. method:: i2c.writeto_mem(addr, memaddr, buf, \*, addrsize=8)
+
+        Write ``buf`` to the slave specified by ``addr`` starting from the
+        memory address specified by ``memaddr``. Param ``addrsize`` specifies the 
+        address size in bits.
+        Set ``stop`` to ``False`` if the transfer should be continued.
+        Returns the number of bytes written.
+
+.. method:: i2c.scan()
+
+   Scan all I2C addresses from 0x01 to 0x7f and return a list of those that respond.
+   Only valid when in master mode.
+
+Constants
+---------
+
+.. data:: I2C.MASTER
+
+   for initialising the bus to master mode

docs/library/machine.Pin.rst

+.. _machine.Pin:
+
+class Pin -- control I/O pins
+=============================
+
+A pin is the basic object to control I/O pins.  It has methods to set
+the mode of the pin (input, output, etc) and methods to get and set the
+digital logic level. For analog control of a pin, see the ADC class.
+
+Usage Model:
+
+.. only:: port_wipy
+
+    Board pins are identified by their string id::
+
+        g = machine.Pin('GP9', mode=machine.Pin.OUT, pull=None, drive=machine.Pin.MED_POWER, alt=-1)
+
+    You can also configure the Pin to generate interrupts. For instance::
+
+        def pincb(pin):
+            print(pin.id())
+
+        pin_int = machine.Pin('GP10', mode=Pin.IN, pull=machine.Pin.PULL_DOWN)
+        pin_int.irq(mode=machine.Pin.IRQ_RISING, handler=pincb)
+        # the callback can be triggered manually
+        pin_int.irq()()
+        # to disable the callback
+        pin_int.irq().disable()
+
+    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.
+
+    All pin objects go through the pin mapper to come up with one of the
+    gpio pins.
+
+Constructors
+------------
+
+.. class:: machine.Pin(id, ...)
+
+   Create a new Pin object associated with the id.  If additional arguments are given,
+   they are used to initialise the pin.  See :meth:`pin.init`.
+
+Methods
+-------
+
+.. only:: port_wipy
+
+    .. method:: pin.init(mode, pull, \*, drive, alt)
+    
+       Initialise the pin:
+
+         - ``mode`` can be one of:
+
+            - ``Pin.IN``  - input pin.
+            - ``Pin.OUT`` - output pin in push-pull mode.
+            - ``Pin.OPEN_DRAIN`` - output pin in open-drain mode.
+            - ``Pin.ALT`` - pin mapped to an alternate function.
+            - ``Pin.ALT_OPEN_DRAIN`` - pin mapped to an alternate function in open-drain mode.
+
+         - ``pull`` can be one of:
+
+            - ``None`` - no pull up or down resistor.
+            - ``Pin.PULL_UP`` - pull up resistor enabled.
+            - ``Pin.PULL_DOWN`` - pull down resitor enabled.
+
+         - ``drive`` can be one of:
+
+            - ``Pin.LOW_POWER`` - 2mA drive capability.
+            - ``Pin.MED_POWER`` - 4mA drive capability.
+            - ``Pin.HIGH_POWER`` - 6mA drive capability.
+
+         - ``alt`` is the number of the alternate function. Please refer to the
+           `pinout and alternate functions table. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_
+           for the specific alternate functions that each pin supports.
+
+       Returns: ``None``.
+
+    .. method:: pin.id()
+
+       Get the pin id.
+
+.. method:: pin.value([value])
+
+   Get or set the digital logic level of the pin:
+
+     - With no argument, return 0 or 1 depending on the logic level of the pin.
+     - With ``value`` given, set the logic level of the pin.  ``value`` can be
+       anything that converts to a boolean.  If it converts to ``True``, the pin
+       is set high, otherwise it is set low.
+
+.. method:: pin.alt_list()
+
+    Returns a list of the alternate functions supported by the pin. List items are
+    a tuple of the form: ``('ALT_FUN_NAME', ALT_FUN_INDEX)``
+
+.. only:: port_wipy
+
+    .. method:: pin([value])
+
+       Pin objects are callable. The call method provides a (fast) shortcut to set and get the value of the pin.
+       See **pin.value** for more details.
+
+    .. method:: pin.toggle()
+
+        Toggle the value of the pin.
+
+    .. method:: pin.mode([mode])
+
+        Get or set the pin mode.
+
+    .. method:: pin.pull([pull])
+
+        Get or set the pin pull.
+
+    .. method:: pin.drive([drive])
+
+        Get or set the pin drive strength.
+
+    .. method:: pin.irq(\*, trigger, priority=1, handler=None, wake=None)
+
+        Create a callback to be triggered when the input level at the pin changes.
+
+            - ``trigger`` configures the pin level which can generate an interrupt. Possible values are:
+
+                - ``Pin.IRQ_FALLING`` interrupt on falling edge.
+                - ``Pin.IRQ_RISING`` interrupt on rising edge.
+                - ``Pin.IRQ_LOW_LEVEL`` interrupt on low level.
+                - ``Pin.IRQ_HIGH_LEVEL`` interrupt on high level.
+              
+              The values can be *ORed* together, for instance mode=Pin.IRQ_FALLING | Pin.IRQ_RISING
+
+            - ``priority`` level of the interrupt. Can take values in the range 1-7.
+              Higher values represent higher priorities.
+            - ``handler`` is an optional function to be called when new characters arrive.
+            - ``wakes`` selects the power mode in which this interrupt can wake up the
+              board. Please note:
+
+              - If ``wake_from=machine.Sleep.ACTIVE`` any pin can wake the board.
+              - If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``,
+                ``GP11``, GP17`` or ``GP24`` can wake the board. Note that only 1
+                of this pins can be enabled as a wake source at the same time, so, only
+                the last enabled pin as a ``machine.Sleep.SUSPENDED`` wake source will have effect.
+              - If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``,
+                ``GP11``, ``GP17`` and ``GP24`` can wake the board. In this case all of the
+                6 pins can be enabled as a ``machine.Sleep.HIBERNATE`` wake source at the same time.
+              - Values can be ORed to make a pin generate interrupts in more than one power
+                mode.
+
+            Returns a callback object.
+
+Attributes
+----------
+
+.. class:: Pin.board
+
+    Contains all ``Pin`` objects supported by the board. Examples::
+
+        Pin.board.GP25
+        led = Pin(Pin.board.GP25, mode=Pin.OUT)
+        Pin.board.GP2.alt_list()
+
+
+Constants
+---------
+
+.. only:: port_wipy
+
+    .. data:: Pin.IN
+
+    .. data:: Pin.OUT
+    
+    .. data:: Pin.OPEN_DRAIN
+
+    .. data:: Pin.ALT
+
+    .. data:: Pin.ALT_OPEN_DRAIN
+
+       Selects the pin mode.
+
+    .. data:: Pin.PULL_UP
+
+    .. data:: Pin.PULL_DOWN
+    
+       Selectes the wether there's pull up/down resistor.
+
+    .. data:: Pin.LOW_POWER
+
+    .. data:: Pin.MED_POWER
+
+    .. data:: Pin.HIGH_POWER
+
+        Selects the drive strength.
+
+    .. data:: Pin.IRQ_FALLING
+
+    .. data:: Pin.IRQ_RISING
+
+    .. data:: Pin.IRQ_LOW_LEVEL
+
+    .. data:: Pin.IRQ_HIGH_LEVEL
+
+        Selects the IRQ trigger type.

docs/library/machine.RTC.rst

+.. _machine.RTC:
+
+class RTC -- real time clock
+============================
+
+The RTC is and independent clock that keeps track of the date
+and time.
+
+Example usage::
+
+    rtc = machine.RTC()
+    rtc.datetime((2014, 5, 1, 4, 13, 0, 0, 0))
+    print(rtc.datetime())
+
+
+Constructors
+------------
+
+.. class:: machine.RTC(id=0, ...)
+
+   Create an RTC object. See init for parameters of initialization.
+
+Methods
+-------
+
+.. method:: rtc.init(id, datetime)
+
+   Initialise the RTC. Datetime is a tuple of the form:
+   
+      ``(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])``
+
+.. method:: rtc.now()
+
+   Get get the current datetime tuple.
+
+.. method:: rtc.deinit()
+
+   Resets the RTC to the time of January 1, 2015 and starts running it again.
+
+.. method:: rtc.alarm(id, time, /*, repeat=False)
+
+   Set the RTC alarm. Time might be either a milllisecond value to program the alarm to
+   current time + time_in_ms in the future, or a datetimetuple. If the time passed is in
+   milliseconds, repeat can be set to ``True`` to make the alarm periodic.
+
+.. method:: rtc.alarm_left(alarm_id=0)
+
+   Get the number of milliseconds left before the alarm expires.
+
+.. method:: rtc.cancel(alarm_id=0)
+
+   Cancel a running alarm.
+
+.. method:: rtc.irq(\*, trigger, handler=None, wake=machine.IDLE)
+
+   Create an irq object triggered by a real time clock alarm.
+
+      - ``trigger`` must be ``RTC.ALARM0``
+      - ``handler`` is the function to be called when the callback is triggered.
+      - ``wake`` specifies the sleep mode from where this interrupt can wake
+        up the system.
+
+Constants
+---------
+
+.. data:: RTC.ALARM0
+
+    irq trigger source

docs/library/pyb.SD.rst → docs/library/machine.SD.rst

-.. _pyb.SD:
+.. _machine.SD:
 
 class SD -- secure digital memory card
 ======================================
@@ -13,36 +13,30 @@ more info regarding the pins which can be remapped to be used with a SD card.
 
 Example usage::
 
-    # data, clk and cmd pins must be passed along with
+    from machine import SD
+    import os
+    # clk cmd and dat0 pins must be passed along with
     # their respective alternate functions
-    sd = pyb.SD(('GP15', 8, 'GP10', 6, 'GP11', 6))
-    sd.mount()
+    sd = machine.SD(pins=('GP10', 'GP11', 'GP15'))
+    os.mount(sd, '/sd')
     # do normal file operations
 
 Constructors
 ------------
 
-.. class:: pyb.SD([pins_tuple])
+.. class:: machine.SD(id,... )
 
-   Create a SD card object. In order to initalize the card, give it a 6-tuple
-   ``(dat_pin, dat_af, clk_pin, clk_af, cmd_pin, cmd_af)`` with the data, clock
-   and cmd pins together their respective alternate functions.
+   Create a SD card object. See init for parameters if initialization. 
 
 Methods
 -------
 
-.. method:: sd.init([pins_tuple])
+.. method:: sd.init(id, pins=('GP10', 'GP11', 'GP15'))
 
    Enable the SD card.
+   In order to initalize the card, give it a 3-tuple ``(clk_pin, cmd_pin, dat0_pin)``
+   ID defaults to zero.
 
 .. method:: sd.deinit()