diff options
Diffstat (limited to 'docs/library/machine.rst')
| -rw-r--r-- | docs/library/machine.rst | 82 |
1 files changed, 48 insertions, 34 deletions
diff --git a/docs/library/machine.rst b/docs/library/machine.rst index dacfe737b9..14d75cb466 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -18,76 +18,90 @@ Reset related functions Get the reset cause. See :ref:`constants <machine_constants>` for the possible return values. -Interrupt related functions ---------------------------- +.. only:: port_wipy -.. function:: disable_irq() + Interrupt related functions + --------------------------- - 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:: disable_irq() -.. function:: enable_irq(state=True) + 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. - 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. + .. 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 ----------------------- .. function:: freq() - Returns a tuple of clock frequencies: ``(sysclk,)`` - These correspond to: + .. only:: not port_wipy + + Returns CPU frequency in hertz. + + .. only:: port_wipy - - sysclk: frequency of the CPU + Returns a tuple of clock frequencies: ``(sysclk,)`` + These correspond to: + + - sysclk: frequency of the CPU .. function:: idle() Gates the clock to the CPU, useful to reduce power consumption at any time during short or long periods. Peripherals continue working and execution resumes as soon - as any interrupt is triggered (including the systick which has a period of 1ms). - Current consumption is reduced to ~12mA (in WLAN STA mode) + as any interrupt is triggered (on many ports this includes system timer + interrupt occuring at regular intervals on the order of millisecond). .. function:: sleep() Stops the CPU and disables all peripherals except for WLAN. Execution is resumed from - the point where the sleep was requested. Wake sources are ``Pin``, ``RTC`` and ``WLAN``. - Current consumption is reduced to 950uA (in WLAN STA mode). + the point where the sleep was requested. For wake up to actually happen, wake sources + should be configured first. .. function:: deepsleep() - Stops the CPU and all peripherals including WLAN. Execution is resumed from main, just - as with a reset. The reset cause can be checked to know that we are coming from - from ``machine.DEEPSLEEP``. Wake sources are ``Pin`` and ``RTC``. Current consumption - is reduced to ~5uA. + Stops the CPU and all peripherals (including networking interfaces, if any). Execution + is resumed from the main script, just as with a reset. The reset cause can be checked + to know that we are coming from ``machine.DEEPSLEEP``. For wake up to actually happen, + wake sources should be configured first, like ``Pin`` change or ``RTC`` timeout. + +.. only:: port_wipy -.. function:: wake_reason() + .. function:: wake_reason() - Get the wake reason. See :ref:`constants <machine_constants>` for the possible return values. + Get the wake reason. See :ref:`constants <machine_constants>` for the possible return values. Miscellaneous functions ----------------------- -.. function:: main(filename) +.. only:: port_wipy + + .. 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. + 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. + It only makes sense to call this function from within boot.py. -.. function:: rng() + .. function:: rng() - Return a 24-bit software generated random number. + Return a 24-bit software generated random number. .. function:: unique_id() - Returns a string of 6 bytes (48 bits), which is the unique ID of the MCU. - This also corresponds to the network ``MAC address``. + Returns a byte string with a unique idenifier of a board/SoC. It will vary + from a board/SoC instance to another, if underlying hardware allows. Length + varies by hardware (so use substring of a full value if you expect a short + ID). In some MicroPython ports, ID corresponds to the network MAC address. .. _machine_constants: |