Skip to content

Commit 2382087

Browse files
pedrominatelpedrominatel
authored
Added the README template for examples and libraries (espressif#5228)
Typos fixed and added more details and instructions Added README file to WiFiScan example Review on the README template Added link to DevKits
1 parent 4f9e583 commit 2382087

File tree

2 files changed

+195
-0
lines changed

2 files changed

+195
-0
lines changed

‎docs/EXAMPLE_README_TEMPLATE.md

+122
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Arduino-ESP32 Example/Library Name ==(REQUIRED)==
2+
3+
==*Add a brief description about this example/library here!*==
4+
5+
This example/library demonstrates how to create a new example README file.
6+
7+
# Supported Targets ==(REQUIRED)==
8+
9+
==*Add the supported devices here!*==
10+
11+
Currently, this example supports the following targets.
12+
13+
| Supported Targets | ESP32 | ESP32-S2 | ESP32-C3 |
14+
| ----------------- | ----- | -------- | -------- |
15+
16+
## How to Use Example/Library ==(OPTIONAL)==
17+
18+
==*Add a brief description on how to use this example.*==
19+
20+
* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide).
21+
22+
### Hardware Connection ==(OPTIONAL)==
23+
24+
==*Add a brief description about wiring or any other hardware specific connection.*==
25+
26+
To use this example, you need to connect the LED to the `GPIOx`.
27+
28+
SDCard GPIO connection scheme:
29+
30+
| SDCard Pin | Function | GPIO |
31+
| ----------- | -------- | ------ |
32+
| 1 | CS | GPIO5 |
33+
| 2 | DI/MOSI | GPIO23 |
34+
| 3 | VSS/GND | GND |
35+
| 4 | VDD/3V3 | 3V3 |
36+
| 5 | SCLK | GPIO18 |
37+
| 6 | VSS/GND | GND |
38+
| 7 | DO/MISO | GPIO19 |
39+
40+
To add images, please create a folder `_asset` inside the example folder to add the relevant images.
41+
42+
### Configure the Project ==(OPTIONAL)==
43+
44+
==*Add a brief description about this example here!*==
45+
46+
Set the LED GPIO by changing the `LED_BUILTIN` value in the function `pinMode(LED_BUILTIN, OUTPUT);`. By default, the GPIO is: `GPIOx`.
47+
48+
#### Example for the GPIO4:
49+
50+
==*Add some code explanation if relevant to the example.*==
51+
52+
```cpp
53+
// the setup function runs once when you press reset or power the board
54+
void setup() {
55+
// initialize digital pin 4 as an output.
56+
pinMode(4, OUTPUT);
57+
}
58+
```
59+
60+
#### Using Arduino IDE
61+
62+
To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits).
63+
64+
* Before Compile/Verify, select the correct board: `Tools -> Board`.
65+
* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port.
66+
67+
#### Using Platform IO
68+
69+
* Select the COM port: `Devices` or setting the `upload_port` option on the `platformio.ini` file.
70+
71+
## Example/Log Output ==(OPTIONAL)==
72+
73+
==*Add the log/serial output here!*==
74+
75+
```
76+
ets Jul 29 2019 12:21:46
77+
78+
rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
79+
configsip: 0, SPIWP:0xee
80+
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
81+
mode:DIO, clock div:1
82+
load:0x3fff0030,len:1412
83+
load:0x40078000,len:13400
84+
load:0x40080400,len:3672
85+
entry 0x400805f8
86+
ESP32 Chip model = ESP32-D0WDQ5 Rev 3
87+
This chip has 2 cores
88+
Chip ID: 3957392
89+
```
90+
91+
## Troubleshooting ==(REQUIRED)==
92+
93+
==*Add specific issues you may find by using this example here!*==
94+
95+
***Important: Make sure you are using a good quality USB cable and that you have a reliable power source***
96+
97+
* **LED not blinking:** Check the wiring connection and the IO selection.
98+
* **Programming Fail:** If the programming/flash procedure fails, try reducing the serial connection speed.
99+
* **COM port not detected:** Check the USB cable and the USB to Serial driver installation.
100+
101+
If the error persist, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute).
102+
103+
## Contribute ==(REQUIRED)==
104+
105+
==*Do not change! Keep as is.*==
106+
107+
To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst)
108+
109+
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!
110+
111+
Before creating a new issue, be sure to try the Troubleshooting and to check if the same issue was already created by someone else.
112+
113+
## Resources ==(REQUIRED)==
114+
115+
==*Do not change here! Keep as is or add only relevant documents/info for this example. Do not add any purchase link/marketing stuff*==
116+
117+
* Official ESP32 Forum: [Link](https://esp32.com)
118+
* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32)
119+
* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf)
120+
* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf)
121+
* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf)
122+
* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com)

‎libraries/WiFi/examples/WiFiScan/README.md

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# WiFiScan Example
2+
3+
This example demonstrates how to use the WiFi library to scan available WiFi networks and print the results.
4+
5+
# Supported Targets
6+
7+
Currently this example supports the following targets.
8+
9+
| Supported Targets | ESP32 | ESP32-S2 | ESP32-C3 |
10+
| ----------------- | ----- | -------- | -------- |
11+
12+
## How to Use Example
13+
14+
* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide).
15+
16+
#### Using Arduino IDE
17+
18+
* Before Compile/Verify, select the correct board: `Tools -> Board`.
19+
* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port.
20+
21+
#### Using Platform IO
22+
23+
* Select the COM port: `Devices` or setting the `upload_port` option on the `platformio.ini` file.
24+
25+
## Example/Log Output
26+
27+
```
28+
ets Jul 29 2019 12:21:46
29+
30+
rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
31+
configsip: 0, SPIWP:0xee
32+
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
33+
mode:DIO, clock div:1
34+
load:0x3fff0030,len:1412
35+
load:0x40078000,len:13400
36+
load:0x40080400,len:3672
37+
entry 0x400805f8
38+
Setup done
39+
scan start
40+
scan done
41+
17 networks found
42+
1: IoTNetwork (-62)*
43+
2: WiFiSSID (-62)*
44+
3: B3A7992 (-63)*
45+
4: WiFi (-63)
46+
5: IoTNetwork2 (-64)*
47+
...
48+
```
49+
50+
## Troubleshooting
51+
52+
***Important: Be sure you're using a good quality USB cable and you have enought power source for your project.***
53+
54+
* **Programming Fail:** If the programming/flash procedure fails, try to reduce the serial connection speed.
55+
* **COM port not detected:** Check the USB cable connection and the USB to Serial driver installation.
56+
57+
If the error persist, you can ask help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute).
58+
59+
## Contribute
60+
61+
To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst)
62+
63+
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!
64+
65+
Before creating a new issue, be sure to try the Troubleshooting and to check if the same issue was already created by someone else.
66+
67+
## Resources
68+
69+
* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32)
70+
* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf)
71+
* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf)
72+
* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf)
73+
* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com)

0 commit comments

Comments
 (0)