From cfcf47c0644952358e1a260db159e807872a37e6 Mon Sep 17 00:00:00 2001 From: Daniel Campora Date: Wed, 10 Jun 2015 23:29:56 +0200 Subject: [PATCH] docs: Add initial draft documentation for the WiPy. This makes all common files "port-aware" using the .. only directive. --- README.md | 6 +- docs/conf.py | 8 +- docs/contents.rst | 20 - docs/esp8266_contents.rst | 7 + docs/esp8266_index.rst | 15 + docs/index.rst | 29 -- docs/library/index.rst | 110 ++++-- docs/library/micropython.rst | 34 +- docs/library/network.rst | 404 ++++++++++++++------- docs/library/os.rst | 16 +- docs/library/pyb.ADC.rst | 93 +++-- docs/library/pyb.HeartBeat.rst | 46 +++ docs/library/pyb.I2C.rst | 269 ++++++++++---- docs/library/pyb.Pin.rst | 565 +++++++++++++++++++---------- docs/library/pyb.RTC.rst | 78 ++-- docs/library/pyb.SD.rst | 39 ++ docs/library/pyb.SPI.rst | 251 +++++++++---- docs/library/pyb.UART.rst | 170 ++++++--- docs/library/pyb.WDT.rst | 33 ++ docs/library/pyb.rst | 335 ++++++++++------- docs/library/time.rst | 20 +- docs/library/uctypes.rst | 2 +- docs/library/uhashlib.rst | 70 +++- docs/pyboard/quickref.rst | 4 +- docs/pyboard/tutorial/amp_skin.rst | 4 +- docs/pyboard/tutorial/lcd_skin.rst | 4 +- docs/pyboard_contents.rst | 12 + docs/pyboard_index.rst | 19 + docs/topindex.html | 14 +- docs/wipy/general.rst | 59 +++ docs/wipy/quickref.rst | 228 ++++++++++++ docs/wipy_contents.rst | 9 + docs/wipy_index.rst | 17 + 33 files changed, 2155 insertions(+), 835 deletions(-) delete mode 100644 docs/contents.rst create mode 100644 docs/esp8266_contents.rst create mode 100644 docs/esp8266_index.rst delete mode 100644 docs/index.rst create mode 100644 docs/library/pyb.HeartBeat.rst create mode 100644 docs/library/pyb.SD.rst create mode 100644 docs/library/pyb.WDT.rst create mode 100644 docs/pyboard_contents.rst create mode 100644 docs/pyboard_index.rst create mode 100644 docs/wipy/general.rst create mode 100644 docs/wipy/quickref.rst create mode 100644 docs/wipy_contents.rst create mode 100644 docs/wipy_index.rst diff --git a/README.md b/README.md index 04df97935..2c9396b04 100644 --- a/README.md +++ b/README.md @@ -121,6 +121,8 @@ preferably in a virtualenv: In `micropython/docs`, build the docs: - make html + make MICROPY_PORT= BUILDDIR=/build html -You'll find the index page at `micropython/docs/build/html/index.html`. +Where ```` can be ``port_unix``, ``port_pyboard``, ``port_wipy`` or ``port_esp8266``. + +You'll find the index page at `micropython/docs//build/html/index.html`. diff --git a/docs/conf.py b/docs/conf.py index 5c5f28a7b..f2971992c 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -47,7 +47,7 @@ source_suffix = '.rst' #source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'index' +#master_doc = 'index' # General information about the project. project = 'MicroPython' @@ -297,3 +297,9 @@ html_context = { 'port_name':ports[micropy_port], 'all_ports':[(n, url_prefix + p) for p, n in ports.items()], } + +# Append the other ports' specific folders/files to the exclude pattern +exclude_patterns.extend([port + '*' for port in ports if port != micropy_port]) + +# Specify a custom master document based on the port name +master_doc = micropy_port + '_' + 'index' diff --git a/docs/contents.rst b/docs/contents.rst deleted file mode 100644 index 15b92f6a0..000000000 --- a/docs/contents.rst +++ /dev/null @@ -1,20 +0,0 @@ -MicroPython documentation contents -================================== - -.. only:: port_pyboard - - .. toctree:: - - pyboard/quickref.rst - pyboard/general.rst - pyboard/tutorial/index.rst - library/index.rst - pyboard/hardware/index.rst - license.rst - -.. only:: port_esp8266 - - .. toctree:: - - library/index.rst - license.rst diff --git a/docs/esp8266_contents.rst b/docs/esp8266_contents.rst new file mode 100644 index 000000000..d1bd69c61 --- /dev/null +++ b/docs/esp8266_contents.rst @@ -0,0 +1,7 @@ +MicroPython documentation contents +================================== + +.. toctree:: + + library/index.rst + license.rst \ No newline at end of file diff --git a/docs/esp8266_index.rst b/docs/esp8266_index.rst new file mode 100644 index 000000000..f8f5bedfc --- /dev/null +++ b/docs/esp8266_index.rst @@ -0,0 +1,15 @@ +MicroPython documentation and references +======================================== + +.. toctree:: + + library/index.rst + license.rst + esp8266_contents.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 3c074e55d..000000000 --- a/docs/index.rst +++ /dev/null @@ -1,29 +0,0 @@ -MicroPython documentation and references -======================================== - -.. only:: port_pyboard - - .. toctree:: - - pyboard/quickref.rst - pyboard/general.rst - pyboard/tutorial/index.rst - library/index.rst - pyboard/hardware/index.rst - license.rst - contents.rst - -.. only:: port_esp8266 - - .. toctree:: - - library/index.rst - license.rst - contents.rst - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/library/index.rst b/docs/library/index.rst index 245a345f3..f00bd1c20 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -17,17 +17,30 @@ The following standard Python libraries are built in to MicroPython. For additional libraries, please download them from the `micropython-lib repository `_. -.. toctree:: - :maxdepth: 1 +.. only:: port_pyboard - cmath.rst - gc.rst - math.rst - os.rst - select.rst - struct.rst - sys.rst - time.rst + .. toctree:: + :maxdepth: 1 + + cmath.rst + gc.rst + math.rst + os.rst + select.rst + struct.rst + sys.rst + time.rst + +.. only:: port_wipy + + .. toctree:: + :maxdepth: 1 + + gc.rst + os.rst + select.rst + sys.rst + time.rst Python micro-libraries ---------------------- @@ -43,37 +56,68 @@ For example, ``import json`` will first search for a file ``json.py`` or directory ``json`` and load that package if it is found. If nothing is found, it will fallback to loading the built-in ``ujson`` module. -.. toctree:: - :maxdepth: 1 +.. only:: port_pyboard - ubinascii.rst - uctypes.rst - uhashlib.rst - uheapq.rst - ujson.rst - ure.rst - usocket.rst - uzlib.rst + .. toctree:: + :maxdepth: 1 + + ubinascii.rst + uctypes.rst + uhashlib.rst + uheapq.rst + ujson.rst + ure.rst + usocket.rst + uzlib.rst -Libraries specific to the pyboard ---------------------------------- +.. only:: port_pyboard -The following libraries are specific to the pyboard. + Libraries specific to the pyboard + --------------------------------- + + The following libraries are specific to the pyboard. + + .. toctree:: + :maxdepth: 2 + + pyb.rst + network.rst -.. toctree:: - :maxdepth: 2 +.. only:: port_wipy + + .. toctree:: + :maxdepth: 1 + + ubinascii.rst + uhashlib.rst + uheapq.rst + ujson.rst + ure.rst + usocket.rst + +.. only:: port_wipy + + Libraries specific to the WiPy + --------------------------------- + + The following libraries are specific to the WiPy. + + .. toctree:: + :maxdepth: 2 + + pyb.rst + network.rst - pyb.rst - network.rst .. only:: port_esp8266 - Libraries specific to the ESP8266 - --------------------------------- + Libraries specific to the ESP8266 + --------------------------------- - The following libraries are specific to the ESP8266. + The following libraries are specific to the ESP8266. - .. toctree:: - :maxdepth: 2 + .. toctree:: + :maxdepth: 2 - esp.rst + pyb.rst + esp.rst diff --git a/docs/library/micropython.rst b/docs/library/micropython.rst index 83ccb2900..14e4c917e 100644 --- a/docs/library/micropython.rst +++ b/docs/library/micropython.rst @@ -7,23 +7,25 @@ Functions --------- -.. function:: mem_info([verbose]) +.. only:: port_pyboard or port_unix - Print information about currently used memory. If the ``verbose`` argument - is given then extra information is printed. - - The information that is printed is implementation dependent, but currently - includes the amount of stack and heap used. In verbose mode it prints out - the entire heap indicating which blocks are used and which are free. - -.. function:: qstr_info([verbose]) - - Print information about currently interned strings. If the ``verbose`` - argument is given then extra information is printed. - - The information that is printed is implementation dependent, but currently - includes the number of interned strings and the amount of RAM they use. In - verbose mode it prints out the names of all RAM-interned strings. + .. function:: mem_info([verbose]) + + Print information about currently used memory. If the ``verbose`` argument + is given then extra information is printed. + + The information that is printed is implementation dependent, but currently + includes the amount of stack and heap used. In verbose mode it prints out + the entire heap indicating which blocks are used and which are free. + + .. function:: qstr_info([verbose]) + + Print information about currently interned strings. If the ``verbose`` + argument is given then extra information is printed. + + The information that is printed is implementation dependent, but currently + includes the number of interned strings and the amount of RAM they use. In + verbose mode it prints out the names of all RAM-interned strings. .. function:: alloc_emergency_exception_buf(size) diff --git a/docs/library/network.rst b/docs/library/network.rst index 62a65144f..b5a674acf 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -27,151 +27,297 @@ For example:: data = s.recv(1000) s.close() -class CC3K -========== +.. only:: port_pyboard -This class provides a driver for CC3000 wifi modules. Example usage:: + class CC3K + ========== + + This class provides a driver for CC3000 wifi modules. Example usage:: + + import network + nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3) + nic.connect('your-ssid', 'your-password') + while not nic.isconnected(): + pyb.delay(50) + print(nic.ifconfig()) + + # now use socket as usual + ... + + For this example to work the CC3000 module must have the following connections: + + - MOSI connected to Y8 + - MISO connected to Y7 + - CLK connected to Y6 + - CS connected to Y5 + - VBEN connected to Y4 + - IRQ connected to Y3 + + It is possible to use other SPI busses and other pins for CS, VBEN and IRQ. + + Constructors + ------------ + + .. class:: CC3K(spi, pin_cs, pin_en, pin_irq) + + Create a CC3K driver object, initialise the CC3000 module using the given SPI bus + and pins, and return the CC3K object. + + Arguments are: + + - ``spi`` is an :ref:`SPI object ` which is the SPI bus that the CC3000 is + connected to (the MOSI, MISO and CLK pins). + - ``pin_cs`` is a :ref:`Pin object ` which is connected to the CC3000 CS pin. + - ``pin_en`` is a :ref:`Pin object ` which is connected to the CC3000 VBEN pin. + - ``pin_irq`` is a :ref:`Pin object ` which is connected to the CC3000 IRQ pin. + + All of these objects will be initialised by the driver, so there is no need to + initialise them yourself. For example, you can use:: + + nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3) + + Methods + ------- + + .. method:: cc3k.connect(ssid, key=None, \*, security=WPA2, bssid=None) + + Connect to a wifi access point using the given SSID, and other security + parameters. + + .. method:: cc3k.disconnect() + + Disconnect from the wifi access point. + + .. method:: cc3k.isconnected() + + Returns True if connected to a wifi access point and has a valid IP address, + False otherwise. + + .. method:: cc3k.ifconfig() + + Returns a 7-tuple with (ip, subnet mask, gateway, DNS server, DHCP server, + MAC address, SSID). + + .. method:: cc3k.patch_version() + + Return the version of the patch program (firmware) on the CC3000. + + .. method:: cc3k.patch_program('pgm') + + Upload the current firmware to the CC3000. You must pass 'pgm' as the first + argument in order for the upload to proceed. + + Constants + --------- + + .. data:: CC3K.WEP + .. data:: CC3K.WPA + .. data:: CC3K.WPA2 + + security type to use + + class WIZNET5K + ============== + + This class allows you to control WIZnet5x00 Ethernet adaptors based on + the W5200 and W5500 chipsets (only W5200 tested). + + Example usage:: + + import network + nic = network.WIZNET5K(pyb.SPI(1), pyb.Pin.board.X5, pyb.Pin.board.X4) + print(nic.ifconfig()) + + # now use socket as usual + ... + + For this example to work the WIZnet5x00 module must have the following connections: + + - MOSI connected to X8 + - MISO connected to X7 + - SCLK connected to X6 + - nSS connected to X5 + - nRESET connected to X4 + + It is possible to use other SPI busses and other pins for nSS and nRESET. + + Constructors + ------------ + + .. class:: WIZNET5K(spi, pin_cs, pin_rst) + + Create a WIZNET5K driver object, initialise the WIZnet5x00 module using the given + SPI bus and pins, and return the WIZNET5K object. + + Arguments are: + + - ``spi`` is an :ref:`SPI object ` which is the SPI bus that the WIZnet5x00 is + connected to (the MOSI, MISO and SCLK pins). + - ``pin_cs`` is a :ref:`Pin object ` which is connected to the WIZnet5x00 nSS pin. + - ``pin_rst`` is a :ref:`Pin object ` which is connected to the WIZnet5x00 nRESET pin. + + All of these objects will be initialised by the driver, so there is no need to + initialise them yourself. For example, you can use:: + + nic = network.WIZNET5K(pyb.SPI(1), pyb.Pin.board.X5, pyb.Pin.board.X4) + + Methods + ------- + + .. method:: wiznet5k.ifconfig([(ip, subnet, gateway, dns)]) + + Get/set IP address, subnet mask, gateway and DNS. + + When called with no arguments, this method returns a 4-tuple with the above information. + + To set the above values, pass a 4-tuple with the required information. For example:: + + nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) + + .. method:: wiznet5k.regs() + + Dump the WIZnet5x00 registers. Useful for debugging. - import network - nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3) - nic.connect('your-ssid', 'your-password') - while not nic.isconnected(): - pyb.delay(50) - print(nic.ifconfig()) +.. only:: port_wipy - # now use socket as usual - ... + class WLAN + ========== -For this example to work the CC3000 module must have the following connections: + .. _network.WLAN: - - MOSI connected to Y8 - - MISO connected to Y7 - - CLK connected to Y6 - - CS connected to Y5 - - VBEN connected to Y4 - - IRQ connected to Y3 + This class provides a driver for WiFi network processor in the WiPy. Example usage:: + + import network + # setup as a station + nic = network.WLAN(WLAN.STA) + nic.connect('your-ssid', security=WLAN.WPA_WPA2, key='your-key') + while not nic.isconnected(): + pyb.delay(50) + print(nic.ifconfig()) -It is possible to use other SPI busses and other pins for CS, VBEN and IRQ. + # now use socket as usual + ... -Constructors ------------- + Constructors + ------------ + + .. class:: WLAN(mode, ssid, \*, security=WLAN.OPEN, key=None, channel=5) + + Create a WLAN driver object, initialise the WLAN engine in station or AP mode. + + Arguments are: + + - ``mode`` can be either ``WLAN.STA`` or ``WLAN.AP``. + - ``ssid`` is a string with the ssid name. Only needed when mode is ``WLAN.AP``. + - ``security`` can be ``WLAN.OPEN``, ``WLAN.WEP`` or ``WLAN.WPA_WPA2``. + Only needed when mode is ``WLAN.AP``. + - ``key`` is a string with the ``WLAN.WPA_WPA2`` key or a byte array with the + ``WLAN.WEP`` key. Not needed when mode is ``WLAN.STA`` or security is ``WLAN.OPEN``. + - ``channel`` a number in the range 1-11. Only needed when mode is ``WLAN.AP``. + + For example, you can use:: -.. class:: CC3K(spi, pin_cs, pin_en, pin_irq) + # configure as an access point + nic = network.WLAN(WLAN.AP, 'wipy-wlan', security=WLAN.WPA_WPA2, key='www.wipy.io', channel=7) - Create a CC3K driver object, initialise the CC3000 module using the given SPI bus - and pins, and return the CC3K object. + or:: - Arguments are: + # configure as an station + nic = network.WLAN(WLAN.STA) + + Methods + ------- + + .. method:: wlan.connect(ssid, \*, security=WLAN.OPEN, key=None, bssid=None, timeout=5000) + + Connect to a wifi access point using the given SSID, and other security + parameters. + + - ``bssid`` is the MAC address of the AP to connect to. Useful when there are several APs + with the same ssid. + - ``timeout`` is the maximum time in milliseconds to wait for the connection to succeed. + + .. method:: wlan.scan() + + Performs a network scan and returns a list of named tuples with (ssid, bssid, security, channel, rssi). + Note that channel is always ``None`` since this info is not provided by the WiPy. + + .. method:: wlan.disconnect() + + Disconnect from the wifi access point. + + .. method:: wlan.isconnected() + + Returns True if connected to a wifi access point and has a valid IP address, + False otherwise. + + .. method:: wlan.ifconfig(['dhcp' or configtuple]) + + With no parameters given eturns a 4-tuple of ``(ip, subnet mask, gateway, DNS server)``. + + if ``'dhcp'`` is passed as a parameter then the DHCP client is enabled and the IP params + are negotiated with the AP. + + if the 4-tuple config is given then a static IP is configured. For example:: + + nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) + + .. method:: wlan.info() + + Provides information about the current WLAN configuration. Returns a named tuple + of (mode, ssid, security, mac) + + - ``mode`` can be either ``WLAN.STA`` or ``WLAN.AP``. + - ``ssid`` is a string with our ssid if in AP mode, ``None`` oterwise. + - ``security`` security type currently used. + - ``mac`` our MAC address. + + .. method:: wlan.connections() + + Returns a list of the devices currently connected. Each item in the list is a + tuple of ``(ssid, mac)``. + + .. method:: wlan.antenna(antenna_type) + + Selects the antenna type to be used. Must be either ``WLAN.INT_ANTENNA`` or + ``WLAN.EXT_ANTENNA``. - - ``spi`` is an :ref:`SPI object ` which is the SPI bus that the CC3000 is - connected to (the MOSI, MISO and CLK pins). - - ``pin_cs`` is a :ref:`Pin object ` which is connected to the CC3000 CS pin. - - ``pin_en`` is a :ref:`Pin object ` which is connected to the CC3000 VBEN pin. - - ``pin_irq`` is a :ref:`Pin object ` which is connected to the CC3000 IRQ pin. + .. method:: wlan.callback(wakes) - All of these objects will be initialised by the driver, so there is no need to - initialise them yourself. For example, you can use:: + Create a callback to be triggered when a WLAN event occurs during ``pyb.Sleep.SUSPENDED`` + mode. Events are triggered by socket activity or by WLAN connection/disconnection. - nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3) + - ``wakes`` can only be ``pyb.Sleep.SUSPENDED``. -Methods -------- + Returns a callback object. -.. method:: cc3k.connect(ssid, key=None, \*, security=WPA2, bssid=None) + Constants + --------- + + .. data:: WLAN.STA + + WiFi station mode + + .. data:: WLAN.AP - Connect to a wifi access point using the given SSID, and other security - parameters. + WiFi access point mode -.. method:: cc3k.disconnect() + .. data:: WLAN.OPEN + + open network (no security) + + .. data:: WLAN.WEP + + WEP network security + + .. data:: WLAN.WPA_WPA2 + + WPA/WPA2 network security - Disconnect from the wifi access point. + .. data:: WLAN.INT_ANTENNA + + selects the internal antenna + + .. data:: WLAN.EXT_ANTENNA -.. method:: cc3k.isconnected() - - Returns True if connected to a wifi access point and has a valid IP address, - False otherwise. - -.. method:: cc3k.ifconfig() - - Returns a 7-tuple with (ip, subnet mask, gateway, DNS server, DHCP server, - MAC address, SSID). - -.. method:: cc3k.patch_version() - - Return the version of the patch program (firmware) on the CC3000. - -.. method:: cc3k.patch_program('pgm') - - Upload the current firmware to the CC3000. You must pass 'pgm' as the first - argument in order for the upload to proceed. - -Constants ---------- - -.. data:: CC3K.WEP -.. data:: CC3K.WPA -.. data:: CC3K.WPA2 - - security type to use - -class WIZNET5K -============== - -This class allows you to control WIZnet5x00 Ethernet adaptors based on -the W5200 and W5500 chipsets (only W5200 tested). - -Example usage:: - - import network - nic = network.WIZNET5K(pyb.SPI(1), pyb.Pin.board.X5, pyb.Pin.board.X4) - print(nic.ifconfig()) - - # now use socket as usual - ... - -For this example to work the WIZnet5x00 module must have the following connections: - - - MOSI connected to X8 - - MISO connected to X7 - - SCLK connected to X6 - - nSS connected to X5 - - nRESET connected to X4 - -It is possible to use other SPI busses and other pins for nSS and nRESET. - -Constructors ------------- - -.. class:: WIZNET5K(spi, pin_cs, pin_rst) - - Create a WIZNET5K driver object, initialise the WIZnet5x00 module using the given - SPI bus and pins, and return the WIZNET5K object. - - Arguments are: - - - ``spi`` is an :ref:`SPI object ` which is the SPI bus that the WIZnet5x00 is - connected to (the MOSI, MISO and SCLK pins). - - ``pin_cs`` is a :ref:`Pin object ` which is connected to the WIZnet5x00 nSS pin. - - ``pin_rst`` is a :ref:`Pin object ` which is connected to the WIZnet5x00 nRESET pin. - - All of these objects will be initialised by the driver, so there is no need to - initialise them yourself. For example, you can use:: - - nic = network.WIZNET5K(pyb.SPI(1), pyb.Pin.board.X5, pyb.Pin.board.X4) - -Methods -------- - -.. method:: wiznet5k.ifconfig([(ip, subnet, gateway, dns)]) - - Get/set IP address, subnet mask, gateway and DNS. - - When called with no arguments, this method returns a 4-tuple with the above information. - - To set the above values, pass a 4-tuple with the required information. For example:: - - nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) - -.. method:: wiznet5k.regs() - - Dump the WIZnet5x00 registers. Useful for debugging. + selects the external antenna diff --git a/docs/library/os.rst b/docs/library/os.rst index e9b7d40bf..e32a409f5 100644 --- a/docs/library/os.rst +++ b/docs/library/os.rst @@ -16,8 +16,14 @@ available physical drives are accessible from here. They are currently: ``/sd`` -- the SD card (if it exists) -On boot up, the current directory is ``/flash`` if no SD card is inserted, -otherwise it is ``/sd``. +.. only:: port_pyboard + + On boot up, the current directory is ``/flash`` if no SD card is inserted, + otherwise it is ``/sd``. + +.. only:: port_wipy + + On boot up, the current directory is ``/flash``. Functions --------- @@ -63,6 +69,12 @@ Functions Return a bytes object with n random bytes, generated by the hardware random number generator. +.. only:: port_wipy + + .. function:: mkfs(drive) + + Formats the specified drive, must be either ``/flash`` or ``/sd``. + Constants --------- diff --git a/docs/library/pyb.ADC.rst b/docs/library/pyb.ADC.rst index cc0934427..64848d577 100644 --- a/docs/library/pyb.ADC.rst +++ b/docs/library/pyb.ADC.rst @@ -3,28 +3,55 @@ class ADC -- analog to digital conversion: read analog values on a pin ====================================================================== -Usage:: +.. only:: port_pyboard - import pyb + Usage:: + + import pyb + + adc = pyb.ADC(pin) # create an analog object from a pin + val = adc.read() # read an analog value + + adc = pyb.ADCAll(resolution) # creale an ADCAll object + val = adc.read_channel(channel) # read the given channel + val = adc.read_core_temp() # read MCU temperature + val = adc.read_core_vbat() # read MCU VBAT + val = adc.read_core_vref() # read MCU VREF - adc = pyb.ADC(pin) # create an analog object from a pin - val = adc.read() # read an analog value +.. only:: port_wipy - adc = pyb.ADCAll(resolution) # creale an ADCAll object - val = adc.read_channel(channel) # read the given channel - val = adc.read_core_temp() # read MCU temperature - val = adc.read_core_vbat() # read MCU VBAT - val = adc.read_core_vref() # read MCU VREF + Usage:: + + import pyb + adc = pyb.ADC(channel) # create an analog object on one of the 4 ADC channels + val = adc.read() # read an analog value Constructors ------------ -.. class:: pyb.ADC(pin) +.. only:: port_pyboard - Create an ADC object associated with the given pin. - This allows you to then read analog values on that pin. + .. class:: pyb.ADC(pin) + + Create an ADC object associated with the given pin. + This allows you to then read analog values on that pin. +.. only:: port_wipy + + .. class:: pyb.ADC(channel) + + Create an ADC object on the given channel. Each channel is associated + to a specific pin. For more info check the `pinout and alternate functions + table. `_ + This allows you to then read analog values on that pin. + + .. warning:: + + ADC pin input range is 0-1.4V (being 1.8V the absolute maximum that it + can withstand). When GPIO2, GPIO3, GPIO4 or GPIO5 are remapped to the + ADC block, 1.8 V is the maximum. If these pins are used in digital mode, + then the maximum allowed input is 3.6V. Methods ------- @@ -34,19 +61,31 @@ Methods Read the value on the analog pin and return it. The returned value will be between 0 and 4095. -.. method:: adc.read_timed(buf, freq) +.. only:: port_pyboard - Read analog values into the given buffer at the given frequency. Buffer - can be bytearray or array.array for example. If a buffer with 8-bit elements - is used, sample resolution will be reduced to 8 bits. - - Example:: - - adc = pyb.ADC(pyb.Pin.board.X19) # create an ADC on pin X19 - buf = bytearray(100) # create a buffer of 100 bytes - adc.read_timed(buf, 10) # read analog values into buf at 10Hz - # this will take 10 seconds to finish - for val in buf: # loop over all values - print(val) # print the value out - - This function does not allocate any memory. + .. method:: adc.read_timed(buf, freq) + + Read analog values into the given buffer at the given frequency. Buffer + can be bytearray or array.array for example. If a buffer with 8-bit elements + is used, sample resolution will be reduced to 8 bits. + + Example:: + + adc = pyb.ADC(pyb.Pin.board.X19) # create an ADC on pin X19 + buf = bytearray(100) # create a buffer of 100 bytes + adc.read_timed(buf, 10) # read analog values into buf at 10Hz + # this will take 10 seconds to finish + for val in buf: # loop over all values + print(val) # print the value out + + This function does not allocate any memory. + +.. only:: port_wipy + + .. method:: adc.enable() + + Enable the ADC channel. + + .. method:: adc.disable() + + Disable the ADC channel. diff --git a/docs/library/pyb.HeartBeat.rst b/docs/library/pyb.HeartBeat.rst new file mode 100644 index 000000000..971f2e93e --- /dev/null +++ b/docs/library/pyb.HeartBeat.rst @@ -0,0 +1,46 @@ +.. _pyb.HeartBeat: + +class HeartBeat -- heart beat LED +================================= + +The HeartBeat class controls the heart beat led which by default +flashes once every 5s. The user can disable the HeartBeat and then +is free to control this LED manually through GPIO25 using the Pin +class. The GPIO25 can also be remapped as a PWM output, an this +can be used to control the light intesity of the heart beat LED. + +Example usage:: + + hb = pyb.HeartBeat() + hb.disable() # disable the heart beat + hb.enable() # enable the heart beat + +Constructors +------------ + +.. class:: pyb.HeartBeat() + + Create a HeartBeat object. + +Methods +------- + +.. method:: heartbeat.enable() + + Enable the heart beat. The LED will flash once every 5 seconds. + +.. method:: heartbeat.disable() + + Disable the heart beat. The LED can then be controlled manually. + + Example:: + + import pyb + + # disable the heart beat + pyb.HeartBeat().disable() + # get the GPIO25 pin object + hbl = pyb.Pin('GPIO25') + # toggle the led + hbl.toggle() + ... diff --git a/docs/library/pyb.I2C.rst b/docs/library/pyb.I2C.rst index e40684a78..d3cbed057 100644 --- a/docs/library/pyb.I2C.rst +++ b/docs/library/pyb.I2C.rst @@ -7,19 +7,34 @@ I2C is a two-wire protocol for communicating between devices. At the physical level it consists of 2 wires: SCL and SDA, the clock and data lines respectively. I2C objects are created attached to a specific bus. They can be initialised -when created, or initialised later on:: +when created, or initialised later on. - from pyb import I2C +.. only:: port_pyboard - i2c = I2C(1) # create on bus 1 - i2c = I2C(1, I2C.MASTER) # create and init as a master - i2c.init(I2C.MASTER, baudrate=20000) # init as a master - i2c.init(I2C.SLAVE, addr=0x42) # init as a slave with given address - i2c.deinit() # turn off the peripheral + Example:: + + from pyb import I2C + + i2c = I2C(1) # create on bus 1 + i2c = I2C(1, I2C.MASTER) # create and init as a master + i2c.init(I2C.MASTER, baudrate=20000) # init as a master + i2c.init(I2C.SLAVE, addr=0x42) # init as a slave with given address + i2c.deinit() # turn off the peripheral + +.. only:: port_wipy + + Example:: + + from pyb import I2C + + i2c = I2C(1) # create on bus 1 + i2c = I2C(1, I2C.MASTER) # create and init as a master + i2c.init(I2C.MASTER, baudrate=20000) # init as a master + i2c.deinit() # turn off the peripheral Printing the i2c object gives you information about its configuration. -Basic methods for slave are send and recv:: +The basic methods are send and recv:: i2c.send('abc') # send 3 bytes i2c.send(0x42) # send a single byte, given by the number @@ -30,9 +45,11 @@ To receive inplace, first create a bytearray:: data = bytearray(3) # create a buffer i2c.recv(data) # receive 3 bytes, writing them into data -You can specify a timeout (in ms):: +.. only:: port_pyboard - i2c.send(b'123', timeout=2000) # timout after 2 seconds + You can specify a timeout (in ms):: + + i2c.send(b'123', timeout=2000) # timout after 2 seconds A master must specify the recipient's address:: @@ -40,31 +57,57 @@ A master must specify the recipient's address:: i2c.send('123', 0x42) # send 3 bytes to slave with address 0x42 i2c.send(b'456', addr=0x42) # keyword for address -Master also has other methods:: +.. only:: port_pyboard - i2c.is_ready(0x42) # check if slave 0x42 is ready - i2c.scan() # scan for slaves on the bus, returning - # a list of valid addresses - i2c.mem_read(3, 0x42, 2) # read 3 bytes from memory of slave 0x42, - # starting at address 2 in the slave - i2c.mem_write('abc', 0x42, 2, timeout=1000) + Master also has other methods:: + + i2c.is_ready(0x42) # check if slave 0x42 is ready + i2c.scan() # scan for slaves on the bus, returning + # a list of valid addresses + i2c.mem_read(3, 0x42, 2) # read 3 bytes from memory of slave 0x42, + # starting at address 2 in the slave + i2c.mem_write('abc', 0x42, 2, timeout=1000) + +.. only:: port_wipy + + There are also other methods:: + + i2c.is_ready(0x42) # check if slave 0x42 is ready + i2c.scan() # scan for slaves on the bus, returning + # a list of valid addresses + i2c.mem_read(3, 0x42, 2) # read 3 bytes from memory of slave 0x42, + # starting at address 2 in the slave + i2c.mem_write('abc', 0x42, 2) # write 'abc' (3 bytes) to memory of slave 0x42 + # starting at address 2 in the slave Constructors ------------ -.. class:: pyb.I2C(bus, ...) +.. only:: port_pyboard - Construct an I2C object on the given bus. ``bus`` can be 1 or 2. - With no additional parameters, the I2C object is created but not - initialised (it has the settings from the last initialisation of - the bus, if any). If extra arguments are given, the bus is initialised. - See ``init`` for parameters of initialisation. - - The physical pins of the I2C busses are: - - - ``I2C(1)`` is on the X position: ``(SCL, SDA) = (X9, X10) = (PB6, PB7)`` - - ``I2C(2)`` is on the Y position: ``(SCL, SDA) = (Y9, Y10) = (PB10, PB11)`` + .. class:: pyb.I2C(bus, ...) + + Construct an I2C object on the given bus. ``bus`` can be 1 or 2. + With no additional parameters, the I2C object is created but not + initialised (it has the settings from the last initialisation of + the bus, if any). If extra arguments are given, the bus is initialised. + See ``init`` for parameters of initialisation. + + The physical pins of the I2C busses are: + + - ``I2C(1)`` is on the X position: ``(SCL, SDA) = (X9, X10) = (PB6, PB7)`` + - ``I2C(2)`` is on the Y position: ``(SCL, SDA) = (Y9, Y10) = (PB10, PB11)`` + +.. only:: port_wipy + + .. class:: pyb.I2C(bus, ...) + + Construct an I2C object on the given bus. `bus` can only be 1. + With no additional parameters, the I2C object is created but not + initialised (it has the settings from the last initialisation of + the bus, if any). If extra arguments are given, the bus is initialised. + See `init` for parameters of initialisation. Methods @@ -74,72 +117,142 @@ Methods Turn off the I2C bus. -.. method:: i2c.init(mode, \*, addr=0x12, baudrate=400000, gencall=False) +.. only:: port_pyboard - Initialise the I2C bus with the given parameters: - - - ``mode`` must be either ``I2C.MASTER`` or ``I2C.SLAVE`` - - ``addr`` is the 7-bit address (only sensible for a slave) - - ``baudrate`` is the SCL clock rate (only sensible for a master) - - ``gencall`` is whether to support general call mode + .. method:: i2c.init(mode, \*, addr=0x12, baudrate=400000, gencall=False) + + Initialise the I2C bus with the given parameters: + + - ``mode`` must be either ``I2C.MASTER`` or ``I2C.SLAVE`` + - ``addr`` is the 7-bit address (only sensible for a slave) + - ``baudrate`` is the SCL clock rate (only sensible for a master) + - ``gencall`` is whether to support general call mode + +.. only:: port_wipy + + .. method:: i2c.init(mode, \*, baudrate=100000) + + Initialise the I2C bus with the given parameters: + + - ``mode`` must be ``I2C.MASTER`` + - ``baudrate`` is the SCL clock rate .. method:: i2c.is_ready(addr) Check if an I2C device responds to the given address. Only valid when in master mode. -.. method:: i2c.mem_read(data, addr, memaddr, timeout=5000, addr_size=8) +.. only:: port_pyboard - Read from the memory of an I2C device: - - - ``data`` can be an integer (number of bytes to read) or a buffer to read into - - ``addr`` is the I2C device address - - ``memaddr`` is the memory location within the I2C device - - ``timeout`` is the timeout in milliseconds to wait for the read - - ``addr_size`` selects width of memaddr: 8 or 16 bits - - Returns the read data. - This is only valid in master mode. + .. method:: i2c.mem_read(data, addr, memaddr, timeout=5000, addr_size=8) + + Read from the memory of an I2C device: + + - ``data`` can be an integer (number of bytes to read) or a buffer to read into + - ``addr`` is the I2C device address + - ``memaddr`` is the memory location within the I2C device + - ``timeout`` is the timeout in milliseconds to wait for the read + - ``addr_size`` selects width of memaddr: 8 or 16 bits -.. method:: i2c.mem_write(data, addr, memaddr, timeout=5000, addr_size=8) + Returns the read data. + This is only valid in master mode. - Write to the memory of an I2C device: - - - ``data`` can be an integer or a buffer to write from - - ``addr`` is the I2C device address - - ``memaddr`` is the memory location within the I2C device - - ``timeout`` is the timeout in milliseconds to wait for the write - - ``addr_size`` selects width of memaddr: 8 or 16 bits - - Returns ``None``. - This is only valid in master mode. +.. only:: port_wipy -.. method:: i2c.recv(recv, addr=0x00, timeout=5000) + .. method:: i2c.mem_read(data, addr, memaddr, addr_size=8) + + Read from the memory of an I2C device: + + - ``data`` can be an integer (number of bytes to read) or a buffer to read into + - ``addr`` is the I2C device address + - ``memaddr`` is the memory location within the I2C device + - ``addr_size`` selects width of memaddr: 8 or 16 bits - Receive data on the bus: - - - ``recv`` can be an integer, which is the number of bytes to receive, - or a mutable buffer, which will be filled with received bytes - - ``addr`` is the address to receive from (only required in master mode) - - ``timeout`` is the timeout in milliseconds to wait for the receive - - Return value: if ``recv`` is an integer then a new buffer of the bytes received, - otherwise the same buffer that was passed in to ``recv``. + Returns the read data. + This is only valid in master mode. + +.. only:: port_pyboard + + .. method:: i2c.mem_write(data, addr, memaddr, timeout=5000, addr_size=8) + + Write to the memory of an I2C device: + + - ``data`` can be an integer or a buffer to write from + - ``addr`` is the I2C device address + - ``memaddr`` is the memory location within the I2C device + - ``timeout`` is the timeout in milliseconds to wait for the write + - ``addr_size`` selects width of memaddr: 8 or 16 bits + + Returns ``None``. + This is only valid in master mode. + +.. only:: port_wipy + + .. method:: i2c.mem_write(data, addr, memaddr, timeout=5000, addr_size=8) + + Write to the memory of an I2C device: + + - ``data`` can be an integer or a buffer to write from + - ``addr`` is the I2C device address + - ``memaddr`` is the memory location within the I2C device + - ``addr_size`` selects width of memaddr: 8 or 16 bits + + Returns ``None``. + This is only valid in master mode. + +.. only:: port_pyboard + + .. method:: i2c.recv(recv, addr=0x00, timeout=5000) + + Receive data on the bus: + + - ``recv`` can be an integer, which is the number of bytes to receive, + or a mutable buffer, which will be filled with received bytes + - ``addr`` is the address to receive from (only required in master mode) + - ``timeout`` is the timeout in milliseconds to wait for the receive + + Return value: if ``recv`` is an integer then a new buffer of the bytes received, + otherwise the same buffer that was passed in to ``recv``. + +.. only:: port_wipy + + .. method:: i2c.recv(recv, addr=0x00) + + Receive data on the bus: + + - ``recv`` can be an integer, which is the number of bytes to receive, + or a mutable buffer, which will be filled with received bytes + - ``addr`` is the address to receive from (only required in master mode) + + Return value: if ``recv`` is an integer then a new buffer of the bytes received, + otherwise the same buffer that was passed in to ``recv``. .. method:: i2c.scan() Scan all I2C addresses from 0x01 to 0x7f and return a list of those that respond. Only valid when in master mode. -.. method:: i2c.send(send, addr=0x00, timeout=5000) +.. only:: port_pyboard - Send data on the bus: - - - ``send`` is the data to send (an integer to send, or a buffer object) - - ``addr`` is the address to send to (only required in master mode) - - ``timeout`` is the timeout in milliseconds to wait for the send - - Return value: ``None``. + .. method:: i2c.send(send, addr=0x00, timeout=5000) + + Send data on the bus: + + - ``send`` is the data to send (an integer to send, or a buffer object) + - ``addr`` is the address to send to (only required in master mode) + - ``timeout`` is the timeout in milliseconds to wait for the send + + Return value: ``None``. +.. only:: port_wipy + + .. method:: i2c.send(send, addr=0x00) + + Send data on the bus: + + - ``send`` is the data to send (an integer to send, or a buffer object) + - ``addr`` is the address to send to (only required in master mode) + + Return value: ``None``. Constants --------- @@ -148,6 +261,8 @@ Constants for initialising the bus to master mode -.. data:: I2C.SLAVE +.. only:: port_pyboard - for initialising the bus to slave mode + .. data:: I2C.SLAVE + + for initialising the bus to slave mode diff --git a/docs/library/pyb.Pin.rst b/docs/library/pyb.Pin.rst index 6f04378b6..9f9100a78 100644 --- a/docs/library/pyb.Pin.rst +++ b/docs/library/pyb.Pin.rst @@ -5,113 +5,190 @@ class Pin -- control I/O pins A pin is the basic object to control I/O pins. It has methods to set the mode of the pin (input, output, etc) and methods to get and set the -digital logic level. For analog control of a pin, see the ADC class. +digital logic level. For analog control of a pin, see the ADC class. Usage Model: -All Board Pins are predefined as pyb.Pin.board.Name :: +.. only:: port_pyboard - x1_pin = pyb.Pin.board.X1 + All Board Pins are predefined as pyb.Pin.board.Name:: + + x1_pin = pyb.Pin.board.X1 + + g = pyb.Pin(pyb.Pin.board.X1, pyb.Pin.IN) + + CPU pins which correspond to the board pins are available + as ``pyb.cpu.Name``. For the CPU pins, the names are the port letter + followed by the pin number. On the PYBv1.0, ``pyb.Pin.board.X1`` and + ``pyb.Pin.cpu.B6`` are the same pin. + + You can also use strings:: + + g = pyb.Pin('X1', pyb.Pin.OUT_PP) + + Users can add their own names:: + + MyMapperDict = { 'LeftMotorDir' : pyb.Pin.cpu.C12 } + pyb.Pin.dict(MyMapperDict) + g = pyb.Pin("LeftMotorDir", pyb.Pin.OUT_OD) + + and can query mappings:: + + pin = pyb.Pin("LeftMotorDir") + + Users can also add their own mapping function:: + + def MyMapper(pin_name): + if pin_name == "LeftMotorDir": + return pyb.Pin.cpu.A0 + + pyb.Pin.mapper(MyMapper) + + So, if you were to call: ``pyb.Pin("LeftMotorDir", pyb.Pin.OUT_PP)`` + then ``"LeftMotorDir"`` is passed directly to the mapper function. + + To summarise, the following order determines how things get mapped into + an ordinal pin number: + + 1. Directly specify a pin object + 2. User supplied mapping function + 3. User supplied mapping (object must be usable as a dictionary key) + 4. Supply a string which matches a board pin + 5. Supply a string which matches a CPU port/pin + + You can set ``pyb.Pin.debug(True)`` to get some debug information about + how a particular object gets mapped to a pin. + + When a pin has the ``Pin.PULL_UP`` or ``Pin.PULL_DOWN`` pull-mode enabled, + that pin has an effective 40k Ohm resistor pulling it to 3V3 or GND + respectively (except pin Y5 which has 11k Ohm resistors). - g = pyb.Pin(pyb.Pin.board.X1, pyb.Pin.IN) +.. only:: port_wipy -CPU pins which correspond to the board pins are available -as ``pyb.cpu.Name``. For the CPU pins, the names are the port letter -followed by the pin number. On the PYBv1.0, ``pyb.Pin.board.X1`` and -``pyb.Pin.cpu.B6`` are the same pin. + Board pins are identified by their string name:: -You can also use strings:: + g = pyb.Pin('GPIO9', af=0, mode=pyb.Pin.IN, type=pyb.Pin.STD, strength=pyb.Pin.S2MA) - g = pyb.Pin('X1', pyb.Pin.OUT_PP) + You can also configure the Pin to generate interrupts. For instance:: -Users can add their own names:: + def pincb(pin): + print(pin.info().name) - MyMapperDict = { 'LeftMotorDir' : pyb.Pin.cpu.C12 } - pyb.Pin.dict(MyMapperDict) - g = pyb.Pin("LeftMotorDir", pyb.Pin.OUT_OD) + pin_int = pyb.Pin('GPIO10', af=0, mode=Pin.IN, type=pyb.Pin.STD_PD, strength=pyb.Pin.S2MA) + pin_int.callback (mode=pyb.Pin.INT_RISING, handler=pincb) + # the callback can be triggered manually + pin_int.callback()() + # to disable the callback + pin_int.callback().disable() -and can query mappings :: + Now every time a falling edge is seen on the gpio pin, the callback will be + executed. Caution: mechanical push buttons have "bounce" and pushing or + releasing a switch will often generate multiple edges. + See: http://www.eng.utah.edu/~cs5780/debouncing.pdf for a detailed + explanation, along with various techniques for debouncing. - pin = pyb.Pin("LeftMotorDir") - -Users can also add their own mapping function:: - - def MyMapper(pin_name): - if pin_name == "LeftMotorDir": - return pyb.Pin.cpu.A0 - - pyb.Pin.mapper(MyMapper) - -So, if you were to call: ``pyb.Pin("LeftMotorDir", pyb.Pin.OUT_PP)`` -then ``"LeftMotorDir"`` is passed directly to the mapper function. - -To summarise, the following order determines how things get mapped into -an ordinal pin number: - -1. Directly specify a pin object -2. User supplied mapping function -3. User supplied mapping (object must be usable as a dictionary key) -4. Supply a string which matches a board pin -5. Supply a string which matches a CPU port/pin - -You can set ``pyb.Pin.debug(True)`` to get some debug information about -how a particular object gets mapped to a pin. - -When a pin has the ``Pin.PULL_UP`` or ``Pin.PULL_DOWN`` pull-mode enabled, -that pin has an effective 40k Ohm resistor pulling it to 3V3 or GND -respectively (except pin Y5 which has 11k Ohm resistors). + All pin objects go through the pin mapper to come up with one of the + gpio pins. Constructors ------------ -.. class:: pyb.Pin(id, ...) +.. only:: port_pyboard - Create a new Pin object associated with the id. If additional arguments are given, - they are used to initialise the pin. See :meth:`pin.init`. + .. class:: pyb.Pin(id, ...) + Create a new Pin object associated with the id. If additional arguments are given, + they are used to initialise the pin. See :meth:`pin.init`. -Class methods -------------- +.. only:: port_wipy -.. method:: Pin.af_list() + .. class:: pyb.Pin(name, ...) - Returns an array of alternate functions available for this pin. + Create a new Pin object associated with the name. If additional arguments are given, + they are used to initialise the pin. See :meth:`pin.init`. -.. method:: Pin.debug([state]) +.. only:: port_pyboard - Get or set the debugging state (``True`` or ``False`` for on or off). - -.. method:: Pin.dict([dict]) - - Get or set the pin mapper dictionary. - -.. method:: Pin.mapper([fun]) - - Get or set the pin mapper function. + Class methods + ------------- + + .. method:: Pin.af_list() + + Returns an array of alternate functions available for this pin. + + .. method:: Pin.debug([state]) + + Get or set the debugging state (``True`` or ``False`` for on or off). + + .. method:: Pin.dict([dict]) + + Get or set the pin mapper dictionary. + + .. method:: Pin.mapper([fun]) + + Get or set the pin mapper function. Methods ------- -.. method:: pin.init(mode, pull=Pin.PULL_NONE, af=-1) +.. only:: port_pyboard - Initialise the pin: - - - ``mode`` can be one of: - - ``Pin.IN`` - configure the pin for input; - - ``Pin.OUT_PP`` - configure the pin for output, with push-pull control; - - ``Pin.OUT_OD`` - configure the pin for output, with open-drain control; - - ``Pin.AF_PP`` - configure the pin for alternate function, pull-pull; - - ``Pin.AF_OD`` - configure the pin for alternate function, open-drain; - - ``Pin.ANALOG`` - configure the pin for analog. - - ``pull`` can be one of: - - ``Pin.PULL_NONE`` - no pull up or down resistors; - - ``Pin.PULL_UP`` - enable the pull-up resistor; - - ``Pin.PULL_DOWN`` - enable the pull-down resistor. - - when mode is Pin.AF_PP or Pin.AF_OD, then af can be the index or name - of one of the alternate functions associated with a pin. - - Returns: ``None``. + .. method:: pin.init(mode, pull=Pin.PULL_NONE, af=-1) + + Initialise the pin: + + - ``mode`` can be one of: + + - ``Pin.IN`` - configure the pin for input; + - ``Pin.OUT_PP`` - configure the pin for output, with push-pull control; + - ``Pin.OUT_OD`` - configure the pin for output, with open-drain control; + - ``Pin.AF_PP`` - configure the pin for alternate function, pull-pull; + - ``Pin.AF_OD`` - configure the pin for alternate function, open-drain; + - ``Pin.ANALOG`` - configure the pin for analog. + + - ``pull`` can be one of: + + - ``Pin.PULL_NONE`` - no pull up or down resistors; + - ``Pin.PULL_UP`` - enable the pull-up resistor; + - ``Pin.PULL_DOWN`` - enable the pull-down resistor. + + - when mode is ``Pin.AF_PP`` or ``Pin.AF_OD``, then af can be the index or name + of one of the alternate functions associated with a pin. + + Returns: ``None``. + +.. only:: port_wipy + + .. method:: pin.init(af, mode, type, strength) + + Initialise the pin: + + - ``af`` is the number of the alternate function. Please refer to the + `pinout and alternate functions table. `_ + for the specific alternate functions that each pin supports. + + - ``mode`` can be one of: + + - ``Pin.OUT`` - no pull up or down resistors. + - ``Pin.IN`` - enable the pull-up resistor. + + - ``type`` can be one of: + + - ``Pin.STD`` - push-pull pin. + - ``Pin.STD_PU`` - push-pull pin with pull-up resistor. + - ``Pin.STD_PD`` - push-pull pin with pull-down resistor. + - ``Pin.OD`` - open drain pin. + - ``Pin.OD_PU`` - open drain pin with pull-up resistor. + - ``Pin.OD_PD`` - open drain pin with pull-down resistor. + + - ``strength`` can be one of: + + - ``Pin.S2MA`` - 2mA drive capability. + - ``Pin.S4MA`` - 4mA drive capability. + - ``Pin.S6MA`` - 6mA drive capability. + + Returns: ``None``. .. method:: pin.high() @@ -130,137 +207,249 @@ Methods anything that converts to a boolean. If it converts to ``True``, the pin is set high, otherwise it is set low. -.. method:: pin.__str__() +.. only:: port_pyboard - Return a string describing the pin object. + .. method:: pin.__str__() + + Return a string describing the pin object. + + .. method:: pin.af() + + Returns the currently configured alternate-function of the pin. The + integer returned will match one of the allowed constants for the af + argument to the init function. + + .. method:: pin.gpio() + + Returns the base address of the GPIO block associated with this pin. + + .. method:: pin.mode() + + Returns the currently configured mode of the pin. The integer returned + will match one of the allowed constants for the mode argument to the init + function. + + .. method:: pin.name() + + Get the pin name. + + .. method:: pin.names() + + Returns the cpu and board names for this pin. + + .. method:: pin.pin() + + Get the pin number. + + .. method:: pin.port() + + Get the pin port. + + .. method:: pin.pull() + + Returns the currently configured pull of the pin. The integer returned + will match one of the allowed constants for the pull argument to the init + function. -.. method:: pin.af() +.. only:: port_wipy - Returns the currently configured alternate-function of the pin. The - integer returned will match one of the allowed constants for the af - argument to the init function. + .. method:: pin.toggle() -.. method:: pin.gpio() + Toggle the value of the pin. - Returns the base address of the GPIO block associated with this pin. + .. method:: pin.info() -.. method:: pin.mode() + Return a 5-tuple with the configuration of the pin: + ``(name, alternate-function, mode, type, strength)`` - Returns the currently configured mode of the pin. The integer returned - will match one of the allowed constants for the mode argument to the init - function. + .. method:: pin.callback(mode, priority=1, handler=None, wakes=pyb.Sleep.ACTIVE) -.. method:: pin.name() + Create a callback to be triggered when data is received on the UART. - Get the pin name. + - ``mode`` configures the pin level which can generate an interrupt. Possible values are: -.. method:: pin.names() + - ``Pin.INT_FALLING`` interrupt on falling edge. + - ``Pin.INT_RISING`` interrupt on rising edge. + - ``Pin.INT_RISING_FALLING`` interrupt on rising and falling edge. + - ``Pin.INT_LOW_LEVEL`` interrupt on low level. + - ``Pin.INT_HIGH_LEVEL`` interrupt on high level. - Returns the cpu and board names for this pin. + - ``priority`` level of the interrupt. Can take values in the range 1-7. + Higher values represent higher priorities. + - ``handler`` is an optional function to be called when new characters arrive. + - ``wakes`` selects the power mode in which this interrupt can wake up the + board. Please note: -.. method:: pin.pin() + - If ``wakes=pyb.Sleep.ACTIVE`` any pin can wake the board. + - If ``wakes=pyb.Sleep.SUSPENDED`` pins ``GPIO2``, ``GPIO4``, ``GPIO10``, + ``GPIO11``, GPIO17`` or ``GPIO24`` can wake the board. Note that only 1 + of this pins can be enabled as a wake source at the same time, so, only + the last enabled pin as a ``pyb.Sleep.SUSPENDED`` wake source will have effect. + - If ``wakes=pyb.Sleep.SUSPENDED`` pins ``GPIO2``, ``GPIO4``, ``GPIO10``, + ``GPIO11``, GPIO17`` and ``GPIO24`` can wake the board. In this case all this 6 + pins can be enabled as a ``pyb.Sleep.HIBERNATE`` wake source at the same time. + - Values can be ORed to make a pin generate interrupts in more than one power + mode. - Get the pin number. - -.. method:: pin.port() - - Get the pin port. - -.. method:: pin.pull() - - Returns the currently configured pull of the pin. The integer returned - will match one of the allowed constants for the pull argument to the init - function. + Returns a callback object. Constants --------- -.. data:: Pin.AF_OD +.. only:: port_pyboard - initialise the pin to alternate-function mode with an open-drain drive + .. data:: Pin.AF_OD + + initialise the pin to alternate-function mode with an open-drain drive + + .. data:: Pin.AF_PP + + initialise the pin to alternate-function mode with a push-pull drive + + .. data:: Pin.ANALOG + + initialise the pin to analog mode + + .. data:: Pin.IN + + initialise the pin to input mode + + .. data:: Pin.OUT_OD + + initialise the pin to output mode with an open-drain drive + + .. data:: Pin.OUT_PP + + initialise the pin to output mode with a push-pull drive + + .. data:: Pin.PULL_DOWN + + enable the pull-down resistor on the pin + + .. data:: Pin.PULL_NONE + + don't enable any pull up or down resistors on the pin + + .. data:: Pin.PULL_UP + + enable the pull-up resistor on the pin -.. data:: Pin.AF_PP +.. only:: port_wipy - initialise the pin to alternate-function mode with a push-pull drive + .. data:: Pin.IN + + input pin mode + + .. data:: Pin.OUT + + output pin mode + + .. data:: Pin.STD + + push-pull pin type + + .. data:: Pin.STD_PU + + push-pull pin with internall pull-up resistor + + .. data:: Pin.STD_PD + + push-pull pin with internall pull-down resistor + + .. data:: Pin.OD + + open-drain pin + + .. data:: Pin.OD_PU + + open-drain pin with pull-up resistor + + .. data:: Pin.OD_PD + + open-drain pin with pull-down resistor + + .. data:: Pin.INT_FALLING + + interrupt on falling edge + + .. data:: Pin.INT_RISING + + interrupt on rising edge + + .. data:: Pin.INT_RISING_FALLING + + interrupt on rising and falling edge + + .. data:: Pin.INT_LOW_LEVEL + + interrupt on low level + + .. data:: Pin.INT_HIGH_LEVEL + + interrupt on high level + + .. data:: Pin.S2MA + + 2mA drive strength + + .. data:: Pin.S4MA + + 4mA drive strength + + .. data:: Pin.S6MA + + 6mA drive strength -.. data:: Pin.ANALOG +.. only:: port_pyboard - initialise the pin to analog mode + class PinAF -- Pin Alternate Functions + ====================================== + + A Pin represents a physical pin on the microcprocessor. Each pin + can have a variety of functions (GPIO, I2C SDA, etc). Each PinAF + object represents a particular function for a pin. + + Usage Model:: + + x3 = pyb.Pin.board.X3 + x3_af = x3.af_list() + + x3_af will now contain an array of PinAF objects which are availble on + pin X3. + + For the pyboard, x3_af would contain: + [Pin.AF1_TIM2, Pin.AF2_TIM5, Pin.AF3_TIM9, Pin.AF7_USART2] + + Normally, each peripheral would configure the af automatically, but sometimes + the same function is available on multiple pins, and having more control + is desired. + + To configure X3 to expose TIM2_CH3, you could use:: + + pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=pyb.Pin.AF1_TIM2) + + or:: + + pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=1) -.. data:: Pin.IN - - initialise the pin to input mode - -.. data:: Pin.OUT_OD - - initialise the pin to output mode with an open-drain drive - -.. data:: Pin.OUT_PP - - initialise the pin to output mode with a push-pull drive - -.. data:: Pin.PULL_DOWN - - enable the pull-down resistor on the pin - -.. data:: Pin.PULL_NONE - - don't enable any pull up or down resistors on the pin - -.. data:: Pin.PULL_UP - - enable the pull-up resistor on the pin - - -class PinAF -- Pin Alternate Functions -====================================== - -A Pin represents a physical pin on the microcprocessor. Each pin -can have a variety of functions (GPIO, I2C SDA, etc). Each PinAF -object represents a particular function for a pin. - -Usage Model:: - - x3 = pyb.Pin.board.X3 - x3_af = x3.af_list() - -x3_af will now contain an array of PinAF objects which are availble on -pin X3. - -For the pyboard, x3_af would contain: - [Pin.AF1_TIM2, Pin.AF2_TIM5, Pin.AF3_TIM9, Pin.AF7_USART2] - -Normally, each peripheral would configure the af automatically, but sometimes -the same function is available on multiple pins, and having more control -is desired. - -To configure X3 to expose TIM2_CH3, you could use:: - - pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=pyb.Pin.AF1_TIM2) - -or:: - - pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=1) - - -Methods -------- - -.. method:: pinaf.__str__() - - Return a string describing the alternate function. - -.. method:: pinaf.index() - - Return the alternate function index. - -.. method:: pinaf.name() - - Return the name of the alternate function. - -.. method:: pinaf.reg() - - Return the base register associated with the peripheral assigned to this - alternate function. For example, if the alternate function were TIM2_CH3 - this would return stm.TIM2 + Methods + ------- + + .. method:: pinaf.__str__() + + Return a string describing the alternate function. + + .. method:: pinaf.index() + + Return the alternate function index. + + .. method:: pinaf.name() + + Return the name of the alternate function. + + .. method:: pinaf.reg() + + Return the base register associated with the peripheral assigned to this + alternate function. For example, if the alternate function were TIM2_CH3 + this would return stm.TIM2 diff --git a/docs/library/pyb.RTC.rst b/docs/library/pyb.RTC.rst index cd4b28eab..dacd2d7bb 100644 --- a/docs/library/pyb.RTC.rst +++ b/docs/library/pyb.RTC.rst @@ -1,3 +1,5 @@ +.. _pyb.RTC: + class RTC -- real time clock ============================ @@ -38,38 +40,52 @@ Methods ``subseconds`` counts down from 255 to 0 -.. method:: rtc.wakeup(timeout, callback=None) +.. only:: port_pyboard - Set the RTC wakeup timer to trigger repeatedly at every ``timeout`` - milliseconds. This trigger can wake the pyboard from both the sleep - states: :meth:`pyb.stop` and :meth:`pyb.standby`. + .. method:: rtc.wakeup(timeout, callback=None) + + Set the RTC wakeup timer to trigger repeatedly at every ``timeout`` + milliseconds. This trigger can wake the pyboard from both the sleep + states: :meth:`pyb.stop` and :meth:`pyb.standby`. + + If ``timeout`` is ``None`` then the wakeup timer is disabled. + + If ``callback`` is given then it is executed at every trigger of the + wakeup timer. ``callback`` must take exactly one argument. + + .. method:: rtc.info() + + Get information about the startup time and reset source. + + - The lower 0xffff are the number of milliseconds the RTC took to + start up. + - Bit 0x10000 is set if a power-on reset occurred. + - Bit 0x20000 is set if an external reset occurred + + .. method:: rtc.calibration(cal) + + Get or set RTC calibration. + + With no arguments, ``calibration()`` returns the current calibration + value, which is an integer in the range [-511 : 512]. With one + argument it sets the RTC calibration. + + The RTC Smooth Calibration mechanism addjusts the RTC clock rate by + adding or subtracting the given number of ticks from the 32768 Hz + clock over a 32 second period (corresponding to 2^20 clock ticks.) + Each tick added will speed up the clock by 1 part in 2^20, or 0.954 + ppm; likewise the RTC clock it slowed by negative values. The + usable calibration range is: + (-511 * 0.954) ~= -487.5 ppm up to (512 * 0.954) ~= 488.5 ppm - If ``timeout`` is ``None`` then the wakeup timer is disabled. +.. only:: port_wipy - If ``callback`` is given then it is executed at every trigger of the - wakeup timer. ``callback`` must take exactly one argument. + .. method:: rtc.callback(\*, value, handler=None, wakes=pyb.Sleep.ACTIVE) + + Create a callback object triggered by a real time clock alarm. + + - ``value`` is the alarm timeout in milliseconds. This parameter is required. + - ``handler`` is the function to be called when the callback is triggered. + - ``wakes`` specifies the power mode from where this interrupt can wake + up the system. -.. method:: rtc.info() - - Get information about the startup time and reset source. - - - The lower 0xffff are the number of milliseconds the RTC took to - start up. - - Bit 0x10000 is set if a power-on reset occurred. - - Bit 0x20000 is set if an external reset occurred - -.. method:: rtc.calibration(cal) - - Get or set RTC calibration. - - With no arguments, ``calibration()`` returns the current calibration - value, which is an integer in the range [-511 : 512]. With one - argument it sets the RTC calibration. - - The RTC Smooth Calibration mechanism addjusts the RTC clock rate by - adding or subtracting the given number of ticks from the 32768 Hz - clock over a 32 second period (corresponding to 2^20 clock ticks.) - Each tick added will speed up the clock by 1 part in 2^20, or 0.954 - ppm; likewise the RTC clock it slowed by negative values. The - usable calibration range is: - (-511 * 0.954) ~= -487.5 ppm up to (512 * 0.954) ~= 488.5 ppm diff --git a/docs/library/pyb.SD.rst b/docs/library/pyb.SD.rst new file mode 100644 index 000000000..84feb8348 --- /dev/null +++ b/docs/library/pyb.SD.rst @@ -0,0 +1,39 @@ +.. _pyb.SD: + +class SD -- secure digital memory card +====================================== + +The SD card class allows to configure and enable the memory card +module of the WiPy and automatically mount it as ``/sd`` as part +of the file system. There are several pin combinations that can be +used to wire the SD card socket to the WiPy and the pins used can +be specified in the constructor. Please check the `pinout and alternate functions +table. `_ for +more info regarding the pins which can be remapped to be used with a SD card. + +Example usage:: + + # data, clk and cmd pins must be passed along with + # their respective alternate functions + sd = pyb.SD('GPIO15', 8, 'GPIO16', 8, 'GPIO17', 8) + sd.enable() # enable and mount the SD card + sd.disable() # disable and unmount it + +Constructors +------------ + +.. class:: pyb.SD(dat_pin, dat_pin_af, clk_pin, clk_pin_af, cmd_pin, cmd_pin_af) + + Create a SD card object. Data, clock and cmd pins must be passed along with + their respective alternate functions. + +Methods +------- + +.. method:: sd.enable() + + Enable the SD card and mount it on the file system. Accesible as ``/sd``. + +.. method:: sd.disable() + + Disable the SD card and remove it from the file system. diff --git a/docs/library/pyb.SPI.rst b/docs/library/pyb.SPI.rst index 70d645401..d6f4bb963 100644 --- a/docs/library/pyb.SPI.rst +++ b/docs/library/pyb.SPI.rst @@ -6,18 +6,32 @@ class SPI -- a master-driven serial protocol SPI is a serial protocol that is driven by a master. At the physical level there are 3 lines: SCK, MOSI, MISO. -See usage model of I2C; SPI is very similar. Main difference is -parameters to init the SPI bus:: +.. only:: port_pyboard - from pyb import SPI - spi = SPI(1, SPI.MASTER, baudrate=600000, polarity=1, phase=0, crc=0x7) + See usage model of I2C; SPI is very similar. Main difference is + parameters to init the SPI bus:: + + from pyb import SPI + spi = SPI(1, SPI.MASTER, baudrate=600000, polarity=1, phase=0, crc=0x7) -Only required parameter is mode, SPI.MASTER or SPI.SLAVE. Polarity can be -0 or 1, and is the level the idle clock line sits at. Phase can be 0 or 1 -to sample data on the first or second clock edge respectively. Crc can be -None for no CRC, or a polynomial specifier. + Only required parameter is mode, SPI.MASTER or SPI.SLAVE. Polarity can be + 0 or 1, and is the level the idle clock line sits at. Phase can be 0 or 1 + to sample data on the first or second clock edge respectively. Crc can be + None for no CRC, or a polynomial specifier. -Additional method for SPI:: +.. only:: port_wipy + + See usage model of I2C; SPI is very similar. Main difference is + parameters to init the SPI bus:: + + from pyb import SPI + spi = SPI(1, SPI.MASTER, baudrate=600000, polarity=1, phase=0) + + Only required parameter is mode, must be SPI.MASTER. Polarity can be 0 or + 1, and is the level the idle clock line sits at. Phase can be 0 or 1 to + sample data on the first or second clock edge respectively. + +Additional methods for SPI:: data = spi.send_recv(b'1234') # send 4 bytes and receive 4 bytes buf = bytearray(4) @@ -28,22 +42,33 @@ Additional method for SPI:: Constructors ------------ -.. class:: pyb.SPI(bus, ...) +.. only:: port_pyboard - Construct an SPI object on the given bus. ``bus`` can be 1 or 2. - With no additional parameters, the SPI object is created but not - initialised (it has the settings from the last initialisation of - the bus, if any). If extra arguments are given, the bus is initialised. - See ``init`` for parameters of initialisation. - - The physical pins of the SPI busses are: - - - ``SPI(1)`` is on the X position: ``(NSS, SCK, MISO, MOSI) = (X5, X6, X7, X8) = (PA4, PA5, PA6, PA7)`` - - ``SPI(2)`` is on the Y position: ``(NSS, SCK, MISO, MOSI) = (Y5, Y6, Y7, Y8) = (PB12, PB13, PB14, PB15)`` - - At the moment, the NSS pin is not used by the SPI driver and is free - for other use. + .. class:: pyb.SPI(bus, ...) + + Construct an SPI object on the given bus. ``bus`` can be 1 or 2. + With no additional parameters, the SPI object is created but not + initialised (it has the settings from the last initialisation of + the bus, if any). If extra arguments are given, the bus is initialised. + See ``init`` for parameters of initialisation. + + The physical pins of the SPI busses are: + + - ``SPI(1)`` is on the X position: ``(NSS, SCK, MISO, MOSI) = (X5, X6, X7, X8) = (PA4, PA5, PA6, PA7)`` + - ``SPI(2)`` is on the Y position: ``(NSS, SCK, MISO, MOSI) = (Y5, Y6, Y7, Y8) = (PB12, PB13, PB14, PB15)`` + + At the moment, the NSS pin is not used by the SPI driver and is free + for other use. +.. only:: port_wipy + + .. class:: pyb.SPI(bus, ...) + + Construct an SPI object on the given bus. ``bus`` can be only 1. + With no additional parameters, the SPI object is created but not + initialised (it has the settings from the last initialisation of + the bus, if any). If extra arguments are given, the bus is initialised. + See ``init`` for parameters of initialisation. Methods ------- @@ -51,73 +76,147 @@ Methods .. method:: spi.deinit() Turn off the SPI bus. - -.. method:: spi.init(mode, baudrate=328125, \*, prescaler, polarity=1, phase=0, bits=8, firstbit=SPI.MSB, ti=False, crc=None) - - Initialise the SPI bus with the given parameters: - - ``mode`` must be either ``SPI.MASTER`` or ``SPI.SLAVE``. - - ``baudrate`` is the SCK clock rate (only sensible for a master). - - ``prescaler`` is the prescaler to use to derive SCK from the APB bus frequency; - use of ``prescaler`` overrides ``baudrate``. - - ``polarity`` can be 0 or 1, and is the level the idle clock line sits at. - - ``phase`` can be 0 or 1 to sample data on the first or second clock edge - respectively. - - ``firstbit`` can be ``SPI.MSB`` or ``SPI.LSB``. - - ``crc`` can be None for no CRC, or a polynomial specifier. +.. only:: port_pyboard - Note that the SPI clock frequency will not always be the requested baudrate. - The hardware only supports baudrates that are the APB bus frequency - (see :meth:`pyb.freq`) divided by a prescaler, which can be 2, 4, 8, 16, 32, - 64, 128 or 256. SPI(1) is on AHB2, and SPI(2) is on AHB1. For precise - control over the SPI clock frequency, specify ``prescaler`` instead of - ``baudrate``. + .. method:: spi.init(mode, baudrate=328125, \*, prescaler, polarity=1, phase=0, bits=8, firstbit=SPI.MSB, ti=False, crc=None) + + Initialise the SPI bus with the given parameters: + + - ``mode`` must be either ``SPI.MASTER`` or ``SPI.SLAVE``. + - ``baudrate`` is the SCK clock rate (only sensible for a master). + - ``prescaler`` is the prescaler to use to derive SCK from the APB bus frequency; + use of ``prescaler`` overrides ``baudrate``. + - ``polarity`` can be 0 or 1, and is the level the idle clock line sits at. + - ``phase`` can be 0 or 1 to sample data on the first or second clock edge + respectively. + - ``firstbit`` can be ``SPI.MSB`` or ``SPI.LSB``. + - ``crc`` can be None for no CRC, or a polynomial specifier. + + Note that the SPI clock frequency will not always be the requested baudrate. + The hardware only supports baudrates that are the APB bus frequency + (see :meth:`pyb.freq`) divided by a prescaler, which can be 2, 4, 8, 16, 32, + 64, 128 or 256. SPI(1) is on AHB2, and SPI(2) is on AHB1. For precise + control over the SPI clock frequency, specify ``prescaler`` instead of + ``baudrate``. + + Printing the SPI object will show you the computed baudrate and the chosen + prescaler. - Printing the SPI object will show you the computed baudrate and the chosen - prescaler. +.. only:: port_wipy -.. method:: spi.recv(recv, \*, timeout=5000) + .. method:: spi.init(mode, baudrate=328125, \*, polarity=1, phase=0, bits=8, nss=SPI.ACTIVE_LOW) + + Initialise the SPI bus with the given parameters: + + - ``mode`` must be ``SPI.MASTER``. + - ``baudrate`` is the SCK clock rate. + - ``polarity`` can be 0 or 1, and is the level the idle clock line sits at. + - ``phase`` can be 0 or 1 to sample data on the first or second clock edge + respectively. + - ``bits`` is the width of each transfer, accepted values are 8, 16 and 32. + - ``nss`` is the polarity of the slave select line. Can be ``SPI.ACTIVE_LOW`` + or ``SPI.ACTIVE_HIGH``. + + Note that the SPI clock frequency will not always be the requested baudrate. + Printing the SPI object will show you the computed baudrate and the chosen + prescaler. - Receive data on the bus: - - - ``recv`` can be an integer, which is the number of bytes to receive, - or a mutable buffer, which will be filled with received bytes. - - ``timeout`` is the timeout in milliseconds to wait for the receive. - - Return value: if ``recv`` is an integer then a new buffer of the bytes received, - otherwise the same buffer that was passed in to ``recv``. +.. only:: port_pyboard -.. method:: spi.send(send, \*, timeout=5000) + .. method:: spi.recv(recv, \*, timeout=5000) + + Receive data on the bus: + + - ``recv`` can be an integer, which is the number of bytes to receive, + or a mutable buffer, which will be filled with received bytes. + - ``timeout`` is the timeout in milliseconds to wait for the receive. + + Return value: if ``recv`` is an integer then a new buffer of the bytes received, + otherwise the same buffer that was passed in to ``recv``. - Send data on the bus: - - - ``send`` is the data to send (an integer to send, or a buffer object). - - ``timeout`` is the timeout in milliseconds to wait for the send. - - Return value: ``None``. +.. only:: port_wipy -.. method:: spi.send_recv(send, recv=None, \*, timeout=5000) + .. method:: spi.recv(recv) + + Receive data on the bus: + + - ``recv`` can be an integer, which is the number of bytes to receive, + or a mutable buffer, which will be filled with received bytes. + + Return value: if ``recv`` is an integer then a new buffer of the bytes received, + otherwise the same buffer that was passed in to ``recv``. - Send and receive data on the bus at the same time: - - - ``send`` is the data to send (an integer to send, or a buffer object). - - ``recv`` is a mutable buffer which will be filled with received bytes. - It can be the same as ``send``, or omitted. If omitted, a new buffer will - be created. - - ``timeout`` is the timeout in milliseconds to wait for the receive. - - Return value: the buffer with the received bytes. +.. only:: port_pyboard + .. method:: spi.send(send, \*, timeout=5000) + + Send data on the bus: + + - ``send`` is the data to send (an integer to send, or a buffer object). + - ``timeout`` is the timeout in milliseconds to wait for the send. + + Return value: ``None``. + +.. only:: port_wipy + + .. method:: spi.send(send) + + Send data on the bus: + + - ``send`` is the data to send (an integer to send, or a buffer object). + + Return value: ``None``. + +.. only:: port_pyboard + + .. method:: spi.send_recv(send, recv=None, \*, timeout=5000) + + Send and receive data on the bus at the same time: + + - ``send`` is the data to send (an integer to send, or a buffer object). + - ``recv`` is a mutable buffer which will be filled with received bytes. + It can be the same as ``send``, or omitted. If omitted, a new buffer will + be created. + - ``timeout`` is the timeout in milliseconds to wait for the receive. + + Return value: the buffer with the received bytes. + +.. only:: port_wipy + + .. method:: spi.send_recv(send, recv=None) + + Send and receive data on the bus at the same time: + + - ``send`` is the data to send (an integer to send, or a buffer object). + - ``recv`` is a mutable buffer which will be filled with received bytes. + It can be the same as ``send``, or omitted. If omitted, a new buffer will + be created. + + Return value: the buffer with the received bytes. Constants --------- -.. data:: SPI.MASTER -.. data:: SPI.SLAVE +.. only:: port_pyboard - for initialising the SPI bus to master or slave mode + .. data:: SPI.MASTER + .. data:: SPI.SLAVE + + for initialising the SPI bus to master or slave mode + + .. data:: SPI.LSB + .. data:: SPI.MSB + + set the first bit to be the least or most significant bit -.. data:: SPI.LSB -.. data:: SPI.MSB +.. only:: port_wipy - set the first bit to be the least or most significant bit + .. data:: SPI.MASTER + + for initialising the SPI bus to master + + .. data:: SPI.ACTIVE_LOW + .. data:: SPI.ACTIVE_HIGH + + decides the polarity of the NSS pin diff --git a/docs/library/pyb.UART.rst b/docs/library/pyb.UART.rst index 75d1fbe9b..01a04ef4e 100644 --- a/docs/library/pyb.UART.rst +++ b/docs/library/pyb.UART.rst @@ -15,10 +15,17 @@ UART objects can be created and initialised using:: uart = UART(1, 9600) # init with given baudrate uart.init(9600, bits=8, parity=None, stop=1) # init with given parameters -Bits can be 7, 8 or 9. Parity can be None, 0 (even) or 1 (odd). Stop can be 1 or 2. +.. only:: port_pyboard + + Bits can be 7, 8 or 9. Parity can be None, 0 (even) or 1 (odd). Stop can be 1 or 2. + + *Note:* with parity=None, only 8 and 9 bits are supported. With parity enabled, + only 7 and 8 bits are supported. + +.. only:: port_wipy + + Bits can be 5, 6, 7, 8. Parity can be None, 0 (even) or 1 (odd). Stop can be 1 or 2. -*Note:* with parity=None, only 8 and 9 bits are supported. With parity enabled, -only 7 and 8 bits are supported. A UART object acts like a stream object and reading and writing is done using the standard stream methods:: @@ -44,46 +51,77 @@ Earlier versions use ``uart.send`` and ``uart.recv``. Constructors ------------ -.. class:: pyb.UART(bus, ...) +.. only:: port_pyboard - Construct a UART object on the given bus. ``bus`` can be 1-6, or 'XA', 'XB', 'YA', or 'YB'. - With no additional parameters, the UART object is created but not - initialised (it has the settings from the last initialisation of - the bus, if any). If extra arguments are given, the bus is initialised. - See ``init`` for parameters of initialisation. + .. class:: pyb.UART(bus, ...) + + Construct a UART object on the given bus. ``bus`` can be 1-6, or 'XA', 'XB', 'YA', or 'YB'. + With no additional parameters, the UART object is created but not + initialised (it has the settings from the last initialisation of + the bus, if any). If extra arguments are given, the bus is initialised. + See ``init`` for parameters of initialisation. + + The physical pins of the UART busses are: + + - ``UART(4)`` is on ``XA``: ``(TX, RX) = (X1, X2) = (PA0, PA1)`` + - ``UART(1)`` is on ``XB``: ``(TX, RX) = (X9, X10) = (PB6, PB7)`` + - ``UART(6)`` is on ``YA``: ``(TX, RX) = (Y1, Y2) = (PC6, PC7)`` + - ``UART(3)`` is on ``YB``: ``(TX, RX) = (Y9, Y10) = (PB10, PB11)`` + - ``UART(2)`` is on: ``(TX, RX) = (X3, X4) = (PA2, PA3)`` - The physical pins of the UART busses are: +.. only:: port_wipy - - ``UART(4)`` is on ``XA``: ``(TX, RX) = (X1, X2) = (PA0, PA1)`` - - ``UART(1)`` is on ``XB``: ``(TX, RX) = (X9, X10) = (PB6, PB7)`` - - ``UART(6)`` is on ``YA``: ``(TX, RX) = (Y1, Y2) = (PC6, PC7)`` - - ``UART(3)`` is on ``YB``: ``(TX, RX) = (Y9, Y10) = (PB10, PB11)`` - - ``UART(2)`` is on: ``(TX, RX) = (X3, X4) = (PA2, PA3)`` + .. class:: pyb.UART(bus, ...) + + Construct a UART object on the given bus. ``bus`` can be 1 or 2. + With no additional parameters, the UART object is created but not + initialised (it has the settings from the last initialisation of + the bus, if any). If extra arguments are given, the bus is initialised. + See ``init`` for parameters of initialisation. Methods ------- -.. method:: uart.init(baudrate, bits=8, parity=None, stop=1, \*, timeout=1000, timeout_char=0, read_buf_len=64) +.. only:: port_pyboard - Initialise the UART bus with the given parameters: + .. method:: uart.init(baudrate, bits=8, parity=None, stop=1, \*, timeout=1000, flow=None, timeout_char=0, read_buf_len=64) + + Initialise the UART bus with the given parameters: + + - ``baudrate`` is the clock rate. + - ``bits`` is the number of bits per character, 7, 8 or 9. + - ``parity`` is the parity, ``None``, 0 (even) or 1 (odd). + - ``stop`` is the number of stop bits, 1 or 2. + - ``flow`` sets the flow control type. Can be None, ``UART.RTS``, ``UART.CTS`` + or ``UART.RTS | UART.CTS``. + - ``timeout`` is the timeout in milliseconds to wait for the first character. + - ``timeout_char`` is the timeout in milliseconds to wait between characters. + - ``read_buf_len`` is the character length of the read buffer (0 to disable). + + This method will raise an exception if the baudrate could not be set within + 5% of the desired value. The minimum baudrate is dictated by the frequency + of the bus that the UART is on; UART(1) and UART(6) are APB2, the rest are on + APB1. The default bus frequencies give a minimum baudrate of 1300 for + UART(1) and UART(6) and 650 for the others. Use :func:`pyb.freq ` + to reduce the bus frequencies to get lower baudrates. + + *Note:* with parity=None, only 8 and 9 bits are supported. With parity enabled, + only 7 and 8 bits are supported. - - ``baudrate`` is the clock rate. - - ``bits`` is the number of bits per character, 7, 8 or 9. - - ``parity`` is the parity, ``None``, 0 (even) or 1 (odd). - - ``stop`` is the number of stop bits, 1 or 2. - - ``timeout`` is the timeout in milliseconds to wait for the first character. - - ``timeout_char`` is the timeout in milliseconds to wait between characters. - - ``read_buf_len`` is the character length of the read buffer (0 to disable). +.. only:: port_wipy - This method will raise an exception if the baudrate could not be set within - 5% of the desired value. The minimum baudrate is dictated by the frequency - of the bus that the UART is on; UART(1) and UART(6) are APB2, the rest are on - APB1. The default bus frequencies give a minimum baudrate of 1300 for - UART(1) and UART(6) and 650 for the others. Use :func:`pyb.freq ` - to reduce the bus frequencies to get lower baudrates. - - *Note:* with parity=None, only 8 and 9 bits are supported. With parity enabled, - only 7 and 8 bits are supported. + .. method:: uart.init(baudrate, bits=8, parity=None, stop=1, \*, timeout=1000, flow=None, timeout_char=0) + + Initialise the UART bus with the given parameters: + + - ``baudrate`` is the clock rate. + - ``bits`` is the number of bits per character, 7, 8 or 9. + - ``parity`` is the parity, ``None``, 0 (even) or 1 (odd). + - ``stop`` is the number of stop bits, 1 or 2. + - ``flow`` sets the flow control type. Can be None, ``UART.RTS``, ``UART.CTS`` + or ``UART.RTS | UART.CTS``. + - ``timeout`` is the timeout in milliseconds to wait for the first character. + - ``timeout_char`` is the timeout in milliseconds to wait between characters. .. method:: uart.deinit() @@ -97,11 +135,18 @@ Methods Read characters. If ``nbytes`` is specified then read at most that many bytes. - *Note:* for 9 bit characters each character takes two bytes, ``nbytes`` must - be even, and the number of characters is ``nbytes/2``. + .. only:: port_pyboard - Return value: a bytes object containing the bytes read in. Returns ``b''`` - on timeout. + *Note:* for 9 bit characters each character takes two bytes, ``nbytes`` must + be even, and the number of characters is ``nbytes/2``. + + Return value: a bytes object containing the bytes read in. Returns ``b''`` + on timeout. + + .. only:: port_wipy + + Return value: a bytes object containing the bytes read in. Returns ``b''`` + on timeout. .. method:: uart.readall() @@ -130,12 +175,20 @@ Methods .. method:: uart.write(buf) - Write the buffer of bytes to the bus. If characters are 7 or 8 bits wide - then each byte is one character. If characters are 9 bits wide then two - bytes are used for each character (little endian), and ``buf`` must contain - an even number of bytes. + .. only:: port_pyboard - Return value: number of bytes written. + Write the buffer of bytes to the bus. If characters are 7 or 8 bits wide + then each byte is one character. If characters are 9 bits wide then two + bytes are used for each character (little endian), and ``buf`` must contain + an even number of bytes. + + Return value: number of bytes written. + + .. only:: port_wipy + + Write the buffer of bytes to the bus. + + Return value: number of bytes written. .. method:: uart.writechar(char) @@ -147,3 +200,36 @@ Methods Send a break condition on the bus. This drives the bus low for a duration of 13 bits. Return value: ``None``. + +.. only:: port_wipy + + .. method:: uart.callback(value, priority=1, handler=None) + + Create a callback to be triggered when data is received on the UART. + + - ``value`` sets the size in bytes of the Rx buffer. Every character + received is put into this buffer as long as there's space free. + - ``priority`` level of the interrupt. Can take values in the range 1-7. + Higher values represent higher priorities. + - ``handler`` an optional function to be called when new characters arrive. + + .. note:: + + The handler will be called whenever any of the following two conditions are met: + + - 4 new characters have been received. + - At least 1 new character is waiting in the Rx buffer and the Rx line has been + silent for the duration of 1 complete frame. + + This means that when the handler function is called there might be 1, 2, 3 or 4 + characters waiting. + + Return a callback object. + +Constants +--------- + +.. data:: UART.RTS +.. data:: UART.CTS + + to select the flow control type diff --git a/docs/library/pyb.WDT.rst b/docs/library/pyb.WDT.rst new file mode 100644 index 000000000..9728e7bca --- /dev/null +++ b/docs/library/pyb.WDT.rst @@ -0,0 +1,33 @@ +.. _pyb.WDT: + +class WDT -- watchdog timer +=========================== + +The WDT is used to restart the system when the application crashes and ends +up into a non recoverable state. Once started it cannot be stopped or +reconfigured in any way. After enabling, the application must "kick" the +watchdog periodically to prevent it from expiring and resetting the system. + +Example usage:: + + wdt = pyb.WDT(5000) # enable with a timeout of 5s + wdt.kick() + +Constructors +------------ + +.. class:: pyb.WDT([timeout]) + + Create a WDT object. If the timeout is specified the WDT is started. + The timeout must be given in seconds and 1s the minimum value that + is accepted. Once it is running the timeout cannot be changed and + the WDT cannot be stopped either. + +Methods +------- + +.. method:: wdt.kick() + + Kick the WDT to prevent it from resetting the system. The application + should place this call in a sensible place ensuring that the WDT is + only kicked after verifying that everything is functioning correctly. diff --git a/docs/library/pyb.rst b/docs/library/pyb.rst index 7cad587f9..5b682e2d6 100644 --- a/docs/library/pyb.rst +++ b/docs/library/pyb.rst @@ -1,10 +1,10 @@ -:mod:`pyb` --- functions related to the pyboard -=============================================== +:mod:`pyb` --- functions related to the board +============================================= .. module:: pyb - :synopsis: functions related to the pyboard + :synopsis: functions related to the board -The ``pyb`` module contains specific functions related to the pyboard. +The ``pyb`` module contains specific functions related to the board. Time related functions ---------------------- @@ -63,14 +63,25 @@ Time related functions Reset related functions ----------------------- -.. function:: hard_reset() +.. only:: port_pyboard - Resets the pyboard in a manner similar to pushing the external RESET - button. + .. function:: hard_reset() + + Resets the pyboard in a manner similar to pushing the external RESET + button. -.. function:: bootloader() +.. only:: port_wipy - Activate the bootloader without BOOT\* pins. + .. function:: reset() + + Resets the WiPy in a manner similar to pushing the external RESET + button. + +.. only:: port_pyboard + + .. function:: bootloader() + + Activate the bootloader without BOOT\* pins. Interrupt related functions --------------------------- @@ -93,93 +104,106 @@ Interrupt related functions Power related functions ----------------------- -.. function:: freq([sysclk[, hclk[, pclk1[, pclk2]]]]) +.. only:: port_pyboard - If given no arguments, returns a tuple of clock frequencies: - (sysclk, hclk, pclk1, pclk2). - These correspond to: + .. function:: freq([sysclk[, hclk[, pclk1[, pclk2]]]]) + + If given no arguments, returns a tuple of clock frequencies: + (sysclk, hclk, pclk1, pclk2). + These correspond to: + + - sysclk: frequency of the CPU + - hclk: frequency of the AHB bus, core memory and DMA + - pclk1: frequency of the APB1 bus + - pclk2: frequency of the APB2 bus + + If given any arguments then the function sets the frequency of the CPU, + and the busses if additional arguments are given. Frequencies are given in + Hz. Eg freq(120000000) sets sysclk (the CPU frequency) to 120MHz. Note that + not all values are supported and the largest supported frequency not greater + than the given value will be selected. + + Supported sysclk frequencies are (in MHz): 8, 16, 24, 30, 32, 36, 40, 42, 48, + 54, 56, 60, 64, 72, 84, 96, 108, 120, 144, 168. + + The maximum frequency of hclk is 168MHz, of pclk1 is 42MHz, and of pclk2 is + 84MHz. Be sure not to set frequencies above these values. + + The hclk, pclk1 and pclk2 frequencies are derived from the sysclk frequency + using a prescaler (divider). Supported prescalers for hclk are: 1, 2, 4, 8, + 16, 64, 128, 256, 512. Supported prescalers for pclk1 and pclk2 are: 1, 2, + 4, 8. A prescaler will be chosen to best match the requested frequency. + + A sysclk frequency of + 8MHz uses the HSE (external crystal) directly and 16MHz uses the HSI + (internal oscillator) directly. The higher frequencies use the HSE to + drive the PLL (phase locked loop), and then use the output of the PLL. + + Note that if you change the frequency while the USB is enabled then + the USB may become unreliable. It is best to change the frequency + in boot.py, before the USB peripheral is started. Also note that sysclk + frequencies below 36MHz do not allow the USB to function correctly. + + .. function:: wfi() + + Wait for an internal or external interrupt. + + This executes a ``wfi`` instruction which reduces power consumption + of the MCU until any interrupt occurs (be it internal or external), + at which point execution continues. Note that the system-tick interrupt + occurs once every millisecond (1000Hz) so this function will block for + at most 1ms. + + .. function:: stop() + + Put the pyboard in a "sleeping" state. + + This reduces power consumption to less than 500 uA. To wake from this + sleep state requires an external interrupt or a real-time-clock event. + Upon waking execution continues where it left off. + + See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event. + + .. function:: standby() + + Put the pyboard into a "deep sleep" state. + + This reduces power consumption to less than 50 uA. To wake from this + sleep state requires an external interrupt or a real-time-clock event. + Upon waking the system undergoes a hard reset. + + See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event. - - sysclk: frequency of the CPU - - hclk: frequency of the AHB bus, core memory and DMA - - pclk1: frequency of the APB1 bus - - pclk2: frequency of the APB2 bus +.. only:: port_wipy - If given any arguments then the function sets the frequency of the CPU, - and the busses if additional arguments are given. Frequencies are given in - Hz. Eg freq(120000000) sets sysclk (the CPU frequency) to 120MHz. Note that - not all values are supported and the largest supported frequency not greater - than the given value will be selected. + .. function:: freq([sysclk]) - Supported sysclk frequencies are (in MHz): 8, 16, 24, 30, 32, 36, 40, 42, 48, - 54, 56, 60, 64, 72, 84, 96, 108, 120, 144, 168. + Returns a tuple of clock frequencies: ``(sysclk)`` + These correspond to: - The maximum frequency of hclk is 168MHz, of pclk1 is 42MHz, and of pclk2 is - 84MHz. Be sure not to set frequencies above these values. - - The hclk, pclk1 and pclk2 frequencies are derived from the sysclk frequency - using a prescaler (divider). Supported prescalers for hclk are: 1, 2, 4, 8, - 16, 64, 128, 256, 512. Supported prescalers for pclk1 and pclk2 are: 1, 2, - 4, 8. A prescaler will be chosen to best match the requested frequency. - - A sysclk frequency of - 8MHz uses the HSE (external crystal) directly and 16MHz uses the HSI - (internal oscillator) directly. The higher frequencies use the HSE to - drive the PLL (phase locked loop), and then use the output of the PLL. - - Note that if you change the frequency while the USB is enabled then - the USB may become unreliable. It is best to change the frequency - in boot.py, before the USB peripheral is started. Also note that sysclk - frequencies below 36MHz do not allow the USB to function correctly. - -.. function:: wfi() - - Wait for an internal or external interrupt. - - This executes a ``wfi`` instruction which reduces power consumption - of the MCU until any interrupt occurs (be it internal or external), - at which point execution continues. Note that the system-tick interrupt - occurs once every millisecond (1000Hz) so this function will block for - at most 1ms. - -.. function:: stop() - - Put the pyboard in a "sleeping" state. - - This reduces power consumption to less than 500 uA. To wake from this - sleep state requires an external interrupt or a real-time-clock event. - Upon waking execution continues where it left off. - - See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event. - -.. function:: standby() - - Put the pyboard into a "deep sleep" state. - - This reduces power consumption to less than 50 uA. To wake from this - sleep state requires an external interrupt or a real-time-clock event. - Upon waking the system undergoes a hard reset. - - See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event. + - sysclk: frequency of the CPU Miscellaneous functions ----------------------- -.. function:: have_cdc() +.. only:: port_pyboard - Return True if USB is connected as a serial device, False otherwise. - - .. note:: This function is deprecated. Use pyb.USB_VCP().isconnected() instead. - -.. function:: hid((buttons, x, y, z)) - - Takes a 4-tuple (or list) and sends it to the USB host (the PC) to - signal a HID mouse-motion event. - - .. note:: This function is deprecated. Use pyb.USB_HID().send(...) instead. - -.. function:: info([dump_alloc_table]) - - Print out lots of information about the board. + .. function:: have_cdc() + + Return True if USB is connected as a serial device, False otherwise. + + .. note:: This function is deprecated. Use pyb.USB_VCP().isconnected() instead. + + .. function:: hid((buttons, x, y, z)) + + Takes a 4-tuple (or list) and sends it to the USB host (the PC) to + signal a HID mouse-motion event. + + .. note:: This function is deprecated. Use pyb.USB_HID().send(...) instead. + + .. function:: info([dump_alloc_table]) + + Print out lots of information about the board. .. function:: main(filename) @@ -188,72 +212,109 @@ Miscellaneous functions It only makes sense to call this function from within boot.py. -.. function:: mount(device, mountpoint, \*, readonly=False, mkfs=False) +.. only:: port_pyboard - Mount a block device and make it available as part of the filesystem. - ``device`` must be an object that provides the block protocol: - - - ``readblocks(self, blocknum, buf)`` - - ``writeblocks(self, blocknum, buf)`` (optional) - - ``count(self)`` - - ``sync(self)`` (optional) - - ``readblocks`` and ``writeblocks`` should copy data between ``buf`` and - the block device, starting from block number ``blocknum`` on the device. - ``buf`` will be a bytearray with length a multiple of 512. If - ``writeblocks`` is not defined then the device is mounted read-only. - The return value of these two functions is ignored. - - ``count`` should return the number of blocks available on the device. - ``sync``, if implemented, should sync the data on the device. - - The parameter ``mountpoint`` is the location in the root of the filesystem - to mount the device. It must begin with a forward-slash. - - If ``readonly`` is ``True``, then the device is mounted read-only, - otherwise it is mounted read-write. - - If ``mkfs`` is ``True``, then a new filesystem is created if one does not - already exist. - - To unmount a device, pass ``None`` as the device and the mount location - as ``mountpoint``. + .. function:: mount(device, mountpoint, \*, readonly=False, mkfs=False) + + Mount a block device and make it available as part of the filesystem. + ``device`` must be an object that provides the block protocol: + + - ``readblocks(self, blocknum, buf)`` + - ``writeblocks(self, blocknum, buf)`` (optional) + - ``count(self)`` + - ``sync(self)`` (optional) + + ``readblocks`` and ``writeblocks`` should copy data between ``buf`` and + the block device, starting from block number ``blocknum`` on the device. + ``buf`` will be a bytearray with length a multiple of 512. If + ``writeblocks`` is not defined then the device is mounted read-only. + The return value of these two functions is ignored. + + ``count`` should return the number of blocks available on the device. + ``sync``, if implemented, should sync the data on the device. + + The parameter ``mountpoint`` is the location in the root of the filesystem + to mount the device. It must begin with a forward-slash. + + If ``readonly`` is ``True``, then the device is mounted read-only, + otherwise it is mounted read-write. + + If ``mkfs`` is ``True``, then a new filesystem is created if one does not + already exist. + + To unmount a device, pass ``None`` as the device and the mount location + as ``mountpoint``. .. function:: repl_uart(uart) Get or set the UART object that the REPL is repeated on. -.. function:: rng() +.. only:: port_pyboard - Return a 30-bit hardware generated random number. + .. function:: rng() + + Return a 30-bit hardware generated random number. + +.. only:: port_wipy + + .. function:: rng() + + Return a 24-bit software generated random number. .. function:: sync() Sync all file systems. -.. function:: unique_id() +.. only:: port_pyboard - Returns a string of 12 bytes (96 bits), which is the unique ID for the MCU. + .. function:: unique_id() + + Returns a string of 12 bytes (96 bits), which is the unique ID for the MCU. + +.. only:: port_wipy + + .. function:: unique_id() + + Returns a string of 6 bytes (48 bits), which is the unique ID for the MCU. + This also corresponds to the ``MAC address`` of the WiPy. Classes ------- -.. toctree:: - :maxdepth: 1 +.. only:: port_pyboard - pyb.Accel.rst - pyb.ADC.rst - pyb.CAN.rst - pyb.DAC.rst - pyb.ExtInt.rst - pyb.I2C.rst - pyb.LCD.rst - pyb.LED.rst - pyb.Pin.rst - pyb.RTC.rst - pyb.Servo.rst - pyb.SPI.rst - pyb.Switch.rst - pyb.Timer.rst - pyb.UART.rst - pyb.USB_VCP.rst + .. toctree:: + :maxdepth: 1 + + pyb.Accel.rst + pyb.ADC.rst + pyb.CAN.rst + pyb.DAC.rst + pyb.ExtInt.rst + pyb.I2C.rst + pyb.LCD.rst + pyb.LED.rst + pyb.Pin.rst + pyb.RTC.rst + pyb.Servo.rst + pyb.SPI.rst + pyb.Switch.rst + pyb.Timer.rst + pyb.UART.rst + pyb.USB_VCP.rst + +.. only:: port_wipy + + .. toctree:: + :maxdepth: 1 + + pyb.ADC.rst + pyb.HeartBeat.rst + pyb.I2C.rst + pyb.Pin.rst + pyb.RTC.rst + pyb.SD.rst + pyb.SPI.rst + pyb.Timer.rst + pyb.UART.rst + pyb.WDT.rst diff --git a/docs/library/time.rst b/docs/library/time.rst index 1ffce7c24..8595daa88 100644 --- a/docs/library/time.rst +++ b/docs/library/time.rst @@ -31,10 +31,24 @@ Functions which expresses a time as per localtime. It returns an integer which is the number of seconds since Jan 1, 2000. -.. function:: sleep(seconds) +.. only:: port_pyboard - Sleep for the given number of seconds. Seconds can be a floating-point number to - sleep for a fractional number of seconds. + .. function:: sleep(seconds) + + Sleep for the given number of seconds. Seconds can be a floating-point number to + sleep for a fractional number of seconds. + +.. only:: port_esp8266 + + .. function:: sleep(seconds) + + Sleep for the given number of seconds. + +.. only:: port_wipy + + .. function:: sleep(milliseconds) + + Sleep for the given number of milliseconds. .. function:: time() diff --git a/docs/library/uctypes.rst b/docs/library/uctypes.rst index 9a1a0d234..73637a0e2 100644 --- a/docs/library/uctypes.rst +++ b/docs/library/uctypes.rst @@ -141,7 +141,7 @@ Module contents at the given memory address. Structure descriptors and instantiating structure objects ------------------------------------------------------ +--------------------------------------------------------- Given a structure descriptor dictionary and its layout type, you can instantiate a specific structure instance at a given memory address diff --git a/docs/library/uhashlib.rst b/docs/library/uhashlib.rst index 708e3d7bc..a8f580fd8 100644 --- a/docs/library/uhashlib.rst +++ b/docs/library/uhashlib.rst @@ -4,34 +4,78 @@ .. module:: uhashlib :synopsis: hashing algorithm -This module implements binary data hashing algorithms. Currently, it -implements SHA256 algorithm. Choosing SHA256 was a deliberate choice, -as a modern, cryptographically secure algorithm. This means that a -single algorithm can cover both usecases of "any hash algorithm" and -security-related usage, and thus save space omitting legacy algorithms -like MD5 or SHA1. +.. only:: port_pyboard + + This module implements binary data hashing algorithms. Currently, it + implements SHA256 algorithm. Choosing SHA256 was a deliberate choice, + as a modern, cryptographically secure algorithm. This means that a + single algorithm can cover both usecases of "any hash algorithm" and + security-related usage, and thus save space omitting legacy algorithms + like MD5 or SHA1. + +.. only:: port_wipy + + This module implements binary data hashing algorithms. Currently, it + implements SHA1 and SHA256 algorithms only. These two algorithms are + more than enough for today's web applications. + Constructors ------------ -.. class:: uhashlib.sha256([data]) +.. only:: port_pyboard - Create a hasher object and optionally feed ``data`` into it. + .. class:: uhashlib.sha256([data]) + + Create a hasher object and optionally feed ``data`` into it. +.. only:: port_wipy + + .. class:: uhashlib.sha1([data[, block_size]]) + + Create a sha1 hasher object and optionally feed ``data`` or ``data and block_size`` into it. + + .. class:: uhashlib.sha256([data[, block_size]]) + + Create a sha256 hasher object and optionally feed ``data`` or ``data and block_size`` into it. + + .. admonition:: CPython extension + :class: attention + + Due to hardware implementation details of the WiPy, data must be buffered before being + digested, which would make impossible to calculate the hash of big blocks of data that + do not fit in RAM. In this case, since most likely the total size of the data is known + in advance, the size can be passed to the constructor and hence the HASH hardware engine + of the WiPy can be properly initialized without needing buffering. If ``block_size`` is + to be given, an initial chunk of ``data`` must be passed as well. **When using this extension, + care must be taken to make sure that the length of all intermediate chunks (including the + initial one) is a multiple of 4 bytes.** The last chunk may be of any length. + + Example:: + + hash = uhashlib.sha1('abcd1234', 1001) # lenght of the initial piece is multiple of 4 bytes + hash.update('1234') # also multiple of 4 bytes + ... + hash.update('12345') # last chunk may be of any length + hash.digest() Methods ------- -.. method:: sha256.update(data) +.. method:: hash.update(data) Feed more binary data into hash. -.. method:: sha256.digest() +.. method:: hash.digest() Return hash for all data passed thru hash, as a bytes object. After this method is called, more data cannot be fed into hash any longer. -.. method:: sha256.hexdigest() + .. only:: port_wipy + + SHA1 hashes are 20-byte long. SHA256 hashes are 32-byte long. - This method is NOT implemented. Use ``ubinascii.hexlify(sha256.digest())`` - to achieve similar effect. +.. method:: hash.hexdigest() + + This method is NOT implemented. Use ``ubinascii.hexlify(hash.digest())`` + to achieve a similar effect. diff --git a/docs/pyboard/quickref.rst b/docs/pyboard/quickref.rst index 2a1429cb0..ebd3c774d 100644 --- a/docs/pyboard/quickref.rst +++ b/docs/pyboard/quickref.rst @@ -1,4 +1,6 @@ -.. _quickref: +.. only:: port_pyboard + + .. _quickref: Quick reference for the pyboard =============================== diff --git a/docs/pyboard/tutorial/amp_skin.rst b/docs/pyboard/tutorial/amp_skin.rst index 9aaf84c75..64f139bb7 100644 --- a/docs/pyboard/tutorial/amp_skin.rst +++ b/docs/pyboard/tutorial/amp_skin.rst @@ -53,8 +53,8 @@ For example:: dac.write_timed(buf, 400 * len(buf), mode=DAC.CIRCULAR) You can also play WAV files using the Python ``wave`` module. You can get -the wave module `here `_ and you will also need -the chunk module available `here `_. Put these +the wave module `here `__ and you will also need +the chunk module available `here `__. Put these on your pyboard (either on the flash or the SD card in the top-level directory). You will need an 8-bit WAV file to play, such as `this one `_, or to convert any file you have with the command:: diff --git a/docs/pyboard/tutorial/lcd_skin.rst b/docs/pyboard/tutorial/lcd_skin.rst index 4f3b30a4a..288ac1bf0 100644 --- a/docs/pyboard/tutorial/lcd_skin.rst +++ b/docs/pyboard/tutorial/lcd_skin.rst @@ -60,7 +60,7 @@ enables the 4 touch sensors. The third line reads the touch status and the ``touch`` variable holds the state of the 4 touch buttons (A, B, X, Y). -There is a simple driver `here `_ +There is a simple driver `here `__ which allows you to set the threshold and debounce parameters, and easily read the touch status and electrode voltage levels. Copy this script to your pyboard (either flash or SD card, in the top @@ -83,4 +83,4 @@ initialise the I2C bus using:: >>> m = mpr121.MPR121(pyb.I2C(2, pyb.I2C.MASTER)) There is also a demo which uses the LCD and the touch sensors together, -and can be found `here `_. +and can be found `here `__. diff --git a/docs/pyboard_contents.rst b/docs/pyboard_contents.rst new file mode 100644 index 000000000..abf7bd025 --- /dev/null +++ b/docs/pyboard_contents.rst @@ -0,0 +1,12 @@ +MicroPython documentation contents +================================== + +.. toctree:: + + pyboard/quickref.rst + pyboard/general.rst + pyboard/tutorial/index.rst + library/index.rst + pyboard/hardware/index.rst + license.rst + diff --git a/docs/pyboard_index.rst b/docs/pyboard_index.rst new file mode 100644 index 000000000..38ccb1ac9 --- /dev/null +++ b/docs/pyboard_index.rst @@ -0,0 +1,19 @@ +MicroPython documentation and references +======================================== + +.. toctree:: + + pyboard/quickref.rst + pyboard/general.rst + pyboard/tutorial/index.rst + library/index.rst + pyboard/hardware/index.rst + license.rst + pyboard_contents.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/topindex.html b/docs/topindex.html index d28132df1..6bdafe856 100644 --- a/docs/topindex.html +++ b/docs/topindex.html @@ -21,11 +21,11 @@ {% endfor %}. -

Documentation for MicroPython and the pyboard:

+

Documentation for MicroPython and {{ port_name }}:

@@ -100,6 +102,12 @@ MicroPython on GitHub
contribute to the source code on GitHub

+ {% if port == "wipy" %} +

+ The WiPy homepage
+ the official WiPy site +

+ {% endif %}
- {% if port == "pyboard" %} + {% if port == "pyboard" or port == "wipy" %}

Quick reference for {{ port_name }}
pinout for {{ port_name }} and snippets of useful code @@ -34,6 +34,8 @@ General information about {{ port_name }}
read this first for a quick overview

+ {% endif %} + {% if port == "pyboard" %}

Tutorials and code examples
start here @@ -76,7 +78,7 @@

- Table of contents
+ Table of contents
a list of all sections and subsections

diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst new file mode 100644 index 000000000..894990619 --- /dev/null +++ b/docs/wipy/general.rst @@ -0,0 +1,59 @@ +General information about the WiPy +================================== + +WLAN default behaviour +---------------------- + +When the WiPy boots with the default factory configuration starts in Access Point +mode with ``ssid: wipy-wlan`` and ``key: www.wipy.io``. +Connect to this network and the WiPy will be reachable at ``192.168.1.1``. In order +to gain access to the interactive prompt, open a telnet session to that IP address on +the default port (23). You will be asked for credentials: +``login: micro`` ``password: python`` + +Local file system and SD card +----------------------------- + +There is a small internal file system (a drive) on the WiPy, called ``/flash``, +which is stored within the external serial flash memory. If a micro SD card +is hooked-up and enabled, it is available as ``/sd``. + +When the WiPy boots up, it always boots from the ``boot.py`` located in the +``/flash`` file system. If during the boot process the SD card is enabled and +it's selected as the current drive then the WiPy will try to execute ``main.py`` +that should be located in the SD card. + +The file system is accessible via the native FTP server running in the WiPy. +Open your FTP client of choice and connect to: + +``ftp://192.168.1.1`` ``user: micro`` ``password: python`` + +Boot modes +---------- + +If you power up normally, or press the reset button, the WiPy will boot +into standard mode: the ``boot.py`` file will be executed first, then +``main.py`` will run. + +You can override this boot sequence by pulling ``GPIO28`` **up** during reset. +The heart beat LED will flash slowly 3 times to signal that safe boot is being +requested, and then 3 more times quickly to let you know that safe boot is +going to be performed. While safe booting, the WiPy runs the factory firmware +and skips the execution of ``boot.py`` and ``main.py``. This is useful to +recover from any crash situation. + +The heart beat LED +------------------ + +By default the heart beat LED flashes once every 5s to signal that the system is +alive. This can be overridden through the HeartBeat class: + +``pyb.HeartBeat().disable()`` + +There are currently 2 kinds of errors that you might see: + +1. If the heart beat LED flashes quickly, then a Python script(eg ``main.py``) + has an error. Use the REPL to debug it. +2. If the heart beat LED stays on, then there was a hard fault, you cannot + recover from this, the only way out is by pressing the reset switch. + diff --git a/docs/wipy/quickref.rst b/docs/wipy/quickref.rst new file mode 100644 index 000000000..9733a8714 --- /dev/null +++ b/docs/wipy/quickref.rst @@ -0,0 +1,228 @@ +.. only:: port_wipy + + .. _quickref_: + +Quick reference for the WiPy +============================ + +.. image:: https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png + :alt: WiPy pinout and alternate functions table + :width: 800px + +General board control +--------------------- + +See :mod:`pyb`. :: + + import pyb + + help(pyb) # display all members from the pyb module + pyb.delay(50) # wait 50 milliseconds + pyb.millis() # number of milliseconds since boot-up + pyb.freq() # get the CPU frequency + pyb.unique_id() # return the 6-byte unique id of the board (it's MAC address) + +Pins and GPIO +------------- + +See :ref:`pyb.Pin `. :: + + from pyb import Pin + + # initialize GPIO2 in gpio mode (af=0) and make it an output + p_out = Pin('GPIO2', af=0, mode=Pin.OUT) + p_out.high() + p_out.low() + p_out.toggle() + + # make GPIO1 an input with the pull-up enabled + p_in = Pin('GPIO1', af = 0, mode=Pin.IN, type = Pin.STD_PU) + p_in.value() # get value, 0 or 1 + +Timers +------ + +See :ref:`pyb.Timer ` and :ref:`pyb.Pin `. :: + + from pyb import Timer + from pyb import Pin + + tim = Timer(1, mode=Timer.PERIODIC) + tim_a = tim.channel(Timer.A, freq=1000) + tim_a.time() # get the value in microseconds + tim_a.freq(1) # 1 Hz + + p_out = Pin('GPIO2', af=0, mode=Pin.OUT) + tim_a.callback(handler=lambda t: p_out.toggle()) + +PWM (pulse width modulation) +---------------------------- + +See :ref:`pyb.Pin ` and :ref:`pyb.Timer `. :: + + from pyb import Timer + from pyb import Pin + + # assign GPIO25 to alternate function 5 (PWM) + p_out = Pin('GPIO25', af=9, type=Pin.STD) + + # timer 2 in PWM mode and width must be 16 buts + tim = Timer(2, mode=Timer.PWM, width=16) + + # enable channel A @1KHz with a 50% duty cycle + tim_a = tim.channel(Timer.A, freq=1000, duty_cycle=50) + +ADC (analog to digital conversion) +---------------------------------- + +See :ref:`pyb.ADC `. :: + + from pyb import ADC + + adc = ADC(1) + adc.read() # read value, 0-4095 + +UART (serial bus) +----------------- + +See :ref:`pyb.Pin ` and :ref:`pyb.UART `. :: + + from pyb import Pin, UART + + # first assign TX and RX to the correct pins + Pin('GPIO1', af=3, mode=Pin.STD_PU) # TX + Pin('GPIO2', af=3, mode=Pin.STD_PU) # RX + + uart = UART(1, 9600) + uart.write('hello') + uart.read(5) # read up to 5 bytes + +SPI bus +------- + +See :ref:`pyb.Pin ` and :ref:`pyb.SPI `. :: + + from pyb import Pin, SPI + + # first assign CLK, MISO, MOSI, CS to the correct pins + Pin('GPIO14', af=7, mode=Pin.STD) # CLK + Pin('GPIO15', af=7, mode=Pin.STD) # MISO + Pin('GPIO16', af=7, mode=Pin.STD) # MOSI + Pin('GPIO17', af=7, mode=Pin.STD) # NSS/CS + + # configure the SPI master @ 2MHz + spi = SPI(1, SPI.MASTER, baudrate=200000, polarity=0, phase=0) + spi.send('hello') + spi.recv(5) # receive 5 bytes on the bus + spi.send_recv('hello') # send a receive 5 bytes + +I2C bus +------- + +See :ref:`pyb.Pin ` and :ref:`pyb.I2C `. :: + + from pyb import Pin, I2C + + # first assign SCL and SDA to the correct pins + Pin('GPIO23', af=9, mode=Pin.STD_PU) # SCL + Pin('GPIO24', af=9, mode=Pin.STD_PU) # SDA + + # configure the I2C bus + i2c = I2C(1, I2C.MASTER, baudrate=100000) + i2c.scan() # returns list of slave addresses + i2c.send('hello', 0x42) # send 5 bytes to slave with address 0x42 + i2c.recv(5, 0x42) # receive 5 bytes from slave + i2c.mem_read(2, 0x42, 0x10) # read 2 bytes from slave 0x42, slave memory 0x10 + i2c.mem_write('xy', 0x42, 0x10) # write 2 bytes to slave 0x42, slave memory 0x10 + +Watchdog timer (WDT) +-------------------- + +See :ref:`pyb.WDT `. :: + + from pyb import WDT + + # enable the WDT with a timeout of 5s (1s is the minimum) + wdt = WDT(5000) + wdt.kick() + +Real time clock (RTC) +--------------------- + +See :ref:`pyb.RTC ` and ``pyb.Sleep``. :: + + from pyb import RTC, Sleep + + rtc = pyb.RTC() + rtc.datetime((2014, 5, 1, 4, 13, 0, 0, 0)) + print(rtc.datetime()) + + def some_handler (rtc_obj): + # trigger the callback again in 30s + rtc_obj.callback(value=30000, handler=some_handler) + + # create a RTC alarm that expires in 30s + rtc.callback(value=30000, handler=some_handler, wakes=Sleep.SUSPENDED) + + # go into suspended mode waiting for the RTC alarm to expire and wake us up + Sleep.suspend() + +SD card +------- + +See :ref:`pyb.SD `. :: + + from pyb import SD + + # SD card pins need special configuration so we pass 'em to the constructor + # data pin, data af, clock pin, clock af, cmd pin, cmd af + sd = SD('GPIO15', 8, 'GPIO16', 8, 'GPIO17', 8) + sd.enable() + +WLAN (WiFi) +----------- + +See :ref:`network.WLAN ` and ``pyb.Sleep``. :: + + from network import WLAN + from pyb import Sleep + + # configure the WLAN subsystem in station mode (the default is AP) + wifi = WLAN(WLAN.STA) + # go for fixed IP settings + wifi.ifconfig('192.168.0.107', '255.255.255.0', '192.168.0.1', '8.8.8.8') + wifi.scan() # scan for available netrworks + wifi.connect(ssid='mynetwork', security=2, key='mynetworkkey') + while not wifi.isconnected(): + pass + print(wifi.ifconfig()) + # enable wake on WLAN + wifi.callback(wakes=Sleep.SUSPENDED) + # go to sleep + Sleep.suspend() + # now, connect to the FTP or the Telnet server and the WiPy will wake-up + +Sleep and power modes control +----------------------------- + +See ``pyb.Sleep``. :: + + from pyb import Sleep + + Sleep.idle() # lowest sleep mode (~12mA), any interrupts wakes it up + Sleep.suspend() # everything except for WLAN is powered down (~950uA) + # wakes from Pin, RTC or WLAN + + Sleep.hibernate() # deepest sleep mode, mcu starts from reset. Wakes from Pin and RTC. + +Heart beat LED +----------------------------- + +See :ref:`pyb.HeartBeat `. :: + + from pyb import HeartBeat + + # disable the heart beat indication (you are free to use this led connected to GPIO25) + HeartBeat.disable() + # enable the heart beat again + HeartBeat.enable() diff --git a/docs/wipy_contents.rst b/docs/wipy_contents.rst new file mode 100644 index 000000000..8a7c0e06e --- /dev/null +++ b/docs/wipy_contents.rst @@ -0,0 +1,9 @@ +MicroPython documentation contents +================================== + +.. toctree:: + + wipy/quickref.rst + wipy/general.rst + library/index.rst + license.rst diff --git a/docs/wipy_index.rst b/docs/wipy_index.rst new file mode 100644 index 000000000..da81ba6bc --- /dev/null +++ b/docs/wipy_index.rst @@ -0,0 +1,17 @@ +MicroPython documentation and references +======================================== + +.. toctree:: + + wipy/quickref.rst + wipy/general.rst + library/index.rst + license.rst + wipy_contents.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search`