Merge pull request #8381 from gojimmypi/pr-post-release-239b85c80-arduino

Update Arduino comments for post-release publish

IDE/ARDUINO/Arduino_README_prepend.md

@@ -4,16 +4,46 @@ This library is restructured from [wolfSSL](https://github.com/wolfSSL/wolfssl/)
 
 The Official wolfSSL Arduino Library is found in [The Library Manager index](http://downloads.arduino.cc/libraries/library_index.json).
 
-See the [Arduino-wolfSSL logs](https://downloads.arduino.cc/libraries/logs/github.com/wolfSSL/Arduino-wolfSSL/).
+See the [Arduino-wolfSSL logs](https://downloads.arduino.cc/libraries/logs/github.com/wolfSSL/Arduino-wolfSSL/) for publishing status.
+
+Instructions for installing and using libraries can be found in the [Arduino docs](https://docs.arduino.cc/software/ide-v1/tutorials/installing-libraries/).
+
+## wolfSSL Configuration
+
+As described in the [Getting Started with wolfSSL on Arduino](https://www.wolfssl.com/getting-started-with-wolfssl-on-arduino/), wolfSSL features are enabled and disabled in the `user_settings.h` file.
+
+The `user_settings.h` file is found in the `<Arduino>/libraries/wolfssl/src` directory.
+
+For Windows this is typically `C:\Users\%USERNAME%\Documents\Arduino\libraries\wolfssl\src`
+
+For Mac: `~/Documents/Arduino/libraries/wolfssl/src`
+
+For Linux: `~/Arduino/libraries/wolfssl/src`
+
+Tips for success:
+
+- The `WOLFSSL_USER_SETTINGS` macro must be defined project-wide. (see [wolfssl.h](https://github.com/wolfSSL/wolfssl/blob/master/IDE/ARDUINO/wolfssl.h))
+- Apply any customizations only to `user_settings.h`;  Do not edit wolfSSL `settings.h` or `configh.h` files.
+- Do not explicitly include `user_settings.h` in any source file.
+- For every source file that uses wolfssl, include `wolfssl/wolfcrypt/settings.h` before any other wolfSSL include, typically via `#include "wolfssl.h"`.
+- See the [wolfSSL docs](https://www.wolfssl.com/documentation/manuals/wolfssl/chapter02.html) for details on build configuration macros.
+
+## wpolfSSL Examples
+
+Additional wolfSSL examples can be found at:
+
+- https://github.com/wolfSSL/wolfssl/tree/master/IDE/ARDUINO
+
+- https://github.com/wolfSSL/wolfssl/tree/master/examples
+
+- https://github.com/wolfSSL/wolfssl-examples/
 
 ## Arduino Releases
 
-This release of wolfSSL is version [5.7.4](https://github.com/wolfSSL/wolfssl/releases/tag/v5.7.4-stable).
+This release of wolfSSL is version [5.7.6](https://github.com/wolfSSL/wolfssl/releases/tag/v5.7.6-stable).
 
-Version [5.7.2](https://github.com/wolfSSL/wolfssl/releases/tag/v5.7.2-stable) of the Arduino wolfSSL was published August 3, 2024.
+See GitHub for [all Arduino wolfSSL releases](https://github.com/wolfSSL/Arduino-wolfSSL/releases).
-
-The next Official wolfSSL Arduino Library was [5.7.0](https://github.com/wolfSSL/wolfssl/releases/tag/v5.7.0-stable)
 
 The first Official wolfSSL Arduino Library was `5.6.6-Arduino.1`: a slightly modified, post [release 5.6.6](https://github.com/wolfSSL/wolfssl/releases/tag/v5.6.6-stable) version update.
 
-See other [wolfSSL releases versions](https://github.com/wolfSSL/wolfssl/releases). The `./wolfssl-arduino.sh INSTALL` [script](https://github.com/wolfSSL/wolfssl/tree/master/IDE/ARDUINO) can be used to install specific GitHub versions as needed.
+The `./wolfssl-arduino.sh INSTALL` [script](https://github.com/wolfSSL/wolfssl/tree/master/IDE/ARDUINO) can be used to install specific GitHub versions as needed.

IDE/ARDUINO/README.md

@@ -7,13 +7,33 @@ See the [example sketches](./sketches/README.md):
 
 When publishing a new version to the Arduino Registry, be sure to edit `WOLFSSL_VERSION_ARUINO_SUFFIX` in the `wolfssl-arduino.sh` script.
 
+## Getting Started
+
+See [Getting Started with wolfSSL on Arduino](https://www.wolfssl.com/getting-started-with-wolfssl-on-arduino/), wolfSSL features are enabled and disabled in the `user_settings.h` file.
+
+The `user_settings.h` file is found in the `<Arduino>/libraries/wolfssl/src` directory.
+
+For Windows this is typically `C:\Users\%USERNAME%\Documents\Arduino\libraries\wolfssl\src`
+
+For Mac: `~/Documents/Arduino/libraries/wolfssl/src`
+
+For Linux: `~/Arduino/libraries/wolfssl/src`
+
+Tips for success:
+
+- The `WOLFSSL_USER_SETTINGS` macro must be defined project-wide. (see [wolfssl.h](https://github.com/wolfSSL/wolfssl/blob/master/IDE/ARDUINO/wolfssl.h))
+- Apply any customizations only to `user_settings.h`;  Do not edit wolfSSL `settings.h` or `configh.h` files.
+- Do not explicitly include `user_settings.h` in any source file.
+- For every source file that uses wolfssl, include `wolfssl/wolfcrypt/settings.h` before any other wolfSSL include, typically via `#include "wolfssl.h"`.
+- See the [wolfSSL docs](https://www.wolfssl.com/documentation/manuals/wolfssl/chapter02.html) for details on build configuration macros.
+
 ## Boards
 
 Many of the supported boards are natively built-in to the [Arduino IDE Board Manager](https://docs.arduino.cc/software/ide-v2/tutorials/ide-v2-board-manager/)
 and by adding [additional cores](https://docs.arduino.cc/learn/starting-guide/cores/) as needed.
 
 STM32 Support can be added by including this link in the "Additional Boards Managers URLs" field
-from [stm32duino/Arduino_Core_STM32](https://github.com/stm32duino/Arduino_Core_STM32?tab=readme-ov-file#getting-started)   .
+from [stm32duino/Arduino_Core_STM32](https://github.com/stm32duino/Arduino_Core_STM32?tab=readme-ov-file#getting-started).
 
 ```
 https://github.com/stm32duino/BoardManagerFiles/raw/main/package_stmicroelectronics_index.json

IDE/ARDUINO/sketches/README.md

@@ -10,3 +10,25 @@ Examples have been most recently confirmed operational on the
 
 For examples on other platforms, see the [IDE directory](https://github.com/wolfssl/wolfssl/tree/master/IDE).
 Additional examples can be found on [wolfSSL/wolfssl-examples](https://github.com/wolfSSL/wolfssl-examples/).
+
+## Using wolfSSL
+
+The typical include will look something like this:
+
+```
+#include <Arduino.h>
+
+ /* wolfSSL user_settings.h must be included from settings.h
+  * Make all configurations changes in user_settings.h
+  * Do not edit wolfSSL `settings.h` or `configh.h` files.
+  * Do not explicitly include user_settings.h in any source code.
+  * Each Arduino sketch that uses wolfSSL must have: #include "wolfssl.h"
+  * C/C++ source files can use: #include <wolfssl/wolfcrypt/settings.h>
+  * The wolfSSL "settings.h" must be included in each source file using wolfSSL.
+  * The wolfSSL "settings.h" must appear before any other wolfSSL include.
+  */
+#include <wolfssl.h>
+#include <wolfssl/version.h>
+```
+
+For more details, see [IDE/ARDUINO/README.md](https://github.com/wolfSSL/wolfssl/blob/master/IDE/ARDUINO/README.md)

IDE/ARDUINO/sketches/wolfssl_client/wolfssl_client.ino

@@ -85,6 +85,15 @@ Tested with:
     #include <NTPClient.h>
 #endif
 
+/* wolfSSL user_settings.h must be included from settings.h
+ * Make all configurations changes in user_settings.h
+ * Do not edit wolfSSL `settings.h` or `configh.h` files.
+ * Do not explicitly include user_settings.h in any source code.
+ * Each Arduino sketch that uses wolfSSL must have: #include "wolfssl.h"
+ * C/C++ source files can use: #include <wolfssl/wolfcrypt/settings.h>
+ * The wolfSSL "settings.h" must be included in each source file using wolfSSL.
+ * The wolfSSL "settings.h" must appear before any other wolfSSL include.
+ */
 #include <wolfssl.h>
 /* Important: make sure settings.h appears before any other wolfSSL headers */
 #include <wolfssl/wolfcrypt/settings.h>

IDE/ARDUINO/sketches/wolfssl_server/wolfssl_server.ino

@@ -85,6 +85,15 @@ Tested with:
     #include <NTPClient.h>
 #endif
 
+/* wolfSSL user_settings.h must be included from settings.h
+ * Make all configurations changes in user_settings.h
+ * Do not edit wolfSSL `settings.h` or `configh.h` files.
+ * Do not explicitly include user_settings.h in any source code.
+ * Each Arduino sketch that uses wolfSSL must have: #include "wolfssl.h"
+ * C/C++ source files can use: #include <wolfssl/wolfcrypt/settings.h>
+ * The wolfSSL "settings.h" must be included in each source file using wolfSSL.
+ * The wolfSSL "settings.h" must appear before any other wolfSSL include.
+ */
 #include <wolfssl.h>
 /* Important: make sure settings.h appears before any other wolfSSL headers */
 #include <wolfssl/wolfcrypt/settings.h>

IDE/ARDUINO/sketches/wolfssl_version/wolfssl_version.ino

@@ -1,24 +1,55 @@
-#include <Arduino.h>
+/* wolfssl_server.ino
-#include <wolfssl.h>
+ *
-#include <wolfssl/version.h>
+ * Copyright (C) 2006-2025 wolfSSL Inc.
-
+ *
-/* Choose a monitor serial baud rate: 9600, 14400, 19200, 57600, 74880, etc. */
+ * This file is part of wolfSSL.
-#define SERIAL_BAUD 115200
+ *
-
+ * wolfSSL is free software; you can redistribute it and/or modify
-/* Arduino setup */
+ * it under the terms of the GNU General Public License as published by
-void setup() {
+ * the Free Software Foundation; either version 2 of the License, or
-    Serial.begin(SERIAL_BAUD);
+ * (at your option) any later version.
-    while (!Serial) {
+ *
-        /* wait for serial port to connect. Needed for native USB port only */
+ * wolfSSL is distributed in the hope that it will be useful,
-    }
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
-    Serial.println(F(""));
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    Serial.println(F(""));
+ * GNU General Public License for more details.
-    Serial.println(F("wolfSSL setup complete!"));
+ *
-}
+ * You should have received a copy of the GNU General Public License
-
+ * along with this program; if not, write to the Free Software
-/* Arduino main application loop. */
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
-void loop() {
+ */
-    Serial.print("wolfSSL Version: ");
+
-    Serial.println(LIBWOLFSSL_VERSION_STRING);
+#include <Arduino.h>
-    delay(60000);
+
-}
+ /* wolfSSL user_settings.h must be included from settings.h
+  * Make all configurations changes in user_settings.h
+  * Do not edit wolfSSL `settings.h` or `configh.h` files.
+  * Do not explicitly include user_settings.h in any source code.
+  * Each Arduino sketch that uses wolfSSL must have: #include "wolfssl.h"
+  * C/C++ source files can use: #include <wolfssl/wolfcrypt/settings.h>
+  * The wolfSSL "settings.h" must be included in each source file using wolfSSL.
+  * The wolfSSL "settings.h" must appear before any other wolfSSL include.
+  */
+#include <wolfssl.h>
+#include <wolfssl/version.h>
+
+/* Choose a monitor serial baud rate: 9600, 14400, 19200, 57600, 74880, etc. */
+#define SERIAL_BAUD 115200
+
+/* Arduino setup */
+void setup() {
+    Serial.begin(SERIAL_BAUD);
+    while (!Serial) {
+        /* wait for serial port to connect. Needed for native USB port only */
+    }
+    Serial.println(F(""));
+    Serial.println(F(""));
+    Serial.println(F("wolfSSL setup complete!"));
+}
+
+/* Arduino main application loop. */
+void loop() {
+    Serial.print("wolfSSL Version: ");
+    Serial.println(LIBWOLFSSL_VERSION_STRING);
+    delay(60000);
+}

IDE/ARDUINO/wolfssl.h

@@ -27,7 +27,15 @@
 
 #include <Arduino.h>
 
-/* wolfSSL user_settings.h must be included from settings.h */
+/* wolfSSL user_settings.h must be included from settings.h
+ * Make all configurations changes in user_settings.h
+ * Do not edit wolfSSL `settings.h` or `configh.h` files.
+ * Do not explicitly include user_settings.h in any source code.
+ * Each Arduino sketch that uses wolfSSL must have: #include "wolfssl.h"
+ * C/C++ source files can use: #include <wolfssl/wolfcrypt/settings.h>
+ * The wolfSSL "settings.h" must be included in each source file using wolfSSL.
+ * The wolfSSL "settings.h" must be listed before any other wolfSSL include.
+ */
 #include <wolfssl/wolfcrypt/settings.h>
 #include <wolfssl/ssl.h>