diff --git a/IDE/ARDUINO/README.md b/IDE/ARDUINO/README.md index e521ecfaa..6ca29942b 100644 --- a/IDE/ARDUINO/README.md +++ b/IDE/ARDUINO/README.md @@ -1,59 +1,79 @@ -### wolfSSL with Arduino +# wolfSSL with Arduino -Many of the supported devices are natively built-in to the [Arduino IDE Board Manager](https://docs.arduino.cc/software/ide-v2/tutorials/ide-v2-board-manager/) +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: - -https://github.com/stm32duino/BoardManagerFiles/raw/main/package_stmicroelectronics_index.json - +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) . +``` +https://github.com/stm32duino/BoardManagerFiles/raw/main/package_stmicroelectronics_index.json +``` +## Using wolfSSL from the Arduino IDE -##### Reformatting wolfSSL as a compatible Arduino Library -This is a shell script that will re-organize the wolfSSL library to be -compatible with Arduino projects that use Arduino IDE 1.5.0 or newer. -The Arduino IDE requires a library's source files to be in the library's root -directory with a header file in the name of the library. This script moves all -src/ files to the `IDE/ARDUINO/wolfSSL/src` directory and creates a stub header -file called `wolfssl.h` inside that directory. +Coming soon! https://github.com/wolfSSL/arduino-wolfSSL See [PR #1](https://github.com/wolfSSL/Arduino-wolfSSL/pull/1). -Step 1: To configure wolfSSL with Arduino, enter one of the following commands +This option will allow wolfSSL to be installed directly using the native Arduino tools. + +## Manually Reformatting wolfSSL as a Compatible Arduino Library + +Use [this](./wolfssl-arduino.sh) shell script that will re-organize the wolfSSL library to be +compatible with [Arduino Library Specification](https://arduino.github.io/arduino-cli/0.35/library-specification/) +for projects that use Arduino IDE 1.5.0 or newer. + +The Arduino IDE requires a library's source files to be in the library's root directory with a +header file in the name of the library. This script moves all `src/` files to the `IDE/ARDUINO/wolfSSL/src` +directory and creates a stub header file called `wolfssl.h` inside that directory. + +### Step 1: + +To configure wolfSSL with Arduino, enter one of the following commands from within the `wolfssl/IDE/ARDUINO` directory: 1. `./wolfssl-arduino.sh` + - Creates an Arduino Library directory structure in the local `wolfSSL` directory of `IDE/ARDUINO`. + - You can add your own `user_settings.h`, or copy/rename the [default](../../examples/configs/user_settings_arduino.h). + +2. `./wolfssl-arduino.sh INSTALL` (The most common option) + - Creates an Arduino Library in the local `wolfSSL` directory + - Moves that directory to the Arduino library directory: + - `$HOME/Arduino/libraries` for most bash environments + - `/mnt/c/Users/$USER/Documents/Arduino/libraries` (for WSL) + - Adds the [default](../../examples/configs/user_settings_arduino.h) as `user_settings.h`. + - The wolfSSL library is now available from the Arduino IDE. + +3. `./wolfssl-arduino.sh INSTALL /path/to/repository` (Used to update [arduino-wolfSSL](https://github.com/wolfSSL/arduino-wolfSSL)) - Creates an Arduino Library in `wolfSSL` directory -2 `./wolfssl-arduino.sh INSTALL` - - Creates an Arduino Library in `wolfSSL` directory - - Moves that directory to the Arduino library directory: - - `$HOME/Arduino/libraries` for most bash environments - - `/mnt/c/Users/$USER/Documents/Arduino/libraries` (for WSL) -3. `./wolfssl-arduino.sh INSTALL /path/to/repository` - - Creates an Arduino Library in `wolfSSL` directory - - Copies that directory contents to the specified `/path/to/repository` + - Copies that directory contents to the specified `/path/to/repository` + - Adds the [default](../../examples/configs/user_settings_arduino.h) as `user_settings.h`. + 4. `./wolfssl-arduino.sh INSTALL /path/to/any/other/directory` - - Creates an Arduino Library in `wolfSSL` directory - - Copies that directory contents to the specified `/path/to/repository` + - Creates an Arduino Library in `wolfSSL` directory + - Copies that directory contents to the specified `/path/to/any/other/directory` -Step 2: Edit `/wolfSSL/src/user_settings.h` +### Step 2: + +Edit `/wolfSSL/src/user_settings.h` If building for Intel Galileo platform add: `#define INTEL_GALILEO`. -Add any other custom settings, for a good start see the examples in wolfssl root -"/examples/configs/user_settings_*.h" +Add any other custom settings. For a good start see the examples in wolfssl root +"[/examples/configs/user_settings_*.h](https://github.com/wolfssl/wolfssl/tree/master/examples/configs)" -Step 3: If you experience any issues with custom user_settings.h see the wolfssl +### Step 3: + +If you experience any issues with custom `user_settings.h` see the wolfssl porting guide here for more assistance: https://www.wolfssl.com/docs/porting-guide/ If you have any issues contact support@wolfssl.com for help. -##### Including wolfSSL in Arduino Libraries (for Arduino version 2.0 or greater) +# Including wolfSSL in Arduino Libraries (for Arduino version 2.0 or greater) 1. In the Arduino IDE: The wolfSSL library should automatically be detected when found in the `libraries` directory. - - In `Sketch -> Include Library` choose wolfSSL for new sketches. + - In `Sketch -> Include Library` choose wolfSSL for new sketches. ##### Including wolfSSL in Arduino Libraries (for Arduino version 1.6.6) @@ -67,9 +87,9 @@ directory. Open an example Arduino sketch for wolfSSL: - - wolfSSL Client INO sketch: `sketches/wolfssl_client/wolfssl_client.ino` + - wolfSSL [Client INO sketch](./sketches/wolfssl_client/README.md): `sketches/wolfssl_client/wolfssl_client.ino` - - wolfSSL Server INO sketch: `sketches/wolfssl_server/wolfssl_server.ino` + - wolfSSL [Server INO sketch](./sketches/wolfssl_server/README.md): `sketches/wolfssl_server/wolfssl_server.ino` #### Script Examples @@ -96,13 +116,14 @@ cd /mnt/c/workspace/wolfssl-$USER ./examples/client/client -h 192.168.1.43 -p 11111 -v 3 ``` -Build wolfSSL to include wolfSSH support, but to an alternate development directory. +Build wolfSSL to include wolfSSH support to an alternate development directory. ```bash - cd /mnt/c/workspace/wolfssl-$USER - ./configure --prefix=/mnt/c/workspace/wolfssh-$USER/wolfssl_install --enable-ssh - make - make install +cd /mnt/c/workspace/wolfssl-$USER +./configure --prefix=/mnt/c/workspace/wolfssh-$USER/wolfssl_install --enable-ssh +make +make install + ``` Build wolfSSH with wolfSSL not installed to default directory. @@ -125,7 +146,7 @@ make clean make && make test ``` -Build and run `testwolfcrypt` +Build and run `testwolfcrypt`. ```bash ./autogen.sh