diff --git a/.gitattributes b/.gitattributes index fbab4e69abe..04a84d3e098 100644 --- a/.gitattributes +++ b/.gitattributes @@ -8,6 +8,7 @@ # These are binary so should never be modified by git. *.a binary +*.FLM binary *.ico binary *.png binary *.jpg binary diff --git a/.github/workflows/ports_psoc-edge-ifx.yml b/.github/workflows/ports_psoc-edge-ifx.yml new file mode 100644 index 00000000000..5dce41e9358 --- /dev/null +++ b/.github/workflows/ports_psoc-edge-ifx.yml @@ -0,0 +1,127 @@ +name: psoc-edge port ifx + +on: + push: + pull_request: + paths: + - '.github/workflows/*.yml' + - 'tools/**' + - 'py/**' + - 'extmod/**' + - 'shared/**' + - 'lib/**' + - 'drivers/**' + - 'ports/psoc-edge/**' + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +env: + mpy_hex_file: firmware.hex + +jobs: + server-build: + runs-on: ubuntu-latest + strategy: + matrix: + board: + - KIT_PSE84_AI + outputs: + commit_sha: ${{ steps.commit_sha.outputs.sha_short }} + + steps: + - uses: actions/checkout@v6 + - name: Install packages + run: source tools/ci.sh && ci_psoc_edge_setup + - name: Build + run: source tools/ci.sh && ci_psoc_edge_build ${{ matrix.board }} + - name: Gets commit SHA + if: success() + id: commit_sha + run: echo "sha_short=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT + - name: Save firmware bin + if: success() + uses: actions/upload-artifact@v4 + with: + name: mpy-psoc-edge_${{ matrix.board }}_${{ steps.commit_sha.outputs.sha_short }} + path: ports/psoc-edge/build-${{ matrix.board }}/${{ env.mpy_hex_file }} + + on-target-test: + runs-on: + - self-hosted + - Linux + - PSOC-EDGE + needs: server-build + env: + LARGE_SECRET_PASSPHRASE: ${{ secrets.LARGE_SECRET_PASSPHRASE }} + pse_test_dir: ../../tests/ports/psoc-edge + strategy: + matrix: + board: + - KIT_PSE84_AI + steps: + - name: Fix permissions + run: echo ${{ secrets.SELF_HOSTED_PASSWORD }} | sudo -S chown -R $(whoami):$(whoami) . + - name: Checkout code + uses: actions/checkout@v6 + - name: Download binaries + uses: actions/download-artifact@v4 + - name: Container setup + run: | + echo ${{ secrets.SELF_HOSTED_PASSWORD }} | sudo -S chmod 666 /var/run/docker.sock + source tools/ci.sh && ci_psoc_edge_setup_hil ${{ matrix.board }} + - name: Setup devices + run: | + cp mpy-psoc-edge_${{ matrix.board }}_${{ needs.server-build.outputs.commit_sha }}/${{ env.mpy_hex_file }} tools/psoc-edge + source tools/ci.sh && ci_psoc_edge_deploy_hil ${{ matrix.board }} ${{ env.mpy_hex_file }} tests/ports/psoc-edge/${{ runner.name }}-devs.yml + - name: Decrypt Wi-Fi secrets + if: ${{ hashFiles('tests/ports/psoc-edge/mp_custom/secrets.py.gpg') != '' && env.LARGE_SECRET_PASSPHRASE != '' }} + run: sh tools/psoc-edge/decrypt_secrets.sh + + - name: Run psoc-edge tests + timeout-minutes: 20 + run: | + cd lib/mpy-test-ext + python -u run_test_plan.py \ + --board ${{ matrix.board }} --max-retries 2 \ + --test-plan $pse_test_dir/test-plan.yml \ + --hil-devs $pse_test_dir/${{ runner.name }}-devs.yml + + - name: Remove decrypted Wi-Fi secrets + if: ${{ always() && hashFiles('tests/ports/psoc-edge/mp_custom/secrets.py.gpg') != '' }} + run: rm -f tests/ports/psoc-edge/mp_custom/secrets.py + + - name: Container teardown + if: always() + run: | + source tools/ci.sh && ci_psoc_edge_teardown_hil + + release: + runs-on: ubuntu-latest + needs: [server-build, on-target-test] + permissions: + contents: write + strategy: + matrix: + board: + - KIT_PSE84_AI + if: startsWith(github.ref, 'refs/tags/v') + steps: + - name: Download binaries + uses: actions/download-artifact@v4 + - name: Prepare release assets + run: | + cd mpy-psoc-edge_${{ matrix.board }}_${{ needs.server-build.outputs.commit_sha }} + mv ${{ env.mpy_hex_file }} ../mpy-psoc-edge_${{ matrix.board }}.hex + - name: Build release changelog + id: build_changelog + uses: mikepenz/release-changelog-builder-action@v3 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + - name: Release + uses: softprops/action-gh-release@v1 + with: + name: MicroPython PSOC Edge ${{ github.ref_name }} + files: mpy-psoc-edge_${{ matrix.board }}.hex + body: ${{steps.build_changelog.outputs.changelog}} diff --git a/.github/workflows/ports_psoc-edge.yml b/.github/workflows/ports_psoc-edge.yml new file mode 100644 index 00000000000..15b2504e413 --- /dev/null +++ b/.github/workflows/ports_psoc-edge.yml @@ -0,0 +1,28 @@ +name: psoc-edge port + +on: + push: + pull_request: + paths: + - '.github/workflows/*.yml' + - 'tools/**' + - 'py/**' + - 'extmod/**' + - 'shared/**' + - 'lib/**' + - 'drivers/**' + - 'ports/psoc-edge/**' + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + build_psoc_edge: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + - name: Install packages + run: tools/ci.sh psoc_edge_setup + - name: Build + run: tools/ci.sh psoc_edge_build diff --git a/.github/workflows/stale_issues.yml b/.github/workflows/stale_issues.yml new file mode 100644 index 00000000000..82f817a4949 --- /dev/null +++ b/.github/workflows/stale_issues.yml @@ -0,0 +1,8 @@ +name: 'Close stale issues/PRs' +on: + schedule: + - cron: "50 14 */2 * *" + +jobs: + call-workflow: + uses: Infineon/workflows/.github/workflows/epe_stale_issues.yml@master \ No newline at end of file diff --git a/.github/workflows/synch_upstream.yml b/.github/workflows/synch_upstream.yml new file mode 100644 index 00000000000..e3c98199de7 --- /dev/null +++ b/.github/workflows/synch_upstream.yml @@ -0,0 +1,72 @@ +name: Sync Upstream + +on: + schedule: + - cron: '0 0 */1 * *' # daily 00:00 + workflow_dispatch: # on button click + +jobs: + synch_master: + runs-on: ubuntu-latest + + steps: + - name: Checkout target repo + uses: actions/checkout@v4 + with: + ref: master + token: ${{ secrets.GH_ACT_SYNCH_UPSTREAM }} + + - name: Sync upstream changes + id: sync + uses: aormsby/Fork-Sync-With-Upstream-action@v3.4.1 + with: + target_sync_branch: master + target_repo_token: ${{ secrets.GH_ACT_SYNCH_UPSTREAM }} + upstream_sync_branch: master + upstream_sync_repo: micropython/micropython + git_config_pull_rebase: true + + + - name: New commits found + if: steps.sync.outputs.has_new_commits == 'true' + run: echo "New commits were found to sync." + + - name: No new commits + if: steps.sync.outputs.has_new_commits == 'false' + run: echo "There were no new commits." + + - name: Show value of 'has_new_commits' + run: echo ${{ steps.sync.outputs.has_new_commits }} + + synch_port_psoc_edge: + runs-on: ubuntu-latest + needs: synch_master + + steps: + - name: Checkout target repo + uses: actions/checkout@v4 + with: + ref: psoc-edge-main + token: ${{ secrets.GH_ACT_SYNCH_UPSTREAM }} + + - name: Sync upstream changes + id: sync + uses: aormsby/Fork-Sync-With-Upstream-action@v3.4.1 + with: + target_sync_branch: psoc-edge-main + target_repo_token: ${{ secrets.GH_ACT_SYNCH_UPSTREAM }} + upstream_sync_branch: master + upstream_sync_repo: micropython/micropython + git_config_pull_rebase: true + target_branch_push_args: '--force' + + - name: New commits found + if: steps.sync.outputs.has_new_commits == 'true' + run: echo "New commits were found to sync." + + - name: No new commits + if: steps.sync.outputs.has_new_commits == 'false' + run: echo "There were no new commits." + + - name: Show value of 'has_new_commits' + run: echo ${{ steps.sync.outputs.has_new_commits }} \ No newline at end of file diff --git a/.gitmodules b/.gitmodules index 9220232ac36..3c52b8a5e4d 100644 --- a/.gitmodules +++ b/.gitmodules @@ -80,3 +80,78 @@ [submodule "lib/CMSIS_6"] path = lib/CMSIS_6 url = https://github.com/ARM-software/CMSIS_6.git +[submodule "lib/mpy-test-ext"] + path = lib/mpy-test-ext + url = https://github.com/Infineon/mpy-test-ext.git +[submodule "lib/psoc-edge/TARGET_KIT_PSE84_AI"] + path = lib/psoc-edge/TARGET_KIT_PSE84_AI + url = https://github.com/Infineon/TARGET_KIT_PSE84_AI.git +[submodule "lib/psoc-edge/core-lib"] + path = lib/psoc-edge/core-lib + url = https://github.com/Infineon/core-lib.git +[submodule "lib/psoc-edge/mtb-dsl-pse8xxgp"] + path = lib/psoc-edge/mtb-dsl-pse8xxgp + url = https://github.com/Infineon/mtb-dsl-pse8xxgp.git +[submodule "lib/psoc-edge/mtb-srf"] + path = lib/psoc-edge/mtb-srf + url = https://github.com/Infineon/mtb-srf.git +[submodule "lib/psoc-edge/se-rt-services-utils"] + path = lib/psoc-edge/se-rt-services-utils + url = https://github.com/Infineon/se-rt-services-utils.git +[submodule "lib/psoc-edge/serial-memory"] + path = lib/psoc-edge/serial-memory + url = https://github.com/Infineon/serial-memory.git +[submodule "lib/psoc-edge/retarget-io"] + path = lib/psoc-edge/retarget-io + url = https://github.com/Infineon/retarget-io.git +[submodule "lib/psoc-edge/mtb-ipc"] + path = lib/psoc-edge/mtb-ipc + url = https://github.com/Infineon/mtb-ipc.git +[submodule "lib/psoc-edge/async-transfer"] + path = lib/psoc-edge/async-transfer + url = https://github.com/Infineon/async-transfer.git +[submodule "lib/psoc-edge/abstraction-rtos"] + path = lib/psoc-edge/abstraction-rtos + url = https://github.com/Infineon/abstraction-rtos.git +[submodule "lib/psoc-edge/clib-support"] + path = lib/psoc-edge/clib-support + url = https://github.com/Infineon/clib-support.git +[submodule "lib/psoc-edge/connectivity-utilities"] + path = lib/psoc-edge/connectivity-utilities + url = https://github.com/cypresssemiconductorco/connectivity-utilities.git +[submodule "lib/psoc-edge/cy-mbedtls-acceleration"] + path = lib/psoc-edge/cy-mbedtls-acceleration + url = https://github.com/Infineon/cy-mbedtls-acceleration.git +[submodule "lib/psoc-edge/freertos"] + path = lib/psoc-edge/freertos + url = https://github.com/Infineon/freertos.git +[submodule "lib/psoc-edge/lwip-freertos-integration"] + path = lib/psoc-edge/lwip-freertos-integration + url = https://github.com/Infineon/lwip-freertos-integration.git +[submodule "lib/psoc-edge/lwip-network-interface-integration"] + path = lib/psoc-edge/lwip-network-interface-integration + url = https://github.com/Infineon/lwip-network-interface-integration.git +[submodule "lib/psoc-edge/lwip"] + path = lib/psoc-edge/lwip + url = https://git.savannah.nongnu.org/git/lwip +[submodule "lib/psoc-edge/secure-sockets"] + path = lib/psoc-edge/secure-sockets + url = https://github.com/cypresssemiconductorco/secure-sockets.git +[submodule "lib/psoc-edge/whd-bsp-integration"] + path = lib/psoc-edge/whd-bsp-integration + url = https://github.com/cypresssemiconductorco/whd-bsp-integration.git +[submodule "lib/psoc-edge/wifi-connection-manager"] + path = lib/psoc-edge/wifi-connection-manager + url = https://github.com/cypresssemiconductorco/wifi-connection-manager.git +[submodule "lib/psoc-edge/wifi-host-driver"] + path = lib/psoc-edge/wifi-host-driver + url = https://github.com/cypresssemiconductorco/wifi-host-driver.git +[submodule "lib/psoc-edge/wpa3-external-supplicant"] + path = lib/psoc-edge/wpa3-external-supplicant + url = https://github.com/Infineon/wpa3-external-supplicant.git +[submodule "lib/psoc-edge/wifi-resources"] + path = lib/psoc-edge/wifi-resources + url = https://github.com/Infineon/wifi-resources.git +[submodule "lib/micropython-deepcraft-model-interface"] + path = lib/micropython-deepcraft-model-interface + url = https://github.com/Infineon/micropython-deepcraft-model-interface diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index ad4136c59fc..e33a337358e 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -5,12 +5,14 @@ repos: name: MicroPython codeformat.py for changed C files entry: tools/codeformat.py -v -c -f language: python + language_version: python3 additional_dependencies: - micropython-uncrustify==1.0.0.post1 - id: verifygitlog name: MicroPython git commit message format checker entry: tools/verifygitlog.py --check-file --ignore-rebase language: python + language_version: python3 verbose: true stages: [commit-msg] - repo: https://github.com/charliermarsh/ruff-pre-commit diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000000..c1049bfaa97 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,22 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +# We recommend specifying your dependencies to enable reproducible builds: +# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: docs/requirements.txt \ No newline at end of file diff --git a/README.md b/README.md index 5f6d4288bf2..23ce8f375e0 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[![Unix CI badge](https://github.com/micropython/micropython/actions/workflows/ports_unix.yml/badge.svg)](https://github.com/micropython/micropython/actions?query=branch%3Amaster+event%3Apush) [![STM32 CI badge](https://github.com/micropython/micropython/actions/workflows/ports_stm32.yml/badge.svg)](https://github.com/micropython/micropython/actions?query=branch%3Amaster+event%3Apush) [![Docs CI badge](https://github.com/micropython/micropython/actions/workflows/docs.yml/badge.svg)](https://docs.micropython.org/) [![codecov](https://codecov.io/gh/micropython/micropython/branch/master/graph/badge.svg?token=I92PfD05sD)](https://codecov.io/gh/micropython/micropython) +[![PSOC Edge CI badge](https://github.com/Infineon/micropython-psoc-edge/actions/workflows/ports_psoc-edge.yml/badge.svg)](https://github.com/Infineon/micropython-psoc-edge/actions/workflows/ports_psoc-edge.yml?query=branch%3Apsoc-edge-main++) [![Docs CI badge](https://readthedocs.org/projects/ifx-micropython/badge/?version=latest)](https://ifx-micropython.readthedocs.io/en/latest/psoc6/quickref.html) [![codecov](https://codecov.io/gh/micropython/micropython/branch/master/graph/badge.svg?token=I92PfD05sD)](https://codecov.io/gh/micropython/micropython) The MicroPython project ======================= @@ -32,23 +32,19 @@ DAC, PWM, SPI, I2C, CAN, Bluetooth, and USB. Getting started --------------- -See the [online documentation](https://docs.micropython.org/) for the API +See the [online documentation (Infineon PSOC™ Edge port ReadTheDocs fork)](https://ifx-micropython-psoc-edge.readthedocs.io/en/latest/psoc-edge/quickref.html) 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) +We use [GitHub Discussions (Infineon PSOC™ Edge fork)](https://github.com/Infineon/micropython-psoc-edge/discussions) as our forum, and [Discord](https://discord.gg/RB8HZSAExQ) for chat. These are great places to ask questions and advice from the community or to discuss your MicroPython-based projects. -For bugs and feature requests, please [raise an issue](https://github.com/micropython/micropython/issues/new/choose) +For bugs and feature requests, please [raise an issue (Infineon PSOC™ Edge fork)](https://github.com/Infineon/micropython-psoc-edge/issues/new/choose) and follow the templates there. -For information about the [MicroPython pyboard](https://store.micropython.org/pyb-features), -the officially supported board from the -[original Kickstarter campaign](https://www.kickstarter.com/projects/214379695/micro-python-python-for-microcontrollers), -see the [schematics and pinouts](http://github.com/micropython/pyboard) and -[documentation](https://docs.micropython.org/en/latest/pyboard/quickref.html). +For information about the MicroPython PSoC supported boards see the [documentation (Infineon PSOC™ Edge port ReadTheDocs fork)](https://ifx-micropython-psoc-edge.readthedocs.io/en/latest/psoc-edge/general.html#supported-boards). MicroPython design values ------------------------- @@ -147,6 +143,7 @@ are mature and have the most active development, support and testing: |--------------------------|----------------------------------------------------------------------------------------|----------------------------------------------------------------------| | [esp32](ports/esp32)* | Espressif ESP32 SoCs (ESP32, ESP32S2, ESP32S3, ESP32C3, ESP32C6) | [here](https://docs.micropython.org/en/latest/esp32/quickref.html) | | [mimxrt](ports/mimxrt) | NXP m.iMX RT | [here](https://docs.micropython.org/en/latest/mimxrt/quickref.html) | +| [psoc-edge](ports/edge) | Infineon PSOC™ Edge | [here](https://ifx-micropython-psoc-edge.readthedocs.io/en/latest/psoc-edge/quickref.html) | | [rp2](ports/rp2) | Raspberry Pi RP2040 and RP2350 | [here](https://docs.micropython.org/en/latest/rp2/quickref.html) | | [samd](ports/samd) | Microchip (formerly Atmel) SAMD21 and SAMD51 | [here](https://docs.micropython.org/en/latest/samd/quickref.html) | | [stm32](ports/stm32) | STMicroelectronics STM32 MCUs (F0, F4, F7, G0, G4, H5, H7, L0, L1, L4, N6, WB, WL) | [here](https://docs.micropython.org/en/latest/pyboard/quickref.html) | diff --git a/docs/conf.py b/docs/conf.py index f80ca97edca..ab0a81f1ffd 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -129,9 +129,14 @@ # -- Options for HTML output ---------------------------------------------- -import sphinx_rtd_theme - -html_theme = "sphinx_rtd_theme" +# on_rtd is whether we are on readthedocs.org +try: + import sphinx_rtd_theme + + html_theme = "sphinx_rtd_theme" + html_theme_path = ["."] +except: + html_theme = "default" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/index.rst b/docs/index.rst index 64b83618da1..a6b68e8e898 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,7 @@ MicroPython documentation and references esp32/quickref.rst rp2/quickref.rst mimxrt/quickref.rst + psoc-edge/quickref.rst wipy/quickref.rst unix/quickref.rst zephyr/quickref.rst diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index 37dcac877fa..e9a5ec1575a 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -209,40 +209,40 @@ The following methods are not part of the core Pin API and only implemented on c Set pin to "0" output level. - Availability: mimxrt, nrf, renesas-ra, rp2, samd, stm32 ports. + Availability: mimxrt, nrf, psoc-edge, renesas-ra, rp2, samd, stm32 ports. .. method:: Pin.high() Set pin to "1" output level. - Availability: mimxrt, nrf, renesas-ra, rp2, samd, stm32 ports. + Availability: mimxrt, nrf, psoc-edge, renesas-ra, rp2, samd, stm32 ports. .. method:: Pin.mode([mode]) Get or set the pin mode. See the constructor documentation for details of the ``mode`` argument. - Availability: cc3200, stm32 ports. + Availability: cc3200, psoc-edge, stm32 ports. .. method:: Pin.pull([pull]) Get or set the pin pull state. See the constructor documentation for details of the ``pull`` argument. - Availability: cc3200, stm32 ports. + Availability: cc3200, psoc-edge, stm32 ports. .. method:: Pin.drive([drive]) Get or set the pin drive strength. See the constructor documentation for details of the ``drive`` argument. - Availability: cc3200 port. + Availability: cc3200, psoc-edge ports. .. method:: Pin.toggle() Toggle output pin from "0" to "1" or vice-versa. - Availability: cc3200, esp32, esp8266, mimxrt, rp2, samd ports. + Availability: cc3200, esp32, esp8266, mimxrt, psoc-edge, rp2, samd ports. Attributes ---------- diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index fbad3fc5922..cbbee69edb0 100644 --- a/docs/library/machine.UART.rst +++ b/docs/library/machine.UART.rst @@ -163,7 +163,7 @@ Methods 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 + Availability: rp2, esp32, esp8266, mimxrt, cc3200, stm32, nrf ports, psoc-edge, renesas-ra .. method:: UART.txdone() @@ -176,7 +176,7 @@ Methods 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 + Availability: rp2, esp32, esp8266, mimxrt, cc3200, stm32, nrf ports, psoc-edge, renesas-ra .. method:: UART.irq(handler=None, trigger=0, hard=False) @@ -216,6 +216,7 @@ Methods ESP32 yes yes yes MIMXRT yes yes NRF yes yes + PSOC-EDGE yes yes yes RENESAS-RA yes yes RP2 yes yes yes SAMD yes yes yes @@ -241,7 +242,7 @@ Methods idle. - Availability: cc3200, esp32, mimxrt, nrf, renesas-ra, rp2, samd, stm32. + Availability: cc3200, esp32, mimxrt, nrf, psoc-edge, renesas-ra, rp2, samd, stm32. Constants --------- @@ -260,4 +261,4 @@ Constants IRQ trigger sources. - Availability: renesas-ra, stm32, esp32, rp2040, mimxrt, samd, cc3200. + Availability: renesas-ra, stm32, esp32, rp2040, mimxrt, samd, cc3200, psoc-edge. diff --git a/docs/psoc-edge/general.rst b/docs/psoc-edge/general.rst new file mode 100644 index 00000000000..ce8a2c6957c --- /dev/null +++ b/docs/psoc-edge/general.rst @@ -0,0 +1,53 @@ +.. _psoc_edge_general: + +.. include:: links.rst + +General information about the PSOC™ Edge port +============================================== + +The PSOC™ Edge is designed for next generation responsive compute and control applications, featuring hardware-assisted machine learning (ML) acceleration. +The PSOC™ Edge devices are based on high performance Arm® Cortex®-M55, including Helium™ DSP support paired with Arm® Ethos™-U55 and Cortex®-M33 paired Infineon’s ultra-low power NNLite neural network accelerator. + +The PSOC™ Edge port supports boards powered by the `Infineon PSOC™ Edge family of microcontrollers `_ and currently supports the following MCUs: + +* PSoC™ Edge 84 + +.. _Supported boards: + +Supported boards +^^^^^^^^^^^^^^^^^ + +The following boards are supported on this port: + +.. list-table:: + :widths: 20 20 50 + :header-rows: 1 + + * - Board name + - Connectivity + - Special feature + * - KIT_PSE84_AI + - Wi-Fi, BT + - 60GHz radar, analog microphone, digital microphone, barometric pressure sensor, external flash, speaker interface, IMU sensor, magnetometer, image sensor + + +For more hardware-related details, refer to the following sections. + +KIT_PSE84_AI +------------ + +Pinout +****** + +.. image:: img/kit_pse84_ai_pinout.png + :width: 500 + + +Technical specifications +************************ +Links for product details: + +* `KIT_PSE84_AI PSOC™ Edge E84 AI product page `_ +* `KIT_PSE84_AI PSOC™ Edge E84 AI Kit guide `_ +* `PSOC™ Edge E8x2, E8x3, E8x5, E8x6 Consumer Datasheet `_ +* `PSOC™ Edge E8x2, E8x3, E8x5, E8x6 Architecture Reference Manual `_ \ No newline at end of file diff --git a/docs/psoc-edge/img/gh-releases.png b/docs/psoc-edge/img/gh-releases.png new file mode 100644 index 00000000000..1365932ce97 Binary files /dev/null and b/docs/psoc-edge/img/gh-releases.png differ diff --git a/docs/psoc-edge/img/kit-pse84-ai.png b/docs/psoc-edge/img/kit-pse84-ai.png new file mode 100644 index 00000000000..d529b31f7a5 Binary files /dev/null and b/docs/psoc-edge/img/kit-pse84-ai.png differ diff --git a/docs/psoc-edge/img/kit_pse84_ai_pinout.png b/docs/psoc-edge/img/kit_pse84_ai_pinout.png new file mode 100644 index 00000000000..4df13ebc801 Binary files /dev/null and b/docs/psoc-edge/img/kit_pse84_ai_pinout.png differ diff --git a/docs/psoc-edge/img/mpy-psoc-edge-repl.jpg b/docs/psoc-edge/img/mpy-psoc-edge-repl.jpg new file mode 100644 index 00000000000..62c814634cd Binary files /dev/null and b/docs/psoc-edge/img/mpy-psoc-edge-repl.jpg differ diff --git a/docs/psoc-edge/img/mpy-thonny-filesystem.jpg b/docs/psoc-edge/img/mpy-thonny-filesystem.jpg new file mode 100644 index 00000000000..0d1bcf6c946 Binary files /dev/null and b/docs/psoc-edge/img/mpy-thonny-filesystem.jpg differ diff --git a/docs/psoc-edge/img/mtb-programmer.png b/docs/psoc-edge/img/mtb-programmer.png new file mode 100644 index 00000000000..0ac88fa3623 Binary files /dev/null and b/docs/psoc-edge/img/mtb-programmer.png differ diff --git a/docs/psoc-edge/installation.rst b/docs/psoc-edge/installation.rst new file mode 100644 index 00000000000..62dbc734c26 --- /dev/null +++ b/docs/psoc-edge/installation.rst @@ -0,0 +1,165 @@ +.. _pse_mpy_install: + +Installing MicroPython +====================== + +To facilitate the installation of the MicroPython PSOC™ Edge port, the ``mpy-pse.py`` Python script is provided. It is compatible with Windows, +Linux and MacOS. + +Before downloading and running the script, it is recommended to create a new folder to keep all the related files together. +For example: + +.. code-block:: bash + + $ mkdir mp-install + $ cd mp-install + +You can easily download the script from the terminal using the following command: + +.. code-block:: bash + + $ curl -s -L https://raw.githubusercontent.com/infineon/micropython-psoc-edge/psoc-edge-main/tools/psoc-edge/mpy-pse.py > mpy-pse.py + +Ensure you have a recent version of `Python3.x `_ installed and the `pip `_ package installer. +Then install the following packages: + +.. code-block:: bash + + $ pip install requests + +Find all available commands and options by running the script with the following command: + +.. code-block:: bash + + $ python mpy-pse.py --help + +.. _pse_device_setup: + +Device setup +------------- + +In order to setup MicroPython in a PSOC™ Edge board, the ``device-setup`` command of the ``mpy-pse.py`` +utility can be executed. Follow the instructions to select the target PSOC™ Edge board, and deploy the latest +MicroPython firmware version: + +.. code-block:: bash + + $ python mpy-pse.py device-setup + +You can run this command whenever you want to upgrade to the latest MicroPython firmware version. +This command will take care of the following steps: + +* Download and install openocd, which is the software required to deploy a firmware file on PSOC™ Edge controllers +* Download the latest ``.hex`` file for your selected board +* Deploy the latest version of MicroPython firmware on your board + +To flash a specific ``.hex`` to CM55 core of this device: +.. code-block:: bash + + $ python mpy-pse.py device-setup --hex-file pathtodir/mpy-psoc-edge_KIT_PSE84_AI_CM55.hex + +Install a specific version +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you want to setup the device with a specific firmware version, you can check the list of available releases in the `GitHub release section `_. + +The ``device-setup`` command can also assist you with this process. In this case, the board and the desired +version needs to be passed as arguments. + +.. code-block:: bash + + $ python mpy-pse.py device-setup -b KIT_PSE84_AI -v v0.1.0 + +.. warning:: + + Be sure to provide the board name as shown in the ``device-setup`` command when running in interactive mode. + Also, provide a valid tag that exists in the release section, in the format *vx.y.z*. + No fail-safe mechanisms or error verifications are (yet) implemented on the ``mpy-pse.py`` utility, and the script will fail to retrieve the necessary firmware file. + +Direct binary deployment +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Another way to program the board is by directly providing the binary file. This can be also done using the ``device-setup`` command. +Specify the board and the path and name of the ``.hex`` file using the ``-f`` flag as shown below: + +.. code-block:: bash + + $ python mpy-pse.py firmware-deploy -b KIT_PSE84_AI -f pathtodir/mpy-psoc-edge_KIT_PSE84_AI.hex + +Multiple devices deployment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you have multiple PSOC™ Edge boards connected to your computer, you can distinguish them by their serial number, and flash them one by one. +To do so, use the ``-n`` flag to provide the serial number of the target board as shown below: + +.. code-block:: bash + + $ python mpy-pse.py device-setup -b KIT_PSE84_AI -n 181F0D5A01212300 + +Alternatively, you can deploy a firmware file to all connected boards if you have a device YAML file following the `etdevs `_ specification. + +.. note:: + + This option is only supported on **Linux** and **MacOS** systems. etdevs is not currently enabled for Windows. + +First, ensure that the etdevs package is installed: + +.. code-block:: bash + + $ pip install etdevs + +Then, create a YAML file (e.g., *devs.yaml*) with the board ``name`` and the ``uid`` (debugger serial number) for all the connected available boards: + +.. code-block:: yaml + + - name: KIT_PSE84_AI + uid: 181F0D5A01212300 + + - name: KIT_PSE84_AI + uid: 181F0D5A01212400 + + ... + + +Finally, run the ``device-setup`` command providing the YAML file with the ``-d`` flag: + +.. code-block:: bash + + $ python mpy-pse.py device-setup -b KIT_PSE84_AI -d devs.yml + +Getting the firmware +^^^^^^^^^^^^^^^^^^^^ + +The binary *.hex* files are available in the `GitHub release section `_. +All PSOC™ Edge firmware versions for each of the supported boards can be found there. + + + .. image:: img/gh-releases.png + :alt: GitHub MicroPython PSOC Edge Releases + :width: 520px + + +Other installation methods +-------------------------- + +Cypress Programmer +^^^^^^^^^^^^^^^^^^ + +Alternatively, you can directly flash the firmware binary file with the `ModusToolbox™ Programming Tools +`_ (minimum version required is 1.6.0). + +It allows you to program the PSOC™ Edge microcontroller family with just a few clicks from your Windows, Linux, or MacOS machine. +Follow the instructions at the provided link to download and install the tool. + +After that, select the downloaded MicroPython firmware *.hex* file to be deployed on the PSOC™ Edge. Then, in +the upper menu, select the connected *Board*, click on *Connect*, and finally click on *Program*. +The log section will show the progress and notify you when the firmware deployment on the controller is completed. + +.. image:: img/mtb-programmer.png + :alt: ModusToolbox Programmer GUI + :width: 520px + +For a detailed description on how to use the ModusToolbox™ Programmer tool, please consult the `ModusToolbox™ Programmer User Guide +`_. + + diff --git a/docs/psoc-edge/links.rst b/docs/psoc-edge/links.rst new file mode 100644 index 00000000000..eccc46bb9d7 --- /dev/null +++ b/docs/psoc-edge/links.rst @@ -0,0 +1,6 @@ +.. _links.rst: + +.. _pse84_kit_ai_product_page: https://www.infineon.com/evaluation-board/KIT-PSE84-AI +.. _pse84_kit_ai_guide: https://www.infineon.com/assets/row/public/documents/30/44/infineon-kit-pse84-ai-user-guide-usermanual-en.pdf +.. _pse8x_consumer_datasheet: https://www.infineon.com/assets/row/public/documents/30/49/infineon-psoc-edge-e8x-consumer-datasheet-datasheet-en.pdf +.. _pse8x_arch_ref_manual: https://www.infineon.com/assets/row/public/documents/30/57/infineon-psoc-edge-e8x-architecture-reference-manual-additionaltechnicalinformation-en.pdf \ No newline at end of file diff --git a/docs/psoc-edge/mpy-usage.rst b/docs/psoc-edge/mpy-usage.rst new file mode 100644 index 00000000000..d15ac3783d2 --- /dev/null +++ b/docs/psoc-edge/mpy-usage.rst @@ -0,0 +1,198 @@ +.. _psoc_edge_mpy_usage: + +Working with MicroPython +========================= + +With MicroPython already installed on your board, there are several flavors and tools to work with MicroPython. (See :ref:`pse_mpy_install` for installation instructions). +In this section, we introduce some of the ways you can work with MicroPython. + +Serial prompt (REPL Mode) +------------------------- + +With MicroPython deployed on your PSOC™ Edge board, you can access the REPL mode using +the USB-UART interface from the on-board debugger. + +REPL stands for Read Evaluate Print Loop and is the name given to the interactive MicroPython +prompt that you can access on the PSOC™ Edge board. Using the REPL is by far the easiest way to test out your +code and run commands. This is equivalent to running the *python* command (without passing a script) in the command line terminal of your machine. + +Use your preferred serial terminal software to connect to the board. Examples of serial +terminal tools are `Putty `_, which works for Windows and +Unix machines; or other platform-specific such as `Tera Term `_, or `minicom `_. + +Configure the serial connection with **115200 bauds** and **8-N-1** (8 bits frame, no parity and 1 stop +bit), and connect to the board's serial port, the MicroPython REPL prompt will appear, and you can start +typing some Python code :) + +.. image:: img/mpy-psoc-edge-repl.jpg + :alt: MicroPython REPL prompt + :width: 520px + +Running a script +---------------- + +To implement more elaborate programs, and use the embedded device stand-alone you can write +Python scripts. + +There are several IDEs that you can install that integrate a text editor with the tools to run your +Python script on your MicroPython device, as well as handling the file system of your MicroPython +device. The most popular are: + +* `Thonny `_ +* `Mu Editor `_ +* `Arduino Lab for MicroPython `_ + +Alternatively, MicroPython offers :ref:`mpremote` as a command line tool that can be as well used for executing +scripts. Find more information in the provided link. + +In MicroPython there are primarily two ways to execute a script: + +Host REPL mode +~~~~~~~~~~~~~~ + +In this mode, the MicroPython PSOC™ Edge board is connected through the serial interface to the +host development machine. +Each of the lines will be executed in the controller. Any output like print messages in your application or +exceptions will be sent through the serial connection to the host machine, which will display them +in the serial terminal console. + +The REPL mode is used, but the IDE or command line tool will take care of sending +each line of the script and process its output to show it in the terminal. + +On-target file system mode +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the board provides a file system and data storage, you will have the possibility to store your +scripts in the device. + +You can split your program into different files, and use ``import`` to make use of the provided features +in other scripts. +To run a script in the device at boot, two scripts need to be present in the file +system: ``boot.py`` and ``main.py``. The scripts are executed in the sequence, first ``boot.py`` followed by ``main.py``. + +User-defined Python modules or code can also be converted into bytecode (:ref:`mpy files `) by using the ``mpy-cross`` tool and then copied onto the +filesystem for getting speed benefits in execution. + +A more advanced and efficient mode of script execution is also available, where the scripts to be executed are :ref:`frozen ` as part of the application. However, this is only possible if the user has access to the build flow of the specific port. + +The filesystem is described in the section below with some examples. + +The MicroPython filesystem +--------------------------- + +The PSOC™ Edge port offers ``LFS2`` (LittleFS v2) filesystem, implemented in :ref:`MicroPython `. The ``LFS2`` filesystem is selected as the default given its stability and reliability. The filesystem is located on the external QSPI flash, which has a capacity of 64 MB. + +The filesystem is automatically mounted at boot with the help of frozen scripts, located in the ``ports/psoc-edge/freeze`` directory. The default mount point of the filesystem is ``/`` (root directory). + +Given below are a few examples of various operations on the filesystem: + +Creating and reading files +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MicroPython on the PSOC™ Edge supports the standard way of accessing files in +CPython, using the built-in ``open()`` function. The ``open()`` function returns a file pointer. The file is created if not already present and otherwise its contents are overwritten. + +To create a file:: + + >>> f = open('data.txt', 'w') + >>> f.write('some data') + 9 + >>> f.close() + +The number "9" returned from the function, is the number of bytes that were written with the ``write()`` method. +Then the user can read back the contents of this new file using:: + + >>> f = open('data.txt') + >>> f.read() + 'some data' + >>> f.close() + +Note that the default mode when opening a file is to open it in read-only mode +and as a text file. Specify ``'wb'`` as the second argument to ``open()`` to +open for writing in binary mode, and ``'rb'`` to open for reading in binary +mode. + +Listing files and more +~~~~~~~~~~~~~~~~~~~~~~ + +The ``os`` module can be used for further control over the filesystem. First, +the ``os`` module needs to be imported:: + + >>> import os + +Then the contents of the filesystem can be listed:: + + >>> os.listdir() + ['boot.py', 'port_config.py', 'data.txt'] + +New directories can be created:: + + >>> os.mkdir('dir') + +And entries can be removed:: + + >>> os.remove('data.txt') + +Also, entries can be renamed:: + + >>> os.rename('data.txt','data_new.txt') # os.rename('old_filepath','new_filepath') + +Start-up scripts +~~~~~~~~~~~~~~~~ + +As mentioned above, two files are treated specially by the port when it starts up: +``boot.py`` and ``main.py``. The user can create these files and populate them with the code that can run at startup. + +Using MicroPython remote control (mpremote) for filesystem operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :ref:`mpremote ` tool can be used to transfer files located on the user's host filesystem into the MicroPython filesystem. + + +Resetting the board +------------------- + +If something goes wrong, you can reset the board in two ways. +The first way is to press CTRL-D at the MicroPython prompt, which performs a soft reset. + +If that does not work, you can perform a hard reset by pressing the RESET button. +This will end your session, disconnecting whatever program (PuTTY, Thonny, etc.) you used to connect to the board. + +Boot modes +---------- + +There are 2 boot modes: + + * Normal boot mode + * Safe boot mode + +``boot.py`` and ``main.py`` are executed in "Normal boot mode". + +``boot.py`` and ``main.py`` are **not** executed in "Safe boot mode". + +Changing boot mode: + + * For normal boot mode, just press and release the RESET button on the board. + + * For safe boot mode, press and release the RESET button while pressing the USER button on the board. Release the USER button after the LED on the board flashes twice. + + +If you change the boot mode to safe boot mode, the MicroPython starts without +the execution of ``main.py``. Then you can remove the ``main.py`` by following command: :: + + import os + os.remove('main.py') + +Using third-party IDEs for filesystem operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Thonny +^^^^^^ + +The MicroPython port for PSOC™ Edge can be detected by the `Thonny IDE `_ when the ``MicroPython (generic)`` option is selected at the bottom right corner, as shown. Additionally, the filesystem is detected by the IDE, as shown in the lower left column. +Using the GUI, you can perform file operations such as creating a new file, adding contents to it, and then saving it to the filesystem on the MicroPython device. + +.. image:: img/mpy-thonny-filesystem.jpg + :alt: Filesystem operation using Thonny IDE + :width: 800px + diff --git a/docs/psoc-edge/quickref.rst b/docs/psoc-edge/quickref.rst new file mode 100644 index 00000000000..99645bf8c82 --- /dev/null +++ b/docs/psoc-edge/quickref.rst @@ -0,0 +1,998 @@ +.. _psoc_edge_quickref: + +.. include:: links.rst + +Quick reference for the PSOC™ Edge +=================================== + +.. image:: img/kit-pse84-ai.png + :alt: KIT_PSE84_AI board + :width: 540px + +The `PSOC™ Edge E84 AI Kit `_. + +Below is a quick reference for PSOC™ Edge E84 boards. If it is your first time +working with this port it may be useful to get an overview of the microcontroller: + +.. toctree:: + :maxdepth: 1 + :includehidden: + + general.rst + installation.rst + mpy-usage.rst + +Pins and GPIO +------------- + +See :ref:`machine.Pin ` for the complete Pin API reference. +This section focuses on the specific PSOC™ Edge port variations and particularities. + +The constructor +^^^^^^^^^^^^^^^ + +The controller pin naming follows the nomenclature ``P_``, where: + + - ```` is a numeric identifier for the port (e.g., 0-21 for the PSOC™ Edge E84) + - ```` is the pin number within that port. + +Use the respective board pinout diagram to find the available pins and their locations. + +This is the ``id`` that needs to be passed to the constructor in one of the following formats: + + - As a **string label**, single or double quoted: ``'P_'`` or ``"P_"`` + - A **pre-instantiated object** ``Pin.cpu.`` or ``Pin.board.``. + +:: + + from machine import Pin + + p_in = Pin('P0_0', Pin.IN) + p_out = Pin("P7_0", Pin.OUT, value=False) + + p = Pin(Pin.cpu.P17_1, Pin.OPEN_DRAIN) + + +The pre-instantiated object can be used directly without calling the constructor. +Instead, you can use ``init()`` to configure it. + +:: + + from machine import Pin + + pin = Pin.cpu.P17_0 + pin.init(mode=Pin.IN) + + +.. tip:: + Use the REPL interface to discover the available user pins, using tab for completion: + + >>> from machine import Pin + >>> Pin.cpu.P + P10_5 P10_7 P11_3 P12_3 + P13_0 P13_1 P13_2 P13_3 + P13_4 P13_5 P13_6 P13_7 + P14_0 P14_1 P14_2 P14_3 + P14_4 P14_5 P14_6 P14_7 + P15_0 P15_1 P15_2 P15_3 + P15_4 P15_5 P15_6 P15_7 + P16_0 P16_1 P16_2 P16_3 + P16_4 P16_5 P16_6 P16_7 + P17_0 P17_1 P17_2 P17_3 + P17_4 P17_5 P17_7 P20_3 + P20_4 P20_5 P20_6 P20_7 + P21_1 P21_2 P21_3 P21_4 + P21_5 P21_6 P21_7 P3_0 + P3_1 P6_4 P6_6 P7_0 + P7_7 P8_0 P8_1 P8_5 + P8_6 P9_0 P9_1 P9_2 + P9_3 + + >>> from machine import Pin + >>> Pin.board. + AMIC1_CTB_INN AMIC1_CTB_INP AMIC1_CTB_OUT AMIC1_CTB_REF + AMIC2_CTB_INN AMIC2_CTB_INP AMIC2_CTB_OUT AMIC2_CTB_REF + I2C_SCL_1V8 I2C_SCL_3V3 I2C_SDA_1V8 I2C_SDA_3V3 + I2S_TX_FYSYNC I2S_TX_MCK I2S_TX_SCK I2S_TX_SD + I3C_SCL I3C_SDA IMU0_INT IMU1_INT + MAG_INT PDM_CLK PDM_DATA PRESS_SENS_INT + RADAR_INT RADAR_RESET RADAR_SPI_CLK RADAR_SPI_CS + RADAR_SPI_MISO RADAR_SPI_MOSI SERIAL_INT0 SERIAL_INT1 + SERIAL_INT2 SERIAL_INT3 USER_BUTTON USER_LED1 + USER_LED2 USER_LED_B USER_LED_G USER_LED_R + + +In addition to the supported ``pull`` configuration values, ``PULL_UP_DOWN`` is also available in this port. + +The ``drive`` parameter accepts up to 8 levels, which set the following drive strength for the pin: + + - ``DRIVE_0``: 1mA/2mA drive current (normal/high speed IO) + - ``DRIVE_1``: 2mA/4mA drive current (normal/high speed IO) + - ``DRIVE_2``: 3mA/6mA drive current (normal/high speed IO) + - ``DRIVE_3``: 4mA/8mA drive current (normal/high speed IO) + - ``DRIVE_4``: 5mA/10mA drive current (normal/high speed IO) + - ``DRIVE_5``: 6mA/12mA drive current (normal/high speed IO) + - ``DRIVE_6``: 7mA/14mA drive current (normal/high speed IO) + - ``DRIVE_7``: 8mA/16mA drive current (normal/high speed IO) + +For more information about drive strength, check the PSOC™ Edge `Datasheet `_ and `Architecture Reference Manual `_. + +.. note:: + + The following constructor arguments and/or configuration values are NOT supported in this port: + + - ``alt``: Alternate functionality is not supported. + - ``mode``: ``Pin.ALT``, ``Pin.ALT_OPEN_DRAIN``, and ``Pin.ANALOG`` modes are not supported. + +Methods +^^^^^^^ + +.. method:: Pin.irq(handler=None, trigger=(Pin.IRQ_FALLING | Pin.IRQ_RISING), priority=7) + +The following parameters have port-specific behavior: + + - ``priority``: Priority values range from 7 (lowest) to 0 (highest). Default is 7. + + .. note:: + + All pins on the same port share the same interrupt line. Therefore, only one priority can be set for all pins on the same port. + If multiple pins configure interrupts for the same port, the highest priority will be used. + If only one pin is configured for an interrupt, its priority can be reconfigured to any value. + +.. note:: + + The following ``irq()`` features are not supported in this port: + + - ``trigger``: The ``Pin.IRQ_LOW_LEVEL`` and ``Pin.IRQ_HIGH_LEVEL`` triggers are not supported. + - ``wake``: The wake parameter is currently not supported. + - ``hard``: This parameter is ignored. It can be passed but currently has no effect. + +.. note:: + + **None** of the non-core methods from the Pin API are currently implemented for this port. + + +Real time clock (RTC) +--------------------- + +See :ref:`machine.RTC `: :: + + from machine import RTC + import time + + irq_counter = 0 + + def cback(event): + global irq_counter + irq_counter += 1 + + rtc = RTC() + rtc.init((2023, 1, 1, 0, 0, 0, 0, 0)) # initialise rtc with specific date and time, + # eg. 2023/1/1 00:00:00 + rtc.datetime((2017, 8, 23, 2, 12, 48, 0, 0)) # set a specific date and + # time, eg. 2017/8/23 1:12:48 + rtc.datetime() # get date and time + + rtc.irq(trigger=RTC.ALARM0, handler=cback) + rtc.alarm(1000, repeat=False) # set one-shot short alarm in ms + rtc.alarm_left() # Read the time left for the alarm to expire + time.sleep_ms(1008) # wait sufficient time + print(irq_counter) # Check irq counter + + rtc.irq(trigger=RTC.ALARM0, handler=cback) + rtc.alarm(3000, repeat=True) # set periodic short alarm in ms + rtc.cancel() # cancel the alarm + + rtc.irq(trigger=RTC.ALARM0, handler=cback) + rtc.alarm((2023, 1, 1, 0, 0, 1, 0, 0), repeat=False) # set one-shot longer duration alarm + + rtc.memory(b"hello") # write bytes into RTC user memory + rtc.memory() # read bytes from RTC user memory + + +.. note:: + Setting a random week day in 'wday' field is not valid. The underlying library implements the logic to always + calculate the right weekday based on the year, date and month passed. However, datetime() will not raise an error + for this but rather re-write the field with the last calculated actual value. + +.. note:: + RTC API behavior on this port has the following specifics: + + - ``RTC()`` is a singleton constructor with no ``id`` or additional constructor arguments. + - ``rtc.irq()`` accepts alarm trigger ``0`` (``RTC.ALARM0``); ``wake`` is not implemented. + - ``rtc.alarm()`` accepts ``time`` and optional ``repeat``; no positional alarm ``id`` argument is used. + - Input ``weekday`` in datetime tuples is ignored and hardware computes the weekday from date fields. + - The current ``rtc.memory([data])`` maximum payload on KIT_PSE84_AI is 28 bytes. + +.. warning:: + RTC alarm timing on this port has second-level resolution. Millisecond alarm values are accepted, but are rounded + up to whole seconds internally. + + +Hardware I2C bus +---------------- + +See :ref:`machine.I2C ` and :ref:`machine.I2CTarget ` for the complete I2C API reference. + +Hardware I2C is available on the PSOC™ Edge E84 using the SCB (Serial Communication Block) +peripheral. The port supports both controller (master) and target (slave) modes. + +.. note:: + External pull-up resistors (typically 4.7kΩ) are required on both SCL and SDA lines. + Only one I2C instance (controller or target) can be active at a time, as both modes + share the same SCB peripheral and pins. + + +Controller mode (Master) +^^^^^^^^^^^^^^^^^^^^^^^^ + +Use the ``I2C`` class for controller (master) operations:: + + from machine import I2C + + i2c = I2C(scl='P17_0', sda='P17_1', freq=100000) + +Constructor arguments: + + - ``id``: I2C bus number (currently only 0 is available). + **This parameter is ignored**. + - ``scl``: SCL pin (string 'P_' or Pin object). + - ``sda``: SDA pin (string 'P_' or Pin object). + - ``freq``: I2C clock frequency in Hz. Supported: 100000 (100kHz) or + 400000 (400kHz). Default is 400000. + - ``timeout``: Transfer timeout in microseconds. Must be > 0. + Default is 50000 (50ms). + +The ``scl`` and ``sda`` pins are the only mandatory arguments. + +Methods +~~~~~~~ + +All the methods(functions) given in :ref:`machine.I2C ` class have been implemented in this port except: + +.. method:: I2C.init() + +Additionally, the following functions are enabled: + +.. method:: I2C.deinit() + +Target mode (Slave) +^^^^^^^^^^^^^^^^^^^ + +Use the ``I2CTarget`` class for target (slave) operations:: + + from machine import I2CTarget + + mem = bytearray([0xAA, 0xBB, 0xCC, 0xDD]) + i2c_target = I2CTarget(scl="P17_0", sda="P17_1", addr=0x43, mem=mem) + + +The I2CTarget implementation on PSoC Edge has the following port-specific details: + +**Memory Addressing:** + - ``addrsize``: 7-bit and 10-bit addresses are accepted. + - ``mem_addrsize``: Only ``0`` is supported. + - EEPROM-like internal address phase (8/16/24/32-bit ``mem_addrsize``) is not implemented. + +**IRQ triggers:** + +The ``hard`` argument in ``i2c_target.irq(..., hard=True)`` is supported. +When using hard IRQ callbacks, keep handlers short and allocation-free. + +Current implementation notes for IRQ data-phase events: + + + - PSoC hardware events are limited and do not map + 1:1 to MicroPython ``IRQ_READ_REQ``/ ``IRQ_WRITE_REQ`` semantics. + - Treat these two flags as optional notifications, not required control points. + - In the current PSOC Edge port implementation, data-path behavior is + strongly tied to ``mem`` buffer configuration. After address match, + hardware/port state handling performs most data movement automatically (when ``mem`` is configured). + + +Practical guidance for this port: + + - For robust target-mode operation, configure ``mem`` and size it to cover + expected master write payloads. + - With ``mem`` configured, explicit ``I2CTarget.readinto()``/ + ``I2CTarget.write()`` calls are usually optional, and mainly needed for + custom protocol handling in IRQ callbacks. + + +Hardware SPI bus +---------------- + +See :ref:`machine.SPI ` for the complete SPI master API reference. +``SPITarget`` is a PSOC™ Edge-specific class and has no separate library page. + +Hardware SPI on PSOC™ Edge uses the SCB peripheral and supports both controller +(master) and target (slave) modes. + +Controller mode (Master) +^^^^^^^^^^^^^^^^^^^^^^^^ + +Use the ``SPI`` class for controller-mode transfers:: + + from machine import SPI, Pin + + spi = SPI( + baudrate=1_000_000, + polarity=0, + phase=0, + bits=8, + firstbit=SPI.MSB, + sck='P16_0', + mosi='P16_1', + miso='P16_2', + ) + + cs = Pin('P16_3', Pin.OUT, value=1) + tx = b'\x9f\x00\x00\x00' + rx = bytearray(4) + + cs(0) + spi.write_readinto(tx, rx) + cs(1) + print(rx) + +Constructor arguments: + + - ``id``: accepted for API compatibility, currently ignored. + - ``baudrate``: SPI clock in Hz. Default is ``1_000_000``. + - ``polarity`` / ``phase``: must be ``0`` or ``1``. + - ``bits``: only ``8`` is supported. + - ``firstbit``: ``SPI.MSB`` or ``SPI.LSB``. + - ``sck``, ``mosi``, ``miso``: required SPI signal pins. + +.. note:: + + Chip select (CS/SS) is controlled by user code with ``machine.Pin``. + It is not driven automatically by ``machine.SPI``. + + +Target mode (Slave) +^^^^^^^^^^^^^^^^^^^ + +Use the ``SPITarget`` class for target-mode communication:: + + from machine import SPITarget + + spi_t = SPITarget( + sck='P16_0', + mosi='P16_1', + miso='P16_2', + ssel='P16_3', + polarity=0, + phase=0, + bits=8, + firstbit=SPITarget.MSB, + ) + + tx = b'\x11\x22\x33\x44' + rx = bytearray(4) + spi_t.write_readinto(tx, rx) + + spi_t.deinit() + +Constructor arguments: + + - ``sck``: SPI clock pin. + - ``mosi``: target TX pin. + - ``miso``: target RX pin. + - ``ssel``: chip-select input pin. + - ``polarity`` / ``phase``: must be ``0`` or ``1``. + - ``bits``: only ``8`` is supported. + - ``firstbit``: ``SPITarget.MSB`` or ``SPITarget.LSB``. + +Constants: + + - ``SPITarget.MSB``: most-significant-bit first. + - ``SPITarget.LSB``: least-significant-bit first. + +Methods: + +.. method:: SPITarget.readinto(buf) + + Read bytes from the SPI target RX FIFO into writable buffer ``buf``. + Returns the number of bytes read. + + Raises ``OSError`` on timeout. + +.. method:: SPITarget.write(buf) + + Write bytes from buffer ``buf`` to the SPI target TX FIFO. + Returns the number of bytes written. + + Raises ``OSError`` on timeout. + +.. method:: SPITarget.write_readinto(tx_buf, rx_buf) + + Full-duplex transfer in target mode. Writes bytes from ``tx_buf`` and + reads bytes into ``rx_buf``. + + ``tx_buf`` and ``rx_buf`` must have the same length. + Returns the number of bytes transferred. + + Raises ``ValueError`` if buffer lengths differ. + Raises ``OSError`` on timeout. + +.. method:: SPITarget.deinit() + + Deinitialise the SPITarget instance and release its underlying SCB resource. + +The SPITarget implementation on PSoC Edge has the following port-specific details: + +- ``sck``, ``mosi``, ``miso``, and ``ssel`` are all required. +- ``bits`` is fixed to 8. +- ``readinto()``, ``write()``, and ``write_readinto()`` are blocking and use an + internal timeout. +- A single ``SPITarget`` instance is supported in this port configuration. + + + +Inter-Processor Communication (IPC) +------------------------------------- + +The ``IPC`` class provides message-passing between the two cores using the +hardware IPC pipe peripheral. This is a PSOC™ Edge-specific module — it is not part of +the standard MicroPython ``machine`` API. Currently, for this port, IPC is supported to enable communication from the CM33 core to the CM55 core. +.. note:: + + IPC is only available on builds compiled with the ``MULTI_CORE`` flag. The module is + not present on single-core firmware images. By default it is enabled for this port. + +.. note:: + + Only CM33 → CM55 communication is currently supported. The CM33 core always acts as + the initiating side; the CM55 firmware must be built and deployed separately. + +The constructor +^^^^^^^^^^^^^^^ + +:: + + from machine import IPC + + ipc = IPC(src_core=IPC.CM33, target_core=IPC.CM55) + +Constructor arguments: + + - ``src_core``: Source core ID. Currently only ``IPC.CM33`` (``0``) is supported. + Default is ``IPC.CM33``. + - ``target_core``: Destination core ID. Currently only ``IPC.CM55`` (``1``) is supported. + Default is ``IPC.CM55``. + +Up to 5 IPC object instances can be created and this is enforced by the constructor. Each instance can be configured with different source and target cores, but currently only CM33 → CM55 communication is supported regardless of the constructor arguments. + +Core ID and command constants +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following class-level constants are available on every ``IPC`` object: + + - ``IPC.CM33``: Core ID for the CM33 core (``0``). + - ``IPC.CM55``: Core ID for the CM55 core (``1``). + - ``IPC.CMD_START``: Pre-defined start command (``0x82``). + - ``IPC.CMD_STOP``: Pre-defined stop command (``0x83``). + +Methods +^^^^^^^ + +.. method:: IPC.init() + + Initialise the IPC pipe hardware. Must be called once after construction and before + any other IPC operation:: + + ipc.init() + +.. method:: IPC.register_client(client_id, callback, endpoint_id, endpoint_addr) + + Register a client on the source endpoint so that incoming messages addressed + to ``client_id`` invoke ``callback``. + + - ``client_id``: Unique client identifier (``0``–``7``). Each registered client + must have a unique ID. + - ``callback``: A callable invoked as ``callback(client)`` when a message arrives + for this client. The callback receives a single ``IPCClient`` object with the + following read-only attributes: + + - ``client.cmd``: Command byte received from the target core. + - ``client.value``: 32-bit value received from the target core. + - ``client.id``: The client ID this message was addressed to. + + The callback is deferred and runs in the MicroPython scheduler context (not in + the ISR), so it is safe to allocate memory and call any MicroPython function. + + - ``endpoint_id``: Endpoint index for source core. + - ``endpoint_addr``: Endpoint address for the source core. + + Returns ``True`` on success, ``False`` otherwise. + + Maximum of 8 clients can be registered per endpoint. This is a PSOC™ Edge-specific limit. + + Example — registering two independent services:: + + def svc1_cb(client): + print("Service1 received cmd=0x{:02X}".format(client.cmd)) + + def svc2_cb(client): + print("Service2 received cmd=0x{:02X}".format(client.cmd)) + + ipc.register_client(3, svc1_cb, 1, 1) # Service 1 + ipc.register_client(4, svc2_cb, 1, 1) # Service 2 + +.. method:: IPC.enable_core(core_id=IPC.CM55) + + Boot the target core and wait for it to start. Currently only ``IPC.CM55`` is + supported. + + - ``core_id``: The core to enable. Default is ``IPC.CM55``. + + Calling this when the CM55 is already running prints a notice and returns immediately. + Allow a short delay after this call for CM55 initialisation + to complete before sending messages:: + + ipc.enable_core(IPC.CM55) + time.sleep(1) # Wait for CM55 firmware to initialise + +.. method:: IPC.send(cmd, value=0, client_id) + + Send a message to a client on the target core. + + - ``cmd``: Command byte. Use ``IPC.CMD_START``, ``IPC.CMD_STOP``, or any + application-defined value. + - ``value``: Optional 32-bit data payload. Default is ``0``. + - ``client_id``: Client ID on the target core. + + Raises ``OSError`` if the send fails after the maximum number of retries + + ipc.send(IPC.CMD_START, 0, 5) # Send CMD_START to CM55 client 5 + ipc.send(IPC.CMD_STOP, 0, 6) # Send CMD_STOP to CM55 client 6 + +.. method:: IPC.is_busy([core_id]) + + Check whether the IPC channel for the given core is currently locked. + + - ``core_id``: ``IPC.CM33`` or ``IPC.CM55`` + + Returns ``True`` if the channel is busy, ``False`` otherwise:: + + if not ipc.is_busy(): + ipc.send(IPC.CMD_START, 0, 5) + + # Check a specific core explicitly + if ipc.is_busy(IPC.CM55): + print("CM33 channel is locked") + +Complete example +^^^^^^^^^^^^^^^^ + +The following example demonstrates two independent services sharing a single IPC endpoint, +with each service using its own client IDs on both the CM33 and CM55 sides:: + + import time + from machine import IPC + + ipc = IPC(src_core=IPC.CM33, target_core=IPC.CM55) + ipc.init() + + # Per-service receive state + svc1 = {"received": False, "cmd": None} + svc2 = {"received": False, "cmd": None} + + def svc1_cb(client): + svc1["received"] = True + svc1["cmd"] = client.cmd + + def svc2_cb(client): + svc2["received"] = True + svc2["cmd"] = client.cmd + + # Register both services on the CM33 endpoint (endpoint_id=1, endpoint_addr=1) + ipc.register_client(3, svc1_cb, 1, 1) # Service 1 -- CM33 client_id=3 + ipc.register_client(4, svc2_cb, 1, 1) # Service 2 -- CM33 client_id=4 + + # Boot CM55 and wait for it to initialise + ipc.enable_core(IPC.CM55) + time.sleep(1) + + # Send CMD_START to CM55 Service 1 (client_id=5); echo comes back to CM33 client_id=3 + ipc.send(IPC.CMD_START, 0, 5) + + # Send CMD_STOP to CM55 Service 2 (client_id=6); echo comes back to CM33 client_id=4 + ipc.send(IPC.CMD_STOP, 0, 6) + +PDM - PCM bus +-------------- + +PDM/PCM is a asynchronous operation used to connect digital audio devices. +At the physical level, a bus consists of 2 lines: CLK, DATA. + +.. warning:: + This is not part of the core MicroPython libraries. Therefore, not mapping any existing machine class API and neither supported by other ports. + +PDM-PCM objects can be created and initialized using:: + + from machine import PDM_PCM + + clk_pin = "P8_5" + data_pin = "P8_6" + + pdm_pcm = PDM_PCM( + sck=clk_pin, + data=data_pin, + sample_rate=16000, + bits=PDM_PCM.BITS_16, + format=PDM_PCM.MONO, + gain=0, + ) + +2 modes of operation are supported: + - blocking + - non-blocking + + +Constructor +^^^^^^^^^^^^ + +.. class:: PDM_PCM(clk, data, sample_rate, bits, format, gain, ibuf) + + Keyword-only parameters that are supported on this port: + + - ``clk`` is a pin object for the clock line + - ``data`` is a pin object for the data line + - ``sample_rate`` specifies audio sampling rate. **Currently only 16 KHz sample rate is supported**. + - ``bits`` specifies word length - 16 and 32 being accepted values. + - ``format`` specifies channel format - STEREO or MONO. + - ``gain`` is the gain in dB. In case of STEREO format is applies to both channels. The range goes from -103 to +83 dB with 6 dB step. Values will be rounded to the closest step. + - ``ibuf`` is the size of the internal ring buffer (in bytes) storing the incoming audio data stream. Default is 20000. + +Methods +^^^^^^^^ + +.. method:: PDM_PCM.init(clk, data, sample_rate, bits, format, gain, ibuf) + + Initializes the PDM_PCM hardware as per the specified parameters. See the constructor for details on the supported parameters. + +.. method:: PDM_PCM.deinit() + + Deinitializes the PDM_PCM object. + +.. method:: PDM_PCM.readinto(buf) + + Read audio samples into the buffer specified by ``buf``. ``buf`` must support the buffer protocol, such as bytearray or array. + Sample size can be calculated as (PCM_bits/8) * (format_size); where format_size is 2(stereo mode) and 1(mono mode). + Returns number of bytes read. + +.. method:: PDM_PCM.irq(handler) + + Set the callback.``handler`` is called when ``buf`` becomes full (``readinto`` method). + Setting a callback changes the ``readinto`` method to non-blocking operation. + ``handler`` is called in the context of the MicroPython scheduler. + +.. method:: PDM_PCM.gain([gain]) + + Set/get the gain for of all the channels. The gain is specified in dB. The range goes from -103 to +83 dB with 6 dB step. Values will be rounded to the closest step. + Default is 0 dB. + +Constants +^^^^^^^^^^ + +.. data:: PDM_PCM.STEREO + + for initialising the PDM_PCM ``format`` to stereo + +.. data:: PDM_PCM.MONO + + for initialising the PDM_PCM ``format`` to mono + +.. data:: PDM_PCM.BITS_16 + + for initialising the PDM_PCM ``bits`` to 16 + +.. data:: PDM_PCM.BITS_32 + + for initialising the PDM_PCM ``bits`` to 32 + + +UART +---- + +See :ref:`machine.UART `. + +The following specialization applies to this port: + +Constructor +^^^^^^^^^^^^ + +.. class:: UART(id) + + The following parameters are supported with limited configuration: + + - ``bits``. Only 8 bits. + + These are planned for future implementation, but yet unavailable: + + - ``rts`` + - ``cts`` + - ``flow`` + +.. Note:: + + These parameters are not implemented: + + - ``txbuf`` + - ``invert`` + + +Methods +^^^^^^^ + +.. method:: UART.init(baudrate=9600, bits=8, parity=None, stop=1, *, ...) + + The same parameters as the constructor are supported, with the same limitations. + + +PWM +---- + +Pulse Width Modulation (PWM) signal output on the PSOC™ Edge. See :ref:`machine.PWM ` for the standard MicroPython PWM API. + +.. note:: + + On this port, PWM output is available exclusively on pins **P16_1** through **P16_7**. Each pin is backed by an independent TCPWM0 counter, + so each instance can run at a different frequency simultaneously. A maximum of **7** PWM instances can be active at the same time. + +.. note:: + + The base clock driving all counters is **1 MHz** (derived from the 100 MHz PCLK via a shared 16-bit divider). + This gives a frequency range of **1 Hz - 500 kHz** and a period resolution of 1 µs. + +A PWM object can be created and started using:: + + from machine import PWM + + pwm = PWM("P16_1", freq=1000, duty_u16=32767) # 1 kHz, 50 % duty cycle + +Constructor +^^^^^^^^^^^^ + +.. class:: PWM(pin, *, freq, duty_u16, duty_ns, invert=False) + + Construct and immediately start a PWM signal on *pin*. + + - ``pin`` — the output pin. Accepts a string label (``"P16_1"``), a ``Pin.cpu.`` object, or a ``Pin.board.`` object. + The pin must be one of the PWM-capable pins P16_1 - P16_7. + - ``freq`` — output frequency in Hz (**required**). Must be in the range 1 - 500 000. + - ``duty_u16`` — duty cycle as a 16-bit unsigned integer 0-65535 (0 % - ~100 %). + - ``duty_ns`` — duty cycle (high pulse width) in nanoseconds. Must not exceed the period (``1 000 000 000 / freq`` ns). + - ``invert`` — if ``True``, inverts the output polarity. Default is ``False``. + + Raises ``ValueError`` if the pin does not support PWM, if a PWM instance for that pin already exists without calling ``deinit()`` + first, or if the frequency or duty arguments are out of range. + +Complete example +^^^^^^^^^^^^^^^^ + +:: + + from machine import PWM + + # Start a 1 kHz signal at 50 % duty cycle on P16_1 + pwm = PWM("P16_1", freq=1000, duty_u16=32767) + print(pwm) # PWM(Pin.cpu.P16_1, freq=1000, duty=50.00%) + + # Read back the current settings + print(pwm.freq()) # 1000 + print(pwm.duty_u16()) # 32767 + print(pwm.duty_ns()) # 500000 (0.5 ms duty cycle at 1 kHz) + + # Update frequency only — duty ratio preserved + pwm.freq(2000) + print(pwm.freq()) # 2000 + + # Switch to nanosecond duty control: 250 µs duty cycle at 2 kHz = 50 % + pwm.duty_ns(250000) + print(pwm.duty_ns()) # 250000 + + # Reconfigure completely + pwm.init(freq=500, duty_u16=16383) # 500 Hz, 25 % + + # Stop and release the pin + pwm.deinit() + + +Timer +----- + +Hardware timer using the TCPWM0 peripheral on the PSOC™ Edge. See :ref:`machine.Timer ` for the standard MicroPython Timer API. + +.. note:: + + This port provides **32** independent hardware timer instances (IDs ``0`` to ``31``). + + - **32-bit timers**: IDs ``0`` through ``7`` (TCPWM0 counters ``0`` through ``7``). + - **16-bit timers**: IDs ``8`` through ``31`` (TCPWM0 counters ``256`` through ``279``). + + Only one instance per ID can exist at a time; constructing a second ``Timer(id)`` without calling ``deinit()`` first raises a ``ValueError``. + +.. note:: + + The timer clock is **1 MHz** (shared with the system tick). This means: + + - The minimum resolvable period is **1 µs**. + - With ``period``, the minimum value is **1 ms**. + - For **32-bit timers** (IDs ``0`` to ``7``), the maximum period is **4 294 967 ms** (~49.7 days). + - For **16-bit timers** (IDs ``8`` to ``31``), the maximum period is **65 ms**. + - With ``freq``, the minimum frequency is **1 Hz** and the maximum is **1 000 000 Hz** (1 MHz). + - Computed period ticks must fit the selected counter width: **1-4 294 967 295** for 32-bit timers, **1-65 535** for 16-bit timers. + - The ``hard`` parameter for ``Timer`` is still under development for this port and is not yet completely implemented. + +Complete example +^^^^^^^^^^^^^^^^ + +:: + + from machine import Timer + import micropython + import time + + # --- Periodic soft timer (default) --- + count = 0 + + def on_tick(timer): + global count + count += 1 + print("tick", count) + + tim = Timer(0, mode=Timer.PERIODIC, period=500, callback=on_tick) + time.sleep(3) # let it fire ~6 times + tim.deinit() + + # --- One-shot timer --- + def on_done(timer): + print("one-shot fired") + + tim = Timer(1, mode=Timer.ONE_SHOT, period=1000, callback=on_done) + time.sleep(2) + tim.deinit() + + # --- Frequency-based timer --- + def on_freq(timer): + print("2 Hz tick") + + tim = Timer(2, mode=Timer.PERIODIC, freq=2, callback=on_freq) + time.sleep(3) + tim.deinit() + + # --- Hard IRQ timer (allocation-free callback required) --- + micropython.alloc_emergency_exception_buf(100) + fired = [False] + + def on_hard(timer): + fired[0] = True # list index write is allocation-free + + tim = Timer(0, mode=Timer.ONE_SHOT, period=100, callback=on_hard, hard=True) + time.sleep_ms(200) + tim.deinit() + print("hard fired:", fired[0]) + +Network Module +-------------- + +The :mod:`network` module. + +See :ref:`network.WLAN `: + +This section documents only the PSOC™ Edge-specific WLAN behaviour. + +.. method:: WLAN.active([is_active]) + + Interface activation differs by interface type: + + * STA: ``WLAN.active()`` returns the current connection state. Setting the STA active state is not supported. + * AP: ``WLAN.active()`` returns whether the access point is running, and ``WLAN.active(True/False)`` starts or stops it. + +.. method:: WLAN.scan(ssid=None, bssid=None) + + STA only. Accepts one optional filter per call: + + * ``ssid`` — return only networks matching this SSID. + * ``bssid`` — return only networks matching this BSSID (bytes of length 6). + + Passing both filters together is not supported. + +.. method:: WLAN.connect(ssid, key=None, *, bssid=None) + + Connect the STA interface to an access point. + + * ``ssid`` is required. + * ``key`` is optional and may be omitted for open networks. + * ``bssid`` is optional and, if provided, must be 6 bytes. + +.. method:: WLAN.isconnected() + + Return the interface connection state: + + * STA: ``True`` when connected to an access point. + * AP: ``True`` when the access point is running and at least one station is associated. + +.. method:: WLAN.status('param') + + .. warning:: + This function does not provide link-up/down connection state. Use + ``isconnected()`` to check connection status. + + The following query parameters are allowed: + + * ``rssi`` — received signal strength in dBm (STA only). + * ``stations`` — list of connected station MAC addresses as bytes (AP only). + +.. method:: WLAN.config('param') + WLAN.config(param=value, ...) + + Supported configuration parameters are: + + * AP query parameters: + + - ``channel`` + - ``ssid`` + - ``security`` + - ``key`` / ``password`` — only queryable when the default AP password is set. + - ``mac`` + + * AP set parameters: + + - ``channel`` + - ``ssid`` + - ``security`` + - ``key`` / ``password`` + + * STA query parameters: + + - ``channel`` + - ``ssid`` + - ``security`` + - ``mac`` + + .. note:: + STA has no settable config parameters. Use ``WLAN.connect(ssid, key)`` to associate to a network. + +Constants +^^^^^^^^^ + +Security mode constants: + +.. data:: WLAN.OPEN + WLAN.WEP + WLAN.WPA + WLAN.WPA2 + WLAN.WPA3 + WLAN.WPA2_WPA_PSK + WLAN.SEC_UNKNOWN + +The following helper can be run manually (or placed in ``boot.py``) to connect +to a Wi-Fi network: + +:: + + def network_connect(ssid, key, timeout_s=30): + import network + import time + + wlan = network.WLAN(network.STA_IF) + + if wlan.isconnected(): + print("[Network] Already connected") + print(wlan.ifconfig()) + return + + wlan.connect(ssid, key) + + for _ in range(timeout_s): + if wlan.isconnected(): + print("[Network] Connected") + print(wlan.ifconfig()) + return + time.sleep(1) + + print("[Network] Connection failed") diff --git a/docs/requirements.txt b/docs/requirements.txt index 4d9b9558575..895f02a2409 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ sphinx~=7.2.6 sphinxcontrib.jquery==4.1 sphinx-rtd-theme==3.0.2 +sphinxemoji==0.1.8 diff --git a/docs/templates/topindex.html b/docs/templates/topindex.html index e3bcd7cce14..a5df317339b 100644 --- a/docs/templates/topindex.html +++ b/docs/templates/topindex.html @@ -57,6 +57,10 @@

MicroPython documentation

Quick reference for the ESP32
pinout for ESP32-based boards, snippets of useful code, and a tutorial

+