diff --git a/IDE/ARDUINO/Arduino_README_prepend.md b/IDE/ARDUINO/Arduino_README_prepend.md index d48dea062d..2d2c5456cf 100644 --- a/IDE/ARDUINO/Arduino_README_prepend.md +++ b/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. -## Arduino Releases +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 `/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: -This release of wolfSSL is version [5.7.4](https://github.com/wolfSSL/wolfssl/releases/tag/v5.7.4-stable). +- 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 -Version [5.7.2](https://github.com/wolfSSL/wolfssl/releases/tag/v5.7.2-stable) of the Arduino wolfSSL was published August 3, 2024. +This release of wolfSSL is version [5.7.6](https://github.com/wolfSSL/wolfssl/releases/tag/v5.7.6-stable). -The next Official wolfSSL Arduino Library was [5.7.0](https://github.com/wolfSSL/wolfssl/releases/tag/v5.7.0-stable) +See GitHub for [all Arduino wolfSSL releases](https://github.com/wolfSSL/Arduino-wolfSSL/releases). 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. diff --git a/IDE/ARDUINO/README.md b/IDE/ARDUINO/README.md index f8b1ad60f1..9a8934e447 100644 --- a/IDE/ARDUINO/README.md +++ b/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 `/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 diff --git a/IDE/ARDUINO/sketches/README.md b/IDE/ARDUINO/sketches/README.md index 26a1d1e187..cc54fdd028 100644 --- a/IDE/ARDUINO/sketches/README.md +++ b/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 + + /* 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 + * 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 +#include +``` + +For more details, see [IDE/ARDUINO/README.md](https://github.com/wolfSSL/wolfssl/blob/master/IDE/ARDUINO/README.md) diff --git a/IDE/ARDUINO/sketches/wolfssl_client/wolfssl_client.ino b/IDE/ARDUINO/sketches/wolfssl_client/wolfssl_client.ino index e4727dce1a..c60404a942 100644 --- a/IDE/ARDUINO/sketches/wolfssl_client/wolfssl_client.ino +++ b/IDE/ARDUINO/sketches/wolfssl_client/wolfssl_client.ino @@ -1,6 +1,6 @@ /* wolfssl_client.ino * - * Copyright (C) 2006-2024 wolfSSL Inc. + * Copyright (C) 2006-2025 wolfSSL Inc. * * This file is part of wolfSSL. * @@ -85,6 +85,15 @@ Tested with: #include #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 + * 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 /* Important: make sure settings.h appears before any other wolfSSL headers */ #include diff --git a/IDE/ARDUINO/sketches/wolfssl_server/wolfssl_server.ino b/IDE/ARDUINO/sketches/wolfssl_server/wolfssl_server.ino index 387052ca6b..68bad175e3 100644 --- a/IDE/ARDUINO/sketches/wolfssl_server/wolfssl_server.ino +++ b/IDE/ARDUINO/sketches/wolfssl_server/wolfssl_server.ino @@ -85,6 +85,15 @@ Tested with: #include #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 + * 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 /* Important: make sure settings.h appears before any other wolfSSL headers */ #include diff --git a/IDE/ARDUINO/sketches/wolfssl_version/wolfssl_version.ino b/IDE/ARDUINO/sketches/wolfssl_version/wolfssl_version.ino index ba34efbb98..9185522fc3 100644 --- a/IDE/ARDUINO/sketches/wolfssl_version/wolfssl_version.ino +++ b/IDE/ARDUINO/sketches/wolfssl_version/wolfssl_version.ino @@ -1,24 +1,55 @@ -#include -#include -#include - -/* 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); -} +/* wolfssl_server.ino + * + * Copyright (C) 2006-2025 wolfSSL Inc. + * + * This file is part of wolfSSL. + * + * wolfSSL is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * wolfSSL is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA + */ + +#include + + /* 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 + * 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 +#include + +/* 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); +} diff --git a/IDE/ARDUINO/wolfssl.h b/IDE/ARDUINO/wolfssl.h index 46ef50d3ea..d742b83fbf 100644 --- a/IDE/ARDUINO/wolfssl.h +++ b/IDE/ARDUINO/wolfssl.h @@ -27,7 +27,15 @@ #include -/* 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 + * 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 #include