diff options
| author | Daniel Campora <daniel@wipy.io> | 2015-06-10 23:29:56 +0200 |
|---|---|---|
| committer | Daniel Campora <daniel@wipy.io> | 2015-06-10 23:37:56 +0200 |
| commit | cfcf47c0644952358e1a260db159e807872a37e6 (patch) | |
| tree | 02522a025a7b803d7de0589dd743b34f3daa4634 /docs/library | |
| parent | b630de1103cd07ac0656c76c7f90d92312705835 (diff) | |
| download | micropython-cfcf47c0644952358e1a260db159e807872a37e6.tar.gz micropython-cfcf47c0644952358e1a260db159e807872a37e6.zip | |
docs: Add initial draft documentation for the WiPy.
This makes all common files "port-aware" using the .. only directive.
Diffstat (limited to 'docs/library')
| -rw-r--r-- | docs/library/index.rst | 110 | ||||
| -rw-r--r-- | docs/library/micropython.rst | 36 | ||||
| -rw-r--r-- | docs/library/network.rst | 442 | ||||
| -rw-r--r-- | docs/library/os.rst | 16 | ||||
| -rw-r--r-- | docs/library/pyb.ADC.rst | 95 | ||||
| -rw-r--r-- | docs/library/pyb.HeartBeat.rst | 46 | ||||
| -rw-r--r-- | docs/library/pyb.I2C.rst | 283 | ||||
| -rw-r--r-- | docs/library/pyb.Pin.rst | 603 | ||||
| -rw-r--r-- | docs/library/pyb.RTC.rst | 84 | ||||
| -rw-r--r-- | docs/library/pyb.SD.rst | 39 | ||||
| -rw-r--r-- | docs/library/pyb.SPI.rst | 273 | ||||
| -rw-r--r-- | docs/library/pyb.UART.rst | 182 | ||||
| -rw-r--r-- | docs/library/pyb.WDT.rst | 33 | ||||
| -rw-r--r-- | docs/library/pyb.rst | 351 | ||||
| -rw-r--r-- | docs/library/time.rst | 20 | ||||
| -rw-r--r-- | docs/library/uctypes.rst | 2 | ||||
| -rw-r--r-- | docs/library/uhashlib.rst | 70 |
17 files changed, 1835 insertions, 850 deletions
diff --git a/docs/library/index.rst b/docs/library/index.rst index 245a345f36..f00bd1c20a 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 <https://github.com/micropython/micropython-lib>`_. -.. toctree:: - :maxdepth: 1 +.. only:: port_pyboard + + .. toctree:: + :maxdepth: 1 + + cmath.rst + gc.rst + math.rst + os.rst + select.rst + struct.rst + sys.rst + time.rst + +.. only:: port_wipy - cmath.rst - gc.rst - math.rst - os.rst - select.rst - struct.rst - sys.rst - time.rst + .. 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 83ccb2900f..14e4c917e0 100644 --- a/docs/library/micropython.rst +++ b/docs/library/micropython.rst @@ -7,23 +7,25 @@ Functions --------- -.. 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. +.. only:: port_pyboard or port_unix + + .. 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 62a65144f1..b5a674acf2 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 -========== - -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 <pyb.SPI>` which is the SPI bus that the CC3000 is - connected to (the MOSI, MISO and CLK pins). - - ``pin_cs`` is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 CS pin. - - ``pin_en`` is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 VBEN pin. - - ``pin_irq`` is a :ref:`Pin object <pyb.Pin>` 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 <pyb.SPI>` which is the SPI bus that the WIZnet5x00 is - connected to (the MOSI, MISO and SCLK pins). - - ``pin_cs`` is a :ref:`Pin object <pyb.Pin>` which is connected to the WIZnet5x00 nSS pin. - - ``pin_rst`` is a :ref:`Pin object <pyb.Pin>` 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. +.. only:: port_pyboard + + 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 <pyb.SPI>` which is the SPI bus that the CC3000 is + connected to (the MOSI, MISO and CLK pins). + - ``pin_cs`` is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 CS pin. + - ``pin_en`` is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 VBEN pin. + - ``pin_irq`` is a :ref:`Pin object <pyb.Pin>` 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 <pyb.SPI>` which is the SPI bus that the WIZnet5x00 is + connected to (the MOSI, MISO and SCLK pins). + - ``pin_cs`` is a :ref:`Pin object <pyb.Pin>` which is connected to the WIZnet5x00 nSS pin. + - ``pin_rst`` is a :ref:`Pin object <pyb.Pin>` 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. + +.. only:: port_wipy + + class WLAN + ========== + + .. _network.WLAN: + + 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()) + + # now use socket as usual + ... + + 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:: + + # configure as an access point + nic = network.WLAN(WLAN.AP, 'wipy-wlan', security=WLAN.WPA_WPA2, key='www.wipy.io', channel=7) + + or:: + + # 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``. + + .. method:: wlan.callback(wakes) + + 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. + + - ``wakes`` can only be ``pyb.Sleep.SUSPENDED``. + + Returns a callback object. + + Constants + --------- + + .. data:: WLAN.STA + + WiFi station mode + + .. data:: WLAN.AP + + WiFi access point mode + + .. data:: WLAN.OPEN + + open network (no security) + + .. data:: WLAN.WEP + + WEP network security + + .. data:: WLAN.WPA_WPA2 + + WPA/WPA2 network security + + .. data:: WLAN.INT_ANTENNA + + selects the internal antenna + + .. data:: WLAN.EXT_ANTENNA + + selects the external antenna diff --git a/docs/library/os.rst b/docs/library/os.rst index e9b7d40bf5..e32a409f53 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 cc0934427f..64848d5779 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. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_ + 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) - - 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_pyboard + + .. 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 0000000000..971f2e93ec --- /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 e40684a78a..d3cbed0574 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:: - - 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 +when created, or initialised later on. + +.. only:: port_pyboard + + 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 + + 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 - 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) + 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 + + .. 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 + 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) - - 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_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. - -.. 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_pyboard + + .. 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 + + Returns the read data. + This is only valid in master mode. + +.. only:: port_wipy + + .. 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 + + 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 + + .. 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 - 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) + + 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 6f04378b6e..9f9100a783 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 + + 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). + +.. only:: port_wipy + + Board pins are identified by their string name:: + + g = pyb.Pin('GPIO9', af=0, mode=pyb.Pin.IN, type=pyb.Pin.STD, strength=pyb.Pin.S2MA) + + You can also configure the Pin to generate interrupts. For instance:: + + def pincb(pin): + print(pin.info().name) + + 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() + + Now every time a falling edge is seen on the gpio pin, the callback will be + executed. Caution: mechanical push buttons have "bounce" and pushing or + releasing a switch will often generate multiple edges. + See: http://www.eng.utah.edu/~cs5780/debouncing.pdf for a detailed + explanation, along with various techniques for debouncing. + + All pin objects go through the pin mapper to come up with one of the + gpio pins. - 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 :: +Constructors +------------ - pin = pyb.Pin("LeftMotorDir") +.. only:: port_pyboard -Users can also add their own mapping function:: + .. class:: pyb.Pin(id, ...) - def MyMapper(pin_name): - if pin_name == "LeftMotorDir": - return pyb.Pin.cpu.A0 + 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`. - pyb.Pin.mapper(MyMapper) +.. only:: port_wipy -So, if you were to call: ``pyb.Pin("LeftMotorDir", pyb.Pin.OUT_PP)`` -then ``"LeftMotorDir"`` is passed directly to the mapper function. + .. class:: pyb.Pin(name, ...) -To summarise, the following order determines how things get mapped into -an ordinal pin number: + 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`. -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 +.. only:: port_pyboard -You can set ``pyb.Pin.debug(True)`` to get some debug information about -how a particular object gets mapped to a pin. + 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. -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). -Constructors ------------- +Methods +------- -.. 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`. + .. 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. -Class methods -------------- + - ``pull`` can be one of: -.. method:: Pin.af_list() + - ``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. - Returns an array of alternate functions available for this pin. + - 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.debug([state]) +.. only:: port_wipy - Get or set the debugging state (``True`` or ``False`` for on or off). + .. 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. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_ + for the specific alternate functions that each pin supports. -.. method:: Pin.dict([dict]) + - ``mode`` can be one of: - Get or set the pin mapper dictionary. + - ``Pin.OUT`` - no pull up or down resistors. + - ``Pin.IN`` - enable the pull-up resistor. -.. method:: Pin.mapper([fun]) + - ``type`` can be one of: - Get or set the pin mapper function. + - ``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: -Methods -------- + - ``Pin.S2MA`` - 2mA drive capability. + - ``Pin.S4MA`` - 4mA drive capability. + - ``Pin.S6MA`` - 6mA drive capability. -.. 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``. + 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__() - - 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. +.. only:: port_pyboard + + .. 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. + +.. only:: port_wipy + + .. method:: pin.toggle() + + Toggle the value of the pin. + + .. method:: pin.info() + + Return a 5-tuple with the configuration of the pin: + ``(name, alternate-function, mode, type, strength)`` + + .. method:: pin.callback(mode, priority=1, handler=None, wakes=pyb.Sleep.ACTIVE) + + Create a callback to be triggered when data is received on the UART. + + - ``mode`` configures the pin level which can generate an interrupt. Possible values are: + + - ``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. + + - ``priority`` level of the interrupt. Can take values in the range 1-7. + Higher values represent higher priorities. + - ``handler`` is an optional function to be called when new characters arrive. + - ``wakes`` selects the power mode in which this interrupt can wake up the + board. Please note: + + - If ``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. + + Returns a callback object. Constants --------- -.. 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 - - -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 +.. only:: port_pyboard + + .. 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 + +.. only:: port_wipy + + .. 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 + +.. only:: port_pyboard + + class PinAF -- Pin Alternate Functions + ====================================== + + A Pin represents a physical pin on the microcprocessor. Each pin + can have a variety of functions (GPIO, I2C SDA, etc). Each PinAF + object represents a particular function for a pin. + + Usage Model:: + + x3 = pyb.Pin.board.X3 + x3_af = x3.af_list() + + x3_af will now contain an array of PinAF objects which are availble on + pin X3. + + For the pyboard, x3_af would contain: + [Pin.AF1_TIM2, Pin.AF2_TIM5, Pin.AF3_TIM9, Pin.AF7_USART2] + + Normally, each peripheral would configure the af automatically, but sometimes + the same function is available on multiple pins, and having more control + is desired. + + To configure X3 to expose TIM2_CH3, you could use:: + + pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=pyb.Pin.AF1_TIM2) + + or:: + + pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=1) + + Methods + ------- + + .. method:: pinaf.__str__() + + Return a string describing the alternate function. + + .. method:: pinaf.index() + + Return the alternate function index. + + .. method:: pinaf.name() + + Return the name of the alternate function. + + .. method:: pinaf.reg() + + Return the base register associated with the peripheral assigned to this + alternate function. For example, if the alternate function were TIM2_CH3 + this would return stm.TIM2 diff --git a/docs/library/pyb.RTC.rst b/docs/library/pyb.RTC.rst index cd4b28eabd..dacd2d7bb9 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) - - 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. +.. only:: port_pyboard + + .. 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 + +.. only:: port_wipy + + .. 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. - 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 diff --git a/docs/library/pyb.SD.rst b/docs/library/pyb.SD.rst new file mode 100644 index 0000000000..84feb83486 --- /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. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_ 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 70d6454015..d6f4bb9637 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, ...) - - 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_pyboard + + .. 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. - - 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. - -.. 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``. - -.. 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``. - -.. 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_pyboard + + .. 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. + +.. only:: port_wipy + + .. 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. + +.. only:: port_pyboard + + .. 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``. + +.. only:: port_wipy + + .. 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``. + +.. 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 + + .. 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 - for initialising the SPI bus to master or slave mode +.. only:: port_wipy -.. data:: SPI.LSB -.. data:: SPI.MSB + .. data:: SPI.MASTER - set the first bit to be the least or most significant bit + 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 75d1fbe9b4..01a04ef4e1 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, ...) - - 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)`` +.. only:: port_pyboard + + .. 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)`` + +.. only:: port_wipy + + .. 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) - - 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. - - ``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 <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. +.. only:: port_pyboard + + .. 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 <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. + +.. only:: port_wipy + + .. 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 + + 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. + 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 0000000000..9728e7bcaf --- /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 7cad587f90..5b682e2d61 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]]]]) - - 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. +.. only:: port_pyboard + + .. 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. + +.. only:: port_wipy + + .. function:: freq([sysclk]) + + Returns a tuple of clock frequencies: ``(sysclk)`` + These correspond to: + + - sysclk: frequency of the CPU Miscellaneous functions ----------------------- -.. 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. +.. only:: port_pyboard + + .. 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) - - 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``. +.. only:: port_pyboard + + .. 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 + + .. function:: rng() + + Return a 30-bit hardware generated random number. + +.. only:: port_wipy - Return a 30-bit hardware generated random number. + .. function:: rng() + + Return a 24-bit software generated random number. .. function:: sync() Sync all file systems. -.. function:: unique_id() +.. only:: port_pyboard + + .. function:: unique_id() + + Returns a string of 12 bytes (96 bits), which is the unique ID for the MCU. + +.. only:: port_wipy - Returns a string of 12 bytes (96 bits), which is the unique ID for the MCU. + .. 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 - - 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_pyboard + + .. 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 1ffce7c247..8595daa888 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 9a1a0d234c..73637a0e27 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 708e3d7bc9..a8f580fd84 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. + +.. method:: hash.hexdigest() - This method is NOT implemented. Use ``ubinascii.hexlify(sha256.digest())`` - to achieve similar effect. + This method is NOT implemented. Use ``ubinascii.hexlify(hash.digest())`` + to achieve a similar effect. |