Merge branch 'docs/http_readme_cleanup' into 'master'

docs: Updated protocols/http* examples READMEs Closes IDF-206 See merge request espressif/esp-idf!15120
2024-10-05 20:47:46 -04:00 · 2021-09-14 11:44:21 +00:00 · 2021-09-14 11:44:21 +00:00 · 4ac198906e
commit 4ac198906e
parent c94b913ced 294b805f31
11 changed files with 556 additions and 18 deletions
--- a/examples/protocols/http2_request/README.md
+++ b/examples/protocols/http2_request/README.md
@ -4,3 +4,69 @@ Established HTTP/2 connection with https://http2.golang.org
 - Performs a GET on /clockstream
 - Performs a PUT on /ECHO

+## How to use example
+Before project configuration and build, be sure to set the correct chip target using `idf.py set-target <chip_name>`.
+
+### Hardware Required
+
+* A development board with ESP32/ESP32-S2/ESP32-C3 SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.)
+* A USB cable for power supply and programming
+
+### Configure the project
+
+```
+idf.py menuconfig
+```
+Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+```
+I (9637) example_connect: - IPv4 address: 192.168.194.219
+I (9637) example_connect: - IPv6 address: fe80:0000:0000:0000:266f:28ff:fe80:2c74, type: ESP_IP6_ADDR_IS_LINK_LOCAL
+Connecting to server
+Connection done
+[data-prvd] Sending 11 bytes
+[echo-response] HELLO WORLD
+[echo-response] Frame fully received
+[echo-response] Frame fully received
+[echo-response] Stream Closed
+[get-response] # ~1KB of junk to force browsers to start rendering immediately:
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+2021-09-07 08:22:10.73175944 +0000 UTC m=+530259.401042400
+
+[get-response] Frame fully received
+[get-response] 2021-09-07 08:22:11.73205314 +0000 UTC m=+530260.401336111
+
+[get-response] Frame fully received
+[get-response] 2021-09-07 08:22:12.7320106 +0000 UTC m=+530261.401293569
+
+[get-response] Frame fully received
+[get-response] 2021-09-07 08:22:13.732013218 +0000 UTC m=+530262.401296183
+```
--- a/examples/protocols/http_request/README.md
+++ b/examples/protocols/http_request/README.md
@ -1,5 +1,111 @@
 # HTTP Request Example

+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
 Uses a POSIX socket to make a very simple HTTP request.

-See the README.md file in the upper level 'examples' directory for more information about examples.
+## How to use example
+Before project configuration and build, be sure to set the correct chip target using `idf.py set-target <chip_name>`.
+
+### Hardware Required
+
+* A development board with ESP32/ESP32-S2/ESP32-C3 SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.)
+* A USB cable for power supply and programming
+
+### Configure the project
+
+```
+idf.py menuconfig
+```
+Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+```
+I (10557) example_connect: - IPv4 address: 192.168.194.219
+I (10557) example_connect: - IPv6 address: fe80:0000:0000:0000:266f:28ff:fe80:2c74, type: ESP_IP6_ADDR_IS_LINK_LOCAL
+W (10577) wifi:<ba-add>idx:0 (ifx:0, ee:6d:19:60:f6:0e), tid:0, ssn:3, winSize:64
+I (10587) example: DNS lookup succeeded. IP=93.184.216.34
+I (10587) example: ... allocated socket
+I (10917) example: ... connected
+I (10917) example: ... socket send success
+I (10927) example: ... set socket receiving timeout success
+HTTP/1.0 200 OK
+Age: 317271
+Cache-Control: max-age=604800
+Content-Type: text/html; charset=UTF-8
+Date: Mon, 06 Sep 2021 08:09:49 GMT
+Etag: "3147526947+ident"
+Expires: Mon, 13 Sep 2021 08:09:49 GMT
+Last-Modified: Thu, 17 Oct 2019 07:18:26 GMT
+Server: ECS (nyb/1D2B)
+Vary: Accept-Encoding
+X-Cache: HIT
+Content-Length: 1256
+Connection: close
+
+<!doctype html>
+<html>
+<head>
+    <title>Example Domain</title>
+
+    <meta charset="utf-8" />
+    <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style type="text/css">
+    body {
+        background-color: #f0f0f2;
+        margin: 0;
+        padding: 0;
+        font-family: -apple-system, system-ui, BlinkMacSystemFont, "Segoe UI", "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+        
+    }
+    div {
+        width: 600px;
+        margin: 5em auto;
+        padding: 2em;
+        background-color: #fdfdff;
+        border-radius: 0.5em;
+        box-shadow: 2px 3px 7px 2px rgba(0,0,0,0.02);
+    }
+    a:link, a:visited {
+        color: #38488f;
+        text-decoration: none;
+    }
+    @media (max-width: 700px) {
+        div {
+            margin: 0 auto;
+            width: auto;
+        }
+    }
+    </style>    
+</head>
+
+<body>
+<div>
+    <h1>Example Domain</h1>
+    <p>This domain is for use in illustrative examples in documents. You may use this
+    domain in literature without prior coordination or asking for permission.</p>
+    <p><a href="https://www.iana.org/domains/example">More information...</a></p>
+</div>
+</body>
+</html>
+I (11467) example: ... done reading from socket. Last read return=0 errno=128.
+I (11477) example: 10... 
+I (12477) example: 9... 
+I (13477) example: 8... 
+```
--- a/examples/protocols/http_server/advanced_tests/README.md
+++ b/examples/protocols/http_server/advanced_tests/README.md
@ -0,0 +1,49 @@
+# HTTP server advanced tests
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+HTTP server example to perform some advanced tests
+
+## How to use example
+
+### Hardware Required
+
+* A development board with ESP32/ESP32-S2/ESP32-C3 SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.)
+* A USB cable for power supply and programming
+
+### Configure the project
+
+```
+idf.py menuconfig
+```
+* Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+```
+I (5561) example_connect: - IPv4 address: 192.168.194.219
+I (5561) example_connect: - IPv6 address: fe80:0000:0000:0000:266f:28ff:fe80:2c74, type: ESP_IP6_ADDR_IS_LINK_LOCAL
+I (5581) TESTS: Started HTTP server on port: '1234'
+I (5581) TESTS: Max URI handlers: '9'
+I (5581) TESTS: Max Open Sessions: '7'
+I (5591) TESTS: Max Header Length: '512'
+I (5591) TESTS: Max URI Length: '512'
+I (5601) TESTS: Max Stack Size: '4096'
+I (5601) TESTS: Registering basic handlers
+I (5601) TESTS: No of handlers = 9
+I (5611) TESTS: Success
+```
--- a/examples/protocols/http_server/file_serving/README.md
+++ b/examples/protocols/http_server/file_serving/README.md
@ -49,3 +49,22 @@ File server implementation can be found under `main/file_server.c` which uses SP
 ## Note

 Browsers often send large header fields when an HTML form is submit. Therefore, for the purpose of this example, `HTTPD_MAX_REQ_HDR_LEN` has been increased to 1024 in `sdkconfig.defaults`. User can adjust this value as per their requirement, keeping in mind the memory constraint of the hardware in use.
+
+## Example Output
+
+```
+I (5583) example_connect: Got IPv6 event: Interface "example_connect: sta" address: fe80:0000:0000:0000:266f:28ff:fe80:2c74, type: ESP_IP6_ADDR_IS_LINK_LOCAL
+I (5583) example_connect: Connected to example_connect: sta
+I (5593) example_connect: - IPv4 address: 192.168.194.219
+I (5593) example_connect: - IPv6 address: fe80:0000:0000:0000:266f:28ff:fe80:2c74, type: ESP_IP6_ADDR_IS_LINK_LOCAL
+I (5603) example: Initializing SPIFFS
+I (5723) example: Partition size: total: 896321, used: 0
+I (5723) file_server: Starting HTTP Server on port: '80'
+I (28933) file_server: Receiving file : /test.html...
+I (28933) file_server: Remaining size : 574
+I (28943) file_server: File reception complete
+I (28993) file_server: Found file : test.html (574 bytes)
+I (35943) file_server: Sending file : /test.html (574 bytes)...
+I (35953) file_server: File sending complete
+I (45363) file_server: Deleting file : /test.html
+```
--- a/examples/protocols/http_server/persistent_sockets/README.md
+++ b/examples/protocols/http_server/persistent_sockets/README.md
@ -3,13 +3,75 @@
 The Example consists of HTTPD server persistent sockets demo.
 This sort of persistency enables the server to have independent sessions/contexts per client.

+## How to use example
+
+### Hardware Required
+
+* A development board with ESP32/ESP32-S2/ESP32-C3 SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.)
+* A USB cable for power supply and programming
+
+### Configure the project
+
+```
+idf.py menuconfig
+```
 * Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details.

-* In order to test the HTTPD server persistent sockets demo :
-    1. compile and burn the firmware `idf.py -p PORT flash`
-    2. run `idf.py -p PORT monitor` and note down the IP assigned to your ESP module. The default port is 80
-    3. run the test script "python scripts/adder.py \<IP\> \<port\> \<N\>"
-        * the provided test script sends (POST) numbers from 1 to N to the server which has a URI POST handler for adding these numbers into an accumulator that is valid throughout the lifetime of the connection socket, hence persistent
-        * the script does a GET before closing and displays the final value of the accumulator
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+### Test the example
+
+In order to test the HTTPD server persistent sockets demo :
+
+* run the test script "python scripts/adder.py \<IP\> \<port\> \<N\>"
+* the provided test script sends (POST) numbers from 1 to N to the server which has a URI POST handler for adding these numbers into an accumulator that is valid throughout the lifetime of the connection socket, hence persistent
+* the script does a GET before closing and displays the final value of the accumulator

 See the README.md file in the upper level 'examples' directory for more information about examples.
+
+## Example Output
+
+```
+I (9570) example_connect: - IPv4 address: 192.168.194.219
+I (9580) example_connect: - IPv6 address: fe80:0000:0000:0000:266f:28ff:fe80:2c74, type: ESP_IP6_ADDR_IS_LINK_LOCAL
+I (9590) example: Starting server on port: '80'
+I (9600) example: Registering URI handlers
+I (12860) example: /adder visitor count = 1
+I (12860) example: /adder PUT handler read 0
+I (12860) example: /adder PUT allocating new session
+I (13070) example: /adder visitor count = 2
+I (13070) example: /adder handler read 1
+I (13090) example: /adder visitor count = 3
+I (13090) example: /adder handler read 2
+I (13110) example: /adder visitor count = 4
+I (13110) example: /adder handler read 3
+I (13170) example: /adder visitor count = 5
+I (13170) example: /adder handler read 4
+I (13190) example: /adder visitor count = 6
+I (13190) example: /adder handler read 5
+I (13210) example: /adder visitor count = 7
+I (13210) example: /adder handler read 6
+I (13270) example: /adder visitor count = 8
+I (13270) example: /adder handler read 7
+I (13290) example: /adder visitor count = 9
+I (13290) example: /adder handler read 8
+I (13300) example: /adder visitor count = 10
+I (13310) example: /adder handler read 9
+I (13370) example: /adder visitor count = 11
+I (13370) example: /adder handler read 10
+I (13390) example: /adder visitor count = 12
+I (13390) example: /adder GET handler send 55
+I (13420) example: /adder Free Context function called
+```
--- a/examples/protocols/http_server/simple/README.md
+++ b/examples/protocols/http_server/simple/README.md
@ -4,12 +4,35 @@ The Example consists of HTTPD server demo with demostration of URI handling :
    1. URI \hello for GET command returns "Hello World!" message
    2. URI \echo for POST command echoes back the POSTed message

+## How to use example
+
+### Hardware Required
+
+* A development board with ESP32/ESP32-S2/ESP32-C3 SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.)
+* A USB cable for power supply and programming
+
+### Configure the project
+
+```
+idf.py menuconfig
+```
 * Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details.

-* In order to test the HTTPD server persistent sockets demo :
-    1. compile and burn the firmware `idf.py -p PORT flash`
-    2. run `idf.py -p PORT monitor` and note down the IP assigned to your ESP module. The default port is 80
-    3. test the example :
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+### Test the example :
        * run the test script : "python scripts/client.py \<IP\> \<port\> \<MSG\>"
            * the provided test script first does a GET \hello and displays the response
            * the script does a POST to \echo with the user input \<MSG\> and displays the response
@ -20,7 +43,16 @@ The Example consists of HTTPD server demo with demostration of URI handling :
                * since the server echoes back the request body, the two files should be same, as can be confirmed using : "cmp anyfile tmpfile"
            3. "curl -X PUT -d "0" 192.168.43.130:80/ctrl" - disable /hello and /echo handlers
            4. "curl -X PUT -d "1" 192.168.43.130:80/ctrl" -  enable /hello and /echo handlers
-            
-* If the server log shows "httpd_parse: parse_block: request URI/header too long", especially when handling POST requests, then you probably need to increase HTTPD_MAX_REQ_HDR_LEN, which you can find in the project configuration menu (`idf.py menuconfig`): Component config -> HTTP Server -> Max HTTP Request Header Length

-See the README.md file in the upper level 'examples' directory for more information about examples.
+## Example Output
+```
+I (9580) example_connect: - IPv4 address: 192.168.194.219
+I (9580) example_connect: - IPv6 address: fe80:0000:0000:0000:266f:28ff:fe80:2c74, type: ESP_IP6_ADDR_IS_LINK_LOCAL
+I (9590) example: Starting server on port: '80'
+I (9600) example: Registering URI handlers
+I (66450) example: Found header => Host: 192.168.194.219
+I (66460) example: Request headers lost
+```
+
+## Troubleshooting
+* If the server log shows "httpd_parse: parse_block: request URI/header too long", especially when handling POST requests, then you probably need to increase HTTPD_MAX_REQ_HDR_LEN, which you can find in the project configuration menu (`idf.py menuconfig`): Component config -> HTTP Server -> Max HTTP Request Header Length
--- a/examples/protocols/https_mbedtls/README.md
+++ b/examples/protocols/https_mbedtls/README.md
@ -0,0 +1,69 @@
+# HTTP server with TLS support using mbedTLS
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+Simple HTTPS example that uses mbedTLS to establish a secure socket connection using the certificate bundle with two custom certificates added for verification:
+
+## How to use example
+
+### Hardware Required
+
+* A development board with ESP32/ESP32-S2/ESP32-C3 SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.)
+* A USB cable for power supply and programming
+
+### Configure the project
+
+```
+idf.py menuconfig
+```
+* Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+```
+I (9599) example_connect: - IPv4 address: 192.168.194.219
+I (9599) example_connect: - IPv6 address: fe80:0000:0000:0000:266f:28ff:fe80:2c74, type: ESP_IP6_ADDR_IS_LINK_LOCAL
+I (9609) example: Seeding the random number generator
+I (9619) example: Attaching the certificate bundle...
+I (9619) example: Setting hostname for TLS session...
+I (9629) example: Setting up the SSL/TLS structure...
+I (9639) example: Connecting to www.howsmyssl.com:443...
+I (10109) example: Connected.
+I (10109) example: Performing the SSL/TLS handshake...
+I (10789) esp-x509-crt-bundle: Certificate validated
+I (15019) example: Verifying peer X.509 certificate...
+I (15019) example: Certificate verified.
+I (15019) example: Cipher suite is TLS-ECDHE-ECDSA-WITH-AES-128-GCM-SHA256
+I (15029) example: Writing HTTP request...
+I (15039) example: 106 bytes written
+I (15039) example: Reading HTTP response...
+HTTP/1.0 200 OK
+Content-Length: 2091
+Access-Control-Allow-Origin: *
+Content-Type: application/json
+Date: Wed, 08 Sep 2021 09:28:59 GMT
+Strict-Transport-Security: max-age=631138519; includeSubdomains; preload
+
+{"given_cipher_suites":["TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384","TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384","TLS_DHE_RSA_WITH_AES_256_GCM_SHA384","TLS_ECDHE_ECDSA_WITH_AES_256_CCM","TLS_DHE_RSA_WITH_AES_256_CCM","TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384","TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384","TLS_DHE_RSA_WITH_AES_256_CBC_SHA256","TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA","TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA","TLS_DHE_RSA_WITH_AES_256_CBC_SHA","TLS_ECDHE_ECDSA_WITH_AES_256_CCM_8","TLS_DHE_RSA_WITH_AES_256_CCM_8","TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256","TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256","TLS_DHE_RSA_WITH_AES_128_GCM_SHA256","TLS_ECDHE_ECDSA_WITH_AES_128_CCM","TLS_DHE_RSA_WITH_AES_128_CCM","TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256","TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256","TLS_DHE_RSA_WITH_AES_128_CBC_SHA256","TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA","TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA","TLS_DHE_RSA_WITH_AES_128_CBC_SHA","TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8","TLS_DHE_RSA_WITH_AES_128_CCM_8","TLS_RSA_WITH_AES_256_GCM_SHA384","TLS_RSA_WITH_AES_256_CCM","TLS_RSA_WITH_AES_256_CBC_SHA256","TLS_RSA_WITH_AES_256_CBC_SHA","TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384","TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384","TLS_ECDH_RSA_WITH_AES_256_CBC_SHA","TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384","TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384","TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA","TLS_RSA_WITH_AES_256_CCM_8","TLS_RSA_WITH_AES_128_GCM_SHA256","TLS_RSA_WITH_AES_128_CCM","TLS_RSA_WITH_AES_128_CBC_SHA256","TLS_RSA_WITH_AES_128_CBC_SHA","TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256","TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256","TLS_ECDH_RSA_WITH_AES_128_CBC_SHA","TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256","TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256","TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA","TLS_RSA_WITH_AES_128_CCM_8","TLS_EMPTY_RENEGOTIATION_INFO_SCSV"],"ephemeral_keys_supported":true,"session_ticket_supported":true,"tls_compression_supported":false,"unknown_cipher_suite_supported":false,"beast_vuln":false,"able_to_detect_n_minus_one_splitting":false,"insecure_cipher_suites":{},"tls_version":"TLS 1.2","rating":"Probably Okay"}
+I (15829) example: Completed 1 requests
+Minimum free heap size: 189136 bytes
+I (15839) example: 10...
+I (16839) example: 9...
+I (17839) example: 8...
+I (18839) example: 7...
+I (19839) example: 6...
+```
--- a/examples/protocols/https_request/README.md
+++ b/examples/protocols/https_request/README.md
@ -2,4 +2,69 @@

 Uses APIs from `esp-tls` component to make a very simple HTTPS request over a secure connection, including verifying the server TLS certificate.

-See the README.md file in the upper level 'examples' directory for more information about examples.
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+## How to use example
+Before project configuration and build, be sure to set the correct chip target using `idf.py set-target <chip_name>`.
+
+### Hardware Required
+
+* A development board with ESP32/ESP32-S2/ESP32-C3 SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.)
+* A USB cable for power supply and programming
+
+### Configure the project
+
+```
+idf.py menuconfig
+```
+Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+```
+I (5634) example_connect: - IPv4 address: 192.168.194.219
+I (5634) example_connect: - IPv6 address: fe80:0000:0000:0000:266f:28ff:fe80:2c74, type: ESP_IP6_ADDR_IS_LINK_LOCAL
+I (5644) example: Start https_request example
+I (5654) example: https_request using crt bundle
+W (6514) wifi:<ba-add>idx:1 (ifx:0, ee:6d:19:60:f6:0e), tid:4, ssn:0, winSize:64
+I (7074) esp-x509-crt-bundle: Certificate validated
+I (9384) example: Connection established...
+I (9384) example: 107 bytes written
+I (9384) example: Reading HTTP response...
+HTTP/1.1 200 OK
+Content-Length: 2091
+Access-Control-Allow-Origin: *
+Connection: close
+Content-Type: application/json
+Date: Tue, 07 Sep 2021 08:30:00 GMT
+Strict-Transport-Security: max-age=631138519; includeSubdomains; preload
+
+{"given_cipher_suites":["TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384","TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384","TLS_DHE_RSA_WITH_AES_256_GCM_SHA384","TLS_ECDHE_ECDSA_WITH_AES_256_CCM","TLS_DHE_RSA_WITH_AES_256_CCM","TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384","TLS_ECDHE_RSA_WITH_AES_
+256_CBC_SHA384","TLS_DHE_RSA_WITH_AES_256_CBC_SHA256","TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA","TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA","TLS_DHE_RSA_WITH_AES_256_CBC_SHA","TLS_ECDHE_ECDSA_WITH_AES_256_CCM_8","TLS_DHE_RSA_WITH_AES_256_CCM_8","TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256","TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256","TLS_DHE_RSA_WITH_AES_128_GCM_SHA256","TLS_ECDHE_ECDSA_WITH_AES_128_CCM","TLS_DHE_RSA_WITH_AES_128_CCM","TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256","TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256","TLS_DHE
+_RSA_WITH_AES_128_CBC_SHA256","TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA","TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA","TLS_DHE_RSA_WITH_AES_128_CBC_SHA","TLS_ECDHE_ECDSA
+_WITH_AES_128_CCM_8","TLS_DHE_RSA_WITH_AES_128_CCM_8","TLS_RSA_WITH_AES_256_GCM_SHA384","TLS_RSA_WITH_AES_256_CCM","TLS_RSA_WITH_AES_256_CBC_SHA256","TLS_RSA_WITH_AES_256_CBC_SHA","TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384","TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384","TLS_ECDH_RSA_WITH_AES_256_CBC_SHA","TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384","TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384","TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA","TLS_RSA_WITH_AES_256_CCM_8","TLS_RSA_WITH_AES_128_GCM_SHA256","TLS_RSA_WITH_AES_128_CCM","TLS_RS
+A_WITH_AES_128_CBC_SHA256","TLS_RSA_WITH_AES_128_CBC_SHA","TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256","TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256","TLS_ECDH_RSA_WITH_AES_128_CBC_SHA","TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256","TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256","TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA","TLS_RSA_WITH_AES_128_CCM_8","TLS_EMPTY_RENEGOTIATION_INFO_SCSV"],"ephemeral_keys_supported":true,"session_ticket_supported":true,"tls_compression_supported":false,"unknown_cipher_suite_supported":false,"beast_vuln":fal
+se,"able_to_detect_n_minus_one_splitting":false,"insecure_cipher_suites":{},"tls_version":"TLS 1.2","rating":"Probably Okay"}
+I (10204) example: connection closed
+I (10204) example: 10...
+I (11204) example: 9...
+I (12204) example: 8...
+I (13204) example: 7...
+I (14204) example: 6...
+I (15204) example: 5...
+I (16204) example: 4...
+```
--- a/examples/protocols/https_server/simple/README.md
+++ b/examples/protocols/https_server/simple/README.md
@ -4,7 +4,29 @@ This example creates a SSL server that returns a simple HTML page when you visit

 See the `esp_https_server` component documentation for details.

-Before using the example, open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details.
+## How to use example
+Before project configuration and build, be sure to set the correct chip target using `idf.py set-target <chip_name>`.
+
+### Configure the project
+
+```
+idf.py menuconfig
+```
+Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.

 ## Certificates

@ -24,3 +46,21 @@ Please see the openssl man pages (man openssl-req) for more details.

 It is **strongly recommended** to not reuse the example certificate in your application;
 it is included only for demonstration.
+
+## Example Output
+
+```
+I (8596) example: Starting server
+I (8596) esp_https_server: Starting server
+I (8596) esp_https_server: Server listening on port 443
+I (8596) example: Registering URI handlers
+I (8606) esp_netif_handlers: example_connect: sta ip: 192.168.194.219, mask: 255.255.255.0, gw: 192.168.194.27
+I (8616) example_connect: Got IPv4 event: Interface "example_connect: sta" address: 192.168.194.219
+I (9596) example_connect: Got IPv6 event: Interface "example_connect: sta" address: fe80:0000:0000:0000:266f:28ff:fe80:2c74, type: ESP_IP6_ADDR_IS_LINK_LOCAL
+I (9596) example_connect: Connected to example_connect: sta
+W (9606) wifi:<ba-add>idx:0 (ifx:0, ee:6d:19:60:f6:0e), tid:0, ssn:2, winSize:64
+I (9616) example_connect: - IPv4 address: 192.168.194.219
+I (9616) example_connect: - IPv6 address: fe80:0000:0000:0000:266f:28ff:fe80:2c74, type: ESP_IP6_ADDR_IS_LINK_LOCAL
+W (14426) wifi:<ba-add>idx:1 (ifx:0, ee:6d:19:60:f6:0e), tid:4, ssn:0, winSize:64
+I (84896) esp_https_server: performing session handshake
+```
--- a/examples/protocols/https_server/wss_server/README.md
+++ b/examples/protocols/https_server/wss_server/README.md
@ -6,13 +6,41 @@ This example creates a SSL server and employs a simple Websocket request handler

 See the `esp_https_server` component documentation for details.

-Before using the example, open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details.

 ### Websocket support in `http_server`

 Please refer to the documentation of [Websocket server](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/protocols/esp_http_server.html#websocket-server) feature in the documentation,
 or to the description of using websocket handlers in httpd in the [simple ws echo](../../http_server/ws_echo_server/README.md#how-to-use-example) example.

+## How to use example
+Before project configuration and build, be sure to set the correct chip target using `idf.py set-target <chip_name>`.
+
+### Hardware Required
+
+* A development board with ESP32/ESP32-S2/ESP32-C3 SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.)
+* A USB cable for power supply and programming
+
+### Configure the project
+
+```
+idf.py menuconfig
+```
+Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
 ## Certificates

 You will need to approve a security exception in your browser. This is because of a self signed
--- a/examples/protocols/https_x509_bundle/README.md
+++ b/examples/protocols/https_x509_bundle/README.md
@ -38,8 +38,10 @@ I (5971) example_connect: Connected to Ethernet
 I (5971) example_connect: IPv4 address: 192.168.2.137
 I (5971) example_connect: IPv6 address: fe80:0000:0000:0000:bedd:c2ff:fed4:a92b
 I (5981) example: Connecting to 2 URLs
+I (7100) esp-x509-crt-bundle: Certificate validated
 I (8371) example: Connection established to https://www.howsmyssl.com/a/check
+I (11730) esp-x509-crt-bundle: Certificate validated
 I (11821) example: Connection established to https://espressif.com
 I (12821) example: Completed 2 connections
 I (12821) example: Starting over again...
-
+```