diff --git a/.github/workflows/ports_psoc6.yml b/.github/workflows/ports_psoc6.yml new file mode 100644 index 0000000000000..ba92db3ca3bca --- /dev/null +++ b/.github/workflows/ports_psoc6.yml @@ -0,0 +1,107 @@ +name: psoc6 port +on: + push: + pull_request: + paths: + - '.github/workflows/*.yml' + - 'tools/**' + - 'py/**' + - 'extmod/**' + - 'shared/**' + - 'lib/**' + - 'drivers/**' + - 'ports/psoc6/**' + +jobs: + server-build: + runs-on: ubuntu-latest + strategy: + matrix: + board: + - CY8CPROTO-062-4343W + - CY8CPROTO-063-BLE + - CY8CKIT-062S2-AI + outputs: + commit_sha: ${{ steps.commit_sha.outputs.sha_short }} + + steps: + - uses: actions/checkout@v4 + - name: Install packages + run: source tools/ci.sh && ci_psoc6_setup + - name: Build + run: source tools/ci.sh && ci_psoc6_build ${{ matrix.board }} + + # Steps only relevant for Infineon fork + # with self-hosted runner available + - name: Gets commit SHA + if: success() && github.repository_owner == 'infineon' + id: commit_sha + run: echo "sha_short=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT + - name: Save firmware bin + if: success() && github.repository_owner == 'infineon' + uses: actions/upload-artifact@v4 + with: + name: mpy-psoc6_${{ matrix.board }}_${{ steps.commit_sha.outputs.sha_short }} + path: ports/psoc6/build/firmware.hex + + # Jobs only relevant for Infineon fork + on-target-test: + if: github.repository_owner == 'infineon' + runs-on: self-hosted + needs: server-build + continue-on-error: true + strategy: + matrix: + board: + - CY8CPROTO-062-4343W + - CY8CPROTO-063-BLE + - CY8CKIT-062S2-AI + steps: + - uses: actions/checkout@v4 + - 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_psoc6_setup + - name: Setup devices + run: | + cp mpy-psoc6_${{ matrix.board }}_${{ needs.server-build.outputs.commit_sha }}/firmware.hex . + source tools/ci.sh && ci_psoc6_flash_multiple_devices ${{ matrix.board }} firmware.hex tools/psoc6/${{ runner.name }}-devs.yml + - name: Run psoc6 tests + timeout-minutes: 12 + run: | + ./tests/ports/psoc6/run_psoc6_tests.sh --test-suite ci-tests --board ${{ matrix.board }} --hil ${{ runner.name }} + - name: Container teardown + if: failure() || success() + run: | + source tools/ci.sh && ci_psoc6_teardown + + release: + runs-on: ubuntu-latest + needs: [server-build, on-target-test] + strategy: + matrix: + board: + - CY8CPROTO-062-4343W + - CY8CPROTO-063-BLE + - CY8CKIT-062S2-AI + if: startsWith(github.ref, 'refs/tags/v') && github.repository_owner == 'infineon' + steps: + - name: Download binaries + uses: actions/download-artifact@v4 + - name: Prepare release assets + run: | + cd mpy-psoc6_${{ matrix.board }}_${{ needs.server-build.outputs.commit_sha }} + mv firmware.hex ../mpy-psoc6_${{ 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 PSoC6 ${{ github.ref_name }} + files: mpy-psoc6_${{ matrix.board }}.hex + body: ${{steps.build_changelog.outputs.changelog}} \ No newline at end of file diff --git a/README.md b/README.md index 02e0b3abb357b..8a0f9139452b2 100644 --- a/README.md +++ b/README.md @@ -114,6 +114,7 @@ In addition, the following ports are provided in this repository: - [nrf](ports/nrf) -- Nordic Semiconductor nRF51 and nRF52. - [pic16bit](ports/pic16bit) -- Microchip PIC 16-bit. - [powerpc](ports/powerpc) -- IBM PowerPC (including Microwatt) + - [psoc6](ports/psoc6) -- Infineon PSoC6. - [qemu-arm](ports/qemu-arm) -- QEMU-based Arm emulated target (for testing) - [qemu-riscv](ports/qemu-riscv) -- QEMU-based RISC-V emulated target (for testing) - [renesas-ra](ports/renesas-ra) -- Renesas RA family. diff --git a/docs/index.rst b/docs/index.rst index 64b83618da149..d0b2e86da03f0 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 + psoc6/quickref.rst wipy/quickref.rst unix/quickref.rst zephyr/quickref.rst diff --git a/docs/psoc6/general.rst b/docs/psoc6/general.rst new file mode 100644 index 0000000000000..d0e0d0decbdd4 --- /dev/null +++ b/docs/psoc6/general.rst @@ -0,0 +1,89 @@ +.. _psoc6_general: + +General information about the PSoC6™ port +========================================= + +The PSoC™ 6 family is built on an ultra-low-power architecture, and the MCUs feature low-power design catering to tailored application domains. +The PSoC6™ port supports boards powered by the `Infineon PSoC6 family of microcontrollers `_ and currently supports the following MCUs: + +* PSoC™ 62 - Performance +* PSoC™ 63 - Bluetooth™ Low Energy + +.. _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 + * - CY8CPROTO-062-4343W + - Wi-Fi, BT + - microSD card slot, external flash memory, thermistor, user button + * - CY8CPROTO-063-BLE + - BLE + - user button, compact form factor + * - CY8CKIT-062S2-AI + - Wi-Fi, BT + - user button, compact form factor, USB-C, MEMS microphone, radar sensor, pressure sensor, 6-axis IMU, 3-axis magnetometer + +For more hardware-related details, refer to the following sections. + +CY8CPROTO-062-4343W +-------------------- + +Pinout +****** + + .. image:: img/CY8CPROTO-062-4343W-pinout.png + :width: 500 + + +Technical specifications +************************ +Links for product details: + +* `CY8CPROTO-062-4343W product page with relevant documents `_ +* `CY8CPROTO-062-4343W MCU Datasheet `_ + +CY8CPROTO-063-BLE +----------------- + +Pinout +****** + + .. image:: img/CY8CPROTO-063-BLE-pinout.png + :width: 350 + + +Technical specifications +************************ +Links for product details: + +* `CY8CPROTO-063-BLE product page with relevant documents `_ +* `CY8CPROTO-063-BLE MCU Datasheet `_ + +CY8CKIT-062S2-AI +---------------- + +Pinout +****** + + .. image:: img/CY8CKIT-062S2-AI-pinout.png + :width: 500 + + +Technical specifications +************************ +Links for product details: + +* `CY8CKIT-062S2-AI product page with relevant documents `_ +* `CY8CKIT-062S2-AI MCU Datasheet `_ + + diff --git a/docs/psoc6/img/CY8CKIT-062S2-AI-pinout.png b/docs/psoc6/img/CY8CKIT-062S2-AI-pinout.png new file mode 100644 index 0000000000000..eebf4c2b239b8 Binary files /dev/null and b/docs/psoc6/img/CY8CKIT-062S2-AI-pinout.png differ diff --git a/docs/psoc6/img/CY8CPROTO-062-4343W-pinout.png b/docs/psoc6/img/CY8CPROTO-062-4343W-pinout.png new file mode 100644 index 0000000000000..8d7500c1c6bcb Binary files /dev/null and b/docs/psoc6/img/CY8CPROTO-062-4343W-pinout.png differ diff --git a/docs/psoc6/img/CY8CPROTO-063-BLE-pinout.png b/docs/psoc6/img/CY8CPROTO-063-BLE-pinout.png new file mode 100644 index 0000000000000..f7f71987d7154 Binary files /dev/null and b/docs/psoc6/img/CY8CPROTO-063-BLE-pinout.png differ diff --git a/docs/psoc6/img/cy-programmer.jpg b/docs/psoc6/img/cy-programmer.jpg new file mode 100644 index 0000000000000..fd03abcde586e Binary files /dev/null and b/docs/psoc6/img/cy-programmer.jpg differ diff --git a/docs/psoc6/img/cy8cproto-062-4343w.jpg b/docs/psoc6/img/cy8cproto-062-4343w.jpg new file mode 100644 index 0000000000000..b7b6ed96e5f3a Binary files /dev/null and b/docs/psoc6/img/cy8cproto-062-4343w.jpg differ diff --git a/docs/psoc6/img/cy8cproto-063-ble.jpg b/docs/psoc6/img/cy8cproto-063-ble.jpg new file mode 100644 index 0000000000000..d6ababeae4911 Binary files /dev/null and b/docs/psoc6/img/cy8cproto-063-ble.jpg differ diff --git a/docs/psoc6/img/gh-releases.png b/docs/psoc6/img/gh-releases.png new file mode 100644 index 0000000000000..c60c52404bfac Binary files /dev/null and b/docs/psoc6/img/gh-releases.png differ diff --git a/docs/psoc6/img/mpy-ide-connect.jpg b/docs/psoc6/img/mpy-ide-connect.jpg new file mode 100644 index 0000000000000..9292663e96f6f Binary files /dev/null and b/docs/psoc6/img/mpy-ide-connect.jpg differ diff --git a/docs/psoc6/img/mpy-ide-prompt.jpg b/docs/psoc6/img/mpy-ide-prompt.jpg new file mode 100644 index 0000000000000..8a9ccdc9c7741 Binary files /dev/null and b/docs/psoc6/img/mpy-ide-prompt.jpg differ diff --git a/docs/psoc6/img/mpy-ide-script.jpg b/docs/psoc6/img/mpy-ide-script.jpg new file mode 100644 index 0000000000000..f1dadf29aec0b Binary files /dev/null and b/docs/psoc6/img/mpy-ide-script.jpg differ diff --git a/docs/psoc6/img/mpy-ide-vfs.png b/docs/psoc6/img/mpy-ide-vfs.png new file mode 100644 index 0000000000000..efb3d4d740c2a Binary files /dev/null and b/docs/psoc6/img/mpy-ide-vfs.png differ diff --git a/docs/psoc6/img/mpy-psoc6-repl.jpg b/docs/psoc6/img/mpy-psoc6-repl.jpg new file mode 100644 index 0000000000000..c216d006c2221 Binary files /dev/null and b/docs/psoc6/img/mpy-psoc6-repl.jpg differ diff --git a/docs/psoc6/img/mpy-thonny-filesystem.jpg b/docs/psoc6/img/mpy-thonny-filesystem.jpg new file mode 100755 index 0000000000000..ac60f9c8bc9da Binary files /dev/null and b/docs/psoc6/img/mpy-thonny-filesystem.jpg differ diff --git a/docs/psoc6/installation.rst b/docs/psoc6/installation.rst new file mode 100644 index 0000000000000..5373110a79704 --- /dev/null +++ b/docs/psoc6/installation.rst @@ -0,0 +1,140 @@ +.. _psoc6_mpy_install: + +Installing MicroPython +====================== + +To facilitate the installation of the MicroPython PSoC6™ port, the ``mpy-psoc6.py`` Python script is provided. It is compatible with Windows, +Linux and MacOS. + +You can easily download the script from the terminal with the following command: + +.. code-block:: bash + + $ curl -s -L https://raw.githubusercontent.com/infineon/micropython/ports-psoc6-main/tools/psoc6/mpy-psoc6.py > mpy-psoc6.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-psoc6.py --help + +.. _psoc6_device_setup: + +Device setup +------------- + +In order to setup MicroPython in a PSoC6™ board, the ``device-setup`` command of the ``mpy-psoc6.py`` +utility can be executed. Follow the instructions to select the target PSoC6™ board, and deploy the latest +MicropPython firmware version: + +.. code-block:: bash + + $ python mpy-psoc6.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 PSoC6™ controllers +* Download the latest ``.hex`` file for your selected board +* Deploy the latest version of MicroPython firmware on your board + +Install a previous version +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you want to setup the device with a previous 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-psoc6.py device-setup -b CY8CPROTO-062-4343W -v v0.1.1 + +.. 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-psoc6.py`` utility, and the script will fail to retrieve the necessary firmware file. + +Updating the flasher firmware +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The evaluation PSoC6™ boards include an integrated hardware programmer tool using `KitProg `_ firmware. +Some older boards may come pre-flashed with KitProg version 2. For the MicroPython PSoC6™ port, KitProg version 3 is required, and the setup process will fail if version 2 is used. + +In case of failure during ``device-setup``, the option ``--kitprog-fw-update`` can be added to the command. +This will update the KitProg firmware to version 3 before flashing the MicroPython firmware. + +.. code-block:: bash + + $ python mpy-psoc6.py device-setup --kitprog-fw-update + +Direct binary flashing +---------------------- + +Another way to program the board is by directly providing the binary file. This can be done using the ``firmware-deploy`` command. +Specify the board and the path and name of the ``.hex`` file as follows: + +.. code-block:: bash + + $ python mpy-psoc6.py firmware-deploy -b CY8CPROTO-062-4343W -f pathtodir/mpy-psoc6_CY8CPROTO-062-4343W.hex + +Erasing the device (external) file system +----------------------------------------- + +Some PSoC6™ boards include an external flash memory which is used by the MicroPython file system. This memory will not be erased when +reprogramming or erasing MicroPython firmware via ``device-setup`` or ``firmware-deploy``. +Use the ``device-erase`` command to erase the external memory of your PSoC6™ device: + + .. code-block:: bash + + $ python mpy-psoc6.py device-erase + +.. warning:: + + This command flashes the PSoC6™ controller with a custom program to delete the external memory. Thus, MicroPython will be removed from the + microcontroller. Use any of the script commands described above to reinstall MicroPython. + +Getting the firmware +^^^^^^^^^^^^^^^^^^^^ + +The binary *.hex* files are available in the `GitHub release section `_. +All PSoC6™ firmware versions for each of the supported boards can be found there. + + + .. image:: img/gh-releases.png + :alt: GitHub MicroPython Releases + :width: 520px + + +Other installation methods +-------------------------- + +Cypress Programmer +^^^^^^^^^^^^^^^^^^ + +Alternatively, you can directly flash the firmware binary file with the `Cypress Programmer +`_ +It allows you to program the PSoC6™ 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 PSoC6™. Then, in +the upper menu, select the connected *Probe/Kit*, 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/cy-programmer.jpg + :alt: Cypress Programmer GUI + :width: 520px + +For a detailed description on how to use the Cypress Programmer tool, please consult the `Cypress +Programmer User Guide +`_. + + diff --git a/docs/psoc6/intro.rst b/docs/psoc6/intro.rst new file mode 100644 index 0000000000000..0478468cd532a --- /dev/null +++ b/docs/psoc6/intro.rst @@ -0,0 +1,119 @@ +.. _psoc6_intro: + +Getting started with MicroPython on the PSoC6™ +============================================== + +This tutorial will guide you on how to get started with running MicroPython on PSoC6™ microcontrollers. +There are only a few steps keeping you away from enjoying the Python programming experience together +with the possibilities of PSoC6™ microcontrollers. + +Let's get started! + +Requirements +------------ + +The only required hardware is: + +* A PSoC6™ board from the :ref:`Supported boards` list. +* A micro USB cable. + +Power the board +------------------ + +Connect the USB cable to your computer and the micro USB end to the board debugger. All PSoC6™ boards come with an onboard debugger required for flashing and debugging operations during development. Please refer to your board's manual. + +Install MicroPython on the board +-------------------------------- + +In your computer terminal, type the following commands and follow the instructions provided. + +First, download the ``mpy-psoc6.py`` utility script: + +.. code-block:: bash + + $ curl -s -L https://raw.githubusercontent.com/infineon/micropython/ports-psoc6-main/tools/psoc6/mpy-psoc6.py > mpy-psoc6.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 + +Finally, run the script: + +.. code-block:: bash + + $ python mpy-psoc6.py device-setup + +These commands will download and run the :ref:`device-setup ` command of the mpy-psoc6 utility and take +care of all the necessary installation steps. + +If everything went fine, your PSoC6™ board is now running MicroPython. If you run into any trouble, please let us know `here `_ :) + +Use a MicroPython IDE +------------------------- + +There are multiple ways to interact with and program your MicroPython device. You can find more information about it in this :ref:`section `. + +For this getting started guide, we recommend using the minimalist `Arduino Lab For MicropPython `_. + +Once installed, open the application and select the serial port of your PSoC6™ board by clicking on the connect icon on the menu bar: + +.. image:: img/mpy-ide-connect.jpg + :alt: Arduino IDE connect + :width: 520px + + +Interact with the MicroPython prompt +------------------------------------ + +As in Python, you can use the prompt mode. Simply start typing some Python commands: + +.. image:: img/mpy-ide-prompt.jpg + :alt: Arduino IDE prompt + :width: 520px + +Run your first script +--------------------- + +Let's try now to run a MicroPython script. As a first example, you will turn on the board LED. + +Copy the following code in the editor and click on run. + +.. code-block:: python + + from machine import Signal, Pin + pin = Pin("P13_7", Pin.OUT) # LED pin for CY8CPROTO-062-4343W + led = Signal(pin, invert=True) # Onboard LED is active low, hence invert=True + led.on() + +.. image:: img/mpy-ide-script.jpg + :alt: Arduino IDE script + :width: 520px + +The red LED on the board should now be on. + +Upload a script to your device +------------------------------ + +Click on the ``Files`` tab to transfer files between your computer and the MicroPython device. +Like with any other storage, you can upload any type of file and format as required by your application, not just *.py* program files. + +If you name a file ``main.py`` and save it in your device, it will be automatically executed during the boot of the MicroPython device. + +.. image:: img/mpy-ide-vfs.png + :alt: Arduino IDE script + :width: 520px + +You are all set now to start programming with MicroPython! + +.. warning:: + + Adding *indefinitely* blocking loops to the ``main.py`` program might block access to the storage device. It is recommended to use the ``main.py`` script only once it is stable, tested, and intended for standalone operation. + +Learn more about MicroPython in the following sections: + +* :ref:`MicroPython libraries ` . +* :ref:`Quick reference for PSoC6™ `. +* :ref:`Working with MicroPython `. diff --git a/docs/psoc6/mpy-usage.rst b/docs/psoc6/mpy-usage.rst new file mode 100644 index 0000000000000..2494d1c00c751 --- /dev/null +++ b/docs/psoc6/mpy-usage.rst @@ -0,0 +1,197 @@ +.. _psoc6_mpy_usage: + +Working with MicroPython +========================= + +With MicroPython already installed on your board, there are several flavors and tools to work with MicroPython. (:ref:`Installing MicroPython `). +In this section, we introduce some of the ways you can work with MicroPython. + +Serial prompt (REPL Mode) +------------------------- + +With MicroPython deployed on your PSoC6™ 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 PSoC6™ 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-psoc6-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 PSoC6™ 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 PSoC6™ port offers both ``FAT`` and ``LFS2`` filesystems, implemented in :ref:`MicroPython `. However, given its stability and reliability, the ``LFS2`` filesystem is selected as the default. The filesystem is located by default on the external flash, which has a capacity of 512 Mb (64 MB). + +The filesystem is mounted with the help of frozen scripts, located in the ``ports/psoc6/freeze`` directory. The default mount point of the filesystem is the ``/flash`` directory, which serves as its root. + +Given below are a few examples of various operations on the filesystem: + +Creating and reading files +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MicroPython on the PSoC6™ 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 PSoC6™ 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/psoc6/quickref.rst b/docs/psoc6/quickref.rst new file mode 100644 index 0000000000000..a674b7a235ccf --- /dev/null +++ b/docs/psoc6/quickref.rst @@ -0,0 +1,850 @@ +.. _psoc6_quickref: + +Quick reference for the PSoC6™ +============================== + +.. image:: img/cy8cproto-062-4343w.jpg + :alt: CY8CPROTO-062-4343W board + :width: 640px + +The `CY8CPROTO-062-4343W PSoC6™ Board `_. + +Below is a quick reference for PSoC6™ 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 + intro.rst + installation.rst + mpy-usage.rst + +.. note:: + + The PSoC6™ port is now a mature port and is expected any MicroPython built-in + library to be supported, but not all libraries, modules and features may have been implemented yet. + For modules relying on platform and hardware dependencies, only those listed and documented in this quick reference are supported. + + Please consider opening an `issue `_ or + `discussion `_ on GitHub for clarification on available features or to request missing features. + +General board control +--------------------- + +The MicroPython REPL is accessed via the USB serial port. Paste mode (Ctrl+E) is useful for pasting large sections of Python code into the REPL. + +This port implements most of the methods described in the :mod:`machine` module. Tab completion is useful to +find out what methods an instantiated object has. + +The :mod:`machine` module:: + + import machine + + machine.freq() # get the current frequency of the CPU + +:: + + from machine import bitstream + + timing = [1000, 7000, 5000, 2500] #timing (high_time_0, low_time_0, high_time_1, low_time_1)in ns + buf = bytearray([0xAB]) #buffer data + bitstream('P13_6', 0, timing, buf) # bitstrem buffer data with timing through pin P13_6 + +.. note:: + All timings greater than 1500 ns work and the accuracy of the timing is +/- 400 ns. + Supported timing_ns ranges below 1500 ns is [500, 1125, 800, 750]. + +Delay and timing +---------------- + +Use the :mod:`time