diff options
Diffstat (limited to 'docs/library/pyb.rst')
| -rw-r--r-- | docs/library/pyb.rst | 321 |
1 files changed, 0 insertions, 321 deletions
diff --git a/docs/library/pyb.rst b/docs/library/pyb.rst deleted file mode 100644 index 799160145..000000000 --- a/docs/library/pyb.rst +++ /dev/null @@ -1,321 +0,0 @@ -:mod:`pyb` --- functions related to the board -============================================= - -.. module:: pyb - :synopsis: functions related to the board - -The ``pyb`` module contains specific functions related to the board. - -Time related functions ----------------------- - -.. function:: delay(ms) - - Delay for the given number of milliseconds. - -.. function:: udelay(us) - - Delay for the given number of microseconds. - -.. function:: millis() - - Returns the number of milliseconds since the board was last reset. - - The result is always a MicroPython smallint (31-bit signed number), so - after 2^30 milliseconds (about 12.4 days) this will start to return - negative numbers. - - Note that if :meth:`pyb.stop()` is issued the hardware counter supporting this - function will pause for the duration of the "sleeping" state. This - will affect the outcome of :meth:`pyb.elapsed_millis()`. - -.. function:: micros() - - Returns the number of microseconds since the board was last reset. - - The result is always a MicroPython smallint (31-bit signed number), so - after 2^30 microseconds (about 17.8 minutes) this will start to return - negative numbers. - - Note that if :meth:`pyb.stop()` is issued the hardware counter supporting this - function will pause for the duration of the "sleeping" state. This - will affect the outcome of :meth:`pyb.elapsed_micros()`. - -.. function:: elapsed_millis(start) - - Returns the number of milliseconds which have elapsed since ``start``. - - This function takes care of counter wrap, and always returns a positive - number. This means it can be used to measure periods up to about 12.4 days. - - Example:: - - start = pyb.millis() - while pyb.elapsed_millis(start) < 1000: - # Perform some operation - -.. function:: elapsed_micros(start) - - Returns the number of microseconds which have elapsed since ``start``. - - This function takes care of counter wrap, and always returns a positive - number. This means it can be used to measure periods up to about 17.8 minutes. - - Example:: - - start = pyb.micros() - while pyb.elapsed_micros(start) < 1000: - # Perform some operation - pass - -Reset related functions ------------------------ - -.. function:: hard_reset() - - Resets the pyboard in a manner similar to pushing the external RESET - button. - -.. function:: bootloader() - - Activate the bootloader without BOOT\* pins. - -.. function:: fault_debug(value) - - Enable or disable hard-fault debugging. A hard-fault is when there is a fatal - error in the underlying system, like an invalid memory access. - - If the *value* argument is ``False`` then the board will automatically reset if - there is a hard fault. - - If *value* is ``True`` then, when the board has a hard fault, it will print the - registers and the stack trace, and then cycle the LEDs indefinitely. - - The default value is disabled, i.e. to automatically reset. - -Interrupt related functions ---------------------------- - -.. function:: disable_irq() - - Disable interrupt requests. - Returns the previous IRQ state: ``False``/``True`` for disabled/enabled IRQs - respectively. This return value can be passed to enable_irq to restore - the IRQ to its original state. - -.. function:: enable_irq(state=True) - - Enable interrupt requests. - If ``state`` is ``True`` (the default value) then IRQs are enabled. - If ``state`` is ``False`` then IRQs are disabled. The most common use of - this function is to pass it the value returned by ``disable_irq`` to - exit a critical section. - -Power related functions ------------------------ - -.. 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 a real-time-clock event, or an external interrupt - on X1 (PA0=WKUP) or X18 (PC13=TAMP1). - Upon waking the system undergoes a hard reset. - - See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event. - -Miscellaneous functions ------------------------ - -.. 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 :meth:`pyb.USB_HID.send()` instead. - - .. function:: info([dump_alloc_table]) - - Print out lots of information about the board. - -.. function:: main(filename) - - Set the filename of the main script to run after boot.py is finished. If - this function is not called then the default file main.py will be executed. - - It only makes sense to call this function from within boot.py. - -.. 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 where the REPL is repeated on. - -.. only:: port_pyboard - - .. function:: rng() - - Return a 30-bit hardware generated random number. - -.. function:: sync() - - Sync all file systems. - -.. only:: port_pyboard - - .. function:: unique_id() - - Returns a string of 12 bytes (96 bits), which is the unique ID of the MCU. - -.. function:: usb_mode([modestr], vid=0xf055, pid=0x9801, hid=pyb.hid_mouse) - - If called with no arguments, return the current USB mode as a string. - - If called with ``modestr`` provided, attempts to set USB mode. - This can only be done when called from ``boot.py`` before - :meth:`pyb.main()` has been called. The following values of - ``modestr`` are understood: - - - ``None``: disables USB - - ``'VCP'``: enable with VCP (Virtual COM Port) interface - - ``'VCP+MSC'``: enable with VCP and MSC (mass storage device class) - - ``'VCP+HID'``: enable with VCP and HID (human interface device) - - For backwards compatibility, ``'CDC'`` is understood to mean - ``'VCP'`` (and similarly for ``'CDC+MSC'`` and ``'CDC+HID'``). - - The ``vid`` and ``pid`` parameters allow you to specify the VID - (vendor id) and PID (product id). - - If enabling HID mode, you may also specify the HID details by - passing the ``hid`` keyword parameter. It takes a tuple of - (subclass, protocol, max packet length, polling interval, report - descriptor). By default it will set appropriate values for a USB - mouse. There is also a ``pyb.hid_keyboard`` constant, which is an - appropriate tuple for a USB keyboard. - -Classes -------- - -.. 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_HID.rst - pyb.USB_VCP.rst |