secrets

.gitignore

@@ -39,4 +39,4 @@ _build/
 *.log
 debug.cfg
 debug.svd
-debug_custom.json
+debug_custom.json

docs/source/guides/secrets.rst

@@ -0,0 +1,74 @@
+#######
+Secrets
+#######
+
+Why?
+----
+
+* DRY (Don't Repeat Yourself) - having your passwords in one place is more manageable than changing them manually in each example, or new sketch.
+
+* Secure - safely share the code without worrying about accidentally exposing WiFi credentials.
+
+How it works - your SSIDs and passwords are ``#defined`` as a plain text constants in a header file located in sketch-book folder (after you manually create it). The platform.txt file automatically includes path to the sketch book as a relative path ``{runtime.hardware.path}/../../``. This header file can be included in any sketch and the passwords used in there hidden with the constant name.
+
+.. note::
+
+    You can still use the traditional way of hard-coded WiFi credentials if you want to. Using ``secrets`` is only something extra on top of that.
+
+.. warning::
+
+    Secrets are stored as a plain text in an unencrypted form. They can be stolen if you keep your computer unlocked and accessible. If the entire disc is unencrypted it can be read when extracted from the computer.
+
+Setup:
+------
+1. Locate your sketch folder and create file secrets.h if it does not exist yet.
+
+    * To locate your sketchbook folder, click in the Arduino IDE on ``File > Preferences`` (or press Ctrl + comma) on the top is the sketchbook path.
+
+2. Edit the secrets.h file and input the WiFi credential you are often using. You can use simply copy & paste the example below and edit the credentials.
+
+3. For examples we are using constants `SECRETS_WIFI_SSID_1` and `SECRETS_WIFI_PASSWORD_1`. You can follow the numbering or create your own constant names, for example `WIFI_SSID_HOME` + `WIFI_PWD_HOME`.
+
+4. For multi Access Point usage you can use an array of credentials you can expand - either add existing constants, or create a plain text.
+
+
+Example contents:
+-----------------
+
+.. code-block:: c++
+
+    #pragma once
+
+    #define SECRETS_WIFI_SSID_1 "example-SSID1"
+    #define SECRETS_WIFI_PASSWORD_1 "example-password-1"
+
+    #define SECRETS_WIFI_SSID_2 "example-SSID2"
+    #define SECRETS_WIFI_PASSWORD_2 "example-password-2"
+
+    #define SECRETS_WIFI_ARRAY_MAX 3 // Number of entries in the array
+
+    const char SECRET_WIFI_SSID_ARRAY[SECRETS_WIFI_ARRAY_MAX][32] = {
+    SECRETS_WIFI_SSID_1,
+    SECRETS_WIFI_SSID_2,
+    "example-SSID3"
+    };
+
+    const char SECRET_WIFI_PASSWORD_ARRAY[SECRETS_WIFI_ARRAY_MAX][32] = {
+    SECRETS_WIFI_PASSWORD_1,
+    SECRETS_WIFI_PASSWORD_2,
+    "example-password-3"
+    };
+
+
+Example usage:
+--------------
+
+.. code-block:: c++
+
+    #include <WiFi.h>
+    #include "secrets.h"
+    const char* ssid     = SECRETS_WIFI_SSID_1;
+    const char* password = SECRETS_WIFI_PASSWORD_1;
+    //const char* ssid     = "example-SSID1"; // Traditional usage
+    //const char* password = "example-password-1"; // Traditional usage
+    WiFi.begin(ssid, password);

libraries/WiFi/examples/SimpleWiFiServer/SimpleWiFiServer.ino

@@ -27,8 +27,22 @@ ported for sparkfun esp32
 
 #include <WiFi.h>
 
-const char* ssid     = "yourssid";
-const char* password = "yourpasswd";
+// To use secrets please read the documentation at https://espressif-docs.readthedocs-hosted.com/projects/arduino-esp32/en/latest/guides/secrets.html
+#if __has_include("secrets.h")
+  #include "secrets.h"
+#endif
+
+#ifdef SECRETS_WIFI_SSID_1
+const char* ssid     = SECRETS_WIFI_SSID_1;
+#else
+const char* ssid     = "example-SSID1"; // Traditional way
+#endif
+
+#ifdef SECRETS_WIFI_PASSWORD_1
+const char* password = SECRETS_WIFI_PASSWORD_1;
+#else
+const char* password = "example-password-1"; // Traditional way
+#endif
 
 WiFiServer server(80);
 

libraries/WiFi/examples/WiFiAccessPoint/WiFiAccessPoint.ino

@@ -15,11 +15,25 @@
 #include <WiFiClient.h>
 #include <WiFiAP.h>
 
+// To use secrets please read the documentation at https://espressif-docs.readthedocs-hosted.com/projects/arduino-esp32/en/latest/guides/secrets.html
+#if __has_include("secrets.h")
+  #include "secrets.h"
+#endif
+
 #define LED_BUILTIN 2   // Set the GPIO pin where you connected your test LED or comment this line out if your dev board has a built-in LED
 
 // Set these to your desired credentials.
-const char *ssid = "yourAP";
-const char *password = "yourPassword";
+#ifdef SECRETS_WIFI_SSID_1
+const char* ssid     = SECRETS_WIFI_SSID_1;
+#else
+const char* ssid     = "example-SSID1"; // Traditional way
+#endif
+
+#ifdef SECRETS_WIFI_PASSWORD_1
+const char* password = SECRETS_WIFI_PASSWORD_1;
+#else
+const char* password = "example-password-1"; // Traditional way
+#endif
 
 WiFiServer server(80);
 

libraries/WiFi/examples/WiFiBlueToothSwitch/WiFiBlueToothSwitch.ino

@@ -16,8 +16,24 @@
 // Button is attached between GPIO 0 and GND and modes are switched with each press
 
 #include "WiFi.h"
-#define STA_SSID "your-ssid"
-#define STA_PASS "your-pass"
+
+// To use secrets please read the documentation at https://espressif-docs.readthedocs-hosted.com/projects/arduino-esp32/en/latest/guides/secrets.html
+#if __has_include("secrets.h")
+  #include "secrets.h"
+#endif
+
+#ifdef SECRETS_WIFI_SSID_1
+const char* ssid     = SECRETS_WIFI_SSID_1;
+#else
+const char* ssid     = "example-SSID1"; // Traditional way
+#endif
+
+#ifdef SECRETS_WIFI_PASSWORD_1
+const char* password = SECRETS_WIFI_PASSWORD_1;
+#else
+const char* password = "example-password-1"; // Traditional way
+#endif
+
 #define AP_SSID  "esp32"
 
 enum { STEP_BTON, STEP_BTOFF, STEP_STA, STEP_AP, STEP_AP_STA, STEP_OFF, STEP_BT_STA, STEP_END };
@@ -35,7 +51,7 @@ void onButton(){
     break;
     case STEP_STA://STA Only
       Serial.println("** Starting STA");
-      WiFi.begin(STA_SSID, STA_PASS);
+      WiFi.begin(ssid, password);
     break;
     case STEP_AP://AP Only
       Serial.println("** Stopping STA");
@@ -45,15 +61,15 @@ void onButton(){
     break;
     case STEP_AP_STA://AP+STA
       Serial.println("** Starting STA");
-      WiFi.begin(STA_SSID, STA_PASS);
+      WiFi.begin(ssid, password);
     break;
     case STEP_OFF://All Off
       Serial.println("** Stopping WiFi");
       WiFi.mode(WIFI_OFF);
     break;
     case STEP_BT_STA://BT+STA
       Serial.println("** Starting STA+BT");
-      WiFi.begin(STA_SSID, STA_PASS);
+      WiFi.begin(ssid, password);
       btStart();
     break;
     case STEP_END://All Off

libraries/WiFi/examples/WiFiClient/WiFiClient.ino

@@ -16,8 +16,22 @@
 
 #include <WiFi.h>
 
-const char* ssid     = "your-ssid"; // Change this to your WiFi SSID
-const char* password = "your-password"; // Change this to your WiFi password
+// To use secrets please read the documentation at https://espressif-docs.readthedocs-hosted.com/projects/arduino-esp32/en/latest/guides/secrets.html
+#if __has_include("secrets.h")
+  #include "secrets.h"
+#endif
+
+#ifdef SECRETS_WIFI_SSID_1
+const char* ssid     = SECRETS_WIFI_SSID_1;
+#else
+const char* ssid     = "example-SSID1"; // Traditional way
+#endif
+
+#ifdef SECRETS_WIFI_PASSWORD_1
+const char* password = SECRETS_WIFI_PASSWORD_1;
+#else
+const char* password = "example-password-1"; // Traditional way
+#endif
 
 const char* host = "api.thingspeak.com"; // This should not be changed
 const int httpPort = 80; // This should not be changed

libraries/WiFi/examples/WiFiClientBasic/WiFiClientBasic.ino

@@ -6,15 +6,32 @@
 #include <WiFi.h>
 #include <WiFiMulti.h>
 
+// To use secrets please read the documentation at https://espressif-docs.readthedocs-hosted.com/projects/arduino-esp32/en/latest/guides/secrets.html
+#if __has_include("secrets.h")
+  #include "secrets.h"
+#endif
+
 WiFiMulti WiFiMulti;
 
+#ifdef SECRETS_WIFI_SSID_1
+const char* ssid     = SECRETS_WIFI_SSID_1;
+#else
+const char* ssid     = "example-SSID1"; // Traditional way
+#endif
+
+#ifdef SECRETS_WIFI_PASSWORD_1
+const char* password = SECRETS_WIFI_PASSWORD_1;
+#else
+const char* password = "example-password-1"; // Traditional way
+#endif
+
 void setup()
 {
     Serial.begin(115200);
     delay(10);
 
     // We start by connecting to a WiFi network
-    WiFiMulti.addAP("SSID", "passpasspass");
+    WiFiMulti.addAP(ssid, password);
 
     Serial.println();
     Serial.println();

libraries/WiFi/examples/WiFiClientConnect/WiFiClientConnect.ino

@@ -9,8 +9,22 @@
 */
 #include <WiFi.h>
 
-const char* ssid     = "your-ssid";
-const char* password = "your-password";
+// To use secrets please read the documentation at https://espressif-docs.readthedocs-hosted.com/projects/arduino-esp32/en/latest/guides/secrets.html
+#if __has_include("secrets.h")
+  #include "secrets.h"
+#endif
+
+#ifdef SECRETS_WIFI_SSID_1
+const char* ssid     = SECRETS_WIFI_SSID_1;
+#else
+const char* ssid     = "example-SSID1"; // Traditional way
+#endif
+
+#ifdef SECRETS_WIFI_PASSWORD_1
+const char* password = SECRETS_WIFI_PASSWORD_1;
+#else
+const char* password = "example-password-1"; // Traditional way
+#endif
 
 int btnGPIO = 0;
 int btnState = false;

libraries/WiFi/examples/WiFiClientEvents/WiFiClientEvents.ino

@@ -38,9 +38,22 @@
 
 #include <WiFi.h>
 
-const char* ssid     = "your-ssid";
-const char* password = "your-password";
-
+// To use secrets please read the documentation at https://espressif-docs.readthedocs-hosted.com/projects/arduino-esp32/en/latest/guides/secrets.html
+#if __has_include("secrets.h")
+  #include "secrets.h"
+#endif
+
+#ifdef SECRETS_WIFI_SSID_1
+const char* ssid     = SECRETS_WIFI_SSID_1;
+#else
+const char* ssid     = "example-SSID1"; // Traditional way
+#endif
+
+#ifdef SECRETS_WIFI_PASSWORD_1
+const char* password = SECRETS_WIFI_PASSWORD_1;
+#else
+const char* password = "example-password-1"; // Traditional way
+#endif
 
 void WiFiEvent(WiFiEvent_t event)
 {

libraries/WiFi/examples/WiFiClientStaticIP/WiFiClientStaticIP.ino

@@ -6,8 +6,22 @@
 
 #include <WiFi.h>
 
-const char* ssid     = "your_network_name";
-const char* password = "your_network_password";
+// To use secrets please read the documentation at https://espressif-docs.readthedocs-hosted.com/projects/arduino-esp32/en/latest/guides/secrets.html
+#if __has_include("secrets.h")
+  #include "secrets.h"
+#endif
+
+#ifdef SECRETS_WIFI_SSID_1
+const char* ssid     = SECRETS_WIFI_SSID_1;
+#else
+const char* ssid     = "example-SSID1"; // Traditional way
+#endif
+
+#ifdef SECRETS_WIFI_PASSWORD_1
+const char* password = SECRETS_WIFI_PASSWORD_1;
+#else
+const char* password = "example-password-1"; // Traditional way
+#endif
 const char* host     = "example.com";
 const char* url      = "/index.html";
 

libraries/WiFi/examples/WiFiIPv6/WiFiIPv6.ino

@@ -1,7 +1,21 @@
 #include "WiFi.h"
 
-#define STA_SSID "**********"
-#define STA_PASS "**********"
+// To use secrets please read the documentation at https://espressif-docs.readthedocs-hosted.com/projects/arduino-esp32/en/latest/guides/secrets.html
+#if __has_include("secrets.h")
+  #include "secrets.h"
+#endif
+
+#ifdef SECRETS_WIFI_SSID_1
+const char* ssid     = SECRETS_WIFI_SSID_1;
+#else
+const char* ssid     = "example-SSID1"; // Traditional way
+#endif
+
+#ifdef SECRETS_WIFI_PASSWORD_1
+const char* password = SECRETS_WIFI_PASSWORD_1;
+#else
+const char* password = "example-password-1"; // Traditional way
+#endif
 #define AP_SSID  "esp32-v6"
 
 static volatile bool wifi_connected = false;
@@ -19,7 +33,7 @@ void wifiOnConnect(){
 void wifiOnDisconnect(){
     Serial.println("STA Disconnected");
     delay(1000);
-    WiFi.begin(STA_SSID, STA_PASS);
+    WiFi.begin(ssid, password);
 }
 
 void wifiConnectedLoop(){
@@ -109,7 +123,7 @@ void setup(){
     WiFi.onEvent(WiFiEvent);
     WiFi.mode(WIFI_MODE_APSTA);
     WiFi.softAP(AP_SSID);
-    WiFi.begin(STA_SSID, STA_PASS);
+    WiFi.begin(ssid, password);
 }
 
 void loop(){