diff --git a/docs/conf.py b/docs/conf.py index b60dd089b914..a56eb588342b 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -51,7 +51,10 @@ 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', +<<<<<<< HEAD 'sphinxcontrib.jquery', +======= +>>>>>>> docs: Added docs and docs conf for PSoC6 port. 'sphinx_tabs.tabs', ] diff --git a/docs/psoc6/feature_list.rst b/docs/psoc6/feature_list.rst new file mode 100644 index 000000000000..9ed7865f7811 --- /dev/null +++ b/docs/psoc6/feature_list.rst @@ -0,0 +1,155 @@ +.. _psoc6_feature_list: + +Supported features +================== +The PSoC6 port is currently configured to configuration level ``MICROPY_CONFIG_ROM_LEVEL_FULL_FEATURES`` with a few additional settings applied, thus enabling most standard modules as listed in the following. + +Enabled modules +--------------- +* Python standard modules and libraries + * cmath + * gc + * math + * uarray + * uasyncio + * ubinascii + * ucollections + * uerrno + * uhashlib + * uheapq + * uio + * ujson + * uos + * urandom + * ure + * uselect + * usocket + * ussl + * ustruct + * usys + * utime + * uzlib + + +* Micropython specific modules and libraries + * framebuf + * machine + * Pin + * I2C + * RTC + * SoftI2C +<<<<<<< HEAD + * SPI + * SoftSPI + * PWM + * Timer + * ADC + * ADCBlock + +======= +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + * micropython + * ucryptolib + * uctypes + * network + + +* Port specific modules and micro-libraries + * psoc6 (flash support) + + +Not yet enabled +--------------- +* Python standard modules and libraries + * _thread + +* Micropython specific modules and libraries + * btree + * ubluetooth + + +Table :ref:`configuration details ` below lists specific settings deviating from the configuration as per config level as well as functionality not yet implemented: + +.. _table_mpy_configuration: + ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| Module | Details | ++=================+======================================================================================================================+ +| gc | Option ``MICROPY_ENABLE_GC`` enabled. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| uhashlib | Options ``MICROPY_PY_UHASHLIB_MD5``, ``MICROPY_PY_UHASHLIB_SHA1``, ``MICROPY_PY_UHASHLIB_SHA256`` enabled. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| uos | Support for LFS2 and FAT, LFS2 enabled by default. FS mounted on external flash at "/flash". | +| | | +| | Options ``MICROPY_PY_OS_DUPTERM``, ``MICROPY_PY_UOS_GETENV_PUTENV_UNSETENV``, ``MICROPY_PY_UOS_INCLUDEFILE``, | +| | ``MICROPY_PY_UOS_SYSTEM``, ``MICROPY_PY_UOS_UNAME``, ``MICROPY_VFS_LFS2`` enabled. | +| | | +| | Function *urandom()* not yet implemented. Requires implementing *mp_uos_urandom()* and setting option | +| | ``MICROPY_PY_UOS_URANDOM``. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| urandom | Function *seed()* not yet implemented. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| ure | Options ``MICROPY_PY_URE_DEBUG``, ``MICROPY_PY_URE_MATCH_GROUPS``, ``MICROPY_PY_URE_MATCH_SPAN_START_END`` enabled. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| usocket | Options ``MICROPY_PY_USOCKET`` enabled. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| ussl | Options ``MICROPY_PY_USSL`` enabled. Has 2 failing tests. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| usys | Options ``MICROPY_PY_SYS_EXC_INFO`` enabled. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| utime | Enabled through HAL functions based on machine.RTC module. Option ``MICROPY_PY_UTIME_MP_HAL`` enabled. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| ucryptolib | Options ``MICROPY_PY_UCRYPTOLIB``, ``MICROPY_PY_UCRYPTOLIB_CTR``, ``MICROPY_PY_UCRYPTOLIB_CONSTS`` enabled. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| machine | Functions not yet implemented: *lightsleep()*, *deepsleep()*, *wake_reason()*, *time_pulse_us()*, *rng()*. | +| | | +| | Constants not yet implemented : *WLAN_WAKE*, *PIN_WAKE*, *RTC_WAKE*, *IDLE*, *SLEEP*, *DEEPSLEEP*. | +| | | +| | Submodules/classes not yet implemented: *ADC*, *bitstream*, *mem*, *Signal*, *SD*, *SDCard*, *SoftSPI*, *SPI*, | +| | *Timer*, *UART*, *WDT*. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| machine.Pin | Functions not yet implemented: *drive()*, *irq()*, *mode()*, *pull()*. | +| | | +| | Constants not yet implemented: *ALT*, *ALT_OPEN_DRAIN*, *PULL_UP*, *PULL_DOWN*, *PULL_HOLD*, *LOW_POWER*, | +| | *MED_POWER*, *HIGH_POWER*, *IRQ_FALLING*, *IRQ_RISING*, *IRQ_LOW_LEVEL*, *IRQ_HIGH_LEVEL*. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| machine.I2C | Option ``MICROPY_PY_MACHINE_I2C`` enabled. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| machine.RTC | Functions not yet implemented: *alarm()*, *alarm_left()*, *cancel()*, *irq()*. | +| | | +| | Constants not yet implemented: *ALARM0*. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| machine.SoftI2C | Option ``MICROPY_PY_MACHINE_SOFTI2C`` enabled. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +<<<<<<< HEAD +| machine.PWM | option ``MICROPY_PY_MACHINE_PWM`` & ``MICROPY_PY_MACHINE_PWM_INCLUDEFILE`` enabled | +| | | +| | option ``MICROPY_PY_MACHINE_PWM_DUTY`` is not enabled. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| machine.SoftSPI | Option ``MICROPY_PY_MACHINE_SOFTSPI`` enabled. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| machine.ADC | ADC.init() not implemented. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| machine.ADCBlock| All functions implemented. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| machine.Timer | mode = Timer.PERIODIC is not supported | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| machine.SPI | Option ``MICROPY_PY_MACHINE_SPI``, ``MICROPY_PY_MACHINE_SPI_MSB`` , ``MICROPY_PY_MACHINE_SPI_MSB`` enabled. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +======= +>>>>>>> docs: Added docs and docs conf for PSoC6 port. +| psoc6 | Option to enable the external instead of the internal flash: ``MICROPY_ENABLE_EXT_QSPI_FLASH``. | +| | | +| | Option to enable the port specific debug logger: ``MICROPY_LOGGER_DEBUG``. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| network | Option ``MICROPY_NETWORK`` enabled. | +| | | +| | Functions not yet implemented: *phy_mode()*. | +| | | +| | Classes not yet implemented: *LAN*. | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ +| network.WLAN | Mode not yet implemented: *STA_AP*. | +| | | +| | Functions not yet implemented: *config*. | +| | | ++-----------------+----------------------------------------------------------------------------------------------------------------------+ \ No newline at end of file diff --git a/docs/psoc6/installation.rst b/docs/psoc6/installation.rst new file mode 100644 index 000000000000..966bf8c397e6 --- /dev/null +++ b/docs/psoc6/installation.rst @@ -0,0 +1,278 @@ +.. _psoc6_mpy_install: + +Installing MicroPython +====================== + +To support the MicroPython PSoC6™ port installation the ``mpy-psoc6`` utility script is provided for Windows and +Linux. +You can easily download from your OS terminal with the following command: + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: bash + +<<<<<<< HEAD + curl -s -L https://raw.githubusercontent.com/infineon/micropython/ports-psoc6-main/tools/psoc6/mpy-psoc6.sh > mpy-psoc6.sh +======= + curl -s -L https://raw.githubusercontent.com/jaenrig-ifx/micropython/ports/psoc6/tools/psoc6/mpy-psoc6.sh > mpy-psoc6.sh +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + + Add execution rights to the script: + + .. code-block:: bash + + chmod +x mpy-psoc6.sh + + .. group-tab:: Windows + + Download the mpy-psoc6 utility script: + + .. code-block:: bash + +<<<<<<< HEAD + curl.exe -s -L https://raw.githubusercontent.com/infineon/micropython/ports-psoc6-main/tools/psoc6/mpy-psoc6.cmd > mpy-psoc6.cmd + + +Find all the available commands and options by running the script with the command help: +======= + curl.exe -s -L https://raw.githubusercontent.com/jaenrig-ifx/micropython/ports/psoc6/tools/psoc6/mpy-psoc6.cmd > mpy-psoc6.cmd + + +Find all the available commands an options by running the script with the command help: +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: bash + + ./mpy-psoc6.sh help + + .. group-tab:: Windows + + .. code-block:: bash + +<<<<<<< HEAD + mpy-psoc6.cmd help +======= + ./mpy-psoc6.sh help +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + +.. _psoc6_quick_start: + +Quick Start +------------ + +<<<<<<< HEAD +With the ``mpy-psoc6`` utility script downloaded, the fastest way to get you up and running with +======= +With the ``mpy-psoc6`` utility script donwloaded, the fastest way to get you up and running with +>>>>>>> docs: Added docs and docs conf for PSoC6 port. +micropython is to run the ``quick-start`` command of the script: + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: bash + + ./mpy-psoc6.sh quick-start + + .. group-tab:: Windows + + .. code-block:: bash + + mpy-psoc6.cmd quick-start + +The command will take care of the following: + +* Install all required software to work with MicroPython +* Deploy the latest version of MicroPython PSoC6 firmware on your board +* Launch Arduino Lab MicroPython IDE + +This command is supporting the getting started tutorial for the first time. Once you get familiar +<<<<<<< HEAD +with MicroPython and its environment, the ``device-setup`` command will be more appropriate to +install MicroPython on PSoC6™ boards, and upgrade your device with the latest firmware. +======= +with MicroPython and its environment, the ``device-setup`` command will be more appropiate to +install MicroPython on PSoC6™ boards, and upgrade your device with the lastest firmware. +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + +Device setup +------------- + +In order to setup MicroPython in a PSoC6™ board, the ``device-setup`` command of the ``mpy-psoc6`` +can be executed. Follow the instructions to select the target PSoC6™ board, and deploy the latest +MicropPython firmware version: + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: bash + +<<<<<<< HEAD + ./mpy-psoc6.sh device-setup +======= + ./mpy-psoc6.sh setup-device +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + + .. group-tab:: Windows + + .. code-block:: bash + +<<<<<<< HEAD + mpy-psoc6.cmd device-setup +======= + mpy-psoc6.cmd setup-device +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + + +You can run any command any time 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 select board +* Deploy the latest version of MicroPython firmware on your board + +Install a previous version +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +<<<<<<< HEAD +If you want to setup the device with a previous firmware version, you can check the list of available release in the `GitHub release section `_. +======= +If you want to setup the device with a previous firmware version, you can check the list of available release in the `GitHub release section `_. +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + +The ``device-setup`` command can as well assist you with this process. In this case the board and the desired +version need to be passed as arguments. + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: bash + +<<<<<<< HEAD + ./mpy-psoc6.sh device-setup CY8CPROTO-062-4343W v0.1.1 +======= + ./mpy-psoc6.sh setup-device CY8CPROTO-062-4343W v0.1.1 +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + + .. group-tab:: Windows + + .. code-block:: bash + +<<<<<<< HEAD + mpy-psoc6.cmd device-setup CY8CPROTO-062-4343W v0.1.1 +======= + mpy-psoc6.cmd setup-device CY8CPROTO-062-4343W v0.1.1 +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + +.. warning:: + + Be sure to provide the board name as shown in the ``device-setup`` command when run in interactive mode. + Equally, provide a valid tag existing in the release section with the format *v.x.y.z*. + No fail safe mechanisms or error verifications are (yet) implemented on the ``mpy-psoc6`` utility, and the script will fail to retrieve the necessary firmware file. + +Direct binary flashing +^^^^^^^^^^^^^^^^^^^^^^ + +Another alternative to program the board is to directly provide the binary file. The ``firmware-deploy`` command is providing this option. +This commands is skipping all the tools download and installation, neither download the MicoPython firmware. +Therefore, it requires that `openocd `_ is already installed and available in the system path. +In exchange, it will be faster for batch flashing, or any situation where subsequent binary flashing needs to be performed. + +The board needs to be specified, and the path and name of the ``.hex`` file: + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: bash + + ./mpy-psoc6.sh firmware-deploy CY8CPROTO-062-4343W pathtodir/mpy-psoc6_CY8CPROTO-062-4343W.hex + + .. group-tab:: Windows + + .. code-block:: bash + + mpy-psoc6.cmd firmware-deploy CY8CPROTO-062-4343W pathtodir/mpy-psoc6_CY8CPROTO-062-4343W.hex + +<<<<<<< HEAD +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 of the external memory of your PSoC6™ device: + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: bash + + ./mpy-psoc6.sh device-erase + + .. group-tab:: Windows + + .. code-block:: bash + + mpy-psoc6.cmd 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. +======= +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + +Getting the firmware +^^^^^^^^^^^^^^^^^^^^ + +<<<<<<< HEAD +The binary *.hex* files are available in the `GitHub release section `_. +======= +The binary *.hex* files are available in the `GitHub release section `_. +>>>>>>> docs: Added docs and docs conf for PSoC6 port. +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 use directly flash the firmware binary file with the `Cypress Programmer +`_ +It allows to program the PSoC6™ microcontrollers family in a few clicks from your Windows, +Linux or Mac OS machine. +Follow the instructions on 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 inform 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 000000000000..98ed9e995629 --- /dev/null +++ b/docs/psoc6/intro.rst @@ -0,0 +1,129 @@ +.. _psoc6_intro: + +Getting started with MicroPython on the PSoC6™ +============================================== + +This tutorial will guide you to get started with running MicroPython on the PSoC6™ microcontrollers. +There are only a few step 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: + +* PSoC6™ board of the :ref:`Supported boards` list. +* A microUSB cable. + +Power the board +------------------ + +Connect the USB cable to your computer and the micro USB to the board debugger. All the PSoC6™ boards +come with a on-board debugger required for flashing/debugging operations during development. Please refer to the +corresponding board manual of your board. + +Install MicroPython +---------------------- + +In your computer terminal, type the following commands and follow the instructions: + +.. tabs:: + + .. group-tab:: Linux + + Download the mpy-psoc6 utility script: + + .. code-block:: bash + +<<<<<<< HEAD + curl -s -L https://raw.githubusercontent.com/infineon/micropython/ports-psoc6-main/tools/psoc6/mpy-psoc6.sh > mpy-psoc6.sh +======= + curl -s -L https://raw.githubusercontent.com/jaenrig-ifx/micropython/ports/psoc6/tools/psoc6/mpy-psoc6.sh > mpy-psoc6.sh +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + + Add execution rights to the script and run the script: + + .. code-block:: bash + + chmod +x mpy-psoc6.sh + ./mpy-psoc6.sh quick-start + + .. group-tab:: Windows + + Download the mpy-psoc6 utility script: + + .. code-block:: bash + +<<<<<<< HEAD + curl.exe -s -L https://raw.githubusercontent.com/infineon/micropython/ports-psoc6-main/tools/psoc6/mpy-psoc6.cmd > mpy-psoc6.cmd +======= + curl.exe -s -L https://raw.githubusercontent.com/jaenrig-ifx/micropython/ports/psoc6/tools/psoc6/mpy-psoc6.cmd > mpy-psoc6.cmd +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + + And run the script: + + .. code-block:: bash + + mpy-psoc6.cmd quick-start + +These commands will download and run the :ref:`quick-start ` 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 and Arduino IDE for +<<<<<<< HEAD +Micropython is now started. If you run into any trouble, please let us know `here `_ :) +======= +Micropython is now started. If you run into any trouble, please let us know `here `_ :) +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + +Select your 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 Pin + + p1 = Pin("P13_7") # LED pin for CY8CPROT-062-4343W + p1.init(Pin.OUT) + p1.on() + +.. image:: img/mpy-ide-script.jpg + :alt: Arduino IDE script + :width: 520px + +The red LED in the board should be now on :D + +Upload a script to your device +------------------------------ + +*Feature unavailable. Placeholder. To be completed.* + +You are all set now to start programming with MicroPython! + +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 000000000000..d6cc0699eccf --- /dev/null +++ b/docs/psoc6/mpy-usage.rst @@ -0,0 +1,190 @@ +.. _psoc6_mpy_usage: + +Working with MicroPython +========================= + +With MicroPython already installed in 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 +<<<<<<< HEAD +code and run commands. This is equivalent to running the *python* command (without passing a script) in the command line terminal of your machine. +======= +code and run commands. This is equivalent to running the *python* commmand (without passing a script) in the command line terminal of your machine. +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + +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 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 +---------------- + +In order to implement more elaborated 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 in your MicroPython device, as well as handling the files 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 the information it 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 line will be executed in the controller. Any output like print messages in your application or +exceptions will be send 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 in different files, and use import to make use of the provided features +in other scripts. +To run a script in the device at boot, there are two scripts that 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 benefit in execution. + +A more advanced and efficient mode of script execution is also available wherein, the scripts to be executed are :ref:`frozen ` as a 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 +--------------------------- + +<<<<<<< HEAD +The PSoC6™ port offers both the ``FAT`` and ``LFS2`` filesystems, implemented in :ref:`MicroPython `. However, given its stability and reliability, the ``LFS2`` filesystem is selected as default. In addition, the filesystem is located, by default on the External Flash which has a capacity of 512 Mb (64 MB). +======= +The PSoC6™ port offers both the ``FAT`` and ``LFS2`` filesystems, implemented in :ref:`MicroPython `. However, given its stabilty and reliability, the ``LFS2`` filesystem is selected as default. In addition, the filesystem is located, by default on the External Flash which has a capacity of 512 Mb (64 MB). +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + +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 on 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 its contents overwritten, otherwise. + +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 file and more +~~~~~~~~~~~~~~~~~~~~~ + +The ``os`` module can be used for further control over the filesystem. First, +the ``os`` module need 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, there are two files that 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 using the command shown below: + +.. code-block:: bash + + $ mpremote.py cp /main.py :/flash/main.py + + +Similarly, to transfer files from the MicroPython filesystem to the host filesystem, the arguments have to be flipped, as shown: + +.. code-block:: bash + + $ mpremote.py cp :/flash/main.py /main.py + + +The tool can also be used to execute scripts on the target board, without utilizing the target's filesystem. In this case, the script is sent to the target over the UART interface and is executed on the REPL, where it is interpreted. Due to the bottleneck of the transmission, execution times may be longer. An example is given below: + +.. code-block:: bash + + $ mpremote.py run /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, file operations can be carried out, such as creating a new file, adding contents to it and then saving it to the filesystem on the MicroPython device, with a given name. + +.. 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 000000000000..7a30200460a0 --- /dev/null +++ b/docs/psoc6/quickref.rst @@ -0,0 +1,592 @@ +.. _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 + feature_list.rst + +.. warning:: + + The PSoC6™ port is still in an early stage of development. It is expected any MicroPython built-in + library to be supported, but not all libraries, modules and features have been implemented yet. + For those modules relying on platform and hardware dependencies, only the listed and documented in this + quick reference are certainyly supported. + Check :ref:`here ` for a complete list of currently enabled or implemented modules as well as not yet implemented functionality. + +<<<<<<< HEAD +<<<<<<< HEAD + Please, consider opening an `issue `_ or + `discussion `_ on GitHub for any clarification +======= + Please, consider opening an `issue `_ or + `discussion `_ on GitHub for any clarification +>>>>>>> 57a502306 (docs: Added docs and docs conf for PSoC6 port.) +======= + Please, consider opening an `issue `_ or + `discussion `_ on GitHub for any clarification +>>>>>>> docs: Added docs and docs conf for PSoC6 port. + required on available features or requests for missing ones. + +General board control +--------------------- + +The MicroPython REPL is accessed via the USB serial port. Paste mode (ctrl-E) is useful to paste a +large slab 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 + +.. + TODO: add more machine module examples when implemented. + machine.freq(240000000) # set the CPU frequency to 240 MHz + +.. + TODO: add ``psoc6`` module when implemented. + + +Delay and timing +---------------- + +Use the :mod:`time