Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added the example guideline and template #7665

Merged
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 87 additions & 3 deletions docs/source/contributing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Before sending us a Pull Request, please consider this:
* Are comments and documentation written in clear English, with no spelling or grammar errors?

* Example contributions are also welcome.
* If you are contributing by adding a new example, please use the `Arduino style guide`_.
* If you are contributing by adding a new example, please use the `Arduino style guide`_ and the example guideline below.
pedrominatel marked this conversation as resolved.
Show resolved Hide resolved

* If the contribution contains multiple commits, are they grouped together into logical changes (one major change per pull request)? Are any commits with names like "fixed typo" `squashed into previous commits <https://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit/>`_?

Expand All @@ -39,11 +39,95 @@ Once the Pull Request is ready to merge, it will first be merged into our intern

If this process passes, it will be merged onto the public github repository.

Example Contribution Guideline
------------------------------

Checklist
*********

* Check if your example proposal has no similar in the project
* Use the `Arduino style guide`_
* Add the header to all source files
* Add the `README.md` file
* Add inline comments if needed
* Test the example

Header
******

All the source files must include the header with the example name and license, if applicable. You can change this header as you with, but it will be reviewed by the community and may not be accepted.
pedrominatel marked this conversation as resolved.
Show resolved Hide resolved

Additionaly, you can add some description about the example, links to the documentation or authors name. Just have in mind to keep it simple and short.

**Header Example**

.. code-block:: arduino

/* Wi-Fi FTM Initiator Arduino Example

This example code is in the Public Domain (or CC0 licensed, at your option.)

Unless required by applicable law or agreed to in writing, this
software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
CONDITIONS OF ANY KIND, either express or implied.
*/


README file
***********

The **README.md** file should contain the example details.

Please see the recommended **README.md** file in the `example template folder <https://github.com/espressif/arduino-esp32/tree/master/libraries/ESP32/examples/Template/ExampleTemplate>`_.

Inline Comments
***************

Inline comments are important if the example contains complex algorithms os specific configuration that the user needs to change.
pedrominatel marked this conversation as resolved.
Show resolved Hide resolved

pedrominatel marked this conversation as resolved.
Show resolved Hide resolved
pedrominatel marked this conversation as resolved.
Show resolved Hide resolved
**Example**

.. code-block:: arduino

// Number of FTM frames requested in terms of 4 or 8 bursts (allowed values - 0 (No pref), 16, 24, 32, 64)

and

.. code-block:: arduino

const char * WIFI_FTM_SSID = "WiFi_FTM_Responder"; // SSID of AP that has FTM Enabled
const char * WIFI_FTM_PASS = "ftm_responder"; // STA Password

Testing
*******

Be sure you have tested the example in all the supported targets. If the example works only with specific targets, add this information in the **README.md** file on the **Supported Targets** and in the example code as inline comment.

**Example**

.. code-block:: arduino

/*
THIS FEATURE IS SUPPORTED ONLY BY ESP32-S2 AND ESP32-C3
*/

and

.. code-block:: markdown

Currently, this example supports the following targets.

| Supported Targets | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 |
| ----------------- | ----- | -------- | -------- | -------- |

Example Template
****************

The example template can be found `here <https://github.com/espressif/arduino-esp32/tree/master/libraries/ESP32/examples/Template/ExampleTemplate>`_ and can be used as a reference.

Legal Part
----------

Before a contribution can be accepted, you will need to sign our contributor-agreement. You will be prompted for this automatically as part of the Pull Request process.



.. _Arduino style guide: https://www.arduino.cc/en/Reference/StyleGuide
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
/* Arduino Example Template

This example code is in the Public Domain (or CC0 licensed, at your option.)

Unless required by applicable law or agreed to in writing, this
software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
CONDITIONS OF ANY KIND, either express or implied.
*/

void setup() {

}

void loop() {

}
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Arduino-ESP32 Example/Library Name ==(REQUIRED)==

==*Add a brief description about this example/library here!*==
==*Add a brief description of this example/library here!*==

This example/library demonstrates how to create a new example README file.

Expand All @@ -15,33 +15,33 @@ Currently, this example supports the following targets.

## How to Use Example/Library ==(OPTIONAL)==

==*Add a brief description on how to use this example.*==
==*Add a brief description of how to use this example.*==

* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide).

### Hardware Connection ==(OPTIONAL)==

==*Add a brief description about wiring or any other hardware specific connection.*==
==*Add a brief description of wiring or any other hardware-specific connection.*==

To use this example, you need to connect the LED to the `GPIOx`.

SDCard GPIO connection scheme:

| SDCard Pin | Function | GPIO |
| SDCard Pin | Function | GPIO |
| ----------- | -------- | ------ |
| 1 | CS | GPIO5 |
| 2 | DI/MOSI | GPIO23 |
| 3 | VSS/GND | GND |
| 4 | VDD/3V3 | 3V3 |
| 5 | SCLK | GPIO18 |
| 6 | VSS/GND | GND |
| 7 | DO/MISO | GPIO19 |
| 1 | CS | GPIO5 |
| 2 | DI/MOSI | GPIO23 |
| 3 | VSS/GND | GND |
| 4 | VDD/3V3 | 3V3 |
| 5 | SCLK | GPIO18 |
| 6 | VSS/GND | GND |
| 7 | DO/MISO | GPIO19 |

To add images, please create a folder `_asset` inside the example folder to add the relevant images.

### Configure the Project ==(OPTIONAL)==

==*Add a brief description about this example here!*==
==*Add a brief description of this example here!*==

Set the LED GPIO by changing the `LED_BUILTIN` value in the function `pinMode(LED_BUILTIN, OUTPUT);`. By default, the GPIO is: `GPIOx`.

Expand All @@ -66,7 +66,7 @@ To get more information about the Espressif boards see [Espressif Development Ki

#### Using Platform IO

* Select the COM port: `Devices` or setting the `upload_port` option on the `platformio.ini` file.
* Select the COM port: `Devices` or set the `upload_port` option on the `platformio.ini` file.

## Example/Log Output ==(OPTIONAL)==

Expand Down Expand Up @@ -98,21 +98,21 @@ Chip ID: 3957392
* **Programming Fail:** If the programming/flash procedure fails, try reducing the serial connection speed.
* **COM port not detected:** Check the USB cable and the USB to Serial driver installation.

If the error persist, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute).
If the error persists, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute).

## Contribute ==(REQUIRED)==

==*Do not change! Keep as is.*==
==*Do not change! Keep it as is.*==

To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst)

If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome!

Before creating a new issue, be sure to try the Troubleshooting and to check if the same issue was already created by someone else.
Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else.

## Resources ==(REQUIRED)==

==*Do not change here! Keep as is or add only relevant documents/info for this example. Do not add any purchase link/marketing stuff*==
==*Do not change here! Keep it as is or add only relevant documents/info for this example. Do not add any purchase link/marketing stuff*==

* Official ESP32 Forum: [Link](https://esp32.com)
* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32)
Copy link
Member

@P-R-O-C-H-Y P-R-O-C-H-Y Jan 19, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pedrominatel As this part was not edited and hidden in the PR (can't even target that line), can you please add ESP32-S3 datasheet link too. To have it in all future example READMEs.

Expand Down