Skip to content

A
arduino-esp32

调味师 / arduino-esp32
与 Fork 源项目一致

从无法访问的项目Fork

通知 1
Star 0
Fork 0
A
arduino-esp32

前往新版Gitcode，体验更适合开发者的 AI 搜索 >>

未验证 提交 1effae46 编写于 作者: P Pedro Minatel 提交者： GitHub
浏览文件
操作

Docs: Initial documentation structure using Sphinx (#5355) 

This PR is the initial documentation structure including the basic information about the project and Sphinx configuration.

####CONTENTS:
- Getting Started
- Installing
- Boards
- Libraries
- Library Builder
- Tutorials
- ESP-IDF as Component
- OTA Web Update
- makeEspArduino
- Troubleshooting
- Contributing

This PR also changes the README.md.
上级 d9833f9b
隐藏空白更改
内联 并排
Showing with 2269 addition and 304 deletion
.gitignore
浏览文件 @ 1effae46
......@@ -18,3 +18,6 @@ __vm/
.vscode/
platform.sloeber.txt
boards.sloeber.txt
# Ignore docs build (Sphinx)
docs/build
README.md
浏览文件 @ 1effae46
# Arduino core for the ESP32
[![Build Status](https://travis-ci.org/espressif/arduino-esp32.svg?branch=master)](https://travis-ci.org/espressif/arduino-esp32) ![](https://github.com/espressif/arduino-esp32/workflows/ESP32%20Arduino%20CI/badge.svg)
[![Build Status](https://travis-ci.org/espressif/arduino-esp32.svg?branch=master)](https://travis-ci.org/espressif/arduino-esp32) ![](https://github.com/espressif/arduino-esp32/workflows/ESP32%20Arduino%20CI/badge.svg) [![Documentation Status](https://readthedocs.com/projects/espressif-arduino-esp32/badge/?version=latest&token=b6c5d887f5e0bcbf37a92cf3bf9f93f9e77b9d805c0f708cf128ac04a2228299)](https://docs.espressif.com/projects/arduino-esp32/en/latest/?badge=latest)
### Need help or have a question? Join the chat at [![https://gitter.im/espressif/arduino-esp32](https://badges.gitter.im/espressif/arduino-esp32.svg)](https://gitter.im/espressif/arduino-esp32?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
## Contents
- [ESP32-S2 and ESP32-C3 Support](#esp32-s2-and-esp32-c3-support)
- [Development Status](#development-status)
- [Installation Instructions](#installation-instructions)
- [Decoding Exceptions](#decoding-exceptions)
- [Issue/Bug report template](#issuebug-report-template)
- [ESP32Dev Board PINMAP](#esp32dev-board-pinmap)
### ESP32-S2 and ESP32-C3 Support
If you want to test ESP32-S2 and/or ESP32-C3 through the board manager, please use the development release link: `https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_dev_index.json` and install the latest 2.0.0 version.
If you want to test ESP32-S2 and/or ESP32-C3 through the board manager, please use the development release link:
```
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_dev_index.json
```
Now you can install the latest 2.0.0 version from the boards manager.
### Development Status
......@@ -20,20 +27,16 @@ Latest Stable Release [![Release Version](https://img.shields.io/github/release
Latest Development Release [![Release Version](https://img.shields.io/github/release/espressif/arduino-esp32/all.svg?style=plastic)](https://github.com/espressif/arduino-esp32/releases/latest/) [![Release Date](https://img.shields.io/github/release-date-pre/espressif/arduino-esp32.svg?style=plastic)](https://github.com/espressif/arduino-esp32/releases/latest/) [![Downloads](https://img.shields.io/github/downloads-pre/espressif/arduino-esp32/latest/total.svg?style=plastic)](https://github.com/espressif/arduino-esp32/releases/latest/)
### Documentation
### Installation Instructions
- Using Arduino IDE Boards Manager (preferred)
+ [Instructions for Boards Manager](docs/arduino-ide/boards_manager.md)
- Using Arduino IDE with the development repository
+ [Instructions for Windows](docs/arduino-ide/windows.md)
+ [Instructions for Mac](docs/arduino-ide/mac.md)
+ [Instructions for Debian/Ubuntu Linux](docs/arduino-ide/debian_ubuntu.md)
+ [Instructions for Fedora](docs/arduino-ide/fedora.md)
+ [Instructions for openSUSE](docs/arduino-ide/opensuse.md)
- [Using PlatformIO](docs/platformio.md)
- [Building with make](docs/make.md)
- [Using as ESP-IDF component](docs/esp-idf_component.md)
- [Using OTAWebUpdater](docs/OTAWebUpdate/OTAWebUpdate.md)
You can use [Arduino-ESP32 Online Documentation](https://docs.espressif.com/projects/arduino-esp32/en/docs-initial_version/index.html) to get all information about this project.
* [Getting Started](https://docs.espressif.com/projects/arduino-esp32/en/docs-initial_version/getting_started.html)
* [Installing (Windows, Linux and macOS)](https://docs.espressif.com/projects/arduino-esp32/en/docs-initial_version/installing.html)
* [Libraries](https://docs.espressif.com/projects/arduino-esp32/en/docs-initial_version/libraries.html)
* [ESP-IDF as Component](https://docs.espressif.com/projects/arduino-esp32/en/docs-initial_version/esp-idf_component.html)
* [FAQ](https://docs.espressif.com/projects/arduino-esp32/en/docs-initial_version/faq.html)
* [Troubleshooting](https://docs.espressif.com/projects/arduino-esp32/en/docs-initial_version/troubleshooting.html)
### Decoding exceptions
......@@ -42,16 +45,10 @@ You can use [EspExceptionDecoder](https://github.com/me-no-dev/EspExceptionDecod
### Issue/Bug report template
Before reporting an issue, make sure you've searched for similar one that was already created. Also make sure to go through all the issues labelled as [for reference](https://github.com/espressif/arduino-esp32/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3A%22for%20reference%22%20).
Finally, if you are sure no one else had the issue, follow the [ISSUE_TEMPLATE](docs/ISSUE_TEMPLATE.md) while reporting any issue.
### ESP32Dev Board PINMAP
![Pin Functions](docs/esp32_pinmap.png)
![ESP32S2_Pinmap](docs/esp32s2_pinmap.png)
Finally, if you are sure no one else had the issue, follow the [issue template](docs/ISSUE_TEMPLATE.md) while reporting any issue.
![ESP32C3_Pinmap](docs/esp32c3_pinmap.png)
### Contributing
### Tip
We welcome contributions to the Arduino ESP32 project!
Sometimes to program ESP32 via serial you must keep GPIO0 LOW during the programming process
See [contributing](https://docs.espressif.com/projects/arduino-esp32/en/docs-initial_version/contributing.html) in the documentation for more information on how to contribute to the project.
docs/Makefile 0 → 100644
浏览文件 @ 1effae46
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
LINKCHECKDIR = build/linkcheck
.PHONY: checklinks
checklinks:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(LINKCHECKDIR)
@echo
@echo "Check finished. Report is in $(LINKCHECKDIR)."
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
docs/arduino-ide/boards_manager.md 已删除 100644 → 0
浏览文件 @ d9833f9b
## Installation instructions using Arduino IDE Boards Manager
### ==========================================================
- Stable release link: `https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json`
- Development release link: `https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_dev_index.json`
Starting with 1.6.4, Arduino allows installation of third-party platform packages using Boards Manager. We have packages available for Windows, Mac OS, and Linux (x86, amd64, armhf and arm64).
- Install the current upstream Arduino IDE at the 1.8 level or later. The current version is at the [Arduino website](http://www.arduino.cc/en/main/software).
- Start Arduino and open Preferences window.
- Enter one of the release links above into *Additional Board Manager URLs* field. You can add multiple URLs, separating them with commas.
- Open Boards Manager from Tools > Board menu and install *esp32* platform (and do not forget to select your ESP32 board from Tools > Board menu after installation).
docs/arduino-ide/debian_ubuntu.md 已删除 100644 → 0
浏览文件 @ d9833f9b
Installation instructions for Debian / Ubuntu OS
=================================================
- Install latest Arduino IDE from [arduino.cc](https://www.arduino.cc/en/Main/Software)
- Open Terminal and execute the following command (copy->paste and hit enter):
```bash
sudo usermod -a -G dialout $USER && \
sudo apt-get install git && \
wget https://bootstrap.pypa.io/get-pip.py && \
sudo python3 get-pip.py && \
sudo pip3 install pyserial && \
mkdir -p ~/Arduino/hardware/espressif && \
cd ~/Arduino/hardware/espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
cd esp32 && \
git submodule update --init --recursive && \
cd tools && \
python3 get.py
```
- Restart Arduino IDE
- If you have Arduino installed to ~/, modify the installation as follows, beginning at `mkdir -p ~/Arduino/hardware`:
```bash
cd ~/Arduino/hardware
mkdir -p espressif && \
cd espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
cd esp32 && \
git submodule update --init --recursive && \
cd tools && \
python3 get.py
```
docs/arduino-ide/fedora.md 已删除 100644 → 0
浏览文件 @ d9833f9b
Installation instructions for Fedora
=====================================
- Install the latest Arduino IDE from [arduino.cc](https://www.arduino.cc/en/Main/Software). `$ sudo dnf -y install arduino` will most likely install an older release.
- Open Terminal and execute the following command (copy->paste and hit enter):
```bash
sudo usermod -a -G dialout $USER && \
sudo dnf install git python3-pip python3-pyserial && \
mkdir -p ~/Arduino/hardware/espressif && \
cd ~/Arduino/hardware/espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
cd esp32 && \
git submodule update --init --recursive && \
cd tools && \
python get.py
```
- Restart Arduino IDE
docs/arduino-ide/mac.md 已删除 100644 → 0
浏览文件 @ d9833f9b
Installation instructions for Mac OS
=====================================
- Install latest Arduino IDE from [arduino.cc](https://www.arduino.cc/en/Main/Software)
- Open Terminal and execute the following command (copy->paste and hit enter):
```bash
mkdir -p ~/Documents/Arduino/hardware/espressif && \
cd ~/Documents/Arduino/hardware/espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 --depth 1 && \
cd esp32 && \
git submodule update --init --recursive --depth 1 && \
cd tools && \
python get.py
```
Where `~/Documents/Arduino` represents your sketch book location as per "Arduino" > "Preferences" > "Sketchbook location" (in the IDE once started). Adjust the command above accordingly if necessary!
 
- If you get the error below. Install the command line dev tools with xcode-select --install and try the command above again:
```xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun```
```xcode-select --install```
- Try `python3` instead of `python` if you get the error: `IOError: [Errno socket error] [SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol version (_ssl.c:590)` when running `python get.py`
- If you get the following error when running `python get.py` urllib.error.URLError: <urlopen error SSL: CERTIFICATE_VERIFY_FAILED, go to Macintosh HD > Applications > Python3.6 folder (or any other python version), and run the following scripts: Install Certificates.command and Update Shell Profile.command
- Restart Arduino IDE
docs/arduino-ide/opensuse.md 已删除 100644 → 0
浏览文件 @ d9833f9b
Installation instructions for openSUSE
======================================
- Install the latest Arduino IDE from [arduino.cc](https://www.arduino.cc/en/Main/Software).
- Open Terminal and execute the following command (copy->paste and hit enter):
```bash
sudo usermod -a -G dialout $USER && \
if [ `python --version 2>&1 | grep '2.7' | wc -l` = "1" ]; then \
sudo zypper install git python-pip python-pyserial; \
else \
sudo zypper install git python3-pip python3-pyserial; \
fi && \
mkdir -p ~/Arduino/hardware/espressif && \
cd ~/Arduino/hardware/espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
cd esp32 && \
git submodule update --init --recursive && \
cd tools && \
python get.py
```
- Restart Arduino IDE
docs/arduino-ide/windows.md 已删除 100644 → 0
浏览文件 @ d9833f9b
## Steps to install Arduino ESP32 support on Windows
### Tested on 32 and 64 bit Windows 10 machines
1. Download and install the latest Arduino IDE ```Windows Installer``` from [arduino.cc](https://www.arduino.cc/en/Main/Software)
2. Download and install Git from [git-scm.com](https://git-scm.com/download/win)
3. Start ```Git GUI``` and run through the following steps:
- Select ```Clone Existing Repository```
![Step 1](win-screenshots/win-gui-1.png)
- Select source and destination
- Sketchbook Directory: Usually ```C:/Users/[YOUR_USER_NAME]/Documents/Arduino``` and is listed underneath the "Sketchbook location" in Arduino preferences.
- Source Location: ```https://github.com/espressif/arduino-esp32.git```
- Target Directory: ```[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32```
- Click ```Clone``` to start cloning the repository
![Step 2](win-screenshots/win-gui-2.png)
![Step 3](win-screenshots/win-gui-3.png)
- open a `Git Bash` session pointing to ```[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32``` and execute ```git submodule update --init --recursive```
- Open ```[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32/tools``` and double-click ```get.exe```
![Step 4](win-screenshots/win-gui-4.png)
- When ```get.exe``` finishes, you should see the following files in the directory
![Step 5](win-screenshots/win-gui-5.png)
4. Plug your ESP32 board and wait for the drivers to install (or install manually any that might be required)
5. Start Arduino IDE
6. Select your board in ```Tools > Board``` menu
7. Select the COM port that the board is attached to
8. Compile and upload (You might need to hold the boot button while uploading)
![Arduino IDE Example](win-screenshots/arduino-ide.png)
### How to update to the latest code
1. Start ```Git GUI``` and you should see the repository under ```Open Recent Repository```. Click on it!
![Update Step 1](win-screenshots/win-gui-update-1.png)
2. From menu ```Remote``` select ```Fetch from``` > ```origin```
![Update Step 2](win-screenshots/win-gui-update-2.png)
3. Wait for git to pull any changes and close ```Git GUI```
4. Open ```[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32/tools``` and double-click ```get.exe```
![Step 4](win-screenshots/win-gui-4.png)
docs/esp-idf_component.md 已删除 100644 → 0
浏览文件 @ d9833f9b
To use as a component of ESP-IDF
=================================================
## esp32-arduino-lib-builder
For a simplified method, see [lib-builder](lib_builder.md)
## Installation
- Download and install [esp-idf](https://github.com/espressif/esp-idf)
- Create blank idf project (from one of the examples)
- in the project folder, create a folder called components and clone this repository inside
```bash
mkdir -p components && \
cd components && \
git clone https://github.com/espressif/arduino-esp32.git arduino && \
cd arduino && \
git submodule update --init --recursive && \
cd ../.. && \
idf.py menuconfig
```
- ```idf.py menuconfig``` has some Arduino options
- "Autostart Arduino setup and loop on boot"
- If you enable this options, your main.cpp should be formated like any other sketch
```arduino
//file: main.cpp
#include "Arduino.h"
void setup(){
Serial.begin(115200);
}
void loop(){
Serial.println("loop");
delay(1000);
}
```
- Else you need to implement ```app_main()``` and call ```initArduino();``` in it.
Keep in mind that setup() and loop() will not be called in this case.
If you plan to base your code on examples provided in [esp-idf](https://github.com/espressif/esp-idf/tree/master/examples), please make sure move the app_main() function in main.cpp from the files in the example.
```arduino
//file: main.cpp
#include "Arduino.h"
extern "C" void app_main()
{
initArduino();
pinMode(4, OUTPUT);
digitalWrite(4, HIGH);
//do your own thing
}
```
- "Disable mutex locks for HAL"
- If enabled, there will be no protection on the drivers from concurently accessing them from another thread/interrupt/core
- "Autoconnect WiFi on boot"
- If enabled, WiFi will start with the last known configuration
- Else it will wait for WiFi.begin
- ```idf.py -p <your-board-serial-port> flash monitor``` will build, upload and open serial monitor to your board
## Logging To Serial
If you are writing code that does not require Arduino to compile and you want your `ESP_LOGx` macros to work in Arduino IDE, you can enable the compatibility by adding the following lines after your includes:
```cpp
#ifdef ARDUINO_ARCH_ESP32
#include "esp32-hal-log.h"
#endif
```
## FreeRTOS Tick Rate (Hz)
You might notice that Arduino-esp32's `delay()` function will only work in multiples of 10ms. That is because, by default, esp-idf handles task events 100 times per second.
To fix that behavior you need to set FreeRTOS tick rate to 1000Hz in `make menuconfig` -> `Component config` -> `FreeRTOS` -> `Tick rate`.
## Compilation Errors
As commits are made to esp-idf and submodules, the codebases can develop incompatibilities which cause compilation errors. If you have problems compiling, follow the instructions in [Issue #1142](https://github.com/espressif/arduino-esp32/issues/1142) to roll esp-idf back to a known good version.
docs/lib_builder.md 已删除 100644 → 0
浏览文件 @ d9833f9b
## Using esp32-arduino-lib-builder to compile custom libraries
Espressif has provided a [tool](https://github.com/espressif/esp32-arduino-lib-builder) to simplify building your own compiled libraries for use in Arduino IDE (or your favorite IDE).
To use it to generate custom libraries, follow these steps:
1. `git clone https://github.com/espressif/esp32-arduino-lib-builder`
2. `cd esp32-arduino-lib-builder`
3. `./tools/update-components.sh`
4. `./tools/install-esp-idf.sh` (if you already have an $IDF_PATH defined, it will use your local copy of the repository)
5. `make menuconfig` or directly edit sdkconfig.
6. `./build.sh`
The script automates the process of building [arduino as an ESP-IDF component](https://github.com/espressif/arduino-esp32/blob/master/docs/esp-idf_component.md).
Once it is complete, you can cherry pick the needed libraries from `out/tools/sdk/lib`, or run `tools/copy-to-arduino.sh` to copy the entire built system.
`tools/config.sh` contains a number of variables that control the process, particularly the $IDF_BRANCH variable. You can adjust this to try building against newer versions, but there are absolutely no guarantees that any components will work or even successfully compile against a newer IDF.
docs/make.bat 0 → 100644
浏览文件 @ 1effae46
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd
docs/make.md 已删除 100644 → 0
浏览文件 @ d9833f9b
To use make
============
[makeEspArduino](https://github.com/plerup/makeEspArduino) is a generic makefile for any ESP8266/ESP32 Arduino project.Using make instead of the Arduino IDE makes it easier to do automated and production builds.
docs/platformio.md 已删除 100644 → 0
浏览文件 @ d9833f9b
Installation instructions for using PlatformIO
=================================================
- [What is PlatformIO?](https://docs.platformio.org/en/latest/what-is-platformio.html?utm_source=github&utm_medium=arduino-esp32)
- [PlatformIO IDE](https://platformio.org/platformio-ide?utm_source=github&utm_medium=arduino-esp32)
- [PlatformIO Core](https://docs.platformio.org/en/latest/core.html?utm_source=github&utm_medium=arduino-esp32) (command line tool)
- [Advanced usage](https://docs.platformio.org/en/latest/platforms/espressif32.html?utm_source=github&utm_medium=arduino-esp32) -
custom settings, uploading to SPIFFS, Over-the-Air (OTA), staging version
- [Integration with Cloud and Standalone IDEs](https://docs.platformio.org/en/latest/ide.html?utm_source=github&utm_medium=arduino-esp32) -
Cloud9, Codeanywhere, Eclipse Che (Codenvy), Atom, CLion, Eclipse, Emacs, NetBeans, Qt Creator, Sublime Text, VIM, Visual Studio, and VSCode
- [Project Examples](https://docs.platformio.org/en/latest/platforms/espressif32.html?utm_source=github&utm_medium=arduino-esp32#examples)
docs/requirements.txt 0 → 100644
浏览文件 @ 1effae46
# This is a list of python packages used to generate documentation. This file is used with pip:
# pip install --user -r requirements.txt
#
# matplotlib is currently required only by the script generate_chart.py
sphinx-copybutton==0.3.0
docs/source/advanced_utils.rst 0 → 100644
浏览文件 @ 1effae46
##################
Advanced Utilities
##################
.. toctree::
:maxdepth: 2
Library Builder <lib_builder>
ESP-IDF as Component <esp-idf_component>
OTA Web Update <ota_web_update>
makeEspArduino <make>
docs/source/api/bluetooth.rst 0 → 100644
浏览文件 @ 1effae46
#############
Bluetooth API
#############
docs/source/api/deepsleep.rst 0 → 100644
浏览文件 @ 1effae46
##########
Deep Sleep
##########
docs/source/api/espnow.rst 0 → 100644
浏览文件 @ 1effae46
#######
ESP-NOW
#######
ESP-NOW is a fast, connectionless communication technology featuring a short packet transmission.
ESP-NOW is ideal for smart lights, remote control devices, sensors and other applications.
Example
-------
Resources
---------
* `ESP-NOW`_ (User Guide)
.. _ESP-NOW: https://www.espressif.com/sites/default/files/documentation/esp-now_user_guide_en.pdf
docs/source/api/rainmaker.rst 0 → 100644
浏览文件 @ 1effae46
#########
RainMaker
#########
docs/source/api/reset_reason.rst 0 → 100644
浏览文件 @ 1effae46
############
Reset Reason
############
docs/source/api/wifi.rst 0 → 100644
浏览文件 @ 1effae46
#########
Wi-Fi API
#########
About
-----
The Wi-Fi API provides support for the 802.11b/g/n protocol driver. This API includes:
* Station mode (STA mode or Wi-Fi client mode). ESP32 connects to an access point
* AP mode (aka Soft-AP mode or Access Point mode). Devices connect to the ESP32
* Security modes (WPA, WPA2, WEP, etc.)
* Scanning for access points
Working as AP
*************
In this mode, the ESP32 is configured as an Access Point (AP) and it's capable of receiving incoming connections from other devices (stations) by providing
a Wi-Fi network.
.. figure:: ../_static/wifi_esp32_ap.png
:align: center
:width: 520
:figclass: align-center
This mode can be used for serving a HTTP or HTTPS server inside the ESP32, for example.
Working as STA
**************
The STA mode is used to connect the ESP32 to a Wi-Fi network, provided by an Access Point.
.. figure:: ../_static/wifi_esp32_sta.png
:align: center
:width: 520
:figclass: align-center
If you need to connect your project to the Internet, this is the mode you are looking for.
API Description
---------------
Here is the description about the WiFi API.
WiFiAP
------
The ``WiFiAP`` is used to configure and manage the Wi-Fi as an Access Point. This is where you can find the related functions for the AP.
Basic Usage
***********
To start the Wi-Fi as an Access Point.
.. code-block:: arduino
WiFi.softAP(ssid, password);
Please see the full WiFiAP example in: `ap example`_.
AP Configuration
----------------
softAP
******
Use the function ``softAP`` to configure the Wi-Fi AP characteristics:
.. code-block:: arduino
bool softAP(const char* ssid, const char* passphrase = NULL, int channel = 1, int ssid_hidden = 0, int max_connection = 4, bool ftm_responder = false);
Where:
* ``ssid`` sets the Wi-Fi network SSID.
* ``passphrase`` sets the Wi-Fi network password. If the network is open, set as ``NULL``.
* ``channel`` configures the Wi-Fi channel.
* ``ssid_hidden`` sets the network as hidden.
* ``max_connection`` sets the maximum number of simultaneous connections. The default is 4.
* ``ftm_responder`` sets the Wi-Fi FTM responder feature. **Only for ESP32-S2 and ESP32-C3 SoC!**
Return ``true`` if the configuration was successful.
softAPConfig
************
Function used to configure the IP as static (fixed) as well as the gateway and subnet.
.. code-block:: arduino
bool softAPConfig(IPAddress local_ip, IPAddress gateway, IPAddress subnet);
Where:
* ``local_ip`` sets the local IP address.
* ``gateway`` sets the gateway IP.
* ``subnet`` sets the subnet mask.
The function will return ``true`` if the configuration is successful.
AP Connection
-------------
softAPdisconnect
****************
Function used to force the AP disconnection.
.. code-block:: arduino
bool softAPdisconnect(bool wifioff = false);
Where:
* ``wifioff`` sets the Wi-Fi off if ``true``.
The function will return ``true`` if the configuration is successful.
softAPgetStationNum
*******************
This function returns the number of clients connected to the AP.
.. code-block:: arduino
uint8_t softAPgetStationNum();
softAPIP
********
Function to get the AP IPv4 address.
.. code-block:: arduino
IPAddress softAPIP();
The function will return the AP IP address in ``IPAddress`` format.
softAPBroadcastIP
*****************
Function to get the AP IPv4 broadcast address.
.. code-block:: arduino
IPAddress softAPBroadcastIP();
The function will return the AP broadcast address in ``IPAddress`` format.
softAPNetworkID
***************
Get the softAP network ID.
.. code-block:: arduino
IPAddress softAPNetworkID();
The function will return the AP network address in ``IPAddress`` format.
softAPSubnetCIDR
****************
Get the softAP subnet CIDR.
.. code-block:: arduino
uint8_t softAPSubnetCIDR();
softAPenableIpV6
****************
Function used to enable the IPv6 support.
.. code-block:: arduino
bool softAPenableIpV6();
The function will return ``true`` if the configuration is successful.
softAPIPv6
**********
Function to get the IPv6 address.
.. code-block:: arduino
IPv6Address softAPIPv6();
The function will return the AP IPv6 address in ``IPv6Address`` format.
softAPgetHostname
*****************
Function to get the AP hostname.
.. code-block:: arduino
const char * softAPgetHostname();
softAPsetHostname
*****************
Function to set the AP hostname.
.. code-block:: arduino
bool softAPsetHostname(const char * hostname);
Where:
* ``hostname`` sets the device hostname.
The function will return ``true`` if the configuration is successful.
softAPmacAddress
****************
Function to define the AP MAC address.
.. code-block:: arduino
uint8_t* softAPmacAddress(uint8_t* mac);
Where:
* ``mac`` sets the new MAC address.
Function to get the AP MAC address.
.. code-block:: arduino
String softAPmacAddress(void);
softAPSSID
**********
Function to get the AP SSID.
.. code-block:: arduino
String softAPSSID(void) const;
Returns the AP SSID.
WiFiSTA
-------
The ``WiFiSTA`` is used to configure and manage the Wi-Fi as Station. The related functions for the STA are here.
Basic Usage
***********
The following code shows the basic usage of the WifiSTA functionality.
.. code-block:: arduino
WiFi.begin(ssid, password);
Where the ``ssid`` and ``password`` are from the network you want to connect the ESP32.
To check if the connection is successful, you can use:
.. code-block:: arduino
while (WiFi.status() != WL_CONNECTED) {
delay(500);
Serial.print(".");
}
After a successful connection, you can print the IP address given by the network.
.. code-block:: arduino
Serial.println("IP address: ");
Serial.println(WiFi.localIP());
Please see the full example of the WiFiSTA in: `sta example`_.
STA Configuration
-----------------
begin
*****
- Functions ``begin`` are used to configure and start the Wi-Fi.
.. code-block:: arduino
wl_status_t begin(const char* ssid, const char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = true);
Where:
* ``ssid`` sets the AP SSID.
* ``passphrase`` sets the AP password. Set as ``NULL`` for open networks.
* ``channel`` sets the Wi-Fi channel.
* ``uint8_t* bssid`` sets the AP BSSID.
* ``connect`` sets ``true`` to connect to the configured network automatically.
.. code-block:: arduino
wl_status_t begin(char* ssid, char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = true);
Where:
* ``ssid`` sets the AP SSID.
* ``passphrase`` sets the AP password. Set as ``NULL`` for open networks.
* ``channel`` sets the Wi-Fi channel.
* ``bssid`` sets the AP BSSID.
* ``connect`` sets ``true`` to connect to the configured network automatically.
Function to start the connection after being configured.
.. code-block:: arduino
wl_status_t begin();
config
******
Function ``config`` is used to configure Wi-Fi. After configuring, you can call function ``begin`` to start the Wi-Fi process.
.. code-block:: arduino
bool config(IPAddress local_ip, IPAddress gateway, IPAddress subnet, IPAddress dns1 = (uint32_t)0x00000000, IPAddress dns2 = (uint32_t)0x00000000);
Where:
* ``local_ip`` sets the local IP.
* ``gateway`` sets the gateway IP.
* ``subnet`` sets the subnet mask.
* ``dns1`` sets the DNS.
* ``dns2`` sets the DNS alternative option.
The function will return ``true`` if the configuration is successful.
The ``IPAddress`` format is defined by 4 bytes as described here:
.. code-block:: arduino
IPAddress(uint8_t first_octet, uint8_t second_octet, uint8_t third_octet, uint8_t fourth_octet);
Example:
.. code-block:: arduino
IPAddress local_ip(192, 168, 10, 20);
See the ``WiFiClientStaticIP.ino`` for more details on how to use this feature.
STA Connection
--------------
reconnect
*********
Function used to reconnect the Wi-Fi connection.
.. code-block:: arduino
bool reconnect();
disconnect
**********
Function to force disconnection.
.. code-block:: arduino
bool disconnect(bool wifioff = false, bool eraseap = false);
Where:
* ``wifioff`` use ``true`` to turn the Wi-Fi radio off.
* ``eraseap`` use ``true`` to erase the AP configuration from the NVS memory.
The function will return ``true`` if the configuration is successful.
isConnected
***********
Function used to get the connection state.
.. code-block:: arduino
bool isConnected();
Return the connection state.
setAutoConnect
**************
Function used to set the automatic connection.
.. code-block:: arduino
bool setAutoConnect(bool autoConnect);
Where:
* ``bool autoConnect`` is set to ``true`` to enable this option.
getAutoConnect
**************
Function used to get the automatic connection setting value.
.. code-block:: arduino
bool getAutoConnect();
The function will return ``true`` if the setting is enabled.
setAutoReconnect
****************
Function used to set the automatic reconnection if the connection is lost.
.. code-block:: arduino
bool setAutoReconnect(bool autoReconnect);
Where:
* ``autoConnect`` is set to ``true`` to enable this option.
getAutoReconnect
****************
Function used to get the automatic reconnection if the connection is lost.
.. code-block:: arduino
bool getAutoReconnect();
The function will return ``true`` if this setting is enabled.
WiFiMulti
---------
The ``WiFiMulti`` allows you to add more than one option for the AP connection while running as a station.
To add the AP, use the following function. You can add multiple AP's and this library will handle the connection.
.. code-block:: arduino
bool addAP(const char* ssid, const char *passphrase = NULL);
After adding the AP's, run by the following function.
.. code-block:: arduino
uint8_t run(uint32_t connectTimeout=5000);
To see how to use the ``WiFiMulti``, take a look at the ``WiFiMulti.ino`` example available.
WiFiScan
--------
To perform the Wi-Fi scan for networks, you can use the following functions:
Start scan WiFi networks available.
.. code-block:: arduino
int16_t scanNetworks(bool async = false, bool show_hidden = false, bool passive = false, uint32_t max_ms_per_chan = 300, uint8_t channel = 0);
Called to get the scan state in Async mode.
.. code-block:: arduino
int16_t scanComplete();
Delete last scan result from RAM.
.. code-block:: arduino
void scanDelete();
Loads all infos from a scanned wifi in to the ptr parameters.
.. code-block:: arduino
bool getNetworkInfo(uint8_t networkItem, String &ssid, uint8_t &encryptionType, int32_t &RSSI, uint8_t* &BSSID, int32_t &channel);
To see how to use the ``WiFiScan``, take a look at the ``WiFiScan.ino`` example available.
Examples
--------
.. _ap example:
Wi-Fi AP Example
****************
.. literalinclude:: ../../../libraries/WiFi/examples/WiFiAccessPoint/WiFiAccessPoint.ino
:language: arduino
.. _sta example:
Wi-Fi STA Example
*****************
.. literalinclude:: ../../../libraries/WiFi/examples/WiFiClient/WiFiClient.ino
:language: arduino
References
----------
docs/source/boards/ESP32-C3-DevKitM-1.rst 0 → 100644
浏览文件 @ 1effae46
##################
ESP32-C3-DevKitM-1
##################
The ESP32-C3-DevKitM-1 development board is one of Espressif's official boards. This board is based on the `ESP32-C3-MINI-1`_ module, with the `ESP32-C3`_ as the core.
Specifications
--------------
- Small­ sized 2.4 GHz Wi­Fi (802.11 b/g/n) and Bluetooth® 5 module
- Built around ESP32­C3 series of SoCs, RISC­V single­core microprocessor
- 4 MB flash in chip package
- 15 available GPIOs (module)
- Peripherals
- 22 × programmable GPIOs
- Digital interfaces:
- 3 × SPI
- 2 × UART
- 1 × I2C
- 1 × I2S
- Remote control peripheral, with 2 transmit channels and 2 receive channels
- LED PWM controller, with up to 6 channels
- Full-speed USB Serial/JTAG controller
- General DMA controller (GDMA), with 3 transmit channels and 3 receive channels
- 1 × TWAI® controller (compatible with ISO 11898-1)
- Analog interfaces:
- 2 × 12-bit SAR ADCs, up to 6 channels
- 1 × temperature sensor
- Timers:
- 2 × 54-bit general-purpose timers
- 3 × watchdog timers
- 1 × 52-bit system timer
- On­board PCB antenna or external antenna connector
Header Block
------------
.. note::
Not all of the chip pins are exposed to the pin headers.
J1
^^^
=== ==== ========== ===================================
No. Name Type [1]_ Function
=== ==== ========== ===================================
1 GND G Ground
2 3V3 P 3.3 V power supply
3 3V3 P 3.3 V power supply
4 IO2 I/O/T GPIO2 [2]_, ADC1_CH2, FSPIQ
5 IO3 I/O/T GPIO3, ADC1_CH3
6 GND G Ground
7 RST I CHIP_PU
8 GND G Ground
9 IO0 I/O/T GPIO0, ADC1_CH0, XTAL_32K_P
10 IO1 I/O/T GPIO1, ADC1_CH1, XTAL_32K_N
11 IO10 I/O/T GPIO10, FSPICS0
12 GND G Ground
13 5V P 5 V power supply
14 5V P 5 V power supply
15 GND G Ground
=== ==== ========== ===================================
J3
^^^
=== ==== ========== ====================================
No. Name Type [1]_ Function
=== ==== ========== ====================================
1 GND G Ground
2 TX I/O/T GPIO21, U0TXD
3 RX I/O/T GPIO20, U0RXD
4 GND G Ground
5 IO9 I/O/T GPIO9 [2]_
6 IO8 I/O/T GPIO8 [2]_, RGB LED
7 GND G Ground
8 IO7 I/O/T GPIO7, FSPID, MTDO
9 IO6 I/O/T GPIO6, FSPICLK, MTCK
10 IO5 I/O/T GPIO5, ADC2_CH0, FSPIWP, MTDI
11 IO4 I/O/T GPIO4, ADC1_CH4, FSPIHD, MTMS
12 GND G Ground
13 IO18 I/O/T GPIO18, USB_D-
14 IO19 I/O/T GPIO19, USB_D+
15 GND G Ground
=== ==== ========== ====================================
.. [1] P: Power supply; I: Input; O: Output; T: High impedance.
.. [2] GPIO2, GPIO8, and GPIO9 are strapping pins of the ESP32-C3FN4 chip. During the chip's system reset, the latches of the strapping pins sample the voltage level as strapping bits, and hold these bits until the chip is powered down or shut down.
Pin Layout
----------
.. figure:: ../_static/esp32-c3_devkitM-1_pinlayout.png
:align: center
:width: 600
:alt: ESP32-C3-DevKitM-1 (click to enlarge)
:figclass: align-center
Strapping Pins
--------------
Some of the GPIO's have important features during the booting process. Here is the list of the strapping pins on the `ESP32-C3`_.
==== ========= ===================================================================== ================ =================
GPIO Default Function Pull-up Pull-down
==== ========= ===================================================================== ================ =================
IO2 N/A Booting Mode See `ESP32-C3`_ See `ESP32-C3`_
IO9 Pull-up Booting Mode SPI Boot Download Boot
IO8 N/A Booting Mode Don't Care Download Boot
IO8 Pull-up Enabling/Disabling Log Print See `ESP32-C3`_ See `ESP32-C3`_
==== ========= ===================================================================== ================ =================
For more detailed information, see the `ESP32-C3`_ datasheet.
Resources
---------
* `ESP32-C3`_ (Datasheet)
* `ESP32-C3-MINI-1`_ (Datasheet)
.. _ESP32-C3: https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf
.. _ESP32-C3-MINI-1: https://www.espressif.com/sites/default/files/documentation/esp32-c3-mini-1_datasheet_en.pdf
docs/source/boards/ESP32-DevKitC-1.rst 0 → 100644
浏览文件 @ 1effae46
###############
ESP32-DevKitC-1
###############
The `ESP32-DevKitC-1`_ development board is one of Espressif's official boards. This board is based on the `ESP32-WROVER-E`_ module, with the `ESP32`_ as the core.
Specifications
--------------
- Wi-Fi 802.11 b/g/n (802.11n up to 150 Mbps)
- Bluetooth v4.2 BR/EDR and BLE specification
- Built around ESP32 series of SoCs
- Integrated 4 MB SPI flash
- Integrated 8 MB PSRAM
- Peripherals
- SD card
- UART
- SPI
- SDIO
- I2C
- LED PWM
- Motor PWM
- I2S
- IR
- Pulse Counter
- GPIO
- Capacitive Touch Sensor
- ADC
- DAC
- Two-Wire Automotive Interface (TWAI®, compatible with ISO11898-1)
- On­board PCB antenna or external antenna connector
Header Block
------------
.. note::
Not all of the chip pins are exposed to the pin headers.
J1
^^^
=== ==== ===== ===================================
No. Name Type Function
=== ==== ===== ===================================
1 3V3 P 3.3 V power supply
2 EN I CHIP_PU, Reset
3 IO36 I GPIO36, ADC1_CH0, S_VP
4 IO39 I GPIO39, ADC1_CH3, S_VN
5 IO34 I GPIO34, ADC1_CH6, VDET_1
6 IO35 I GPIO35, ADC1_CH7, VDET_2
7 IO32 I/O GPIO32, ADC1_CH4, TOUCH_CH9, XTAL_32K_P
8 IO33 I/O GPIO33, ADC1_CH5, TOUCH_CH8, XTAL_32K_N
9 IO25 I/O GPIO25, ADC1_CH8, DAC_1
10 IO26 I/O GPIO26, ADC2_CH9, DAC_2
11 IO27 I/O GPIO27, ADC2_CH7, TOUCH_CH7
12 IO14 I/O GPIO14, ADC2_CH6, TOUCH_CH6, MTMS
13 IO12 I/O GPIO12, ADC2_CH5, TOUCH_CH5, MTDI
14 GND G Ground
15 IO13 I/O GPIO13, ADC2_CH4, TOUCH_CH4, MTCK
16 IO9 I/O GPIO9, D2
17 IO10 I/O GPIO10, D3
18 IO11 I/O GPIO11, CMD
19 5V0 P 5 V power supply
=== ==== ===== ===================================
J3
^^^
=== ==== ===== ====================================
No. Name Type Function
=== ==== ===== ====================================
1 GND G Ground
2 IO23 I/O GPIO23
3 IO22 I/O GPIO22
4 IO1 I/O GPIO1, U0TXD
5 IO3 I/O GPIO3, U0RXD
6 IO21 I/O GPIO21
7 GND G Ground
8 IO19 I/O GPIO19
9 IO18 I/O GPIO18
10 IO5 I/O GPIO5
11 IO17 I/O GPIO17
12 IO16 I/O GPIO16
13 IO4 I/O GPIO4, ADC2_CH0, TOUCH_CH0
14 IO0 I/O GPIO0, ADC2_CH1, TOUCH_CH1, Boot
16 IO2 I/O GPIO2, ADC2_CH2, TOUCH_CH2
17 IO15 I/O GPIO15, ADC2_CH3, TOUCH_CH3, MTDO
17 IO8 I/O GPIO8, D1
18 IO7 I/O GPIO7, D0
19 IO6 I/O GPIO6, SCK
=== ==== ===== ====================================
P: Power supply;
I: Input;
O: Output;
T: High impedance.
Pin Layout
----------
.. figure:: ../_static/esp32_devkitC_pinlayout.png
:align: center
:width: 600
:alt: ESP32-DevKitC-1 (click to enlarge)
:figclass: align-center
Strapping Pins
--------------
Some of the GPIO's have important features during the booting process. Here is the list of the strapping pins on the `ESP32`_.
==== ========= ===================================================================== ============ ==============
GPIO Default Function Pull-up Pull-down
==== ========= ===================================================================== ============ ==============
IO12 Pull-down Voltage of Internal LDO (VDD_SDIO) 1V8 3V3
IO0 Pull-up Booting Mode SPI Boot Download Boot
IO2 Pull-down Booting Mode Don't Care Download Boot
IO15 Pull-up Enabling/Disabling Log Print During Booting and Timing of SDIO Slave U0TXD Active U0TXD Silent
IO5 Pull-up Timing of SDIO Slave See `ESP32`_ See `ESP32`_
==== ========= ===================================================================== ============ ==============
Be aware when choosing which pins to use.
Restricted Usage GPIO's
-----------------------
Some of the GPIO's are used for the external flash and PSRAM. These GPIO's cannot be used:
==== ===================
GPIO Shared Function
==== ===================
IO6 External SPI Flash
IO7 External SPI Flash
IO8 External SPI Flash
IO9 External SPI Flash
IO10 External SPI Flash
IO11 External SPI Flash
==== ===================
Other GPIO's are `INPUT ONLY` and cannot be used as output pin:
==== =========================
GPIO Function
==== =========================
IO34 GPIO34, ADC1_CH6, VDET_1
IO35 GPIO35, ADC1_CH7, VDET_2
IO36 GPIO36, ADC1_CH0, S_VP
IO39 GPIO39, ADC1_CH3, S_VN
==== =========================
Resources
---------
* `ESP32`_ (Datasheet)
* `ESP32-WROVER-E`_ (Datasheet)
* `ESP32-DevKitC`_ (Schematic)
.. _ESP32: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf
.. _ESP32-WROVER-E: https://www.espressif.com/sites/default/files/documentation/esp32-wrover-e_esp32-wrover-ie_datasheet_en.pdf
.. _ESP32-DevKitC: https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch.pdf
docs/source/boards/ESP32-S2-Saola-1.rst 0 → 100644
浏览文件 @ 1effae46
################
ESP32-S2-Saola-1
################
The `ESP32-S2-Saola-1`_ development board is one of Espressif's official boards. This board is based on the `ESP32-S2-WROVER`_ module, with the `ESP32-S2`_ as the core.
Specifications
--------------
- Wi-Fi 802.11 b/g/n (802.11n up to 150 Mbps)
- Built around ESP32-S2 series of SoCs Xtensa® single-core
- Integrated 4 MB SPI flash
- Integrated 2 MB PSRAM
- Peripherals
- 43 × programmable GPIOs
- 2 × 13-bit SAR ADCs, up to 20 channels
- 2 × 8-bit DAC
- 14 × touch sensing IOs
- 4 × SPI
- 1 × I2S
- 2 × I2C
- 2 × UART
- RMT (TX/RX)
- LED PWM controller, up to 8 channels
- 1 × full-speed USB OTG
- 1 × temperature sensor
- 1 × DVP 8/16 camera interface, implemented using the hardware resources of I2S
- 1 × LCD interface (8-bit serial RGB/8080/6800), implemented using the hardware resources of SPI2
- 1 × LCD interface (8/16/24-bit parallel), implemented using the hardware resources of I2S
- 1 × TWAI® controller (compatible with ISO 11898-1)
- On­board PCB antenna or external antenna connector
Header Block
------------
.. note::
Not all of the chip pins are exposed to the pin headers.
J2
^^^
=== ==== ===== ===================================
No. Name Type Function
=== ==== ===== ===================================
1 3V3 P 3.3 V power supply
2 IO0 I/O GPIO0, Boot
3 IO1 I/O GPIO1, ADC1_CH0, TOUCH_CH1
4 IO2 I/O GPIO2, ADC1_CH1, TOUCH_CH2
5 IO3 I/O GPIO3, ADC1_CH2, TOUCH_CH3
6 IO4 I/O GPIO4, ADC1_CH3, TOUCH_CH4
7 IO5 I/O GPIO5, ADC1_CH4, TOUCH_CH5
8 IO6 I/O GPIO6, ADC1_CH5, TOUCH_CH6
9 IO7 I/O GPIO7, ADC1_CH6, TOUCH_CH7
10 IO8 I/O GPIO8, ADC1_CH7, TOUCH_CH8
11 IO9 I/O GPIO9, ADC1_CH8, TOUCH_CH9
12 IO10 I/O GPIO10, ADC1_CH9, TOUCH_CH10
13 IO11 I/O GPIO11, ADC2_CH0, TOUCH_CH11
14 IO12 I/O GPIO12, ADC2_CH1, TOUCH_CH12
15 IO13 I/O GPIO13, ADC2_CH2, TOUCH_CH13
16 IO14 I/O GPIO14, ADC2_CH3, TOUCH_CH14
17 IO15 I/O GPIO15, ADC2_CH4, XTAL_32K_P
18 IO16 I/O GPIO16, ADC2_CH5, XTAL_32K_N
19 IO17 I/O GPIO17, ADC2_CH6, DAC_1
20 5V0 P 5 V power supply
21 GND G Ground
=== ==== ===== ===================================
J3
^^^
=== ==== ===== ====================================
No. Name Type Function
=== ==== ===== ====================================
1 GND G Ground
2 RST I CHIP_PU, Reset
3 IO46 I GPIO46
4 IO45 I/O GPIO45
5 IO44 I/O GPIO44, U0RXD
6 IO43 I/O GPIO43, U0TXD
7 IO42 I/O GPIO42, MTMS
8 IO41 I/O GPIO41, MTDI
9 IO40 I/O GPIO40, MTDO
10 IO39 I/O GPIO39, MTCK
11 IO38 I/O GPIO38
12 IO37 I/O GPIO37
13 IO36 I/O GPIO36
14 IO35 I/O GPIO35
16 IO34 I/O GPIO34
17 IO33 I/O GPIO33
17 IO26 I/O GPIO26
18 IO21 I/O GPIO21
19 IO20 I/O GPIO20, ADC2_CH3, USB_D+
20 IO19 I/O GPIO19, ADC2_CH3, USB_D-
21 IO18 I/O GPIO18, ADC2_CH3, DAC_2
=== ==== ===== ====================================
P: Power supply;
I: Input;
O: Output;
T: High impedance.
Pin Layout
----------
.. figure:: ../_static/esp32-s2_saola1_pinlayout.png
:align: center
:width: 600
:alt: ESP32-S2-Saola-1 (click to enlarge)
:figclass: align-center
Strapping Pins
--------------
Some of the GPIO's have important features during the booting process. Here is the list of the strapping pins on the `ESP32-S2`_.
==== ========= ===================================================================== ============ ==============
GPIO Default Function Pull-up Pull-down
==== ========= ===================================================================== ============ ==============
IO45 Pull-down Voltage of Internal LDO (VDD_SDIO) 1V8 3V3
IO0 Pull-up Booting Mode SPI Boot Download Boot
IO46 Pull-down Booting Mode Don't Care Download Boot
IO46 Pull-up Enabling/Disabling Log Print During Booting and Timing of SDIO Slave U0TXD Active U0TXD Silent
==== ========= ===================================================================== ============ ==============
For more detailed information, see the `ESP32-S2`_ datasheet.
Restricted Usage GPIOS
----------------------
Some of the GPIO's are used for the external flash and PSRAM. These GPIO's cannot be used:
==== ===================
GPIO Shared Function
==== ===================
IO26 Connected to PSRAM
==== ===================
Other GPIO's are `INPUT ONLY` and cannot be used as output pin:
==== ===========================
GPIO Function
==== ===========================
IO46 GPIO46
==== ===========================
Resources
---------
* `ESP32-S2`_ (Datasheet)
* `ESP32-S2-WROVER`_ (Datasheet)
* `ESP32-S2-Saola-1`_ (Schematics)
.. _ESP32-S2: https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf
.. _ESP32-S2-WROVER: https://www.espressif.com/sites/default/files/documentation/esp32-s2-wrover_esp32-s2-wrover-i_datasheet_en.pdf
.. _ESP32-S2-Saola-1: https://dl.espressif.com/dl/schematics/ESP32-S2-SAOLA-1_V1.1_schematics.pdf
docs/source/boards/boards.rst 0 → 100644
浏览文件 @ 1effae46
######
Boards
######
Development Boards
------------------
You will need a development board or a custom board with the ESP32 (see Supported SoC's) to start playing.
There is a bunch of different types and models widely available on the Internet. You need to choose one that covers all your requirements.
To help you on this selection, we point out some facts about choosing the proper boardsto help you to save money and time.
**One ESP32 to rule them all!**
One important information that usually bring about some confusion is regarding the different models of the ESP32 SoC and modules.
The ESP32 is divided by family:
* ESP32
* Wi-Fi and BLE
* ESP32-S
* Wi-Fi only
* ESP32-C
* Wi-Fi and BLE 5
For each family, we have SoC variants with some differentiation. The differences are more about the embedded flash and its size and the number of the cores (dual or single).
The modules use the SoC internally, including the external flash, PSRAM (in some models) and other essential electronic components. Essentially, all
modules from the same family use the same SoC.
.. figure:: ../_static/soc-module.png
:align: center
:width: 250
:alt: ESP32 SoC and Module (click to enlarge)
:figclass: align-center
**For example:**
The SoC partnumber is the ESP32-D0WD-V3 and it's the same SoC used inside of the ESP32-WROVER (with PSRAM) and ESP32-WROOM modules. This means that the
same characteristics are present in both modules' core.
For more detailed information regarding the SoC's and modules, see the `Espressif Product Selector`_.
Now that you know that the module can be different but the heart is the same, you can choose your development board.
Before buying: Keep in mind that for some "must have" features when choosing the best board for your needs:
- Embedded USB-to-Serial
- This is very convenient for programming and monitoring the logs with the terminal via USB.
- Breadboard friendly
- If you are prototyping, this will be very useful to connect your board directly on the breadboard.
- open-source/open-hardware
- Check if the schematics are available for download. This helps a lot on prototyping.
- Support
- Some of the manufacturers offer a very good level of support, with examples and demo projects.
Espressif
---------
.. figure:: ../_static/logo_espressif.png
:align: center
:width: 250
:alt: Espressif Logo
:figclass: align-center
.. toctree::
:maxdepth: 1
ESP32-DevKitC <ESP32-DevKitC-1>
ESP32-S2-Saola-1 <ESP32-S2-Saola-1>
ESP32-C3-DevKitM-1 <ESP32-C3-DevKitM-1>
Third Party
-----------
Add here the third party boards, listed by vendors.
.. note::
All the information must be provided by the vendor. If your favorite board is not here, consider
creating an `issue on GitHub <https://github.com/espressif/arduino-esp32/issues>`_ and directly
link/mention the vendor in the issue description.
Generic Vendor
**************
.. toctree::
:maxdepth: 1
Generic Board Name <generic>
.. note::
Create one file per board or one file with multiple boards. Do not add board information/description on this file.
Resources
---------
* `ESP32 Datasheet`_ (Datasheet)
* `ESP32-S2 Datasheet`_ (Datasheet)
* `ESP32-C3 Datasheet`_ (Datasheet)
.. _Espressif Systems: https://www.espressif.com
.. _Espressif Product Selector: https://products.espressif.com/
.. _ESP32 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf
.. _ESP32-S2 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf
.. _ESP32-C3 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf
docs/source/boards/generic.rst 0 → 100644
浏览文件 @ 1effae46
####################
Generic ESP32 Boards
####################
Specifications
--------------
Add here the board/kit specifications.
Header Block
------------
Header1
^^^^^^^
=== ==== ===== ===================================
No. Name Type Function
=== ==== ===== ===================================
1 3V3 P 3.3 V power supply
2 IO0 I/O GPIO0, Boot
3 5V0 P 5 V power supply
4 GND G Ground
=== ==== ===== ===================================
Pin Layout
----------
Add here the pin layout image (not required).
Resources
---------
* `ESP32`_ (Datasheet)
.. _ESP32: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf
docs/source/conf.py 0 → 100644
浏览文件 @ 1effae46
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'Arduino-ESP32'
copyright = '2021, Espressif'
author = 'Espressif'
# The full version, including alpha/beta/rc tags
release = '2.0.0'
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx_copybutton'
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'default'
html_logo = 'logo_espressif.png'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Style
# pygments_style = "sphinx"
docs/source/contributing.rst 0 → 100644
浏览文件 @ 1effae46
###################
Contributions Guide
###################
We welcome contributions to the Arduino ESP32 project!
How to Contribute
-----------------
Contributions to the Arduino ESP32 (fixing bugs, adding features, adding documentation) are welcome.
We accept contributions via `Github Pull Requests <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_.
Before Contributing
-------------------
Before sending us a Pull Request, please consider this:
* Is the contribution entirely your own work, or is it already licensed under an LGPL 2.1 compatible Open Source License? If not, we unfortunately cannot accept it.
* Is the code adequately commented for people to understand how it is structured?
* Is there documentation or examples that go with code contributions?
* 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 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/>`_?
If you're unsure about any of these points, please open the Pull Request anyhow and then ask us for feedback.
Pull Request Process
--------------------
After you open the Pull Request, there will probably be some discussion in the comments' field of the request itself.
Once the Pull Request is ready to merge, it will first be merged into our internal git system for in-house automated testing.
If this process passes, it will be merged onto the public github repository.
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
docs/source/esp-idf_component.rst 0 → 100644
浏览文件 @ 1effae46
##############################
Arduino as a ESP-IDF component
##############################
ESP32 Arduino lib-builder
-------------------------
For a simplified method, see `lib-builder <lib_builder>`_.
Installation
------------
- Download and install `ESP-IDF <https://github.com/espressif/esp-idf>`_.
- Create blank idf project (from one of the examples).
- In the project folder, create a new folder called `components` and clone this repository inside the new created folder.
.. code-block:: bash
mkdir -p components && \
cd components && \
git clone https://github.com/espressif/arduino-esp32.git arduino && \
cd arduino && \
git submodule update --init --recursive && \
cd ../.. && \
idf.py menuconfig
- The `idf.py menuconfig` has some Arduino options.
- On `Autostart Arduino setup and loop on boot`.
- If you enable these options, your main.cpp should be formated like any other sketch.
.. code-block:: c
//file: main.cpp
#include "Arduino.h"
void setup(){
Serial.begin(115200);
}
void loop(){
Serial.println("loop");
delay(1000);
}
- Otherwise, you need to implement ```app_main()``` and call ```initArduino();``` in it.
Keep in mind that setup() and loop() will not be called in this case.
If you plan to base your code on examples provided in `examples <https://github.com/espressif/esp-idf/tree/master/examples>`_, please make sure to move the app_main() function in main.cpp from the files in the example.
.. code-block:: cpp
//file: main.cpp
#include "Arduino.h"
extern "C" void app_main()
{
initArduino();
pinMode(4, OUTPUT);
digitalWrite(4, HIGH);
//do your own thing
}
- "Disable mutex locks for HAL"
- If enabled, there will be no protection on the drivers from concurently accessing them from another thread/interrupt/core
- "Autoconnect WiFi on boot"
- If enabled, WiFi will start with the last known configuration
- Otherwise it will wait for WiFi.begin
- ```idf.py -p <your-board-serial-port> flash monitor``` will build, upload and open serial monitor to your board
Logging To Serial
-----------------
If you are writing code that does not require Arduino to compile and you want your `ESP_LOGx` macros to work in Arduino IDE, you can enable the compatibility by adding the following lines after:
.. code-block:: c
#ifdef ARDUINO_ARCH_ESP32
#include "esp32-hal-log.h"
#endif
FreeRTOS Tick Rate (Hz)
-----------------------
You might notice that Arduino-esp32's `delay()` function will only work in multiples of 10ms. That is because, by default, esp-idf handles task events 100 times per second.
To fix that behavior, you need to set FreeRTOS tick rate to 1000Hz in `make menuconfig` -> `Component config` -> `FreeRTOS` -> `Tick rate`.
Compilation Errors
------------------
As commits are made to esp-idf and submodules, the codebases can develop incompatibilities which cause compilation errors. If you have problems compiling, follow the instructions in `Issue #1142 <https://github.com/espressif/arduino-esp32/issues/1142>`_ to roll esp-idf back to a different version.
docs/source/faq.rst 0 → 100644
浏览文件 @ 1effae46
##########################
Frequently Asked Questions
##########################
docs/source/getting_started.rst 0 → 100644
浏览文件 @ 1effae46
###############
Getting Started
###############
About Arduino ESP32
-------------------
Welcome to the Arduino ESP32 support documentation! Here you will find important information on how to use the project.
First Things First
------------------
.. note::
Before continuing, we must be clear that this project is supported by `Espressif Systems`_ and the community.
Everyone is more than welcome to contribute back to this project.
ESP32 is a single 2.4 GHz Wi-Fi-and-Bluetooth SoC (System On a Chip) designed by `Espressif Systems`_.
ESP32 is designed for mobile, wearable electronics, and Internet-of-Things (IoT) applications. It features all the state-of-the-art characteristics
of low-power chips, including fine-grained clock gating, multiple power modes,and dynamic power scaling. For instance, in a low-power IoT sensor
hub application scenario, ESP32 is woken-up periodically and only when a specified condition is detected. Low-duty cycle is used to minimize the
amount of energy that the chip expends.
The output of the power amplifier is also adjustable, thus contributing to an optimal trade-off between communication range, data rate and
power consumption.
The ESP32 series is available as a chip or module.
Supported SoC's
---------------
Here are the ESP32 series supported by the Arduino-ESP32 project:
======== ====== =========== ===================================
SoC Stable Development Datasheet
======== ====== =========== ===================================
ESP32 Yes Yes `ESP32 Datasheet`_
ESP32-S2 No Yes `ESP32-S2 Datasheet`_
ESP32-C3 No Yes `ESP32-C3 Datasheet`_
ESP32-S3 No No Not Available Yet
======== ====== =========== ===================================
See `Boards <boards/boards.html>`_ for more details about ESP32 development boards.
Arduino Core Reference
----------------------
This documentation is built on the ESP32 and we are not going to cover the common Arduino API. To see the Arduino reference documentation,
please consider reading the official documentation.
Arduino Official Documentation: `Arduino Reference`_.
Supported Operating Systems
---------------------------
+-------------------+-------------------+-------------------+
| |windows-logo| | |linux-logo| | |macos-logo| |
+-------------------+-------------------+-------------------+
| Windows | Linux | macOS |
+-------------------+-------------------+-------------------+
.. |windows-logo| image:: _static/logo_windows.png
.. |linux-logo| image:: _static/logo_linux.png
.. |macos-logo| image:: _static/logo_macos.png
See `Installing Guides <installing.html>`_ for more details on how to install the Arduino ESP32 support.
Support
-------
This is an open project and it's supported by the community. Fell free to ask for help in one of the community channels.
Community
---------
The Arduino community is huge! You can find a lot of useful content on the Internet.
Here are some community channels where you may find information and ask for some help, if needed.
- `ESP32 Forum`_: Official Espressif Forum.
- `ESP32 Forum - Arduino`_: Official Espressif Forum for Arduino related discussions.
- `ESP32 Forum - Hardware`_: Official Espressif Forum for Hardware related discussions.
- `Gitter`_
- `Espressif MCUs (Discord)`_
- `ESP32 on Reddit`_
Issues Reporting
----------------
Before opening a new issue, please read this:
Be sure to search for a similar reported issue. This avoids duplicating or creating noise in the GitHub Issues reporting.
We also have the troubleshooting guide to save your time on the most common issues reported by users.
For more details, see the `Issue Template <https://github.com/espressif/arduino-esp32/blob/master/docs/ISSUE_TEMPLATE.md>`_.
First Steps
-----------
Here are the first steps to get the Arduino ESP32 support running.
To install Arduino-ESP32, please see the dedicated section on the Installation guide. We recommend you install it using the boards manager.
.. toctree::
:maxdepth: 2
How to Install <installing>
Development Boards <boards/boards>
Examples
--------
After installing the toolchain into your environment, you will be able to see all the dedicated examples for the ESP32. These examples are located
in the examples menu or inside each library folder.
https://github.com/espressif/arduino-esp32/tree/master/libraries
Resources
---------
.. _Espressif Systems: https://www.espressif.com
.. _Espressif Product Selector: https://products.espressif.com/
.. _ESP32 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf
.. _ESP32-S2 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf
.. _ESP32-C3 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf
.. _Arduino.cc: https://www.arduino.cc/en/Main/Software
.. _Arduino Reference: https://www.arduino.cc/reference/en/
.. _ESP32 Forum: https://esp32.com
.. _ESP32 Forum - Arduino: https://esp32.com/viewforum.php?f=19
.. _ESP32 Forum - Hardware: https://esp32.com/viewforum.php?f=12
.. _Gitter: https://gitter.im/espressif/arduino-esp32
.. _Adafruit (Discord): https://discord.gg/adafruit
.. _Espressif MCUs (Discord): https://discord.gg/nKxMTnkD
.. _ESP32 on Reddit: https://www.reddit.com/r/esp32
docs/source/index.rst 0 → 100644
浏览文件 @ 1effae46
#############################################
Welcome to ESP32 Arduino Core's documentation
#############################################
Here you will find all the relevant information about the project.
.. note::
This is a work in progress documentation and we will appreciate your help! We are looking for contributors!
.. toctree::
:maxdepth: 2
:caption: Contents:
Getting Started <getting_started>
Libraries <libraries>
Tutorials <tutorials/tutorials>
Advanced Utilities <advanced_utils>
FAQ <faq>
Troubleshooting <troubleshooting>
Contributing <contributing>
docs/source/installing.rst 0 → 100644
浏览文件 @ 1effae46
##########
Installing
##########
This guide will show how to install the Arduino-ESP32 support.
Before Installing
-----------------
We recommend you install the support using the Boards Manager, but other options are available depending on your operating system.
To install Arduino-ESP32 support, you can use one of the following options.
Installing using Boards Manager
-------------------------------
This is the preferred and easiest way to install Arduino-ESP32.
.. note::
Currently, the support for new chips (ESP32-S2 and ESP32-C3) is in the development release. Consider installing the development release if you need to test the new supported SoC in beta.
- Stable release link::
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
- Development release link::
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_dev_index.json
.. note::
Starting with the Arduino IDE version 1.6.4, Arduino allows installation of third-party platform
packages using Boards Manager. We have packages available for Windows, macOS, and Linux (x86, amd64, armhf and arm64).
To start the installation process using the Boards Managaer, follow these steps:
- Install the current upstream Arduino IDE at the 1.8 level or later. The current version is at the `arduino.cc`_ website.
- Start Arduino and open the Preferences window.
.. figure:: _static/install_guide_preferences.png
:align: center
:width: 600
:figclass: align-center
- Enter one of the release links above into *Additional Board Manager URLs* field. You can add multiple URLs, separating them with commas.
.. figure:: _static/install_guide_boards_manager_url.png
:align: center
:width: 600
:figclass: align-center
- Open Boards Manager from Tools > Board menu and install *esp32* platform (and do not forget to select your ESP32 board from Tools > Board menu after installation).
.. figure:: _static/install_guide_boards_manager_esp32.png
:align: center
:width: 600
:figclass: align-center
- Restart Arduino IDE.
Windows
-------
Steps to install Arduino ESP32 support on Windows:
.. note::
Tested on Windows 10 32 and 64 bit machines.
**Step 1**
1. Download and install the latest Arduino IDE ``Windows Installer`` from [arduino.cc](https://www.arduino.cc/en/Main/Software)
2. Download and install Git from [git-scm.com](https://git-scm.com/download/win)
3. Start ``Git GUI`` and do the following steps:
- Select ``Clone Existing Repository``
.. figure:: _static/win-gui-1.png
:align: center
:width: 600
:figclass: align-center
- Select source and destination
- Sketchbook Directory: Usually ``C:/Users/[YOUR_USER_NAME]/Documents/Arduino`` and is listed underneath the "Sketchbook location" in Arduino preferences.
- Source Location: ``https://github.com/espressif/arduino-esp32.git``
- Target Directory: ``[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32``
- Click ``Clone`` to start cloning the repository
**Step 2**
.. figure:: _static/win-gui-2.png
:align: center
:figclass: align-center
**Step 3**
.. figure:: _static/win-gui-3.png
:align: center
:figclass: align-center
- open a `Git Bash` session pointing to ``[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32`` and execute ```git submodule update --init --recursive```
- Open ``[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32/tools`` and double-click ``get.exe``
**Step 4**
.. figure:: _static/win-gui-4.png
:align: center
:figclass: align-center
- When ```get.exe``` finishes, you should see the following files in the directory
**Step 5**
.. figure:: _static/win-gui-5.png
:align: center
:figclass: align-center
1. Plug your ESP32 board and wait for the drivers to install (or install manually any that might be required)
2. Start Arduino IDE
3. Select your board in ``Tools > Board`` menu
4. Select the COM port that the board is attached to
5. Compile and upload (You might need to hold the boot button while uploading)
.. figure:: _static/arduino-ide.png
:align: center
:figclass: align-center
How to update to the latest code
********************************
1. Start ``Git GUI`` and you should see the repository under ``Open Recent Repository``. Click on it!
.. figure:: _static/win-gui-update-1.png
:align: center
:figclass: align-center
1. From menu ``Remote`` select ``Fetch from`` > ``origin``
.. figure:: _static/win-gui-update-2.png
:align: center
:figclass: align-center
1. Wait for git to pull any changes and close ``Git GUI``
2. Open ``[ARDUINO_SKETCHBOOK_DIR]/hardware/espressif/esp32/tools`` and double-click ``get.exe``
.. figure:: _static/win-gui-4.png
:align: center
:figclass: align-center
Linux
-----
Debian/Ubuntu
*************
- Install latest Arduino IDE from `arduino.cc`_.
- Open Terminal and execute the following command (copy -> paste and hit enter):
.. code-block:: bash
sudo usermod -a -G dialout $USER && \
sudo apt-get install git && \
wget https://bootstrap.pypa.io/get-pip.py && \
sudo python3 get-pip.py && \
sudo pip3 install pyserial && \
mkdir -p ~/Arduino/hardware/espressif && \
cd ~/Arduino/hardware/espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
cd esp32 && \
git submodule update --init --recursive && \
cd tools && \
python3 get.py
- Restart Arduino IDE.
- If you have Arduino installed to ~/, modify the installation as follows, beginning at `mkdir -p ~/Arduino/hardware`:
.. code-block:: bash
cd ~/Arduino/hardware
mkdir -p espressif && \
cd espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
cd esp32 && \
git submodule update --init --recursive && \
cd tools && \
python3 get.py
Fedora
******
- Install the latest Arduino IDE from `arduino.cc`_.
.. note::
Command ``$ sudo dnf -y install arduino`` will most likely install an older release.
- Open Terminal and execute the following command (copy -> paste and hit enter):
.. code-block:: bash
sudo usermod -a -G dialout $USER && \
sudo dnf install git python3-pip python3-pyserial && \
mkdir -p ~/Arduino/hardware/espressif && \
cd ~/Arduino/hardware/espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
cd esp32 && \
git submodule update --init --recursive && \
cd tools && \
python get.py
- Restart Arduino IDE.
openSUSE
********
- Install the latest Arduino IDE from `arduino.cc`_.
- Open Terminal and execute the following command (copy -> paste and hit enter):
.. code-block:: bash
sudo usermod -a -G dialout $USER && \
if [ `python --version 2>&1 | grep '2.7' | wc -l` = "1" ]; then \
sudo zypper install git python-pip python-pyserial; \
else \
sudo zypper install git python3-pip python3-pyserial; \
fi && \
mkdir -p ~/Arduino/hardware/espressif && \
cd ~/Arduino/hardware/espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 && \
cd esp32 && \
git submodule update --init --recursive && \
cd tools && \
python get.py
- Restart Arduino IDE.
macOS
-----
- Install the latest Arduino IDE from `arduino.cc`_.
- Open Terminal and execute the following command (copy -> paste and hit enter):
.. code-block:: bash
mkdir -p ~/Documents/Arduino/hardware/espressif && \
cd ~/Documents/Arduino/hardware/espressif && \
git clone https://github.com/espressif/arduino-esp32.git esp32 --depth 1 && \
cd esp32 && \
git submodule update --init --recursive --depth 1 && \
cd tools && \
python get.py
Where ``~/Documents/Arduino`` represents your sketch book location as per "Arduino" > "Preferences" > "Sketchbook location" (in the IDE once started). Adjust the command above accordingly.
- If you get the error below, install through the command line dev tools with `xcode-select --install` and try the command above again:
.. code-block:: bash
xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun
- Run the command:
.. code-block:: bash
xcode-select --install
- Try ``python3`` instead of ``python`` if you get the error: ``IOError: [Errno socket error] [SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol version (_ssl.c:590)`` when running ``python get.py``
- If you get the following error when running ``python get.py`` urllib.error.URLError: <urlopen error SSL: CERTIFICATE_VERIFY_FAILED, go to Macintosh HD > Applications > Python3.6 folder (or any other python version), and run the following scripts: Install Certificates.command and Update Shell Profile.command
- Restart Arduino IDE.
PlatformIO
----------
- `What is PlatformIO? <https://docs.platformio.org/en/latest/what-is-platformio.html?utm_source=github&utm_medium=arduino-esp32>`_
- `PlatformIO IDE <https://platformio.org/platformio-ide?utm_source=github&utm_medium=arduino-esp32>`_
- `PlatformIO Core <https://docs.platformio.org/en/latest/core.html?utm_source=github&utm_medium=arduino-esp32>`_
- `Advanced usage <https://docs.platformio.org/en/latest/platforms/espressif32.html?utm_source=github&utm_medium=arduino-esp32>`_: Custom settings, uploading to SPIFFS, Over-the-Air (OTA), staging version
- `Integration with Cloud and Standalone IDEs <https://docs.platformio.org/en/latest/ide.html?utm_source=github&utm_medium=arduino-esp32>`_: Cloud9, Codeanywhere, Eclipse Che (Codenvy), Atom, CLion, Eclipse, Emacs, NetBeans, Qt Creator, Sublime Text, VIM, Visual Studio, and VSCode
- `Project Examples <https://docs.platformio.org/en/latest/platforms/espressif32.html?utm_source=github&utm_medium=arduino-esp32#examples>`_
.. _Arduino.cc: https://www.arduino.cc/en/Main/Software
docs/source/lib_builder.rst 0 → 100644
浏览文件 @ 1effae46
###############
Library Builder
###############
How to Use Library Builder
--------------------------
Espressif has provided a `tool <https://github.com/espressif/esp32-arduino-lib-builder>`_ to simplify building your own compiled libraries for use in Arduino IDE (or your favorite IDE).
To generate custom libraries, follow these steps:
- Step 1 - Clone the ESP32 Arduino lib builder::
git clone https://github.com/espressif/esp32-arduino-lib-builder
- Step 2 - Go to the ``esp32-arduino-lib-builder`` folder::
cd esp32-arduino-lib-builder
- Step 3 - Run the ``update-components`` script::
./tools/update-components.sh`
- Step 4 - Run ``install-esp-idf`` installation script (if you already have an ``$IDF_PATH`` defined, it will use your local copy of the repository)::
./tools/install-esp-idf.sh
- Step 5 - Copy the configuration (recommended) or directly edit sdkconfig using ``idf.py menuconfig``::
cp sdkconfig.esp32s2 sdkconfig
- Step 6 - Build::
idf.py build
The script automates the process of building `Arduino as an ESP-IDF component <https://github.com/espressif/arduino-esp32/blob/master/docs/esp-idf_component.md>`_.
Once it is complete, you can cherry pick the needed libraries from ``out/tools/sdk/lib``, or run ``tools/copy-to-arduino.sh`` to copy the entire built system.
``tools/config.sh`` contains a number of variables that control the process, particularly the ``$IDF_BRANCH`` variable. You can adjust this to try building against newer versions, but there are absolutely no guarantees that any components will work or even successfully compile against a newer IDF.
docs/source/libraries.rst 0 → 100644
浏览文件 @ 1effae46
#########
Libraries
#########
Here is where the Libraries API's descriptions are located.
.. toctree::
:maxdepth: 1
:caption: API's:
Bluetooth <api/bluetooth>
Deep Sleep <api/deepsleep>
ESPNOW <api/espnow>
GPIO <api/gpio>
RainMaker <api/rainmaker>
Reset Reason <api/reset_reason>
Wi-Fi <api/wifi>
docs/source/make.rst 0 → 100644
浏览文件 @ 1effae46
==============
makeEspArduino
==============
The `makeEspArduino <https://github.com/plerup/makeEspArduino>`_ is a generic makefile for any ESP8266/ESP32 Arduino project.
Using it instead of the Arduino IDE makes it easier to do automated and production builds.
docs/OTAWebUpdate/OTAWebUpdate.md → docs/source/ota_web_update.rst
浏览文件 @ 1effae46
# Over the Air through Web browser
OTAWebUpdate is done with a web browser that can be useful in the following typical scenarios:
- Once the application developed and loading directly from Arduino IDE is inconvenient or not possible
- after deployment if user is unable to expose Firmware for OTA from external update server
- provide updates after deployment to small quantity of modules when setting an update server is not practicable
## Requirements
- The ESP and the computer must be connected to the same network
## Implementation
The sample implementation has been done using:
- example sketch OTAWebUpdater.ino
- ESP32 (Dev Module)
You can use another module also if it meets Flash chip size of the sketch
1-Before you begin, please make sure that you have the following software installed:
- Arduino IDE
- Host software depending on O/S you use:
- Avahi http://avahi.org/ for Linux
- Bonjour http://www.apple.com/support/bonjour/ for Windows
- Mac OSX and iOS - support is already built in / no any extra s/w is required
Prepare the sketch and configuration for initial upload with a serial port
- Start Arduino IDE and load sketch OTAWebUpdater.ino available under File > Examples > OTAWebUpdater.ino
- Update ssid and pass in the sketch so the module can join your Wi-Fi network
- Open File > Preferences, look for “Show verbose output during:” and check out “compilation” option
![verbrose](esp32verbose.PNG)
- Upload sketch (Ctrl+U)
- Now open web browser and enter the url, i.e. http://esp32.local. Once entered, browser should display a form
![login](esp32login.PNG)
> username= admin
> password= admin
**Note**-*If entering “http://ESP32.local” does not work, try replacing “ESP32” with module’s IP address.This workaround is useful in case the host software installed does not work*.
Now click on Login button and browser will display a upload form
![upload](esp32upload.PNG)
For Uploading the New Firmware you need to provide the Binary File of your Code.
Exporting Binary file of the Firmware (Code)
- Open up the Arduino IDE
- Open up the Code, for Exporting up Binary file
- Now go to Sketch > export compiled Binary
![export](exportTobinary.PNG)
- Binary file is exported to the same Directory where your code is present
Once you are comfortable with this procedure go ahead and modify OTAWebUpdater.ino sketch to print some additional messages, compile it, Export new binary file and upload it using web browser to see entered changes on a Serial Monitor
##############
OTA Web Update
##############
OTAWebUpdate is done with a web browser that can be useful in the following typical scenarios:
- Once the application developed and loading directly from Arduino IDE is inconvenient or not possible
- after deployment if user is unable to expose Firmware for OTA from external update server
- provide updates after deployment to small quantity of modules when setting an update server is not practicable
Requirements
------------
- The ESP and the computer must be connected to the same network
Implementation
--------------
The sample implementation has been done using:
- Example sketch ```OTAWebUpdater.ino```.
- ESP32 Board.
You can also use another module if it meets Flash chip size of the sketch
Before you begin, please make sure that you have the following software installed:
- Arduino IDE
- Host software depending on O/S you use
- `Avahi <http://avahi.org/>`_ for Linux
- `Bonjour <http://www.apple.com/support/bonjour/>`_ for Windows
- Mac OSX and iOS - support is already built in / no any extra s/w is required
Prepare the sketch and configuration for initial upload with a serial port
- Start Arduino IDE and load sketch OTAWebUpdater.ino available under File > Examples > OTAWebUpdater.ino
- Update ssid and pass in the sketch so the module can join your Wi-Fi network
- Open File > Preferences, look for “Show verbose output during:” and check out “compilation” option
.. figure:: _static/ota_esp32_verbose.png
:align: center
:figclass: align-center
- Upload sketch (Ctrl+U)
- Now open web browser and enter the url, i.e. http://esp32.local. Once entered, browser should display a form
.. figure:: _static/ota_esp32_login.png
:align: center
:figclass: align-center
* username = admin
* password = admin
.. note::
*If entering “http://ESP32.local” does not work, try replacing “ESP32” with module’s IP address. This workaround is useful in case the host software installed does not work*.
Now click on the Login button and browser will display an upload form
.. figure:: _static/ota_esp32_upload.png
:align: center
:figclass: align-center
For Uploading the New Firmware, you need to provide the Binary File of your Code.
Exporting Binary file of the Firmware (Code)
- Open up the Arduino IDE
- Open up the Code, for Exporting up Binary file
- Now go to Sketch > export compiled Binary
.. figure:: _static/ota_export_to_binary.png
:align: center
:figclass: align-center
- Binary file is exported to the same Directory where your code is present
Once you are comfortable with this procedure, go ahead and modify OTAWebUpdater.ino sketch to print some additional messages and compile it. Then, export the new binary file and upload it using web browser to see entered changes on a Serial Monitor.
docs/source/troubleshooting.rst 0 → 100644
浏览文件 @ 1effae46
###############
Troubleshotting
###############
Common Issues
=============
Here are some of the most common issues around the ESP32 development using Arduino.
.. note:: Please consider contributing if you have found any issues with the solution here.
Installing
----------
Building
--------
Flashing
--------
* The board is not flashing.
Hardware
--------
* Power Source
* Bad USB cable or charging only cables
docs/source/tutorials/basic.rst 0 → 100644
浏览文件 @ 1effae46
##############
Basic Tutorial
##############
Introduction
------------
This is the basic tutorial and should be used as template for other tutorials.
Requirements
------------
* Arduino IDE
* ESP32 Board
* Good USB Cable
Steps
-----
Here are the steps for this tutorial.
1. Open the Arduino IDE
.. figure:: ../_static/tutorials/basic/tutorial_basic_ide.png
:align: center
:width: 600
:alt: Arduino IDE (click to enlarge)
:figclass: align-center
2. Build and Flash the `blink` project.
Code
----
.. code-block:: arduino
:caption: Blink.ino
/*
Blink
Turns an LED on for one second, then off for one second, repeatedly.
Most Arduinos have an on-board LED you can control. On the UNO, MEGA and ZERO
it is attached to digital pin 13, on MKR1000 on pin 6. LED_BUILTIN is set to
the correct LED pin independent of which board is used.
If you want to know what pin the on-board LED is connected to on your Arduino
model, check the Technical Specs of your board at:
https://www.arduino.cc/en/Main/Products
modified 8 May 2014
by Scott Fitzgerald
modified 2 Sep 2016
by Arturo Guadalupi
modified 8 Sep 2016
by Colby Newman
This example code is in the public domain.
http://www.arduino.cc/en/Tutorial/Blink
*/
// the setup function runs once when you press reset or power the board
void setup() {
// initialize digital pin LED_BUILTIN as an output.
pinMode(LED_BUILTIN, OUTPUT);
}
// the loop function runs over and over again forever
void loop() {
digitalWrite(LED_BUILTIN, HIGH); // turn the LED on (HIGH is the voltage level)
delay(1000); // wait for a second
digitalWrite(LED_BUILTIN, LOW); // turn the LED off by making the voltage LOW
delay(1000); // wait for a second
}
Log Output
----------
If the log output from the serial monitor is relevant, please add here:
.. code-block::
I (0) cpu_start: App cpu up.
I (418) cpu_start: Pro cpu start user code
I (418) cpu_start: cpu freq: 160000000
Resources
---------
* `ESP32 Datasheet`_ (Datasheet)
.. _ESP32 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf
docs/source/tutorials/dfu.rst 0 → 100644
浏览文件 @ 1effae46
###
DFU
###
.. note::
DFU is only supported by the ESP32-S2.
docs/source/tutorials/io_mux.rst 0 → 100644
浏览文件 @ 1effae46
#######################
GPIO Matrix and Pin Mux
#######################
Introduction
------------
This is a basic introduction on how the peripherals work in the ESP32. This tutorial can be used to understand
how to define the peripheral usage and its corresponding pins.
In some microcontrollers' architecture, the peripherals are attached to specific pins and cannot be redefined to another one.
For example.
The *XYZ* MCU defines that the I2C peripheral SDA signal is the IO5 on the physical pin 10 and the SCL is on the IO6 and physical pin 11.
This means that, in your hardware project, you **NEED** to use these pins as the I2C and this cannot be changed due to the internal architecture.
In this case, you must be very careful during the hardware design to not make any mistake by switching the SDA and SCL connections. Firmware will not help you if you do so.
GPIO Matrix and Pin Mux
-----------------------
The ESP32 architecture includes the capability of configuring some peripherals to any of the GPIOs pins, managed by the `IO MUX GPIO`_.
Essentially, this capability means that we can route the internal peripheral into a different physical pin using the IO MUX and the GPIO Matrix.
.. figure:: ../_static/tutorials/peripherals/tutorial_peripheral_diagram.png
:align: center
:width: 600
:figclass: align-center
It means that in the scenario of the *XYZ* MCU, in the ESP32 we can use any of the GPIOs to route the SDA (input/output) and the SCL (output).
To use this functionality, we must be aware of some precautions:
* Some of the GPIOs are **INPUT** only.
* Some peripherals have output signals and must be used on GPIO's capable to be configured as **OUTPUT**.
* Some peripherals, mostly the high speed ones, ADC, DAC, Touch, and JTAG use dedicated GPIOs pins.
.. warning::
Before assigning the peripheral pins in your design, double check if the pins you're using are appropriate.
The input-only pins cannot be used for peripherals that require output or input/output signals.
The greatest advantage of this functionality is the fact that we don't need to be fully dependent on the physical pin, since we can change according to our needs.
This can facilitate the hardware design routing or in some cases, fix some pin swap mistake during the hardware design phase.
Peripherals
-----------
Here is the basic peripherals list present on the `ESP32`_. The peripheral list may vary from each ESP32 SoC family.
To see all peripherals available on the `ESP32-S2`_ and `ESP32-C3`_, check each of the datasheets.
Peripheral Table
****************
============================== ===================================
Type Function
============================== ===================================
ADC Dedicated GPIOs
DAC Dedicated GPIOs
Touch Sensor Dedicated GPIOs
JTAG Dedicated GPIOs
SD/SDIO/MMC HostController Dedicated GPIOs
Motor PWM Any GPIO
SDIO/SPI SlaveController Dedicated GPIOs
UART Any GPIO
I2C Any GPIO
I2S Any GPIO
LED PWM Any GPIO
RMT Any GPIO
GPIO Any GPIO
Parallel QSPI Dedicated GPIOs
EMAC Dedicated GPIOs
Pulse Counter Any GPIO
TWAI Any GPIO
============================== ===================================
This table is present on each datasheet provided by Espressif.
Usage Examples
--------------
In the Arduino Uno, we have the I2C pins defined by hardware, A4 is the SDA and A5 the SCL. In this case, we do not need to set
these pins in the ``Wire.begin();`` function, because they are already into the Wire library.
.. code-block:: arduino
void setup()
{
Wire.begin(); // join i2c bus (address optional for master)
}
Now, for the ESP32, the default pins for the I2C are SDA (GPIO21) and SCL (GPIO22). We can use a different pin as alternative for the
default ones if you need to change the pins.
To change the pins, we must call the ``Wire.setPins(int sda, int scl);`` function before calling ``Wire.begin();``.
.. code-block:: arduino
int sda_pin = 16; // GPIO16 as I2C SDA
int scl_pin = 17; // GPIO17 as I2C SCL
void setup()
{
Wire.setPins(sda_pin, scl_pin); // Set the I2C pins before begin
Wire.begin(); // join i2c bus (address optional for master)
}
A similar approach also applies for the other peripherals.
Resources
---------
* `ESP32`_ (Datasheet)
* `ESP32-S2`_ (Datasheet)
* `ESP32-C3`_ (Datasheet)
.. _Espressif Systems: https://www.espressif.com
.. _Espressif Product Selector: https://products.espressif.com/
.. _ESP32: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf
.. _ESP32-S2: https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf
.. _ESP32-C3: https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf
.. _IO MUX GPIO: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#iomuxgpio
docs/source/tutorials/tutorials.rst 0 → 100644
浏览文件 @ 1effae46
#########
Tutorials
#########
.. toctree::
:maxdepth: 2
:caption: Tutorials:
Basic <basic>
DFU <dfu>
GPIO Matrix and Pin Mux <io_mux>
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或