diff --git a/.github/workflows/compile_examples.yml b/.github/workflows/compile_examples.yml index c16c6b4f..602f047b 100644 --- a/.github/workflows/compile_examples.yml +++ b/.github/workflows/compile_examples.yml @@ -2,7 +2,8 @@ name: Compile examples on: push: - + paths-ignore: + - 'docs/**' jobs: arduino-devops: uses: Infineon/arduino-devops/.github/workflows/compile-examples.yml@latest diff --git a/.github/workflows/hil_checks.yml b/.github/workflows/hil_checks.yml index d2f0610e..ac549210 100644 --- a/.github/workflows/hil_checks.yml +++ b/.github/workflows/hil_checks.yml @@ -2,7 +2,9 @@ name: Hil Checks on: push: - + paths-ignore: + - 'docs/**' + jobs: makers-devops: uses: Infineon/makers-devops/.github/workflows/hil_checks.yml@main diff --git a/README.md b/README.md index 91eb67c9..257a237a 100644 --- a/README.md +++ b/README.md @@ -42,23 +42,7 @@ Please visit our [PSOC™ 6 products page](https://www.infineon.com/products/mic ## Contributing -We welcome community contributions! Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated** 👐. - -If you have a suggestion that would make this better, please fork the repo and create a [pull request](https://github.com/Infineon/arduino-core-psoc6/pulls). You can also simply open a feature request [issue](https://github.com/Infineon/arduino-core-psoc6/issues). - -1. [Fork](https://github.com/Infineon/arduino-core-psoc6/fork) the project -2. Create your feature branch (`git checkout -b feature/amazing-feature`) -3. Commit your changes (`git commit -sm 'folder/sub-folder: Add some amazing-feature.'`) -4. Push to the branch (`git push origin feature/amazing-feature`) -5. Open a [pull request](https://github.com/Infineon/arduino-core-psoc6/pulls) - -Before submitting a pull request, please check the [code of conduct](https://github.com/Infineon/arduino-core-psoc6/blob/main/CODE_OF_CONDUCT.md) and [code conventions](https://github.com/Infineon/arduino-core-psoc6/blob/main/CODE_CONVENTIONS.md) for the PSOC™ 6 for Arduino project. Thank you for following these guidelines. - -Don't forget to give the project a star :star:! Thanks again! - -### Important Note - -Significant contributions should be aligned with the project team in advance. +We welcome contributions to the Arduino Core for Infineon's PSOC™ 6 microcontrollers. If you are interested in contributing, please follow our [contributing guidelines](https://arduino-core-psoc6.readthedocs.io/en/latest/contributing.html). ### Top Contributors diff --git a/docs/arduino-deviations.rst b/docs/arduino-deviations.rst index c46d1b57..ea171f3f 100644 --- a/docs/arduino-deviations.rst +++ b/docs/arduino-deviations.rst @@ -1,7 +1,7 @@ Arduino API Deviations ====================== -This section documents the differences between the standard Arduino Language Reference and `PSOC6-for-Arduino`. +This section documents the differences between the standard `Arduino Language Reference `_ and the Arduino core for PSOC™ 6. Digital IO ---------- @@ -42,7 +42,7 @@ Depending on the bits parameter, the function modifies the resolution of the ADC void analogReference(uint8_t mode) -Only the `DEFAULT` mode is supported and uses the internal reference voltage of the PSOC6 device, which is typically 3.3V. +Only the `DEFAULT` mode is supported and uses the internal reference voltage of the PSOC™ 6 device, which is typically 3.3V. .. code-block:: cpp @@ -78,14 +78,14 @@ Advanced IO void tone(uint8_t _pin, unsigned int frequency, unsigned long duration) -The `tone()` function in the `PSOC6-for-Arduino` core leverages the PWM (Pulse Width Modulation) peripheral to generate square wave signals at specific frequencies. +The `tone()` function in the PSOC™ 6 core leverages the PWM (Pulse Width Modulation) peripheral to generate square wave signals at specific frequencies. Do not call `pinMode()` on the pin prior to using the `tone()` function. The `tone()` function automatically configures the pin for output mode and sets it up internally. Calling `pinMode()` beforehand may result in unexpected behavior or conflicts with the PWM peripheral. SPI ---------- -The `PSOC6-for-Arduino` core does not support the following Arduino APIs: +The PSOC™ 6 core does not support the following Arduino APIs: .. code-block:: cpp @@ -112,6 +112,6 @@ Random Number Generation void randomSeed(unsigned long seed) -The function is optional. Random seed initialization is not required because the `PSOC6-for-Arduino` core uses the hardware-based True Random Number Generator (TRNG) for generating random numbers. +The function is optional. Random seed initialization is not required because the PSOC™ 6 core uses the hardware-based True Random Number Generator (TRNG) for generating random numbers. Calling `randomSeed(seed)` does nothing but is provided for compatibility with the standard Arduino API. diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 00000000..5964dbb5 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,26 @@ +Contributing +============= + +We welcome community contributions! Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated** 👐. + +If you have a suggestion that would make this better, please fork the repo and create a pull request for your changes as described step by step below. You can also simply open a feature request `issue `_. + +1. `Fork `_ this repository +2. Create your feature branch (``git checkout -b feature/amazing-feature``) +3. Commit your changes (``git commit -sm 'folder/sub-folder: Add some amazing-feature.'``) +4. Push to the branch (``git push origin feature/amazing-feature``) +5. Open a `pull request `_ + +Before submitting a pull request, please check the `code of conduct `_ and `code conventions `_ for the PSOC™ 6 for Arduino project. + +.. important:: + Significant contributions should be aligned with the project team in advance. Please open an issue to discuss your ideas before starting work on a large feature or change. + This helps ensure that your contributions align with the project's goals and standards. + +Additionally, the following sections might be helpful for developing and testing your contributions: + + - :doc:`env-setup` + - :doc:`run-tests` + - :doc:`metafiles-naming` + +Thank you for following these guidelines! \ No newline at end of file diff --git a/docs/development-instructions.rst b/docs/env-setup.rst similarity index 71% rename from docs/development-instructions.rst rename to docs/env-setup.rst index 5e877a88..fedcfffb 100644 --- a/docs/development-instructions.rst +++ b/docs/env-setup.rst @@ -1,28 +1,5 @@ -Development Instructions -========================= - -.. warning:: - - This is a work in progress version of the Arduino Core for PSOC™ 6 documentation. - While this warning notice is present, the documentation is NOT ready for public usage. - -.. - TODOS: - - Contribution guidelines (move here from Contributing.md) - - Code conventions - - .... - - Tools installation: - - uncrustify - - python ? - - pip ? - - pre-commit hook? - - spellchecker - - ... - -.. _env_dev_setup: - Environment Setup ------------------- +================= .. note:: | The development environment setup is (currently) only supported on **Linux** |:penguin:|. @@ -31,31 +8,27 @@ Environment Setup 0. Obviously |:neutral_face:|, install `Arduino IDE (2.0 or higher) `_ or `Arduino CLI (1.0.0 or higher) `_. -1. Install the :ref:`Infineon PSOC™ 6 microcontroller ` boards package. +1. Install the PSOC™ 6 Arduino core as described :ref:`here `. -2. Locate in your computer where the Arduino15 packages are installed. Usually: +2. Locate, where the Arduino15 packages are installed on your computer. Usually: :: ~/.arduino15/ - .. TODO: I would postpone the Windows part, as we won´t have all the dev tools available there - c:/Users/%USERNAME%/AppData/local/Arduino15 -3. From the Arduino installation location, change directories +3. Starting from the Arduino installation location, change directories: :: cd packages/infineon/hardware/psoc6 -4. Remove any existing installed "x.y.z" version of the core +4. Remove any existing installed "x.y.z" version of the core: :: rm -rf x.y.z - .. This won´t be needed if the package is NOT installed using the .json package index installation. - 5. | Clone this repo in a folder with a semver version name. A orderly practice could be to bump the existing version, and add a suffix to indicate the feature or bugfix. | For example, from installed ``1.1.0`` to ``1.2.0-new-feature``: @@ -63,7 +36,7 @@ Environment Setup git clone https://github.com/Infineon/arduino-core-psoc6.git 1.2.0-new-feature - You can check if the correct version is installed by running + You can check if the correct version is installed by running: :: @@ -91,12 +64,12 @@ Environment Setup .. _dev_manual_setup: -Manual setup +Manual Setup ------------ -| This section describes the manual setup of the development environment for the Infineon PSOC™ 6 microcontroller core. +| This section describes the manual setup of the development environment for the Arduino core for PSOC™ 6. | You can consider this a detailed explanation of the development setup process. -| Unless you want to know the details |:detective:|, it is easier and recommended to use the automated setup script |:scroll:| in :ref:`Environment setup `. +| Unless you want to know the details |:detective:|, it is easier and recommended to use the automated setup script |:scroll:| in :doc:`env-setup`. Installing the ArduinoCore-API ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -123,20 +96,20 @@ Installing the ArduinoCore-API cd packages/infineon/hardware/psoc6/ -3. Initialize the ArduinoCore-API submodule +3. Initialize the ArduinoCore-API submodule: :: git submodule update --init --recursive -4. Change directories +4. Change directories: :: cd cores/psoc6 -5. Copy or symlink the ``api`` folder from the ArduinoCore-API submodule +5. Copy or symlink the ``api`` folder from the ArduinoCore-API submodule: .. tabs:: diff --git a/docs/hw-platforms.rst b/docs/hw-platforms.rst index 5e03e3c4..a9931804 100644 --- a/docs/hw-platforms.rst +++ b/docs/hw-platforms.rst @@ -1,11 +1,6 @@ Supported Boards ================= -.. warning:: - - This is a work in progress version of the Arduino Core for PSOC™ 6 documentation. - While this warning notice is present, the documentation is NOT ready for public usage. - List of supported PSOC™ 6 boards: .. list-table:: diff --git a/docs/index.rst b/docs/index.rst index 052adc7f..467d825e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,11 +2,6 @@ Arduino Core for PSOC™ 6 ************************* -.. warning:: - - This is a work in progress version of the Arduino Core for PSOC™ 6 documentation. - While this warning notice is present, the documentation is NOT ready for public usage. - Welcome to the Arduino Core for Infineon's PSOC™ 6 microcontrollers. .. image:: img/board_CY8CKIT-062S2-AI.png @@ -19,10 +14,17 @@ Welcome to the Arduino Core for Infineon's PSOC™ 6 microcontrollers. Introduction installation-instructions hw-platforms - development-instructions arduino-deviations - run-tests - supported-features + +.. toctree:: + :maxdepth: 1 + :caption: CONTRIBUTING + :hidden: + + Introduction + env-setup + run-tests + metafiles-naming License ======= diff --git a/docs/installation-instructions.rst b/docs/installation-instructions.rst index e19f981f..8c271582 100644 --- a/docs/installation-instructions.rst +++ b/docs/installation-instructions.rst @@ -3,10 +3,6 @@ Installation Instructions ========================= -.. warning:: - - This is a work in progress version of the Arduino Core for PSOC™ 6 documentation. - While this warning notice is present, the documentation is NOT ready for public usage. Integration in Arduino IDE -------------------------- diff --git a/docs/metafiles-naming.rst b/docs/metafiles-naming.rst new file mode 100644 index 00000000..db239c19 --- /dev/null +++ b/docs/metafiles-naming.rst @@ -0,0 +1,128 @@ +Metafiles Naming Conventions +============================= + + +This section describes the naming conventions for metafiles used in the Arduino Core for PSOC™ 6. +When adding new variables to these metafiles, follow these conventions to maintain consistency and clarity. + + +.. note:: + + Most variables are already defined and likely will not require modification soon. They are documented here to clarify their usage and the rationale behind their values. + +The conventions apply to the following files: + +- ``boards.txt`` +- ``platform.txt`` +- ``package/package_psoc6_index.template.json`` + +boards.txt +----------- + +.. list-table:: + :header-rows: 1 + :widths: 20 30 30 30 + + * - Parameter + - Value + - Description + - Example + * - ```` + - | **OPN (Original Part number)** + | of the board converted to **snake_case** + - | This defines the ``board_unique_id`` field + | of the `Fully Qualified Board Name (FQBN) `_ + | used in arduino-cli. + - ``cy8ckit_062s2_ai`` + * - ``.name`` + - | **OPN (Original Part number)** of + | the board + - | Human readable friendly Board Name + | shown in Arduino IDE menus. + - ``CY8CKIT-062S2-AI`` + +platform.txt +------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 30 30 + + * - Parameter + - Value + - Description + * - ``name=`` + - ``Infineon PSOC Boards`` + - | The **name** will be shown as the Arduino IDE's Board + | menu section title or the Name field of arduino-cli core + | list's output for the platform. + * - ``version=`` + - | Empty. + | Automatically set during + | release core packaging. + - | The **version** is currently unused, it is reserved for + | future use (probably together with the Boards Manager + | to handle dependencies on cores). + +package_psoc6_index.json +------------------------ + +.. list-table:: + :header-rows: 1 + :widths: 20 40 30 + + * - Parameter + - Value + - Description + * - JSON file name + - ``package_psoc6_index.json`` + - | `Specification `_ requirement: + | package__index.json + * - ``name`` + - ``infineon`` + - | This defines the vendor directory `name` of + | the installed package in the Arduino installation + | path. + | It also defines the **vendor** field of the + | `Fully Qualified Board Name (FQBN) `_. + * - ``maintainer`` + - ``Infineon Technologies AG`` + - | The extended name of the vendor that is displayed + | on the Arduino IDE Boards Manager GUI + * - ``websiteURL`` + - `Link to docs `_ + - | The URL to the vendor's website, appears + | on the Arduino IDE Boards Manager as "More info" link. + * - ``email`` + - ``maker@infineon.com`` + - Contact email of the maintainer + * - ``platforms.name`` + - ``Infineon PSOC Boards`` + - | The extended name of the platform that + | is displayed on the Boards Manager GUI. + * - ``platforms.architecture`` + - ``psoc6`` + - | It defines the **architecture** field of the + | `Fully Qualified Board Name (FQBN) `_. + * - ``platforms.category`` + - ``Contributed`` + - | This field is reserved. Third-party + | cores must set it to "Contributed." + * - ``platforms.help.online`` + - Empty + - | Used only in legacy Arduino IDE 1.x. + | Not used in Arduino IDE 2.x. + * - ``platforms.boards.name`` + - | **OPN (Original Part number)** + | of the board + - | The list of supported boards shown in + | the Arduino IDE's Boards Manager GUI + | core entry. + * - ``platforms.toolsDependencies.packager`` + - ``infineon`` + - | No specification. Use the same name + | as the vendor. + * - ``platforms.tools`` + - **kebab-case** naming + - | No additional requirements other + | than the `package index specification `_. \ No newline at end of file diff --git a/docs/run-tests.rst b/docs/run-tests.rst index db59868d..fe4bf247 100644 --- a/docs/run-tests.rst +++ b/docs/run-tests.rst @@ -1,11 +1,6 @@ Running Hardware Tests ========================= -.. warning:: - - This is a work in progress version of the Arduino Core for PSOC™ 6 documentation. - While this warning notice is present, the documentation is NOT ready for public usage. - This document provides instructions on running tests on hardware using the Unity framework. These tests call the Arduino APIs to execute and verify functionality. @@ -18,13 +13,14 @@ Test Environment Setup | The development environment setup is (currently) only supported on **Linux** |:penguin:|. | As many tools and scripts are not cross-platform, some of them will not directly work on Windows |:abcd:| or macOS |:apple:|. -| To successfully run the tests, ensure that your development environment is properly configured. -| See the section on :ref:`Environment Setup ` +.. important:: + | To successfully run the tests, ensure that your development environment is properly configured. + | See the section on :ref:`Environment Setup `. Board Setup ------------- -1. Connect your PSOC™ 6 board (e.g., CY8CKIT-062S2-AI) to your computer |:computer:| via USB. +1. Connect your PSOC™ 6 board (e.g. CY8CKIT-062S2-AI) to your computer |:computer:| via USB. 2. Make the board-to-board pin connections as described below: @@ -36,9 +32,9 @@ Board Setup Executing Test Cases Using `make` --------------------------------- -Makefile relies on arduino-cli for compiling, uploading, and monitoring. Unity is included as a library. +The Makefile relies on arduino-cli for compiling, uploading, and monitoring. Unity is included as a library. -1. Change directories +1. Change directories: :: @@ -46,9 +42,9 @@ Makefile relies on arduino-cli for compiling, uploading, and monitoring. Unity i 2. Use the `make` command to run a specific test. For example, to run a digital I/O test: - ``` - make FQBN= `FQBN` PORT= `PORT` test_digitalio_single monitor - ``` + .. code-block:: bash + + make FQBN= `FQBN` PORT= `PORT` test_digitalio_single monitor - `FQBN`: select the connected board (e.g., `infineon:psoc6:cy8ckit_062s2_a`). - `PORT`: set the appropriate serial port (e.g., `/dev/ttyUSB0`). @@ -56,9 +52,9 @@ Makefile relies on arduino-cli for compiling, uploading, and monitoring. Unity i 3. Display usage information about the available make targets: - - ``` - make help - ``` + + .. code-block:: bash + + make help -4. Start testing other features |:tools:| ! +4. Start testing other features |:tools:| ! \ No newline at end of file diff --git a/docs/supported-features.rst b/docs/supported-features.rst deleted file mode 100644 index a7591e30..00000000 --- a/docs/supported-features.rst +++ /dev/null @@ -1,89 +0,0 @@ -Supported Features -=================== - -.. warning:: - - This is a work in progress version of the Arduino Core for PSOC™ 6 documentation. - While this warning notice is present, the documentation is NOT ready for public usage. - - -This section indicates implementation status of Arduino functions and libraries. - - -Built-in Libraries -^^^^^^^^^^^^^^^^^^^ - -.. list-table:: - :header-rows: 1 - - * - Features - - Description - - Status - * - Serial/UART - - | `Serial `_ - - ✅ Implemented - * - Stream - - | `Stream `_ - - ✅ Implemented - * - Digital I/O - - | `digitalRead `_ - | `digitalWrite `_ - | `pinMode `_ - - ✅ Implemented - * - Time - - | `delay `_ - | `delayMicroseconds `_ - | `micros `_ - | `millis `_ - - ✅ Implemented - * - WiFi Network - - | `WiFi Network `_ - - ✅ Implemented - * - WiFi Server - - | `WiFiServer `_ - - ✅ Implemented (except SSL) - * - WiFi Client - - | `WiFiClient `_ - - ✅ Implemented (except SSL) - * - WiFi UDP - - | `WiFiUDP `_ - - ✅ Implemented (except Multicast) - * - Wire/I2C - - | `Wire `_ - - ✅ Implemented - * - Interrupts - - | `interrupts `_ - | `noInterrupts `_ - - ✅ Implemented - * - External Interrupts - - | `attachInterrupt `_ - | `detachInterrupt `_ - | `digitalPinToInterrupt `_ - - ✅ Implemented - * - SPI - - | `SPI `_ - - ✅ Implemented - * - Analog I/O - - | `analogRead `_ - | `analogReadResolution `_ - | `analogReference `_ - | `analogWrite `_ - | `analogWriteResolution `_ - - ✅ Implemented - * - Advanced I/O - - | `noTone `_ - | `pulseIn `_ - | `pulseInLong `_ - | `shiftIn `_ - | `shiftOut `_ - | `tone `_ - - ✅ Implemented - * - Random - - | `random `_ - | `randomSeed `_ - - ✅ Implemented - - -.. note:: - - The features that are currently not implemented are planned to be implemented soon. Stay tuned for updates in future releases.