fastled 1.4.34__tar.gz → 1.4.36__tar.gz

{fastled-1.4.34 → fastled-1.4.36}/.cursorrules

@@ -31,8 +31,43 @@
 3. Install dependencies with `uv add <package>`
 4. Run scripts with `uv run <script>`
 
+## Emoji/Emoticon Usage
+
+**ALWAYS use the `EMO()` function for emojis, NEVER hardcode emojis directly!**
+
+### Guidelines:
+- ✅ Use: `from fastled.emoji_util import EMO` then `EMO('⚠️', 'WARNING:')`
+- ✅ Use: `from fastled.emoji_util import safe_print` for Unicode-safe printing
+- ❌ NEVER use: hardcoded emojis like `print("⚠️ Warning")`
+- ❌ NEVER use: raw Unicode without fallback handling
+
+### Common Patterns:
+- Warning messages: `EMO('⚠️', 'WARNING:')`
+- Success messages: `EMO('✅', 'SUCCESS:')`
+- Error messages: `EMO('❌', 'ERROR:')`
+- Info messages: `EMO('ℹ️', 'INFO:')`
+- Playwright/browser: `EMO('🎭', '*')`
+- Package/install: `EMO('📦', '*')`
+
+### Rationale:
+- Windows cmd.exe has poor Unicode support and will crash on raw emojis
+- The `EMO()` function provides fallback text for systems that don't support emojis
+- Ensures consistent behavior across all platforms (Windows, macOS, Linux)
+- Prevents application crashes due to encoding issues
+
+### Examples:
+```python
+# Good - with EMO function
+from fastled.emoji_util import EMO
+print(f"{EMO('⚠️', 'WARNING:')} Debug mode detected with Playwright installed")
+
+# Bad - hardcoded emoji
+print("⚠️ Debug mode detected with Playwright installed")
+```
+
 ## Additional Rules:
 - When suggesting Python commands, always prefix with `uv run`
 - When creating scripts that execute Python, use `uv run` in the script
 - When documenting Python usage, emphasize `uv run` syntax
-- Update any existing scripts that use `python` or `python3` to use `uv run`
+- Update any existing scripts that use `python` or `python3` to use `uv run`
+- When adding user-facing messages with emojis, always use the `EMO()` function

fastled-1.4.36/.vscode/launch.json

@@ -0,0 +1,26 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "🎯 Auto Debug (Smart File Detection)",
+            "type": "auto-debug",
+            "request": "launch",
+            "map": {
+                "*.ino": "Arduino: Run .ino with FastLED",
+                "*.py": "Python: Current File (UV)"
+            }
+        },
+        {
+            "name": "Python: Current File (UV)",
+            "type": "python",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "cwd": "${workspaceFolder}",
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/src"
+            },
+            "justMyCode": true
+        }
+    ]
+}

fastled-1.4.36/EXTENDED_INO.md

@@ -0,0 +1,463 @@
+# Extended INO Format Specification
+
+## Overview
+
+Extended INO is a format that allows Arduino sketch files (`.ino`) to embed build configuration metadata directly within the source code, similar to Astral UV's inlined script dependencies. This enables self-contained sketches that carry their own build requirements, making them more portable and easier to share.
+
+## Motivation
+
+Traditional Arduino development requires external configuration files (`platformio.ini`, `arduino-cli.yaml`) or IDE-specific settings to specify build parameters. Extended INO embeds this configuration directly in the sketch file, providing:
+
+- **Portability**: Sketches carry their build requirements
+- **Self-Documentation**: Build configuration is visible alongside code
+- **Reproducibility**: Consistent builds across different environments
+- **Simplicity**: Single file contains both code and configuration
+
+## Format Specification
+
+### Basic Structure
+
+Extended INO files use a comment block with TOML configuration embedded between delimiter markers:
+
+```cpp
+// /// extended-ino
+// [build]
+// board = "arduino:avr:uno"
+// 
+// [flags]
+// build = ["-DDEBUG=1", "-O2"]
+// link = ["-Wl,--gc-sections"]
+// 
+// [defines]
+// DEBUG = "1"
+// VERSION = "\"1.0.0\""
+// ///
+
+#include <FastLED.h>
+
+void setup() {
+    // Your Arduino code here
+}
+
+void loop() {
+    // Your Arduino code here
+}
+```
+
+### Delimiter Rules
+
+- Start delimiter: `// /// extended-ino`
+- End delimiter: `// ///`
+- All configuration lines must be prefixed with `// ` (comment prefix + space)
+- The content between delimiters must be valid TOML
+- All relative paths in configuration are resolved relative to the sketch file's directory
+
+### Required Fields
+
+#### `[build]` Section
+
+- `board` (string): Board Fully Qualified Name (FQBN)
+  - Format: `package:architecture:board_id`
+  - Example: `"arduino:avr:uno"`, `"esp32:esp32:esp32"`
+
+### Optional Fields
+
+#### `[flags]` Section
+
+- `build` (array of strings): Compiler flags passed during compilation
+- `link` (array of strings): Linker flags passed during linking
+- `upload` (array of strings): Upload-specific flags
+
+#### `[defines]` Section
+
+Key-value pairs of preprocessor definitions:
+- Keys become `#define` names
+- Values become `#define` values
+- String values should be quoted appropriately for C/C++
+
+#### `[dependencies]` Section
+
+- `libraries` (array of strings): Library dependencies with optional version constraints
+- `additional_urls` (array of strings): Board Manager package index URLs for custom boards
+- `cores` (array of strings): Core dependencies
+- `tools` (array of strings): Tool dependencies
+
+#### `[settings]` Section
+
+- `cpu_frequency` (string): CPU frequency setting
+- `flash_frequency` (string): Flash frequency setting  
+- `upload_speed` (integer): Upload baud rate
+- `partition_scheme` (string): Flash partition scheme
+
+#### `[cli]` Section (Essential Arduino CLI Settings)
+
+**Required for Build Process:**
+- `directories_user` (string): Arduino sketchbook directory for libraries and hardware
+- `directories_data` (string): Arduino CLI data directory for core installations
+- `export_binaries` (boolean): Always save compiled binaries to sketch folder
+
+**Required for Custom Boards:**
+- `board_manager_additional_urls` (array of strings): URLs for additional board package indexes
+- `enable_unsafe_library_install` (boolean): Allow installation from git URLs or zip files
+
+#### `[cli_optional]` Section (Nice-to-Have Arduino CLI Settings)
+
+**Build Performance:**
+- `build_cache_path` (string): Custom location for build cache files
+- `build_cache_extra_paths` (array of strings): Additional directories to include in build cache
+- `build_cache_ttl` (string): Time-to-live for cached compilation units (e.g., "720h")
+
+**Development Experience:**
+- `logging_level` (string): Log verbosity level ("trace", "debug", "info", "warn", "error", "fatal")
+- `logging_file` (string): Log file path for persistent logging
+- `output_no_color` (boolean): Disable colored output for terminals that don't support it
+- `locale` (string): Language setting for Arduino CLI messages
+
+**Network Configuration:**
+- `network_proxy` (string): HTTP/HTTPS proxy server URL
+- `connection_timeout` (string): Network timeout duration (e.g., "10s")
+
+**Advanced Features:**
+- `daemon_port` (string): gRPC port for Arduino CLI daemon mode
+- `metrics_enabled` (boolean): Enable telemetry collection
+- `updater_enable_notification` (boolean): Check for Arduino CLI updates
+
+## Multi-Board Support
+
+Extended INO supports multiple board configurations using TOML table arrays:
+
+```cpp
+// /// extended-ino
+// [[board]]
+// fqbn = "arduino:avr:uno"
+// 
+// [board.flags]
+// build = ["-DARDUINO_UNO=1"]
+// 
+// [board.defines]
+// BOARD_TYPE = "\"UNO\""
+// 
+// [[board]]
+// fqbn = "esp32:esp32:esp32"
+// 
+// [board.flags]
+// build = ["-DARDUINO_ESP32=1"]
+// 
+// [board.defines]
+// BOARD_TYPE = "\"ESP32\""
+// ///
+```
+
+## Examples
+
+### Simple Example
+
+```cpp
+// /// extended-ino
+// [build]
+// board = "arduino:avr:uno"
+// 
+// [defines]
+// LED_PIN = "13"
+// BAUD_RATE = "9600"
+// ///
+
+void setup() {
+    pinMode(LED_PIN, OUTPUT);
+    Serial.begin(BAUD_RATE);
+}
+
+void loop() {
+    digitalWrite(LED_PIN, HIGH);
+    delay(1000);
+    digitalWrite(LED_PIN, LOW);
+    delay(1000);
+}
+```
+
+### Advanced Example
+
+```cpp
+// /// extended-ino
+// [build]
+// board = "esp32:esp32:esp32"
+// 
+// [flags]
+// build = [
+//     "-DCORE_DEBUG_LEVEL=4",
+//     "-DARDUINO_RUNNING_CORE=1",
+//     "-DARDUINO_EVENT_RUNNING_CORE=1"
+// ]
+// link = ["-Wl,--gc-sections"]
+// 
+// [defines]
+// WIFI_SSID = "\"MyNetwork\""
+// WIFI_PASSWORD = "\"MyPassword\""
+// DEBUG_ENABLED = "1"
+// 
+// [dependencies]
+// libraries = ["WiFi", "WebServer", "ArduinoJson@>=6.0.0"]
+// additional_urls = ["https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json"]
+// 
+// [settings]
+// cpu_frequency = "240MHz"
+// flash_frequency = "80MHz"
+// upload_speed = 921600
+// partition_scheme = "default"
+// 
+// [cli]
+// directories_user = "/home/user/Arduino"
+// export_binaries = true
+// board_manager_additional_urls = ["https://adafruit.github.io/arduino-board-index/package_adafruit_index.json"]
+// 
+// [cli_optional]
+// build_cache_ttl = "720h"
+// logging_level = "info"
+// output_no_color = false
+// ///
+
+#include <WiFi.h>
+#include <WebServer.h>
+#include <ArduinoJson.h>
+
+void setup() {
+    Serial.begin(115200);
+    WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
+}
+
+void loop() {
+    // Application code
+}
+```
+
+### Arduino CLI Configuration Example
+
+```cpp
+// /// extended-ino
+// [build]
+// board = "esp32:esp32:esp32dev"
+// 
+// [dependencies]
+// libraries = ["FastLED@>=3.6.0", "WiFiManager", "ArduinoJson@^6.21.0"]
+// additional_urls = [
+//     "https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json",
+//     "https://adafruit.github.io/arduino-board-index/package_adafruit_index.json"
+// ]
+// 
+// [defines]
+// FASTLED_INTERNAL = "1"
+// LED_COUNT = "100"
+// 
+// [cli]
+// directories_user = "./libraries"       # Relative to sketch directory
+// directories_data = "./arduino-data"    # Relative to sketch directory  
+// export_binaries = true
+// enable_unsafe_library_install = true
+// 
+// [cli_optional]
+// build_cache_path = "./build-cache"     # Relative to sketch directory
+// build_cache_ttl = "168h"
+// logging_level = "debug"
+// logging_file = "./arduino-cli.log"     # Relative to sketch directory
+// ///
+
+#include <FastLED.h>
+#include <WiFiManager.h>
+#include <ArduinoJson.h>
+
+CRGB leds[LED_COUNT];
+
+void setup() {
+    FastLED.addLeds<WS2812B, 2, GRB>(leds, LED_COUNT);
+    WiFiManager wifiManager;
+    wifiManager.autoConnect("FastLED_Setup");
+}
+
+void loop() {
+    // LED effects and WiFi communication
+}
+```
+
+### Multi-Board Example
+
+```cpp
+// /// extended-ino
+// [[board]]
+// fqbn = "arduino:avr:uno"
+// 
+// [board.defines]
+// LED_COUNT = "50"
+// DATA_PIN = "6"
+// 
+// [board.flags]
+// build = ["-DAVR_BOARD=1"]
+// 
+// [[board]]
+// fqbn = "esp32:esp32:esp32"
+// 
+// [board.defines]
+// LED_COUNT = "100"
+// DATA_PIN = "2"
+// 
+// [board.flags]
+// build = ["-DESP32_BOARD=1"]
+// 
+// [board.settings]
+// cpu_frequency = "240MHz"
+// ///
+
+#include <FastLED.h>
+
+CRGB leds[LED_COUNT];
+
+void setup() {
+    FastLED.addLeds<WS2812, DATA_PIN, GRB>(leds, LED_COUNT);
+}
+
+void loop() {
+    // LED animation code
+}
+```
+
+## Implementation Considerations
+
+### Parsing
+
+1. **Automatic Discovery**: Detect Extended INO configuration in any `.ino` file being processed (no path argument required)
+2. **Comment Extraction**: Parse comment blocks between delimiters within the sketch file
+3. **TOML Validation**: Validate embedded TOML syntax
+4. **Field Validation**: Ensure required fields are present
+5. **Board Resolution**: Validate FQBN format and availability
+6. **Path Resolution**: Use sketch file directory as base path for all relative paths and generated files
+
+### Integration Points
+
+Extended INO can integrate with:
+
+- **Arduino CLI**: Generate temporary `arduino-cli.yaml` configuration files from `[cli]` and `[cli_optional]` sections
+- **PlatformIO**: Convert to `platformio.ini` format using board, flags, and dependencies
+- **Arduino IDE 2.x**: Plugin/extension support for parsing and applying Extended INO configuration
+- **VS Code**: Language server extensions with Arduino CLI integration
+
+### Arduino CLI Configuration Generation
+
+Extended INO tools can generate Arduino CLI configuration files from embedded metadata:
+
+```yaml
+# Generated arduino-cli.yaml from Extended INO [cli] section
+board_manager:
+  additional_urls:
+    - "https://adafruit.github.io/arduino-board-index/package_adafruit_index.json"
+
+directories:
+  user: "./libraries"
+  data: "./arduino-data"
+
+sketch:
+  always_export_binaries: true
+
+library:
+  enable_unsafe_install: true
+
+build_cache:
+  path: "./build-cache"
+  ttl: "168h"
+
+logging:
+  level: "debug"
+  file: "./arduino-cli.log"
+```
+
+### Error Handling
+
+- **Invalid TOML**: Clear syntax error messages with line numbers
+- **Missing Required Fields**: Specify which fields are missing
+- **Invalid FQBN**: Validate board availability
+- **Conflicting Configurations**: Handle multi-board conflicts
+
+### Backward Compatibility
+
+- Files without Extended INO blocks remain valid Arduino sketches
+- Existing build systems can ignore the comment blocks
+- Gradual adoption possible
+
+## Future Considerations
+
+### Planned Extensions
+
+1. **Variable Substitution**: Environment variable and computed value support
+2. **Conditional Configuration**: Platform-specific sections
+3. **Include Support**: Reference external configuration fragments
+4. **Version Constraints**: Semantic versioning for dependencies
+5. **Custom Build Steps**: Pre/post-build actions
+
+### Example Future Syntax
+
+```cpp
+// /// extended-ino
+// [build]
+// board = "${BOARD_FQBN:-arduino:avr:uno}"
+// 
+// [conditional.esp32]
+// condition = "platform == 'esp32'"
+// 
+// [conditional.esp32.defines]
+// WIFI_ENABLED = "1"
+// 
+// [includes]
+// common = "./common-config.toml"
+// ///
+```
+
+## Tool Invocation
+
+Extended INO tools operate directly on sketch files without requiring explicit path arguments:
+
+```bash
+# Tool discovers configuration from the sketch file automatically
+extended-ino-build MySketch.ino
+
+# Working directory becomes the sketch's directory
+extended-ino-compile MyProject/MySketch.ino
+
+# All generated files appear in the sketch's directory
+extended-ino-upload ./examples/Blink/Blink.ino
+```
+
+**Key Behaviors:**
+- **Implicit Path Discovery**: Tools automatically detect Extended INO configuration in the specified `.ino` file
+- **Working Directory**: The sketch file's directory becomes the base path for all operations
+- **Generated Files**: All temporary files (`arduino-cli.yaml`, `platformio.ini`, build cache) are created relative to the sketch location
+- **No Path Arguments**: Tools never require separate path or directory arguments beyond the sketch file itself
+
+## Tooling Support
+
+### Required Tools
+
+- **TOML Parser**: For configuration extraction and validation from sketch files
+- **Board Database**: FQBN validation and resolution
+- **Build System Integration**: Convert to native build formats using sketch file location as working directory
+
+### Recommended Workflow
+
+1. **Parse**: Extract and validate Extended INO configuration from comment block in the sketch file
+2. **Resolve**: Validate board FQBN and check dependency availability  
+3. **Configure**: Generate temporary `arduino-cli.yaml` from `[cli]` and `[cli_optional]` sections in the sketch directory
+4. **Dependencies**: Install libraries and board packages as specified
+5. **Generate**: Create appropriate build system files (platformio.ini, compile_commands.json) in the sketch directory
+6. **Build**: Execute Arduino CLI build process with generated configuration using the sketch file path
+7. **Export**: Save binaries to sketch directory if `export_binaries` is enabled
+8. **Clean**: Remove temporary configuration files and build artifacts from sketch directory
+
+## Conclusion
+
+Extended INO provides a self-contained format for Arduino sketches that embeds build configuration alongside source code. This improves portability, reproducibility, and ease of sharing while maintaining backward compatibility with existing Arduino development workflows.
+
+The format integrates comprehensive Arduino CLI configuration options, enabling complete control over the build environment, dependency management, and development experience through embedded TOML metadata.
+
+The format is designed to be:
+- **Human-readable**: TOML syntax is clear and well-documented
+- **Tool-friendly**: Structured format enables automated processing and Arduino CLI integration
+- **Extensible**: Future features can be added without breaking changes
+- **Compatible**: Works with existing Arduino ecosystems and CLI tools
+- **Comprehensive**: Covers essential build settings and optional developer experience enhancements

{fastled-1.4.34 → fastled-1.4.36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastled
-Version: 1.4.34
+Version: 1.4.36
 Summary: FastLED Wasm Compiler
 Home-page: https://github.com/zackees/fastled-wasm
 Maintainer: Zachary Vorhies
@@ -23,6 +23,7 @@ Requires-Dist: flask-cors>=4.0.0
 Requires-Dist: livereload
 Requires-Dist: disklru>=2.0.4
 Requires-Dist: playwright>=1.40.0
+Requires-Dist: websockify>=0.13.0
 Dynamic: home-page
 Dynamic: license-file
 Dynamic: maintainer

{fastled-1.4.34 → fastled-1.4.36}/pyproject.toml

@@ -26,7 +26,7 @@ dependencies = [
     "livereload",
     "disklru>=2.0.4",
     "playwright>=1.40.0",
-
+    "websockify>=0.13.0",
 ]
 
 dynamic = ["version"]

fastled-1.4.36/requirements.docker.txt

@@ -0,0 +1 @@
+fastled-wasm-server>=1.1.42

{fastled-1.4.34 → fastled-1.4.36}/src/fastled/__version__.py

@@ -1,6 +1,6 @@
 # IMPORTANT! There's a bug in github which will REJECT any version update
 # that has any other change in the repo. Please bump the version as the
 # ONLY change in a commit, or else the pypi update and the release will fail.
-__version__ = "1.4.34"
+__version__ = "1.4.36"
 
 __version_url_latest__ = "https://raw.githubusercontent.com/zackees/fastled-wasm/refs/heads/main/src/fastled/__version__.py"

{fastled-1.4.34 → fastled-1.4.36}/src/fastled/app.py

@@ -12,6 +12,7 @@ from fastled.compile_server import CompileServer
 from fastled.emoji_util import EMO
 from fastled.filewatcher import file_watcher_set
 from fastled.parse_args import Args, parse_args
+from fastled.settings import DEFAULT_URL
 from fastled.sketch import find_sketch_directories, looks_like_fastled_repo
 
 
@@ -53,6 +54,31 @@ def main() -> int:
 
     args = parse_args()
 
+    if args.emsdk_headers:
+        import httpx
+
+        out_path = args.emsdk_headers
+        base_url = args.web if isinstance(args.web, str) else DEFAULT_URL
+        try:
+            response = httpx.get(f"{base_url}/headers/emsdk")
+            if response.status_code == 200:
+                Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+                with open(out_path, "wb") as f:
+                    f.write(response.content)
+                print(f"{EMO('✅','SUCCESS:')} EMSDK headers exported to {out_path}")
+                return 0
+            else:
+                print(
+                    f"{EMO('❌','ERROR:')} Failed to export EMSDK headers: HTTP {response.status_code}"
+                )
+                return 1
+        except KeyboardInterrupt:
+            print("\nExiting from main...")
+            return 1
+        except Exception as e:
+            print(f"{EMO('❌','ERROR:')} Exception: {e}")
+            return 1
+
     # Handle --install command early
     if args.install:
         from fastled.install.main import fastled_install

{fastled-1.4.34 → fastled-1.4.36}/src/fastled/args.py

@@ -29,6 +29,7 @@ class Args:
     install: bool = False  # Install FastLED development environment
     dry_run: bool = False  # Dry run mode for testing
     no_interactive: bool = False  # Non-interactive mode
+    emsdk_headers: str | None = None  # Path to export EMSDK headers ZIP
 
     @staticmethod
     def from_namespace(args: argparse.Namespace) -> "Args":
@@ -84,6 +85,9 @@ class Args:
         assert isinstance(
             args.no_interactive, bool
         ), f"expected bool, got {type(args.no_interactive)}"
+        assert isinstance(
+            args.emsdk_headers, str | None
+        ), f"expected str | None, got {type(args.emsdk_headers)}"
 
         init: bool | str = False
         if args.init is None:
@@ -115,5 +119,6 @@ class Args:
             ram_disk_size=args.ram_disk_size,
             install=args.install,
             dry_run=args.dry_run,
+            emsdk_headers=args.emsdk_headers,
             no_interactive=args.no_interactive,
         )