diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index c44a140faf0f..1ec6c7067f9c 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -11,19 +11,10 @@ body: * If you have a question \"How Do I ...?\", please post it on [GitHub Discussions](https://github.com/orgs/micropython/discussions/) or [Discord](https://discord.gg/RB8HZSAExQ) instead of here. * For missing or incorrect documentation, or feature requests, then please [choose a different issue type](https://github.com/micropython/micropython/issues/new/choose). - - type: checkboxes - id: terms - attributes: - label: Checks - description: | - Before submitting your bug report, please go over these check points: - options: - - label: | - I agree to follow the MicroPython [Code of Conduct](https://github.com/micropython/micropython/blob/master/CODEOFCONDUCT.md) to ensure a safe and respectful space for everyone. - required: true - - label: | - I've searched for [existing issues](https://github.com/micropython/micropython/issues) matching this bug, and didn't find any. - required: true + + #### Existing issue? + + * Please search for [existing issues](https://github.com/micropython/micropython/issues) matching this bug before reporting. - type: input id: port-board-hw attributes: @@ -33,7 +24,7 @@ body: placeholder: | esp32 port, ESP32-Fantastic board. validations: - required: true + required: true - type: textarea id: version attributes: @@ -101,6 +92,17 @@ body: description: | Is there anything else that might help to resolve this issue? value: No, I've provided everything above. + - type: dropdown + id: code-of-conduct + attributes: + label: Code of Conduct + description: | + Do you agree to follow the MicroPython [Code of Conduct](https://github.com/micropython/micropython/blob/master/CODEOFCONDUCT.md) to ensure a safe and respectful space for everyone? + options: + - "Yes, I agree" + multiple: true + validations: + required: true - type: markdown attributes: value: | diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml index 5be024170174..93051e51c80c 100644 --- a/.github/ISSUE_TEMPLATE/documentation.yml +++ b/.github/ISSUE_TEMPLATE/documentation.yml @@ -9,19 +9,10 @@ body: This form is for reporting issues with the documentation or examples provided with MicroPython. If you have a general question \"How Do I ...?\", please post it on [GitHub Discussions](https://github.com/orgs/micropython/discussions/) or [Discord](https://discord.gg/RB8HZSAExQ) instead of here. - - type: checkboxes - id: terms - attributes: - label: Checks - description: | - Before submitting your bug report, please go over these check points: - options: - - label: | - I agree to follow the MicroPython [Code of Conduct](https://github.com/micropython/micropython/blob/master/CODEOFCONDUCT.md) to ensure a safe and respectful space for everyone. - required: true - - label: | - I've searched for [existing issues](https://github.com/micropython/micropython/issues) and didn't find any that matched. - required: true + + #### Existing issue? + + * Please search for [existing issues](https://github.com/micropython/micropython/issues) before reporting a new one. - type: input id: page attributes: @@ -38,6 +29,17 @@ body: Please describe what was missing from the documentation and/or what was incorrect/incomplete. validations: required: true + - type: dropdown + id: code-of-conduct + attributes: + label: Code of Conduct + description: | + Do you agree to follow the MicroPython [Code of Conduct](https://github.com/micropython/micropython/blob/master/CODEOFCONDUCT.md) to ensure a safe and respectful space for everyone? + options: + - "Yes, I agree" + multiple: true + validations: + required: true - type: markdown attributes: value: | diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 845fbed810ef..7d5162a32a4a 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -15,19 +15,10 @@ body: * If you have a question \"How Do I ...?\", please post it on GitHub Discussions or Discord instead of here. * Could this feature be implemented as a pure Python library? If so, please open the request on the [micropython-lib repository](https://github.com/micropython/micropython-lib/issues) instead. - - type: checkboxes - id: terms - attributes: - label: Checks - description: | - Before submitting your feature request, please go over these check points: - options: - - label: | - I agree to follow the MicroPython [Code of Conduct](https://github.com/micropython/micropython/blob/master/CODEOFCONDUCT.md) to ensure a safe and respectful space for everyone. - required: true - - label: | - I've searched for [existing issues](https://github.com/micropython/micropython/issues) regarding this feature, and didn't find any. - required: true + + #### Existing issue? + + * Please search for [existing issues](https://github.com/micropython/micropython/issues) before opening a new one. - type: textarea id: feature attributes: @@ -51,14 +42,32 @@ body: MicroPython aims to strike a balance between functionality and code size. Can this feature be optionally enabled? If you believe the usefulness of this feature would outweigh the additional code size, please explain. (It's OK to say you're unsure here, we're happy to discuss this with you.) - - type: checkboxes + - type: dropdown id: implementation attributes: label: Implementation + description: | + What is your suggestion for implementing this feature? + + (See also: [How to sponsor](https://github.com/sponsors/micropython#sponsors), [How to submit a Pull Request](https://github.com/micropython/micropython/wiki/ContributorGuidelines).) options: - - label: I intend to implement this feature and would submit a Pull Request if desirable. - - label: I hope the MicroPython maintainers or community will implement this feature. - - label: I would like to [Sponsor](https://github.com/sponsors/micropython#sponsors) development of this feature. + - I hope the MicroPython maintainers or community will implement this feature + - I intend to implement this feature and would submit a Pull Request if desirable + - I would like to sponsor development of this feature + multiple: true + validations: + required: true + - type: dropdown + id: code-of-conduct + attributes: + label: Code of Conduct + description: | + Do you agree to follow the MicroPython [Code of Conduct](https://github.com/micropython/micropython/blob/master/CODEOFCONDUCT.md) to ensure a safe and respectful space for everyone? + options: + - "Yes, I agree" + multiple: true + validations: + required: true - type: markdown attributes: value: | diff --git a/.github/ISSUE_TEMPLATE/security.yml b/.github/ISSUE_TEMPLATE/security.yml index 7d66a72f6412..57c2a5885ed8 100644 --- a/.github/ISSUE_TEMPLATE/security.yml +++ b/.github/ISSUE_TEMPLATE/security.yml @@ -9,21 +9,11 @@ body: 1. For issues that are readily exploitable or have high impact, please email contact@micropython.org instead. 1. If this is a question about security, please ask it in [Discussions](https://github.com/orgs/micropython/discussions/) or [Discord](https://discord.gg/RB8HZSAExQ) instead. - - type: checkboxes - id: terms - attributes: - label: Checks - description: | - Before submitting your bug report, please go over these check points: - options: - - label: | - I agree to follow the MicroPython [Code of Conduct](https://github.com/micropython/micropython/blob/master/CODEOFCONDUCT.md) to ensure a safe and respectful space for everyone. - required: true - - label: I wish to report a specific security issue that is **not readily exploitable and does not have high impact** for MicroPython developers or users. - required: true - - label: | - I've searched for [existing issues](https://github.com/micropython/micropython/issues) and didn't find any that matched. - required: true + + #### Existing issue? + + * Please search for [existing issues](https://github.com/micropython/micropython/issues) before reporting a new one. + - type: input id: port-board-hw attributes: @@ -57,3 +47,14 @@ body: * How does the attacker exploit this issue? validations: required: true + - type: dropdown + id: code-of-conduct + attributes: + label: Code of Conduct + description: | + Do you agree to follow the MicroPython [Code of Conduct](https://github.com/micropython/micropython/blob/master/CODEOFCONDUCT.md) to ensure a safe and respectful space for everyone? + options: + - "Yes, I agree" + multiple: true + validations: + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000000..e11cebddb371 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,33 @@ + + +### Summary + + + + +### Testing + + + + +### Trade-offs and Alternatives + + + diff --git a/.github/workflows/code_size.yml b/.github/workflows/code_size.yml index 1ef43d1fd396..163d4455cffe 100644 --- a/.github/workflows/code_size.yml +++ b/.github/workflows/code_size.yml @@ -24,7 +24,7 @@ concurrency: jobs: build: - runs-on: ubuntu-20.04 + runs-on: ubuntu-22.04 steps: - uses: actions/checkout@v4 with: diff --git a/.github/workflows/code_size_comment.yml b/.github/workflows/code_size_comment.yml index a394f7a14b05..521afad709d1 100644 --- a/.github/workflows/code_size_comment.yml +++ b/.github/workflows/code_size_comment.yml @@ -11,7 +11,7 @@ concurrency: jobs: comment: - runs-on: ubuntu-20.04 + runs-on: ubuntu-22.04 steps: - name: 'Download artifact' id: download-artifact diff --git a/.github/workflows/ports_qemu-arm.yml b/.github/workflows/ports_qemu-arm.yml deleted file mode 100644 index db3cd7871d59..000000000000 --- a/.github/workflows/ports_qemu-arm.yml +++ /dev/null @@ -1,32 +0,0 @@ -name: qemu-arm port - -on: - push: - pull_request: - paths: - - '.github/workflows/*.yml' - - 'tools/**' - - 'py/**' - - 'extmod/**' - - 'shared/**' - - 'lib/**' - - 'drivers/**' - - 'ports/qemu-arm/**' - - 'tests/**' - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -jobs: - build_and_test: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - name: Install packages - run: source tools/ci.sh && ci_qemu_arm_setup - - name: Build and run test suite - run: source tools/ci.sh && ci_qemu_arm_build - - name: Print failures - if: failure() - run: grep --before-context=100 --text "FAIL" ports/qemu-arm/build/console.out diff --git a/.github/workflows/ports_qemu.yml b/.github/workflows/ports_qemu.yml new file mode 100644 index 000000000000..57192c43936e --- /dev/null +++ b/.github/workflows/ports_qemu.yml @@ -0,0 +1,44 @@ +name: qemu port + +on: + push: + pull_request: + paths: + - '.github/workflows/*.yml' + - 'tools/**' + - 'py/**' + - 'extmod/**' + - 'shared/**' + - 'lib/**' + - 'drivers/**' + - 'ports/qemu/**' + - 'tests/**' + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + build_and_test_arm: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Install packages + run: source tools/ci.sh && ci_qemu_setup_arm + - name: Build and run test suite + run: source tools/ci.sh && ci_qemu_build_arm + - name: Print failures + if: failure() + run: tests/run-tests.py --print-failures + + build_and_test_rv32: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Install packages + run: source tools/ci.sh && ci_qemu_setup_rv32 + - name: Build and run test suite + run: source tools/ci.sh && ci_qemu_build_rv32 + - name: Print failures + if: failure() + run: tests/run-tests.py --print-failures diff --git a/.github/workflows/ports_unix.yml b/.github/workflows/ports_unix.yml index 4473847db61e..1707fdc9fb37 100644 --- a/.github/workflows/ports_unix.yml +++ b/.github/workflows/ports_unix.yml @@ -194,7 +194,7 @@ jobs: run: tests/run-tests.py --print-failures macos: - runs-on: macos-11.0 + runs-on: macos-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 @@ -235,3 +235,17 @@ jobs: - name: Print failures if: failure() run: tests/run-tests.py --print-failures + + qemu_riscv64: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Install packages + run: source tools/ci.sh && ci_unix_qemu_riscv64_setup + - name: Build + run: source tools/ci.sh && ci_unix_qemu_riscv64_build + - name: Run main test suite + run: source tools/ci.sh && ci_unix_qemu_riscv64_run_tests + - name: Print failures + if: failure() + run: tests/run-tests.py --print-failures diff --git a/.github/workflows/ports_windows.yml b/.github/workflows/ports_windows.yml index be2a2a8dac33..91a3192a10a4 100644 --- a/.github/workflows/ports_windows.yml +++ b/.github/workflows/ports_windows.yml @@ -42,6 +42,8 @@ jobs: configuration: Debug - visualstudio: '2019' configuration: Debug + env: + CI_BUILD_CONFIGURATION: ${{ matrix.configuration }} runs-on: ${{ matrix.runner }} steps: - name: Install Visual Studio 2017 @@ -108,16 +110,6 @@ jobs: run: shell: msys2 {0} steps: - - name: Get Python path - id: python_path - shell: python - run: | - import os - import sys - output = f"python={os.fspath(sys.executable)}" - print(output) - with open(os.environ["GITHUB_OUTPUT"], "w") as f: - f.write(output) - uses: msys2/setup-msys2@v2 with: msystem: ${{ matrix.sys }} @@ -126,7 +118,7 @@ jobs: make mingw-w64-${{ matrix.env }}-gcc pkg-config - python3 + mingw-w64-${{ matrix.env }}-python3 git diffutils - uses: actions/checkout@v4 @@ -138,8 +130,7 @@ jobs: run: make -C ports/windows -j2 VARIANT=${{ matrix.variant }} - name: Run tests id: test - # msys python breaks tests so we need to use "real" windows python - run: MICROPY_CPYTHON3=$(cygpath "${{ steps.python_path.outputs.python }}") make -C ports/windows test_full VARIANT=${{ matrix.variant }} + run: make -C ports/windows test_full VARIANT=${{ matrix.variant }} - name: Print failures if: failure() && steps.test.conclusion == 'failure' working-directory: tests diff --git a/.github/workflows/ports_zephyr.yml b/.github/workflows/ports_zephyr.yml index f6f328c9277e..444b0973daff 100644 --- a/.github/workflows/ports_zephyr.yml +++ b/.github/workflows/ports_zephyr.yml @@ -20,6 +20,15 @@ jobs: build: runs-on: ubuntu-latest steps: + - uses: jlumbroso/free-disk-space@main + with: + # Only free up a few things so this step runs quickly. + android: false + dotnet: true + haskell: true + large-packages: false + docker-images: false + swap-storage: false - uses: actions/checkout@v4 - name: Install packages run: source tools/ci.sh && ci_zephyr_setup @@ -27,3 +36,8 @@ jobs: run: source tools/ci.sh && ci_zephyr_install - name: Build run: source tools/ci.sh && ci_zephyr_build + - name: Run main test suite + run: source tools/ci.sh && ci_zephyr_run_tests + - name: Print failures + if: failure() + run: tests/run-tests.py --print-failures diff --git a/.gitignore b/.gitignore index 2d20cb18970e..b5010dfd14db 100644 --- a/.gitignore +++ b/.gitignore @@ -11,8 +11,9 @@ build/ build-*/ docs/genrst/ -# Test failure outputs +# Test failure outputs and intermediate artefacts tests/results/* +tests/ports/unix/ffi_lib.so # Python cache files __pycache__/ diff --git a/.gitmodules b/.gitmodules index 7c9dbce0e00f..5d5170d39e94 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +1,9 @@ +[submodule "lib/axtls"] + path = lib/axtls + url = https://github.com/micropython/axtls.git +[submodule "lib/lwip"] + path = lib/lwip + url = https://github.com/lwip-tcpip/lwip.git [submodule "lib/berkeley-db-1.xx"] path = lib/berkeley-db-1.xx url = https://github.com/micropython/berkeley-db-1.xx diff --git a/LICENSE b/LICENSE index 469ae1927396..550ed9574d06 100644 --- a/LICENSE +++ b/LICENSE @@ -59,7 +59,6 @@ used during the build process and is not part of the compiled source code. /pico-sdk (BSD-3-clause) /re15 (BSD-3-clause) /stm32lib (BSD-3-clause) - /tinytest (BSD-3-clause) /tinyusb (MIT) /uzlib (Zlib) /wiznet5k (MIT) @@ -73,6 +72,7 @@ used during the build process and is not part of the compiled source code. /ppp_set_auth.* (Apache-2.0) /rp2 /mutex_extra.c (BSD-3-clause) + /clocks_extra.c (BSD-3-clause) /stm32 /usbd*.c (MCD-ST Liberty SW License Agreement V2) /stm32_it.* (MIT + BSD-3-clause) diff --git a/README.md b/README.md index f5bc6d78f0a4..c78a2384604f 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Python 3.5 and some select features from later versions). The following core datatypes are provided: `str`(including basic Unicode support), `bytes`, `bytearray`, `tuple`, `list`, `dict`, `set`, `frozenset`, `array.array`, `collections.namedtuple`, classes and instances. Builtin modules include -`os`, `sys`, `time`, `re`, and `struct`, etc. Select ports have support for +`os`, `sys`, `time`, `re`, and `struct`, etc. Some ports have support for `_thread` module (multithreading), `socket` and `ssl` for networking, and `asyncio`. Note that only a subset of Python 3 functionality is implemented for the data types and modules. @@ -35,8 +35,8 @@ DAC, PWM, SPI, I2C, CAN, Bluetooth, and USB. Getting started --------------- -See the [online documentation](https://docs.micropython.org/) for API -references and information about using MicroPython and information about how +See the [online documentation](https://docs.micropython.org/) for the API +reference and information about using MicroPython and information about how it is implemented. We use [GitHub Discussions](https://github.com/micropython/micropython/discussions) @@ -108,13 +108,13 @@ track of the code size of the core runtime and VM. In addition, the following ports are provided in this repository: - [cc3200](ports/cc3200) -- Texas Instruments CC3200 (including PyCom WiPy). - - [esp32](ports/esp32) -- Espressif ESP32 SoC (including ESP32S2, ESP32S3, ESP32C3). + - [esp32](ports/esp32) -- Espressif ESP32 SoC (including ESP32S2, ESP32S3, ESP32C3, ESP32C6). - [esp8266](ports/esp8266) -- Espressif ESP8266 SoC. - [mimxrt](ports/mimxrt) -- NXP m.iMX RT (including Teensy 4.x). - [nrf](ports/nrf) -- Nordic Semiconductor nRF51 and nRF52. - [pic16bit](ports/pic16bit) -- Microchip PIC 16-bit. - [powerpc](ports/powerpc) -- IBM PowerPC (including Microwatt) - - [qemu-arm](ports/qemu-arm) -- QEMU-based emulated target, for testing) + - [qemu](ports/qemu) -- QEMU-based emulated target (for testing) - [renesas-ra](ports/renesas-ra) -- Renesas RA family. - [rp2](ports/rp2) -- Raspberry Pi RP2040 (including Pico and Pico W). - [samd](ports/samd) -- Microchip (formerly Atmel) SAMD21 and SAMD51. diff --git a/docs/develop/cmodules.rst b/docs/develop/cmodules.rst index 75dbc953c06f..c5aa919b7645 100644 --- a/docs/develop/cmodules.rst +++ b/docs/develop/cmodules.rst @@ -59,7 +59,7 @@ A MicroPython user C module is a directory with the following files: SRC_USERMOD_LIB_C += $(EXAMPLE_MOD_DIR)/utils/algorithm.c Similarly, use ``SRC_USERMOD_CXX`` and ``SRC_USERMOD_LIB_CXX`` for C++ - source files. + source files. If you want to include assembly files use ``SRC_USERMOD_LIB_ASM``. If you have custom compiler options (like ``-I`` to add directories to search for header files), these should be added to ``CFLAGS_USERMOD`` for C code diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst index 2be1dbadc353..3ab4e8f5ecd9 100644 --- a/docs/esp32/quickref.rst +++ b/docs/esp32/quickref.rst @@ -18,7 +18,7 @@ working with this board it may be useful to get an overview of the microcontroll general.rst tutorial/index.rst -Note that there are several varieties of ESP32 -- ESP32, ESP32C3, ESP32S2, ESP32S3 -- +Note that there are several varieties of ESP32 -- ESP32, ESP32C3, ESP32C6, ESP32S2, ESP32S3 -- supported by MicroPython, with some differences in functionality between them. Installing MicroPython @@ -61,13 +61,13 @@ The :mod:`esp32` module:: import esp32 esp32.raw_temperature() # read the internal temperature of the MCU, in Fahrenheit - esp32.ULP() # access to the Ultra-Low-Power Co-processor, not on ESP32C3 + esp32.ULP() # access to the Ultra-Low-Power Co-processor, not on ESP32C3/C6 Note that the temperature sensor in the ESP32 will typically read higher than ambient due to the IC getting warm while it runs. This effect can be minimised by reading the temperature sensor immediately after waking up from sleep. -ESP32C3, ESP32S2, and ESP32S3 also have an internal temperature sensor available. +ESP32C3, ESP32C6, ESP32S2, and ESP32S3 also have an internal temperature sensor available. It is implemented a bit differently to the ESP32 and returns the temperature in Celsius:: @@ -89,7 +89,7 @@ The :mod:`network` module:: wlan.isconnected() # check if the station is connected to an AP wlan.connect('ssid', 'key') # connect to an AP wlan.config('mac') # get the interface's MAC address - wlan.ifconfig() # get the interface's IP/netmask/gw/DNS addresses + wlan.ipconfig('addr4') # get the interface's IPv4 addresses ap = network.WLAN(network.AP_IF) # create access-point interface ap.config(ssid='ESP-AP') # set the SSID of the access point @@ -107,7 +107,7 @@ A useful function for connecting to your local WiFi network is:: wlan.connect('ssid', 'key') while not wlan.isconnected(): pass - print('network config:', wlan.ifconfig()) + print('network config:', wlan.ipconfig('addr4')) Once the network is established the :mod:`socket ` module can be used to create and use TCP/UDP sockets as usual, and the ``requests`` module for @@ -130,7 +130,7 @@ To use the wired interfaces one has to specify the pins and mode :: lan = network.LAN(mdc=PIN_MDC, ...) # Set the pin and mode configuration lan.active(True) # activate the interface - lan.ifconfig() # get the interface's IP/netmask/gw/DNS addresses + lan.ipconfig('addr4') # get the interface's IPv4 addresses The keyword arguments for the constructor defining the PHY type and interface are: diff --git a/docs/esp32/tutorial/peripheral_access.rst b/docs/esp32/tutorial/peripheral_access.rst index ecdec101f7ef..f7c32c367ca0 100644 --- a/docs/esp32/tutorial/peripheral_access.rst +++ b/docs/esp32/tutorial/peripheral_access.rst @@ -32,6 +32,18 @@ the prescaler of the MCPWM0 peripheral. mem32[MCPWM0] = 0x55 # change PWM_CLK_PRESCALE print(hex(mem32[MCPWM0])) # read PWM_CLK_CFG_REG +The specific addresses will be different on different ESP32 +models. For example, ESP32-S3 uses these values: + +.. code-block:: python3 + + DR_REG_DPORT_BASE = const(0x600C_0000) + DPORT_PERIP_CLK_EN0_REG = const(DR_REG_DPORT_BASE + 0x0018) + DPORT_PERIP_RST_EN0_REG = const(DR_REG_DPORT_BASE + 0x0020) + DPORT_PWM0_CLK_EN = const(1 << 17) + MCPWM0 = const(0x6001_E000 + 0x0004) + ... + Note that before a peripheral can be used its clock must be enabled and it must be taken out of reset. In the above example the following registers are used for this: diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst index ed2199737099..b130ce65db2b 100644 --- a/docs/esp8266/quickref.rst +++ b/docs/esp8266/quickref.rst @@ -59,7 +59,7 @@ The :mod:`network` module:: wlan.isconnected() # check if the station is connected to an AP wlan.connect('ssid', 'key') # connect to an AP wlan.config('mac') # get the interface's MAC address - wlan.ifconfig() # get the interface's IP/netmask/gw/DNS addresses + wlan.ipconfig('addr4') # get the interface's IPv4 addresses ap = network.WLAN(network.AP_IF) # create access-point interface ap.active(True) # activate the interface @@ -76,7 +76,7 @@ A useful function for connecting to your local WiFi network is:: wlan.connect('ssid', 'key') while not wlan.isconnected(): pass - print('network config:', wlan.ifconfig()) + print('network config:', wlan.ipconfig('addr4')) Once the network is established the :mod:`socket ` module can be used to create and use TCP/UDP sockets as usual. diff --git a/docs/esp8266/tutorial/network_basics.rst b/docs/esp8266/tutorial/network_basics.rst index dc3cd3dd5e07..9d74a6283ac4 100644 --- a/docs/esp8266/tutorial/network_basics.rst +++ b/docs/esp8266/tutorial/network_basics.rst @@ -19,10 +19,10 @@ You can check if the interfaces are active by:: You can also check the network settings of the interface by:: - >>> ap_if.ifconfig() - ('192.168.4.1', '255.255.255.0', '192.168.4.1', '8.8.8.8') + >>> ap_if.ipconfig('addr4') + ('192.168.4.1', '255.255.255.0') -The returned values are: IP address, netmask, gateway, DNS. +The returned values are: IP address and netmask. Configuration of the WiFi ------------------------- @@ -45,8 +45,8 @@ To check if the connection is established use:: Once established you can check the IP address:: - >>> sta_if.ifconfig() - ('192.168.0.2', '255.255.255.0', '192.168.0.1', '8.8.8.8') + >>> sta_if.ipconfig('addr4') + ('192.168.0.2', '255.255.255.0') You can then disable the access-point interface if you no longer need it:: @@ -64,7 +64,7 @@ connect to your WiFi network:: sta_if.connect('', '') while not sta_if.isconnected(): pass - print('network config:', sta_if.ifconfig()) + print('network config:', sta_if.ipconfig('addr4')) Sockets ------- diff --git a/docs/library/builtins.rst b/docs/library/builtins.rst index 7a0229c2aaaf..e489375b1f91 100644 --- a/docs/library/builtins.rst +++ b/docs/library/builtins.rst @@ -82,6 +82,10 @@ Functions and types In MicroPython, `byteorder` parameter must be positional (this is compatible with CPython). + .. note:: The optional ``signed`` kwarg from CPython is not supported. + MicroPython currently converts negative integers as signed, + and positive as unsigned. (:ref:`Details `.) + .. function:: isinstance() .. function:: issubclass() diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index 49fb66beb38e..68070133b8fb 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -238,6 +238,12 @@ The following methods are not part of the core Pin API and only implemented on c Availability: cc3200 port. +.. method:: Pin.toggle() + + Toggle output pin from "0" to "1" or vice-versa. + + Availability: mimxrt, samd, rp2 ports. + Constants --------- diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index 2238561e708c..04159176919a 100644 --- a/docs/library/machine.UART.rst +++ b/docs/library/machine.UART.rst @@ -145,7 +145,7 @@ Methods .. note:: - For the rp2, esp8266 and nrf ports the call returns while the last byte is sent. + For the esp8266 and nrf ports the call returns while the last byte is sent. If required, a one character wait time has to be added in the calling script. Availability: rp2, esp32, esp8266, mimxrt, cc3200, stm32, nrf ports, renesas-ra @@ -157,8 +157,91 @@ Methods .. note:: - For the rp2, esp8266 and nrf ports the call may return ``True`` even if the last byte + For the esp8266 and nrf ports the call may return ``True`` even if the last byte of a transfer is still being sent. If required, a one character wait time has to be added in the calling script. Availability: rp2, esp32, esp8266, mimxrt, cc3200, stm32, nrf ports, renesas-ra + +.. method:: UART.irq(handler=None, trigger=0, hard=False) + + Configure an interrupt handler to be called when a UART event occurs. + + The arguments are: + + - *handler* is an optional function to be called when the interrupt event + triggers. The handler must take exactly one argument which is the + ``UART`` instance. + + - *trigger* configures the event(s) which can generate an interrupt. + Possible values are a mask of one or more of the following: + + - ``UART.IRQ_RXIDLE`` interrupt after receiving at least one character + and then the RX line goes idle. + - ``UART.IRQ_RX`` interrupt after each received character. + - ``UART.IRQ_TXIDLE`` interrupt after or while the last character(s) of + a message are or have been sent. + - ``UART.IRQ_BREAK`` interrupt when a break state is detected at RX + + - *hard* if true a hardware interrupt is used. This reduces the delay + between the pin change and the handler being called. Hard interrupt + handlers may not allocate memory; see :ref:`isr_rules`. + + Returns an irq object. + + Due to limitations of the hardware not all trigger events are available on all ports. + + .. table:: Availability of triggers + :align: center + + ============== ========== ====== ========== ========= + Port / Trigger IRQ_RXIDLE IRQ_RX IRQ_TXIDLE IRQ_BREAK + ============== ========== ====== ========== ========= + CC3200 yes + ESP32 yes yes yes + MIMXRT yes yes + NRF yes yes + RENESAS-RA yes yes + RP2 yes yes yes + SAMD yes yes yes + STM32 yes yes + ============== ========== ====== ========== ========= + + + .. note:: + - The ESP32 port does not support the option hard=True. + + - The rp2 port's UART.IRQ_TXIDLE is only triggered when the message + is longer than 5 characters and the trigger happens when still 5 characters + are to be sent. + + - The rp2 port's UART.IRQ_BREAK needs receiving valid characters for triggering + again. + + - The SAMD port's UART.IRQ_TXIDLE is triggered while the last character is sent. + + - On STM32F4xx MCU's, using the trigger UART.IRQ_RXIDLE the handler will be called once + after the first character and then after the end of the message, when the line is + idle. + + + Availability: cc3200, esp32, mimxrt, nrf, renesas-ra, rp2, samd, stm32. + +Constants +--------- + +.. data:: UART.RTS + UART.CTS + + Flow control options. + + Availability: esp32, mimxrt, renesas-ra, rp2, stm32. + +.. data:: UART.IRQ_RXIDLE + UART.IRQ_RX + UART.IRQ_TXIDLE + UART.IRQ_BREAK + + IRQ trigger sources. + + Availability: renesas-ra, stm32, esp32, rp2040, mimxrt, samd, cc3200. diff --git a/docs/library/machine.USBDevice.rst b/docs/library/machine.USBDevice.rst index 5fc71651612b..a47fda2a28d3 100644 --- a/docs/library/machine.USBDevice.rst +++ b/docs/library/machine.USBDevice.rst @@ -215,6 +215,13 @@ Methods drivers. Placing a different string at any of these indexes overrides that string in the built-in driver. +.. method:: USBDevice.remote_wakeup(self) + + Wake up host if we are in suspend mode and the REMOTE_WAKEUP feature + is enabled by the host. This has to be enabled in the USB attributes, + and on the host. Returns ``True`` if remote wakeup was enabled and + active and the host was woken up. + .. method:: USBDevice.submit_xfer(self, ep, buffer /) Submit a USB transfer on endpoint number ``ep``. ``buffer`` must be diff --git a/docs/library/machine.rst b/docs/library/machine.rst index 004188ba6ec5..3405cd041855 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -126,14 +126,20 @@ Power related functions .. 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 (on many ports this includes system timer - interrupt occurring at regular intervals on the order of millisecond). + 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, or at most one millisecond + after the CPU was paused. + + It is recommended to call this function inside any tight loop that is + continuously checking for an external change (i.e. polling). This will reduce + power consumption without significantly impacting performance. To reduce + power consumption further then see the :func:`lightsleep`, + :func:`time.sleep()` and :func:`time.sleep_ms()` functions. .. function:: sleep() - .. note:: This function is deprecated, use `lightsleep()` instead with no arguments. + .. note:: This function is deprecated, use :func:`lightsleep()` instead with no arguments. .. function:: lightsleep([time_ms]) deepsleep([time_ms]) diff --git a/docs/library/math.rst b/docs/library/math.rst index a05edf0c3d8c..8b48aebe2e77 100644 --- a/docs/library/math.rst +++ b/docs/library/math.rst @@ -122,8 +122,11 @@ Functions Return the natural logarithm of the gamma function of ``x``. .. function:: log(x) + log(x, base) - Return the natural logarithm of ``x``. + With one argument, return the natural logarithm of *x*. + + With two arguments, return the logarithm of *x* to the given *base*. .. function:: log10(x) diff --git a/docs/library/micropython.rst b/docs/library/micropython.rst index b17dfa9a75a4..4d5a064a7a70 100644 --- a/docs/library/micropython.rst +++ b/docs/library/micropython.rst @@ -136,6 +136,14 @@ Functions the heap may be locked) and scheduling a function to call later will lift those restrictions. + On multi-threaded ports, the scheduled function's behaviour depends on + whether the Global Interpreter Lock (GIL) is enabled for the specific port: + + - If GIL is enabled, the function can preempt any thread and run in its + context. + - If GIL is disabled, the function will only preempt the main thread and run + in its context. + Note: If `schedule()` is called from a preempting IRQ, when memory allocation is not allowed and the callback to be passed to `schedule()` is a bound method, passing this directly will fail. This is because creating a @@ -147,3 +155,71 @@ Functions There is a finite queue to hold the scheduled functions and `schedule()` will raise a `RuntimeError` if the queue is full. + +Classes +------- + +.. class:: RingIO(size) +.. class:: RingIO(buffer) + :noindex: + + Provides a fixed-size ringbuffer for bytes with a stream interface. Can be + considered like a fifo queue variant of `io.BytesIO`. + + When created with integer size a suitable buffer will be allocated. + Alternatively a `bytearray` or similar buffer protocol object can be provided + to the constructor for in-place use. + + The classic ringbuffer algorithm is used which allows for any size buffer + to be used however one byte will be consumed for tracking. If initialised + with an integer size this will be accounted for, for example ``RingIO(16)`` + will allocate a 17 byte buffer internally so it can hold 16 bytes of data. + When passing in a pre-allocated buffer however one byte less than its + original length will be available for storage, eg. ``RingIO(bytearray(16))`` + will only hold 15 bytes of data. + + A RingIO instance can be IRQ / thread safe when used to pass data in a single + direction eg. when written to in an IRQ and read from in a non-IRQ function + (or vice versa). This does not hold if you try to eg. write to a single instance + from both IRQ and non-IRQ code, this would often cause data corruption. + + .. method:: RingIO.any() + + Returns an integer counting the number of characters that can be read. + + .. method:: RingIO.read([nbytes]) + + Read available characters. This is a non-blocking function. If ``nbytes`` + is specified then read at most that many bytes, otherwise read as much + data as possible. + + Return value: a bytes object containing the bytes read. Will be + zero-length bytes object if no data is available. + + .. method:: RingIO.readline([nbytes]) + + Read a line, ending in a newline character or return if one exists in + the buffer, else return available bytes in buffer. If ``nbytes`` is + specified then read at most that many bytes. + + Return value: a bytes object containing the line read. + + .. method:: RingIO.readinto(buf[, nbytes]) + + Read available bytes into the provided ``buf``. If ``nbytes`` is + specified then read at most that many bytes. Otherwise, read at + most ``len(buf)`` bytes. + + Return value: Integer count of the number of bytes read into ``buf``. + + .. method:: RingIO.write(buf) + + Non-blocking write of bytes from ``buf`` into the ringbuffer, limited + by the available space in the ringbuffer. + + Return value: Integer count of bytes written. + + .. method:: RingIO.close() + + No-op provided as part of standard `stream` interface. Has no effect + on data in the ringbuffer. diff --git a/docs/library/neopixel.rst b/docs/library/neopixel.rst index edcbc9345c30..b618e6012c38 100644 --- a/docs/library/neopixel.rst +++ b/docs/library/neopixel.rst @@ -43,7 +43,8 @@ Constructors - *pin* is a machine.Pin instance. - *n* is the number of LEDs in the strip. - *bpp* is 3 for RGB LEDs, and 4 for RGBW LEDs. - - *timing* is 0 for 400KHz, and 1 for 800kHz LEDs (most are 800kHz). + - *timing* is 0 for 400KHz, and 1 for 800kHz LEDs (most are 800kHz). You + may also supply a timing tuple as accepted by `machine.bitstream()`. Pixel access methods -------------------- diff --git a/docs/library/network.LAN.rst b/docs/library/network.LAN.rst index 375e02cefecd..31ce8e98411c 100644 --- a/docs/library/network.LAN.rst +++ b/docs/library/network.LAN.rst @@ -10,7 +10,7 @@ Example usage:: import network nic = network.LAN(0) - print(nic.ifconfig()) + print(nic.ipconfig("addr4")) # now use socket as usual ... diff --git a/docs/library/network.PPP.rst b/docs/library/network.PPP.rst new file mode 100644 index 000000000000..85f580ce540e --- /dev/null +++ b/docs/library/network.PPP.rst @@ -0,0 +1,98 @@ +.. currentmodule:: network +.. _network.PPP: + +class PPP -- create network connections over serial PPP +======================================================= + +This class allows you to create a network connection over a serial port using +the PPP protocol. It is only available on selected ports and boards. + +Example usage:: + + import network + + ppp = network.PPP(uart) + ppp.connect() + + while not ppp.isconnected(): + pass + + print(ppp.ipconfig("addr4")) + + # use the socket module as usual, etc + + ppp.disconnect() + +Constructors +------------ + +.. class:: PPP(stream) + + Create a PPP driver object. + + Arguments are: + + - *stream* is any object that supports the stream protocol, but is most commonly a + :class:`machine.UART` instance. This stream object must have an ``irq()`` method + and an ``IRQ_RXIDLE`` constant, for use by `PPP.connect`. + +Methods +------- + +.. method:: PPP.connect(security=SEC_NONE, user=None, key=None) + + Initiate a PPP connection with the given parameters: + + - *security* is the type of security, either ``PPP.SEC_NONE``, ``PPP.SEC_PAP``, + or ``PPP.SEC_CHAP``. + - *user* is an optional user name to use with the security mode. + - *key* is an optional password to use with the security mode. + + When this method is called the underlying stream has its interrupt configured to call + `PPP.poll` via ``stream.irq(ppp.poll, stream.IRQ_RXIDLE)``. This makes sure the + stream is polled, and data passed up the PPP stack, wheverver data becomes available + on the stream. + + The connection proceeds asynchronously, in the background. + +.. method:: PPP.disconnect() + + Terminate the connection. This must be called to cleanly close the PPP connection. + +.. method:: PPP.isconnected() + + Returns ``True`` if the PPP link is connected and up. + Returns ``False`` otherwise. + +.. method:: PPP.status() + + Returns the PPP status. + +.. method:: PPP.config(config_parameters) + + Sets or gets parameters of the PPP interface. There are currently no parameter that + can be set or retrieved. + +.. method:: PPP.ipconfig('param') + PPP.ipconfig(param=value, ...) + + See `AbstractNIC.ipconfig`. + +.. method:: PPP.ifconfig([(ip, subnet, gateway, dns)]) + + See `AbstractNIC.ifconfig`. + +.. method:: PPP.poll() + + Poll the underlying stream for data, and pass it up the PPP stack. + This is called automatically if the stream is a UART with a RXIDLE interrupt, + so it's not usually necessary to call it manually. + +Constants +--------- + +.. data:: PPP.SEC_NONE + PPP.SEC_PAP + PPP.SEC_CHAP + + The type of connection security. diff --git a/docs/library/network.WIZNET5K.rst b/docs/library/network.WIZNET5K.rst index c13d43a376ec..a19bd4528239 100644 --- a/docs/library/network.WIZNET5K.rst +++ b/docs/library/network.WIZNET5K.rst @@ -13,7 +13,7 @@ Example usage:: import network nic = network.WIZNET5K(pyb.SPI(1), pyb.Pin.board.X5, pyb.Pin.board.X4) - print(nic.ifconfig()) + print(nic.ipconfig("addr4")) # now use socket as usual ... @@ -51,20 +51,7 @@ Constructors Methods ------- -.. method:: WIZNET5K.isconnected() - - Returns ``True`` if the physical Ethernet link is connected and up. - Returns ``False`` otherwise. - -.. 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')) +This class implements most methods from `AbstractNIC `, which are documented there. Additional methods are: .. method:: WIZNET5K.regs() diff --git a/docs/library/network.WLAN.rst b/docs/library/network.WLAN.rst index 68cd49769aff..c1eb520961fc 100644 --- a/docs/library/network.WLAN.rst +++ b/docs/library/network.WLAN.rst @@ -107,7 +107,7 @@ Methods Get or set general network interface parameters. These methods allow to work with additional parameters beyond standard IP configuration (as dealt with by - `WLAN.ifconfig()`). These include network-specific and hardware-specific + `AbstractNIC.ipconfig()`). These include network-specific and hardware-specific parameters. For setting parameters, keyword argument syntax should be used, multiple parameters can be set at once. For querying, parameters name should be quoted as a string, and only one parameter can be queries at time:: diff --git a/docs/library/network.WLANWiPy.rst b/docs/library/network.WLANWiPy.rst index 2a5ba118454b..4ac82e92c6a5 100644 --- a/docs/library/network.WLANWiPy.rst +++ b/docs/library/network.WLANWiPy.rst @@ -20,7 +20,7 @@ This class provides a driver for the WiFi network processor in the WiPy. Example wlan.connect('your-ssid', auth=(WLAN.WPA2, 'your-key')) while not wlan.isconnected(): time.sleep_ms(50) - print(wlan.ifconfig()) + print(wlan.ipconfig("addr4")) # now use socket as usual ... @@ -96,16 +96,10 @@ Methods In case of STA mode, returns ``True`` if connected to a WiFi access point and has a valid IP address. In AP mode returns ``True`` when a station is connected, ``False`` otherwise. -.. method:: WLANWiPy.ifconfig(if_id=0, config=['dhcp' or configtuple]) +.. method:: WLANWiPy.ipconfig('param') + WLANWiPy.ipconfig(param=value, ...) - With no parameters given returns 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 instance:: - - wlan.ifconfig(config=('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) + See :meth:`AbstractNIC.ipconfig `. Supported parameters are: ``dhcp4``, ``addr4``, ``gw4``. .. method:: WLANWiPy.mode([mode]) diff --git a/docs/library/network.rst b/docs/library/network.rst index 0ea90772bb0c..3123a7c14155 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -24,7 +24,7 @@ For example:: print("Waiting for connection...") while not nic.isconnected(): time.sleep(1) - print(nic.ifconfig()) + print(nic.ipconfig("addr4")) # now use socket as usual import socket @@ -113,8 +113,48 @@ parameter should be `id`. connected to the AP. The list contains tuples of the form (MAC, RSSI). +.. method:: AbstractNIC.ipconfig('param') + AbstractNIC.ipconfig(param=value, ...) + + Get or set interface-specific IP-configuration interface parameters. + Supported parameters are the following (availability of a particular + parameter depends on the port and the specific network interface): + + * ``dhcp4`` (``True/False``) obtain an IPv4 address, gateway and dns + server via DHCP. This method does not block and wait for an address + to be obtained. To check if an address was obtained, use the read-only + property ``has_dhcp4``. + * ``gw4`` Get/set the IPv4 default-gateway. + * ``dhcp6`` (``True/False``) obtain a DNS server via stateless DHCPv6. + Obtaining IP Addresses via DHCPv6 is currently not implemented. + * ``autoconf6`` (``True/False``) obtain a stateless IPv6 address via + the network prefix shared in router advertisements. To check if a + stateless address was obtained, use the read-only + property ``has_autoconf6``. + * ``addr4`` (e.g. ``192.168.0.4/24``) obtain the current IPv4 address + and network mask as ``(ip, subnet)``-tuple, regardless of how this + address was obtained. This method can be used to set a static IPv4 + address either as ``(ip, subnet)``-tuple or in CIDR-notation. + * ``addr6`` (e.g. ``fe80::1234:5678``) obtain a list of current IPv6 + addresses as ``(ip, state, preferred_lifetime, valid_lifetime)``-tuple. + This include link-local, slaac and static addresses. + ``preferred_lifetime`` and ``valid_lifetime`` represent the remaining + valid and preferred lifetime of each IPv6 address, in seconds. + ``state`` indicates the current state of the address: + + * ``0x08`` - ``0x0f`` indicates the address is tentative, counting the + number of probes sent. + * ``0x10`` The address is deprecated (but still valid) + * ``0x30`` The address is preferred (and valid) + * ``0x40`` The address is duplicated and can not be used. + + This method can be used to set a static IPv6 + address, by setting this parameter to the address, like ``fe80::1234:5678``. + .. method:: AbstractNIC.ifconfig([(ip, subnet, gateway, dns)]) + .. note:: This function is deprecated, use `ipconfig()` instead. + Get/set IP-level network interface parameters: IP address, subnet mask, gateway and DNS server. When called with no arguments, this method returns a 4-tuple with the above information. To set the above values, pass a @@ -127,7 +167,7 @@ parameter should be `id`. Get or set general network interface parameters. These methods allow to work with additional parameters beyond standard IP configuration (as dealt with by - `ifconfig()`). These include network-specific and hardware-specific + `ipconfig()`). These include network-specific and hardware-specific parameters. For setting parameters, the keyword argument syntax should be used, and multiple parameters can be set at once. For querying, a parameter name should be quoted as a string, and only one @@ -151,6 +191,7 @@ provide a way to control networking interfaces of various kinds. network.WINC.rst network.WLAN.rst network.LAN.rst + network.PPP.rst Network functions ================= @@ -193,3 +234,32 @@ The following are functions available in the network module. is raised. The default hostname is typically the name of the board. + +.. function:: ipconfig('param') + ipconfig(param=value, ...) + + Get or set global IP-configuration parameters. + Supported parameters are the following (availability of a particular + parameter depends on the port and the specific network interface): + + * ``dns`` Get/set DNS server. This method can support both, IPv4 and + IPv6 addresses. + * ``prefer`` (``4/6``) Specify which address type to return, if a domain + name has both A and AAAA records. Note, that this does not clear the + local DNS cache, so that any previously obtained addresses might not + change. + +.. function:: phy_mode([mode]) + + Get or set the PHY mode. + + If the *mode* parameter is provided, the PHY mode will be set to this value. + If the function is called without parameters, it returns the current PHY + mode. + + The possible modes are defined as constants: + * ``MODE_11B`` -- IEEE 802.11b, + * ``MODE_11G`` -- IEEE 802.11g, + * ``MODE_11N`` -- IEEE 802.11n. + + Availability: ESP8266. diff --git a/docs/library/rp2.PIO.rst b/docs/library/rp2.PIO.rst index e0675af1e9a2..f922456c8c48 100644 --- a/docs/library/rp2.PIO.rst +++ b/docs/library/rp2.PIO.rst @@ -27,6 +27,17 @@ Constructors Methods ------- +.. method:: PIO.gpio_base([base]) + + Query and optionally set the current GPIO base for this PIO instance. + + If an argument is given then it must be a pin (or integer corresponding to a pin + number), restricted to either GPIO0 or GPIO16. The GPIO base will then be set to + that pin. Setting the GPIO base must be done before any programs are added or state + machines created. + + Returns the current GPIO base pin. + .. method:: PIO.add_program(program) Add the *program* to the instruction memory of this PIO instance. diff --git a/docs/mimxrt/quickref.rst b/docs/mimxrt/quickref.rst index 1a73929bedbe..cfd0605054a7 100644 --- a/docs/mimxrt/quickref.rst +++ b/docs/mimxrt/quickref.rst @@ -438,6 +438,10 @@ The i.MXRT MCU supports battery backup of the RTC. By connecting a battery of current drawn from the battery is ~20µA, which is rather high. A CR2032 coin cell will last for about one year. +Note: In v1.23.0 the support for subseconds was removed. When reading the RTC, 0 will +be returned as value for subsecond, When setting the RTC time, the subsecond +field is ignored. The RTC itself does not provide a microsecond value. + SD card ------- @@ -528,7 +532,7 @@ Ethernet. Example usage:: lan.active(True) If there is a DHCP server in the LAN, the IP address is supplied by that server. -Otherwise, the IP address can be set with lan.ifconfig(). The default address +Otherwise, the IP address can be set with lan.ipconfig(addr4="..."). The default address is 192.168.0.1. Teensy 4.1 does not have an Ethernet jack on the board, but PJRC offers an diff --git a/docs/reference/mpremote.rst b/docs/reference/mpremote.rst index bf25e29d93d9..4d86f0080b11 100644 --- a/docs/reference/mpremote.rst +++ b/docs/reference/mpremote.rst @@ -227,11 +227,12 @@ The full list of supported commands are: - ``cat `` to show the contents of a file or files on the device - ``ls`` to list the current directory - ``ls `` to list the given directories - - ``cp [-r] `` to copy files + - ``cp [-rf] `` to copy files - ``rm `` to remove files on the device - ``mkdir `` to create directories on the device - ``rmdir `` to remove directories on the device - ``touch `` to create the files (if they don't already exist) + - ``sha256sum `` to calculate the SHA256 sum of files The ``cp`` command uses a convention where a leading ``:`` represents a remote path. Without a leading ``:`` means a local path. This is based on the @@ -256,6 +257,11 @@ The full list of supported commands are: This will copy the file to the device then enter the REPL. The ``+`` prevents ``"repl"`` being interpreted as a path. + The ``cp`` command supports the ``-r`` option to make a recursive copy. By + default ``cp`` will skip copying files to the remote device if the SHA256 hash + of the source and destination file matches. To force a copy regardless of the + hash use the ``-f`` option. + **Note:** For convenience, all of the filesystem sub-commands are also :ref:`aliased as regular commands `, i.e. you can write ``mpremote cp ...`` instead of ``mpremote fs cp ...``. @@ -469,9 +475,9 @@ An example ``config.py`` might look like: for ap in wl.scan(): print(ap) """,], # Print out nearby WiFi networks. - "wl_ifconfig": [ + "wl_ipconfig": [ "exec", - "import network; sta_if = network.WLAN(network.STA_IF); print(sta_if.ifconfig())", + "import network; sta_if = network.WLAN(network.STA_IF); print(sta_if.ipconfig('addr4'))", """,], # Print ip address of station interface. "test": ["mount", ".", "exec", "import test"], # Mount current directory and run test.py. "demo": ["run", "path/to/demo.py"], # Execute demo.py on the device. diff --git a/docs/reference/mpyfiles.rst b/docs/reference/mpyfiles.rst index 8e8284928dac..be0114701aea 100644 --- a/docs/reference/mpyfiles.rst +++ b/docs/reference/mpyfiles.rst @@ -58,7 +58,7 @@ If importing an .mpy file fails then try the following: sys_mpy = sys.implementation._mpy arch = [None, 'x86', 'x64', 'armv6', 'armv6m', 'armv7m', 'armv7em', 'armv7emsp', 'armv7emdp', - 'xtensa', 'xtensawin'][sys_mpy >> 10] + 'xtensa', 'xtensawin', 'rv32imc'][sys_mpy >> 10] print('mpy version:', sys_mpy & 0xff) print('mpy sub-version:', sys_mpy >> 8 & 3) print('mpy flags:', end='') diff --git a/docs/reference/pyboard.py.rst b/docs/reference/pyboard.py.rst index a06ffdcd8fa9..13fc6b7a7a49 100644 --- a/docs/reference/pyboard.py.rst +++ b/docs/reference/pyboard.py.rst @@ -120,9 +120,8 @@ Some more examples:: # Same, but using . instead. $ pyboard.py --device /dev/ttyACM0 -f cp :main.py . - # Copy three files to the device, keeping their names - # and paths (note: `lib` must exist on the device) - $ pyboard.py --device /dev/ttyACM0 -f cp main.py app.py lib/foo.py : + # Copy three files to the device, keeping their names. + $ pyboard.py --device /dev/ttyACM0 -f cp main.py app.py foo.py : # Remove a file from the device. $ pyboard.py --device /dev/ttyACM0 -f rm util.py diff --git a/docs/rp2/quickref.rst b/docs/rp2/quickref.rst index 11a808c11027..9b82ea5dc674 100644 --- a/docs/rp2/quickref.rst +++ b/docs/rp2/quickref.rst @@ -31,12 +31,25 @@ The MicroPython REPL is accessed via the USB serial port. Tab-completion is usef find out what methods an object has. Paste mode (ctrl-E) is useful to paste a large slab of Python code into the REPL. -The :mod:`machine` module:: +The :mod:`machine` module: + +machine.freq() allows to change the MCU frequency and control the peripheral +frequency for UART and SPI. Usage:: + + machine.freq(MCU_frequency[, peripheral_frequency=48_000_000]) + +The MCU frequency can be set in a range from less than 48 MHz to about 250MHz. +The default at boot time is 125 MHz. The peripheral frequency must be either +48 MHz or identical to the MCU frequency, with 48 MHz as the default. +If the peripheral frequency is changed, any already existing instance of +UART and SPI will change it's baud rate and may have to be re-configured:: import machine machine.freq() # get the current frequency of the CPU - machine.freq(240000000) # set the CPU frequency to 240 MHz + machine.freq(240000000) # set the CPU frequency to 240 MHz and keep + # the UART frequency at 48MHz + machine.freq(125000000, 125000000) # set the CPU and UART frequency to 125 MHz The :mod:`rp2` module:: @@ -187,6 +200,14 @@ Use the :ref:`machine.ADC ` class:: adc = ADC(Pin(26)) # create ADC object on ADC pin adc.read_u16() # read value, 0-65535 across voltage range 0.0v - 3.3v +The argument of the constructor ADC specifies either a Pin by number, name of as +Pin object, or a channel number in the range 0 - 3 or ADC.CORE_TEMP for the +internal temperature sensor. If a pin is specified, +the pin is initialized in high-Z mode. If a channel number is used, the pin +is not initialized and configuring is left to the user code. After hard reset, +RP2040 pins operate in current sink mode at about 60µA. If the pin is not +otherwise configured, that may lead to wrong ADC readings. + Software SPI bus ---------------- diff --git a/docs/samd/quickref.rst b/docs/samd/quickref.rst index 60c57b3a47a3..25b5a8fc8ab2 100644 --- a/docs/samd/quickref.rst +++ b/docs/samd/quickref.rst @@ -65,6 +65,8 @@ Use the :mod:`time