diff --git a/backend/app/services/esp-idf-template/main/velxio_compat.h b/backend/app/services/esp-idf-template/main/velxio_compat.h
new file mode 100644
index 00000000..0cca12da
--- /dev/null
+++ b/backend/app/services/esp-idf-template/main/velxio_compat.h
@@ -0,0 +1,30 @@
+#ifndef VELXIO_COMPAT_H
+#define VELXIO_COMPAT_H
+
+// Compatibility shims for sketches written against arduino-esp32 3.x running
+// on the toolchain pinned to 2.0.17. Only kept until we bump the toolchain.
+//
+// ledcAttach / ledcAttachChannel were added in 3.x. Map them onto the 2.x
+// ledcSetup + ledcAttachPin pair so the sketch compiles unchanged.
+
+#if defined(ARDUINO_ARCH_ESP32) && !defined(ledcAttach)
+#include "Arduino.h"
+
+static inline bool ledcAttach(uint8_t pin, uint32_t freq, uint8_t resolution) {
+    static uint8_t _velxio_next_channel = 0;
+    if (_velxio_next_channel >= 16) return false;
+    uint8_t ch = _velxio_next_channel++;
+    ledcSetup(ch, freq, resolution);
+    ledcAttachPin(pin, ch);
+    return true;
+}
+
+static inline bool ledcAttachChannel(uint8_t pin, uint32_t freq, uint8_t resolution, uint8_t channel) {
+    if (channel >= 16) return false;
+    ledcSetup(channel, freq, resolution);
+    ledcAttachPin(pin, channel);
+    return true;
+}
+#endif
+
+#endif // VELXIO_COMPAT_H
diff --git a/backend/app/services/espidf_compiler.py b/backend/app/services/espidf_compiler.py
index 0633fe31..b0e55cb3 100644
--- a/backend/app/services/espidf_compiler.py
+++ b/backend/app/services/espidf_compiler.py
@@ -846,9 +846,21 @@ class ESPIDFCompiler:
             if self.has_arduino:
                 # Arduino-as-component mode: copy sketch as .cpp
                 sketch_cpp = project_dir / 'main' / 'sketch.ino.cpp'
-                # Prepend Arduino.h if not already included
+                # Prepend Arduino.h + velxio_compat.h if not already included.
+                # velxio_compat.h shims arduino-esp32 3.x APIs (ledcAttach, …)
+                # onto the 2.0.17 toolchain we currently pin. See
+                # esp-idf-template/main/velxio_compat.h.
                 if '#include' not in main_content or 'Arduino.h' not in main_content:
-                    main_content = '#include "Arduino.h"\n' + main_content
+                    main_content = (
+                        '#include "Arduino.h"\n'
+                        '#include "velxio_compat.h"\n' + main_content
+                    )
+                else:
+                    main_content = main_content.replace(
+                        '#include "Arduino.h"',
+                        '#include "Arduino.h"\n#include "velxio_compat.h"',
+                        1,
+                    )
                 sketch_cpp.write_text(main_content, encoding='utf-8')
 
                 # Copy additional files (.h, .cpp)