refactor: update and fix OTA updates

ph1p · ph1p · commit edb8dd8270be · 2025-12-19T13:49:12.000+01:00
Add documentation
diff --git a/README.md b/README.md
@@ -19,6 +19,10 @@ Turn your OBEGRÄNSAD LED Wall Lamp into a live drawing canvas
 - [Software Setup](#software-setup)
   - [ESP32 Setup with VS Code and PlatformIO](#esp32-setup-with-vs-code-and-platformio)
   - [WiFi Configuration](#wifi-configuration)
+- [OTA Updates](#ota-updates)
+  - [Configuration](#configuration)
+  - [Upload Methods](#upload-methods)
+  - [Visual Feedback](#visual-feedback)
 - [HTTP API Reference](#http-api-reference)
   - [Device Information](#device-information)
   - [Plugin Control](#plugin-control)
@@ -180,6 +184,80 @@ For ESP8266, WiFi Manager is not available. Set `WIFI_SSID` and `WIFI_PASSWORD`
 
 ---
 
+## OTA Updates
+
+Over-The-Air (OTA) updates allow you to upload new firmware wirelessly without a USB connection. This is powered by [ElegantOTA](https://github.com/ayushsharma82/ElegantOTA).
+
+### Configuration
+
+Before using OTA, configure the following:
+
+1. **Set OTA Credentials** in `include/secrets.h`:
+   ```cpp
+   #define OTA_USERNAME "admin"
+   #define OTA_PASSWORD "your-password"
+   ```
+
+2. **Configure Upload Settings** in `platformio.ini` (for the `esp32dev` environment):
+   ```ini
+   extra_scripts = upload.py
+   upload_protocol = custom
+   custom_upload_url = http://192.168.178.50  # Your device IP
+   custom_username = admin
+   custom_password = your-password
+   ```
+
+**Note:** Replace `192.168.178.50` with your device's actual IP address.
+
+### Upload Methods
+
+#### Method 1: Web Interface (Manual Upload)
+
+1. Navigate to `http://your-device-ip/update` in your browser
+2. Login with your configured credentials (default: `admin` / `ikea-led-wall`)
+3. Select your firmware file (`.pio/build/esp32dev/firmware.bin`)
+4. Click "Update" and wait for completion
+5. Device will automatically reboot with new firmware
+
+#### Method 2: PlatformIO (Automated Upload)
+
+Upload directly from PlatformIO via the command line:
+
+```bash
+pio run -e esp32dev -t upload
+```
+
+Or use the PlatformIO Upload button in VS Code (bottom toolbar).
+
+**Requirements:**
+- Python packages: `requests_toolbelt` and `tqdm`
+- Install if needed: `pip install requests_toolbelt tqdm`
+
+### Visual Feedback
+
+During OTA updates, the LED matrix provides visual feedback:
+
+- **"U" letter displayed**: Update has started
+- **Serial output**: Progress updates every second
+- **"R" letter displayed**: Update completed (device will reboot)
+
+Monitor the serial output for detailed progress:
+```
+OTA update started!
+OTA Progress Current: 262144 bytes, Final: 1440655 bytes
+OTA Progress Current: 524288 bytes, Final: 1440655 bytes
+...
+OTA update finished successfully!
+```
+
+**Troubleshooting:**
+- Ensure device is connected to the same network
+- Verify IP address in `platformio.ini` matches device IP
+- Check credentials match in both `secrets.h` and `platformio.ini`
+- For upload failures, try the web interface method first
+
+---
+
 ## HTTP API Reference
 
 Base URL: `http://your-server/api`
@@ -524,7 +602,7 @@ Create a second automation or condition to call `rest_command.obegraensad_bright
 **Structure:**
 - `src/` - Arduino code
 - `platformio.ini` - Build configuration
-  - Uncomment OTA lines for over-the-air updates (replace IP with your device)
+  - See [OTA Updates](#ota-updates) section for wireless firmware upload configuration
 
 ### Frontend Development
 
diff --git a/include/secrets.h b/include/secrets.h
@@ -10,5 +10,5 @@
 #endif
 
 // If you would like to perform OTA updates, you need to define the credentials here
-#define OTA_USERNAME ""
-#define OTA_PASSWORD ""
+#define OTA_USERNAME "admin"
+#define OTA_PASSWORD "ikea-led-wall"
diff --git a/platformio.ini b/platformio.ini
@@ -10,6 +10,7 @@
 
 [platformio]
 default_envs = esp32dev
+lib_compat_mode = strict
 
 [env]
 framework = arduino
@@ -44,8 +45,10 @@ monitor_filters = esp32_exception_decoder
 ; -DARDUINO_USB_MODE=1
 ; extra_scripts = upload.py
 ; upload_protocol = custom
-; upload_url = http://192.168.178.50/update
+; custom_upload_url = http://192.168.178.50
 ; upload_port = 192.168.178.50
+; custom_username = admin
+; custom_password = ikea-led-wall
 
 [env:ESP32-wemos]
 lib_deps =
@@ -62,8 +65,9 @@ board_build.partitions = partitions-4MB.csv
 monitor_filters = esp32_exception_decoder
 ; extra_scripts = upload.py
 ; upload_protocol = custom
-; upload_url = http://192.168.178.50/update
-; upload_port = 192.168.178.50
+; custom_upload_url = http://192.168.178.50
+; custom_username = admin
+; custom_password = ikea-led-wall
 
 [env:esp32dev]
 lib_deps =
@@ -80,8 +84,9 @@ board_build.partitions = partitions-4MB.csv
 monitor_filters = esp32_exception_decoder
 ; extra_scripts = upload.py
 ; upload_protocol = custom
-; upload_url = http://192.168.178.50/update
-; upload_port = 192.168.178.50
+; custom_upload_url = http://192.168.178.50
+; custom_username = admin
+; custom_password = ikea-led-wall
 
 [env:nodemcuv2]
 board = nodemcuv2
diff --git a/src/ota.cpp b/src/ota.cpp
@@ -9,7 +9,6 @@ unsigned long ota_progress_millis = 0;
 
 void onOTAStart()
 {
-  // Log when OTA has started
   Serial.println("OTA update started!");
   currentStatus = UPDATE;
 
@@ -56,12 +55,15 @@ void onOTAEnd(bool success)
 
 void initOTA(AsyncWebServer &server)
 {
-  ElegantOTA.begin(&server); // Start ElegantOTA
+  ElegantOTA.begin(&server);
+  ElegantOTA.setAutoReboot(true);
   ElegantOTA.setAuth(otaUser, otaPassword);
-  // ElegantOTA callbacks
-  ElegantOTA.onStart(onOTAStart);
-  ElegantOTA.onProgress(onOTAProgress);
-  ElegantOTA.onEnd(onOTAEnd);
+
+  ElegantOTA.onStart([]() { onOTAStart(); });
+
+  ElegantOTA.onProgress([](size_t current, size_t final) { onOTAProgress(current, final); });
+
+  ElegantOTA.onEnd([](bool success) { onOTAEnd(success); });
 }
 
 #endif
diff --git a/upload.py b/upload.py
@@ -1,4 +1,4 @@
-# Allows PlatformIO to upload directly to AsyncElegantOTA
+# Allows PlatformIO to upload directly to ElegantOTA
 #
 # To use:
 # - copy this script into the same folder as your platformio.ini
@@ -9,14 +9,16 @@
 # custom_upload_url = <your upload URL>
 #
 # An example of an upload URL:
-# custom_upload_URL = http://192.168.1.123/update
+#                custom_upload_url = http://192.168.1.123/update
+# also possible: custom_upload_url = http://domainname/update
 
+import sys
 import requests
 import hashlib
-Import('env')
-
-username = "admin"
-password = "ikea-led-wall"
+from urllib.parse import urlparse
+import time
+from requests.auth import HTTPDigestAuth
+Import("env")
 
 try:
     from requests_toolbelt import MultipartEncoder, MultipartEncoderMonitor
@@ -29,31 +31,113 @@
 
 def on_upload(source, target, env):
     firmware_path = str(source[0])
-    upload_url = env.GetProjectOption('upload_url')
+
+    auth = None
+    upload_url_compatibility = env.GetProjectOption('custom_upload_url')
+    upload_url = upload_url_compatibility.replace("/update", "")
 
     with open(firmware_path, 'rb') as firmware:
         md5 = hashlib.md5(firmware.read()).hexdigest()
+
+        parsed_url = urlparse(upload_url)
+        host_ip = parsed_url.netloc
+
+        is_spiffs = source[0].name == "spiffs.bin"
+        file_type = "fs" if is_spiffs else "fr"
+
+        # execute GET request
+        start_url = f"{upload_url}/ota/start?mode={file_type}&hash={md5}"
+
+        start_headers = {
+            'Host': host_ip,
+            'User-Agent': 'Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/118.0',
+            'Accept': '*/*',
+            'Accept-Language': 'de,en-US;q=0.7,en;q=0.3',
+            'Accept-Encoding': 'gzip, deflate',
+            'Referer': f'{upload_url}/update',
+            'Connection': 'keep-alive'
+            }
+
+        try:
+            checkAuthResponse = requests.get(f"{upload_url_compatibility}/update")
+        except Exception as e:
+            return 'Error checking auth: ' + repr(e)
+
+        if checkAuthResponse.status_code == 401:
+            try:
+                username = env.GetProjectOption('custom_username')
+                password = env.GetProjectOption('custom_password')
+            except:
+                username = None
+                password = None
+                print("No authentication values specified.")
+                print('Please, add some Options in your .ini file like: \n\ncustom_username=username\ncustom_password=password\n')
+            if username is None or password is None:
+                return "Authentication required, but no credentials provided."
+            print("Serverconfiguration: authentication needed.")
+            auth = HTTPDigestAuth(username, password)
+            try:
+                doUpdateAuth = requests.get(start_url, headers=start_headers, auth=auth)
+            except Exception as e:
+                return 'Error while authenticating: ' + repr(e)
+
+            if doUpdateAuth.status_code != 200:
+                return "Authentication failed " + str(doUpdateAuth.status_code)
+            print("Authentication successful")
+        else:
+            auth = None
+            print("Serverconfiguration: authentication not needed.")
+            try:
+                doUpdate = requests.get(start_url, headers=start_headers)
+            except Exception as e:
+                return 'Error while starting upload: ' + repr(e)
+
+            if doUpdate.status_code != 200:
+                return "Start request failed " + str(doUpdate.status_code)
+
         firmware.seek(0)
         encoder = MultipartEncoder(fields={
             'MD5': md5,
             'firmware': ('firmware', firmware, 'application/octet-stream')}
         )
 
         bar = tqdm(desc='Upload Progress',
-              total=encoder.len,
-              dynamic_ncols=True,
-              unit='B',
-              unit_scale=True,
-              unit_divisor=4096
-              )
+                   total=encoder.len,
+                   dynamic_ncols=True,
+                   unit='B',
+                   unit_scale=True,
+                   unit_divisor=1024
+                   )
 
         monitor = MultipartEncoderMonitor(encoder, lambda monitor: bar.update(monitor.bytes_read - bar.n))
 
-        response = requests.post(upload_url,
-                                 auth=(username, password),
-                                 data=monitor,
-                                 headers={'Content-Type': monitor.content_type})
+        post_headers = {
+            'Host': host_ip,
+            'User-Agent': 'Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/118.0',
+            'Accept': '*/*',
+            'Accept-Language': 'de,en-US;q=0.7,en;q=0.3',
+            'Accept-Encoding': 'gzip, deflate',
+            'Referer': f'{upload_url}/update',
+            'Connection': 'keep-alive',
+            'Content-Type': monitor.content_type,
+            'Content-Length': str(monitor.len),
+            'Origin': f'{upload_url}'
+        }
+
+        try:
+            response = requests.post(f"{upload_url}/ota/upload", data=monitor, headers=post_headers, auth=auth)
+        except Exception as e:
+            return 'Error while uploading: ' + repr(e)
+
         bar.close()
-        print(response,response.text)
+        time.sleep(0.1)
+
+        if response.status_code != 200:
+            message = "\nUpload failed.\nServer response: " + response.text
+            tqdm.write(message)
+        else:
+            message = "\nUpload successful.\nServer response: " + response.text
+            tqdm.write(message)
+
 
-env.Replace(UPLOADCMD=on_upload)
+env.Replace(UPLOADCMD=on_upload)
