secrets

.gitignore

@@ -43,4 +43,4 @@ _build/
 debug.cfg
 debug.svd
 debug_custom.json
-libraries/Insights/examples/*/*.ino.zip
+liraries/Insights/examples/*/*.ino.zip

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/ArduinoOTA/examples/BasicOTA/BasicOTA.ino

@@ -3,8 +3,22 @@
 #include <WiFiUdp.h>
 #include <ArduinoOTA.h>
 
-const char* ssid = "..........";
-const char* 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 setup() {
   Serial.begin(115200);

libraries/ArduinoOTA/examples/OTAWebUpdater/OTAWebUpdater.ino

@@ -4,10 +4,24 @@
 #include <ESPmDNS.h>
 #include <Update.h>
 
-const char* host = "esp32";
-const char* ssid = "xxx";
-const char* password = "xxxx";
+// 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 = "esp32";
 WebServer server(80);
 
 /*

libraries/AsyncUDP/examples/AsyncUDPClient/AsyncUDPClient.ino

@@ -1,8 +1,22 @@
 #include "WiFi.h"
 #include "AsyncUDP.h"
 
-const char * ssid = "***********";
-const char * 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
 
 AsyncUDP udp;
 

libraries/AsyncUDP/examples/AsyncUDPMulticastServer/AsyncUDPMulticastServer.ino

@@ -1,8 +1,22 @@
 #include "WiFi.h"
 #include "AsyncUDP.h"
 
-const char * ssid = "***********";
-const char * 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
 
 AsyncUDP udp;
 

libraries/AsyncUDP/examples/AsyncUDPServer/AsyncUDPServer.ino

@@ -1,8 +1,22 @@
 #include "WiFi.h"
 #include "AsyncUDP.h"
 
-const char * ssid = "***********";
-const char * 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
 
 AsyncUDP udp;
 

libraries/ESP32/examples/Camera/CameraWebServer/CameraWebServer.ino

@@ -32,11 +32,22 @@
 //#define CAMERA_MODEL_DFRobot_Romeo_ESP32S3 // Has PSRAM
 #include "camera_pins.h"
 
-// ===========================
-// Enter your WiFi credentials
-// ===========================
-const char* ssid = "**********";
-const char* 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 startCameraServer();
 void setupLedFlash(int pin);

libraries/ESP32/examples/Time/SimpleTime/SimpleTime.ino

@@ -2,8 +2,22 @@
 #include "time.h"
 #include "esp_sntp.h"
 
-const char* ssid       = "YOUR_SSID";
-const char* password   = "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
 
 const char* ntpServer1 = "pool.ntp.org";
 const char* ntpServer2 = "time.nist.gov";

libraries/ESPmDNS/examples/mDNS-SD_Extended/mDNS-SD_Extended.ino

@@ -12,8 +12,22 @@
 #include <WiFi.h>
 #include <ESPmDNS.h>
 
-const char* ssid     = "...";
-const char* 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 setup() {
     Serial.begin(115200);

libraries/ESPmDNS/examples/mDNS_Web_Server/mDNS_Web_Server.ino

@@ -15,13 +15,26 @@
 
  */
 
-
 #include <WiFi.h>
 #include <ESPmDNS.h>
 #include <WiFiClient.h>
 
-const char* ssid = "............";
-const char* 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
 
 // TCP server at port 80 will respond to HTTP requests
 WiFiServer server(80);

libraries/FFat/examples/FFat_time/FFat_time.ino

@@ -3,8 +3,22 @@
 #include <time.h> 
 #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
 
 long timezone = 1; 
 byte daysavetime = 1;

libraries/HTTPUpdateServer/examples/WebUpdater/WebUpdater.ino

@@ -8,14 +8,24 @@
 #include <ESPmDNS.h>
 #include <HTTPUpdateServer.h>
 
-#ifndef STASSID
-#define STASSID "your-ssid"
-#define STAPSK  "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
 
 const char* host = "esp32-webupdate";
-const char* ssid = STASSID;
-const char* password = STAPSK;
 
 WebServer httpServer(80);
 HTTPUpdateServer httpUpdater;