Merge branch 'master' into esp32-s3-support

.github/workflows/publish.yml

@@ -3,6 +3,7 @@ name: Unit Test Results
 on:
   workflow_run:
     workflows: [Run tests in hardware]
+    branches-ignore: [master]
 
     types:
       - completed
@@ -11,6 +12,9 @@ jobs:
   unit-test-results:
     name: Unit Test Results
     runs-on: ubuntu-latest
+    if: |
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion != 'skipped'
     steps:
       - name: Download and Extract Artifacts
         env:

docs/source/guides/docs_contributing.rst

@@ -0,0 +1,334 @@
+#####################################
+Documentation Contribution Guidelines
+#####################################
+
+Introduction
+------------
+
+This is a guideline for the Arduino ESP32 project documentation. The idea for this guideline is to show how to start collaborating on the project.
+
+The guideline works to give you the directions and to keep the documentation more concise, helping users to better understand the structure.
+
+About Documentation
+-------------------
+
+We all know how important documentation is. This project is no different.
+
+This documentation was created in a collaborative and open way, letting everyone contribute, from a small typo fix to a new chapter writing. We try to motivate our community by giving all the support needed through this guide.
+
+The documentation is in **English only**. Future translations can be added when we finish the essential content in English first.
+
+How to Collaborate
+------------------
+
+Everyone with some knowledge to share is welcome to collaborate.
+
+One thing you need to consider is the fact that your contribution must be concise and assertive since it will be used by people developing projects. The information is very important for everyone, be sure you are not making the developer's life harder!
+
+Documentation Guide
+-------------------
+
+This documentation is based on the `Sphinx`_ with `reStructuredText`_ and hosted by `ReadTheDocs`_.
+
+If you want to get started with `Sphinx`_, see the official documentation:
+
+* `Documentation Index <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+* `Basics <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
+* `Directives <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`_
+
+First Steps
+***********
+
+Before starting your collaboration, you need to get the documentation source code from the Arduino-ESP32 project.
+
+* **Step 1** - Fork the `Arduino-ESP32`_ to your GitHub account.
+* **Step 2** - Check out the recently created fork.
+* **Step 3** - Create a new branch for the changes/addition to the docs.
+* **Step 4** - Write!
+
+Requirements
+************
+
+To properly work with the documentation, you need to install some packages in your system.
+
+.. code-block::
+
+    pip install -U Sphinx
+    pip install -r requirements.txt
+
+The requirements file is under the ``docs`` folder.
+
+Using Visual Studio Code
+************************
+
+If you are using the Visual Studio Code, you can install some extensions to help you while writing documentation.
+
+`reStructuredText Pack <https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext-pack>`_
+
+We also recommend you install to grammar check extension to help you to review English grammar.
+
+`Grammarly <https://marketplace.visualstudio.com/items?itemName=znck.grammarly>`_
+
+Building
+********
+
+To build the documentation and generate the HTLM files, you can use the following command inside the ``docs`` folder. After a successful build, you can check the files inside the `build/html` folder.
+
+.. code-block::
+
+    make html
+
+This step is essential to ensure that there are no syntax errors and also to see the final result.
+
+If everything is ok, you will see some output logs similar to this one:
+
+.. code-block::
+
+    Running Sphinx v2.3.1
+    loading pickled environment... done
+    building [mo]: targets for 0 po files that are out of date
+    building [html]: targets for 35 source files that are out of date
+    updating environment: [extensions changed ('sphinx_tabs.tabs')] 41 added, 3 changed, 0 removed
+    reading sources... [100%] tutorials/tutorials                                                                                                                                                                                                                                                             
+    looking for now-outdated files... none found
+    pickling environment... done
+    checking consistency... done
+    preparing documents... done
+    writing output... [100%] tutorials/tutorials                                                                                                                                                                                                                                                              
+    generating indices...  genindexdone
+    writing additional pages...  searchdone
+    copying images... [100%] tutorials/../_static/tutorials/peripherals/tutorial_peripheral_diagram.png                                                                                                                                                                                                       
+    copying static files... ... done
+    copying extra files... done
+    dumping search index in English (code: en)... done
+    dumping object inventory... done
+    build succeeded.
+
+The HTML pages are in build/html.
+
+Sections
+--------
+
+The Arduino ESP32 is structured in some sections to make it easier to maintain. Here is a brief description of this structure.
+
+API
+***
+
+In this section, you will include all the documentation about drivers, libraries, and any other related to the core.
+
+In this section, we do not add general information. For more general information, we have sections for other related parts, like the FAQ, library builder, troubleshooting, etc.
+
+Boards
+******
+
+Here is the place to add any special guide on the development boards, pin layout, schematics, and any other relevant content.
+
+Common
+******
+
+In this folder, you can add all common information used in several different places. This helps to make documentation easily maintainable.
+
+
+Guides
+******
+
+This is the place to add the guides for common applications, IDEs configuration, and any other information that can be used as a guideline.
+
+Tutorials
+*********
+
+If you want to add a specific tutorial related to the Arduino core for ESP32, this is the place. The intention is not to create a blog or a demo area, but this can be used to add some complex description or to add some more information about APIs.
+
+Images and Assets
+*****************
+
+All the files used on the documentation must be stored in the ``_static`` folder. Be sure that the content used is not with any copyright restriction.
+
+Documentation Rules
+-------------------
+
+Here are some guidelines to help you. We also recommend copying a sample file from the same category you are creating.
+
+This will help you to follow the structure as well as to get inspired.
+
+Basic Structure
+***************
+
+To help you create a new section from scratch, we recommend you include this structure in your content if it applies.
+
+* **About** - Brief description of the document.
+    * Description of the peripheral, driver, protocol, including all different modes and configurations.
+* **API** - Description of each public function, macros, and structs.
+* **Basic Usage**
+* **Example Application**
+
+About Section
+^^^^^^^^^^^^^
+
+In this section, you need to add a brief description of the API. If you are describing a peripheral API, you should explain a little bit about the peripheral and the working modes, if it's applicable.
+
+API Functions
+^^^^^^^^^^^^^
+
+To add a new function description, you must know that the users only have access to the public functions.
+
+
+Here is an example of how to add the function description from `I2C API <https://docs.espressif.com/projects/arduino-esp32/en/latest/api/i2c.html>`_:
+
+.. code-block::
+
+    setPins
+    ^^^^^^^
+
+    This function is used to define the ``SDA`` and ``SCL`` pins. 
+
+    .. note:: Call this function before ``begin`` to change the pins from the default ones.
+
+    .. code-block:: arduino
+
+        bool setPins(int sdaPin, int sclPin);
+
+    * ``sdaPin`` sets the GPIO to be used as the I2C peripheral data line.
+
+    * ``sclPin`` sets the GPIO to be used as the I2C peripheral clock line.
+
+    The default pins may vary from board to board. On the *Generic ESP32* the default I2C pins are:
+
+    * ``sdaPin`` **GPIO21**
+
+    * ``sclPin`` **GPIO22**
+
+    This function will return ``true`` if the peripheral was configured correctly.
+
+Be sure to include a very comprehensive description, add all the parameters in and out, and describe the desired output.
+
+If the function uses a specific structure, you can also describe the structure in the same function block or add a specific section if the structure is shared with other functions.
+
+Basic Usage
+^^^^^^^^^^^
+
+Some APIs are more complex to use or require more steps in order to configure or initialize. If the API is not straightforward in terms of usability, please consider adding a how-to-use section describing all the steps to get the API configured.
+
+Here is an example:
+
+.. code-block::
+
+    Basic Usage
+    ^^^^^^^^^^^
+
+    To start using I2C as slave mode on the Arduino, the first step is to include the ``Wire.h`` header to the sketch.
+
+    .. code-block:: arduino
+
+        #include "Wire.h"
+
+    Before calling ``begin``, you must create two callback functions to handle the communication with the master device.
+
+    .. code-block:: arduino
+
+        Wire.onReceive(onReceive);
+
+    and
+
+    .. code-block:: arduino
+
+        Wire.onRequest(onRequest);
+
+    The ``onReceive`` will handle the request from the ``master`` device upon a slave read request and the ``onRequest`` will handle the answer to the master.
+
+    Now, we can start the peripheral configuration by calling ``begin`` function with the device address.
+
+    .. code-block:: arduino
+
+        Wire.begin((uint8_t)I2C_DEV_ADDR);
+
+    By using ``begin`` without any arguments, all the settings will be done by using the default values. To set the values on your own, see the function description. This function is described here: `i2c begin`_
+
+
+
+Example Application
+^^^^^^^^^^^^^^^^^^^
+It is very important to include at least one application example or a code snippet to help people using the API.
+
+If the API does not have any application example, you can embed the code directly. However, if the example is available, you must include it as a literal block.
+
+.. code-block::
+
+    .. literalinclude:: ../../../libraries/WiFi/examples/WiFiAccessPoint/WiFiAccessPoint.ino
+        :language: arduino
+
+
+Sphinx Basics
+-------------
+
+Heading Levels
+**************
+
+The heading levels used on this documentation are:
+
+* **H1**: - (Dash)
+* **H2**: * (Asterisk)
+* **H3**: ^ (Circumflex)
+* **H4**: # (Sharp)
+
+Code Block
+**********
+
+To add a code block, you can use the following structure:
+
+.. code-block::
+
+    .. code-block:: arduino
+        bool begin(); //Code example
+
+Links
+*****
+
+To include links to external content, you can use two ways.
+
+* First option:
+
+.. code-block::
+
+    `Arduino Wire Library`_
+
+    _Arduino Wire Library: https://www.arduino.cc/en/reference/wire
+
+* Second option:
+
+.. code-block::
+
+    `Arduino Wire Library <https://www.arduino.cc/en/reference/wire>`_
+
+Images
+******
+
+To include images in the docs, first, add all the files into the ``_static`` folder with a filename that makes sense for the topic.
+
+After that, you can use the following structure to include the image in the docs.
+
+.. code-block::
+
+    .. figure:: ../_static/arduino_i2c_master.png
+        :align: center
+        :width: 720
+        :figclass: align-center
+
+You can adjust the ``width`` according to the image size.
+
+Be sure the file size does not exceed 600kB.
+
+Support
+*******
+
+If you need support on the documentation, you can ask a question in the discussion `here <https://github.com/espressif/arduino-esp32/discussions>`_.
+
+Additional Guidelines
+---------------------
+
+If you want to contribute with code on the Arduino ESP32 core, be sure to follow the `ESP-IDF Documenting Code <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/contribute/documenting-code.html>`_ as a reference.
+
+.. _Arduino-ESP32: https://github.com/espressif/arduino-esp32
+.. _Sphinx: https://www.sphinx-doc.org/en/master/
+.. _ReadTheDocs: https://readthedocs.org/
+.. _reStructuredText: https://docutils.sourceforge.io/rst.html

libraries/AsyncUDP/src/AsyncUDP.h

@@ -4,6 +4,7 @@
 #include "IPAddress.h"
 #include "IPv6Address.h"
 #include "Print.h"
+#include "Stream.h"
 #include <functional>
 extern "C" {
 #include "lwip/ip_addr.h"

libraries/WiFi/examples/WiFiClientEnterprise/WiFiClientEnterprise.ino

@@ -1,10 +1,22 @@
 #include <WiFi.h> //Wifi library
 #include "esp_wpa2.h" //wpa2 library for connections to Enterprise networks
 #define EAP_IDENTITY "login" //if connecting from another corporation, use identity@organisation.domain in Eduroam 
+#define EAP_USERNAME "login" //oftentimes just a repeat of the identity
 #define EAP_PASSWORD "password" //your Eduroam password
 const char* ssid = "eduroam"; // Eduroam SSID
 const char* host = "arduino.php5.sk"; //external server domain for HTTP connection after authentification
 int counter = 0;
+
+// NOTE: For some systems, various certification keys are required to connect to the wifi system.
+//       Usually you are provided these by the IT department of your organization when certs are required
+//       and you can't connect with just an identity and password.
+//       Most eduroam setups we have seen do not require this level of authentication, but you should contact
+//       your IT department to verify.
+//       You should uncomment these and populate with the contents of the files if this is required for your scenario (See Example 2 and Example 3 below).
+//const char *ca_pem = "insert your CA cert from your .pem file here";
+//const char *client_cert = "insert your client cert from your .crt file here";
+//const char *client_key = "insert your client key from your .key file here";
+
 void setup() {
   Serial.begin(115200);
   delay(10);
@@ -13,11 +25,17 @@ void setup() {
   Serial.println(ssid);
   WiFi.disconnect(true);  //disconnect form wifi to set new wifi connection
   WiFi.mode(WIFI_STA); //init wifi mode
-  esp_wifi_sta_wpa2_ent_set_identity((uint8_t *)EAP_IDENTITY, strlen(EAP_IDENTITY)); //provide identity
+  
-  esp_wifi_sta_wpa2_ent_set_username((uint8_t *)EAP_IDENTITY, strlen(EAP_IDENTITY)); //provide username --> identity and username is same
+  // Example1 (most common): a cert-file-free eduroam with PEAP (or TTLS)
-  esp_wifi_sta_wpa2_ent_set_password((uint8_t *)EAP_PASSWORD, strlen(EAP_PASSWORD)); //provide password
+  WiFi.begin(ssid, WPA2_AUTH_PEAP, EAP_IDENTITY, EAP_USERNAME, EAP_PASSWORD);
-  esp_wifi_sta_wpa2_ent_enable();
+
-  WiFi.begin(ssid); //connect to wifi
+  // Example 2: a cert-file WPA2 Enterprise with PEAP
+  //WiFi.begin(ssid, WPA2_AUTH_PEAP, EAP_IDENTITY, EAP_USERNAME, EAP_PASSWORD, ca_pem, client_cert, client_key);
+  
+  // Example 3: TLS with cert-files and no password
+  //WiFi.begin(ssid, WPA2_AUTH_TLS, EAP_IDENTITY, NULL, NULL, ca_pem, client_cert, client_key);
+  
+  
   while (WiFi.status() != WL_CONNECTED) {
     delay(500);
     Serial.print(".");

libraries/WiFi/src/WiFiSTA.cpp

@@ -42,6 +42,7 @@ extern "C" {
 #include "lwip/dns.h"
 #include <esp_smartconfig.h>
 #include <esp_netif.h>
+#include "esp_wpa2.h"
 }
 
 // -----------------------------------------------------------------------------------------------------------------------
@@ -145,6 +146,67 @@ wl_status_t WiFiSTAClass::status()
     return (wl_status_t)xEventGroupClearBits(_sta_status_group, 0);
 }
 
+/**
+ * Start Wifi connection with a WPA2 Enterprise AP
+ * if passphrase is set the most secure supported mode will be automatically selected
+ * @param ssid const char*          Pointer to the SSID string.
+ * @param method wpa2_method_t      The authentication method of WPA2 (WPA2_AUTH_TLS, WPA2_AUTH_PEAP, WPA2_AUTH_TTLS)
+ * @param wpa2_identity  const char*          Pointer to the entity
+ * @param wpa2_username  const char*          Pointer to the username
+ * @param password const char *     Pointer to the password.
+ * @param ca_pem const char*        Pointer to a string with the contents of a  .pem  file with CA cert
+ * @param client_crt const char*        Pointer to a string with the contents of a .crt file with client cert
+ * @param client_key const char*        Pointer to a string with the contants of a .key file with client key
+ * @param bssid uint8_t[6]          Optional. BSSID / MAC of AP
+ * @param channel                   Optional. Channel of AP
+ * @param connect                   Optional. call connect
+ * @return
+ */
+wl_status_t WiFiSTAClass::begin(const char* wpa2_ssid, wpa2_auth_method_t method, const char* wpa2_identity, const char* wpa2_username, const char *wpa2_password, const char* ca_pem, const char* client_crt, const char* client_key, int32_t channel, const uint8_t* bssid, bool connect)
+{
+    if(!WiFi.enableSTA(true)) {
+        log_e("STA enable failed!");
+        return WL_CONNECT_FAILED;
+    }
+
+    if(!wpa2_ssid || *wpa2_ssid == 0x00 || strlen(wpa2_ssid) > 32) {
+        log_e("SSID too long or missing!");
+        return WL_CONNECT_FAILED;
+    }
+
+    if(wpa2_identity && strlen(wpa2_identity) > 64) {
+        log_e("identity too long!");
+        return WL_CONNECT_FAILED;
+    }
+
+    if(wpa2_username && strlen(wpa2_username) > 64) {
+        log_e("username too long!");
+        return WL_CONNECT_FAILED;
+    }
+
+    if(wpa2_password && strlen(wpa2_password) > 64) {
+        log_e("password too long!");
+    }
+
+    if(ca_pem) {
+        esp_wifi_sta_wpa2_ent_set_ca_cert((uint8_t *)ca_pem, strlen(ca_pem));
+    }
+
+    if(client_crt) {
+        esp_wifi_sta_wpa2_ent_set_cert_key((uint8_t *)client_crt, strlen(client_crt), (uint8_t *)client_key, strlen(client_key), NULL, 0);
+    }
+
+    esp_wifi_sta_wpa2_ent_set_identity((uint8_t *)wpa2_identity, strlen(wpa2_identity));
+    if(method == WPA2_AUTH_PEAP || method == WPA2_AUTH_TTLS) {
+        esp_wifi_sta_wpa2_ent_set_username((uint8_t *)wpa2_username, strlen(wpa2_username));
+        esp_wifi_sta_wpa2_ent_set_password((uint8_t *)wpa2_password, strlen(wpa2_password));
+    }
+    esp_wifi_sta_wpa2_ent_enable(); //set config settings to enable function
+    WiFi.begin(wpa2_ssid); //connect to wifi
+
+    return status();
+}
+
 /**
  * Start Wifi connection
  * if passphrase is set the most secure supported mode will be automatically selected

libraries/WiFi/src/WiFiSTA.h

@@ -30,6 +30,11 @@
 #include "esp_event.h"
 #endif
 
+typedef enum {
+    WPA2_AUTH_TLS = 0,
+    WPA2_AUTH_PEAP = 1,
+    WPA2_AUTH_TTLS = 2
+} wpa2_auth_method_t;
 
 class WiFiSTAClass
 {
@@ -39,6 +44,7 @@ class WiFiSTAClass
 
 public:
 
+    wl_status_t begin(const char* wpa2_ssid, wpa2_auth_method_t method, const char* wpa2_identity=NULL, const char* wpa2_username=NULL, const char *wpa2_password=NULL, const char* ca_pem=NULL, const char* client_crt=NULL, const char* client_key=NULL, int32_t channel=0, const uint8_t* bssid=0, bool connect=true);
     wl_status_t begin(const char* ssid, const char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = true);
     wl_status_t begin(char* ssid, char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = true);
     wl_status_t begin();

variants/adafruit_feather_esp32_v2/pins_arduino.h

@@ -42,20 +42,19 @@ static const uint8_t A9 = 33;
 static const uint8_t A10 = 27;
 static const uint8_t A11 = 12;
 static const uint8_t A12 = 13;
-
-// vbat measure
-static const uint8_t BATT_MONITOR = 35;
 static const uint8_t A13 = 35;
 
+// vbat measure
+#define BATT_MONITOR 35
+
 // internal switch
-static const uint8_t BUTTON = 38;
+#define BUTTON = 38;
 
 // Neopixel
-static const uint8_t NEOPIXEL_PIN = 0;
+#define PIN_NEOPIXEL 0
-static const uint8_t PIN_NEOPIXEL = 0;
 
 // Neopixel & I2C power
-static const uint8_t NEOPIXEL_I2C_POWER = 2;
+#define NEOPIXEL_I2C_POWER 2
 
 static const uint8_t T0 = 4;
 static const uint8_t T1 = 0;

variants/adafruit_feather_esp32s2/variant.cpp

@@ -36,10 +36,11 @@ void initVariant(void)
   pinMode(NEOPIXEL_POWER, OUTPUT);
   digitalWrite(NEOPIXEL_POWER, HIGH);
 
-  // This board has a power control pin, and we must set it to output and low
+  // turn on the I2C power by setting pin to opposite of 'rest state'
-  // in order to enable the I2C port.
+  pinMode(PIN_I2C_POWER, INPUT);
+  delay(1);
+  bool polarity = digitalRead(PIN_I2C_POWER);
   pinMode(PIN_I2C_POWER, OUTPUT);
-  digitalWrite(PIN_I2C_POWER, LOW);
+  digitalWrite(PIN_I2C_POWER, !polarity);
 }
-
 }

variants/adafruit_qtpy_esp32c3/pins_arduino.h

@@ -11,8 +11,8 @@
 #define digitalPinToInterrupt(p)    (((p)<NUM_DIGITAL_PINS)?(p):-1)
 #define digitalPinHasPWM(p)         (p < EXTERNAL_NUM_INTERRUPTS)
 
-static const uint8_t SWITCH = 9;
+#define BUTTON 9
-static const uint8_t NEOPIXEL_PIN = 2;
+#define PIN_NEOPIXEL 2
 
 static const uint8_t TX = 21;
 static const uint8_t RX = 20;