{"id":30676412,"url":"https://github.com/shortarrow/cc-led","last_synced_at":"2026-05-20T07:02:48.684Z","repository":{"id":312531158,"uuid":"1041137489","full_name":"ShortArrow/cc-led","owner":"ShortArrow","description":"Cross-platform CLI for Arduino LED control with multi-board support","archived":false,"fork":false,"pushed_at":"2025-08-31T10:20:47.000Z","size":179,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-31T10:29:25.056Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ShortArrow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-20T03:29:03.000Z","updated_at":"2025-08-31T10:28:54.000Z","dependencies_parsed_at":"2025-08-31T10:29:26.761Z","dependency_job_id":"b6ef766a-9f00-4a52-922d-fab9faa778a6","html_url":"https://github.com/ShortArrow/cc-led","commit_stats":null,"previous_names":["shortarrow/cc-led"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ShortArrow/cc-led","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShortArrow%2Fcc-led","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShortArrow%2Fcc-led/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShortArrow%2Fcc-led/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShortArrow%2Fcc-led/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ShortArrow","download_url":"https://codeload.github.com/ShortArrow/cc-led/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShortArrow%2Fcc-led/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273105960,"owners_count":25046950,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-01T02:00:09.058Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-01T10:13:15.091Z","updated_at":"2026-05-20T07:02:48.669Z","avatar_url":"https://github.com/ShortArrow.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cc-led\n\nThis project allows controlling the onboard LED on a arduino using a scriptable interface.\n\n## 📁 Project Structure\n\n```\ncc-led/                          # NPM package root\n├── package.json                 # NPM package definition\n├── src/                         # CLI source code\n│   ├── cli.js                  # Main CLI entry point\n│   ├── arduino.js              # Arduino CLI wrapper\n│   ├── controller.js           # LED controller via serial\n│   ├── boards/                 # Board management\n│   └── utils/                  # Utilities\n├── sketches/                    # Board configurations and sketches\n│   ├── xiao-rp2040/            # XIAO RP2040 support\n│   │   ├── board.json          # Board configuration\n│   │   ├── LEDBlink/           # Arduino sketches\n│   │   └── UniversalLedControl/\n│   ├── arduino-uno-r4/         # Arduino Uno R4 support\n│   │   ├── board.json          # Board configuration\n│   │   ├── LEDBlink/           # Arduino sketches\n│   │   └── UniversalLedControl/\n│   ├── raspberry-pi-pico/      # Raspberry Pi Pico support\n│   └── common/                 # Shared Arduino libraries\n├── test/                        # Vitest test files\n└── legacy/                      # PowerShell scripts (legacy)\n```\n\n## Support\n\n- Claude Code ✅ Supporte\n- Codex  📅 W.I.P. \n- Gemini  📅 W.I.P. \n\n| Board | Status | LED | Signeture | Wiki |\n|----------|--------|------|-----------|------|\n| Seeed Studio XIAO RP2040 | ✅ Supported | RGB | xiao-rp2040 | [Wiki](https://wiki.seeedstudio.com/XIAO-RP2040/) |\n| Arduino Uno R4 Minima | ✅ Supported | Digital | arduino-uno-r4 | [Wiki](https://docs.arduino.cc/hardware/uno-r4-minima/) |\n| Raspberry Pi Pico | ✅ Supported | Digital | raspberry-pi-pico | [Wiki](https://www.raspberrypi.com/documentation/microcontrollers/pico-series.html) |\n| Arduino Uno R4 WiFi | 📅 W.I.P. | Digital | uno-r4-wifi | [Wiki](https://docs.arduino.cc/hardware/uno-r4-wifi/) |\n| Waveshare RA4M1-Zero | 📅 W.I.P. | RGB | ra4m1-zero | [Wiki](https://www.waveshare.com/wiki/RA4M1-Zero) |\n| Seeed Studio XIAO RA4M1 | 📅 W.I.P. | RGB | xiao-ra4m1 | [Wiki](https://wiki.seeedstudio.com/getting_started_xiao_ra4m1/) |\n| Seeed Studio XIAO nRF52840 | 📅 W.I.P. | RGB | xiao-nrf52840 | [Wiki](https://wiki.seeedstudio.com/XIAO_BLE/) |\n| Seeed Studio XIAO nRF52840 Sense | 📅 W.I.P. | RGB | xiao-nrf52840-sense | [Wiki](https://wiki.seeedstudio.com/XIAO_BLE/) |\n| WaveShare RP2350-Matrix | 📅 W.I.P. | RGB | rp2350-matrix | |\n| WaveShare ESP32-H2-ZERO | 📅 W.I.P. | RGB | esp32-h2-zero | |\n| Pimoroni Tiny 2040 | 📅 W.I.P. | RGB | tiny-2040 | |\n\n## Prerequisites\n\n- Node.js (v16 or later) and npm\n- [Arduino CLI](https://arduino.github.io/arduino-cli/latest/) installed and in your system's PATH\n- Arduino board (e.g., XIAO RP2040)\n- USB cable for board connection\n\n**WSL Users**: Use [usbipd](https://github.com/dorssel/usbipd-win) to share USB devices between Windows and WSL for board connectivity.\n\n## Setup\n\n### Quick Start with npm Global Install\n\nInstall the CLI globally via npm:\n\n```bash\n# Install globally\nnpm install -g cc-led\n\n# Install Arduino dependencies for your board\ncc-led --board xiao-rp2040 install        # For XIAO RP2040\ncc-led --board arduino-uno-r4 install     # For Arduino Uno R4\ncc-led --board raspberry-pi-pico install  # For Raspberry Pi Pico\n\n# Compile and upload the control sketch (same for all boards)\ncc-led --board xiao-rp2040 compile UniversalLedControl\ncc-led --board xiao-rp2040 upload UniversalLedControl -p COM3\n\n# For Arduino Uno R4\ncc-led --board arduino-uno-r4 compile UniversalLedControl\ncc-led --board arduino-uno-r4 upload UniversalLedControl -p COM3\n\n# For Raspberry Pi Pico\ncc-led --board raspberry-pi-pico compile UniversalLedControl\ncc-led --board raspberry-pi-pico upload UniversalLedControl -p COM3\n\n# Control the LED (no --board needed - universal protocol)\ncc-led led --color red -p COM3      # Works on any board\ncc-led led --blink -p COM3          # Universal blink command  \ncc-led led --on -p COM3             # Universal on command\n```\n\n### Quick Start with npx (Alternative)\n\nYou can also use `npx` without global installation:\n\n```bash\n# First time setup - install Arduino boards and libraries\nnpx cc-led --board xiao-rp2040 install\n\n# Compile the LED control sketch (same for all boards)\nnpx cc-led --board xiao-rp2040 compile UniversalLedControl\n\n# Upload to your board (replace COM3 with your port)\nnpx cc-led --board xiao-rp2040 upload UniversalLedControl -p COM3\n\n# Control the LED (universal protocol)\nnpx cc-led led --color red -p COM3   # Works on any board\nnpx cc-led led --blink -p COM3       # Universal command\n```\n\n### 🔧 Development Setup\n\nFor contributors and developers working on cc-led itself:\n\n```bash\n# Clone the repository\ngit clone https://github.com/ShortArrow/cc-led.git\ncd cc-led\n\n# Install dependencies\nnpm install\n\n# Link for development\nnpm link\n\n# Run tests\nnpm test\n```\n\nSee our **[Contributing Guide](docs/CONTRIBUTING.md)** for detailed development instructions.\n\n### Legacy PowerShell Setup\n\nFor users of the original PowerShell scripts, see files in the `legacy/` directory.\n\n\u003e **💡 Recommendation**: New users should use the modern CLI setup above for better cross-platform support and ongoing development.\n\n## Usage\n\nThe CLI provides a modern interface for controlling Arduino board LEDs across multiple platforms.\n\n#### Available Commands\n\n```bash\n# Show help\ncc-led --help\n\n# List available boards\ncc-led boards\n\n# Install Arduino dependencies (run once per board)\ncc-led --board \u003cboard-id\u003e install\n\n# Compile Arduino sketch\ncc-led --board \u003cboard-id\u003e compile \u003csketch-name\u003e\n\n# Upload sketch to board\ncc-led --board \u003cboard-id\u003e upload \u003csketch-name\u003e -p \u003cport\u003e\n\n# Control LED\ncc-led --board \u003cboard-id\u003e led [options]\n\n# Show examples\ncc-led examples\n```\n\n#### LED Control Examples\n\n```bash\n# Universal LED Control (works on all boards)\ncc-led led --on -p COM3                    # Turn LED on (white)\ncc-led led --off -p COM3                   # Turn LED off\n\n# Set solid color (board firmware executes within its LED capabilities)\ncc-led led --color red -p COM3\ncc-led led --color \"255,128,0\" -p COM3     # Custom RGB\n\n# Blink single color\ncc-led led --blink --color green --interval 500 -p COM3\n\n# Blink two colors (board firmware adapts to its LED type)\ncc-led led --blink --color red --second-color blue --interval 1000 -p COM3\n\n# Rainbow effect (board firmware adapts to its LED capabilities)\ncc-led led --rainbow --interval 50 -p COM3\n\n# Examples on different ports (same commands work on all boards)\ncc-led led --on -p COM3                      # XIAO RP2040 on COM3\ncc-led led --blink -p COM5                   # Arduino Uno R4 on COM5\ncc-led led --color blue -p COM6              # Raspberry Pi Pico on COM6\ncc-led led --rainbow --interval 30 -p COM7   # Any board on COM7\n```\n\n#### Port Configuration\n\nYou can set the serial port in multiple ways (in order of priority):\n\n1. Command line: `-p COM3`\n2. Environment variable: `SERIAL_PORT=COM3`\n3. `.env` file in project root:\n\n   ```\n   SERIAL_PORT=COM3\n   ```\n\n\n### Finding Your COM Port\n\n**Windows:**\n\n```bash\n# In Device Manager, look for \"Ports (COM \u0026 LPT)\"\n# Or use PowerShell:\nGet-PnpDevice -Class Ports\n```\n\n**Linux/Mac:**\n\n```bash\nls /dev/tty*  # Look for /dev/ttyACM0 or similar\n```\n\n## 🔧 How It Works\n\n### Universal LED Control Protocol\n\ncc-led implements a **universal protocol** that works across all supported boards through a unified command processing system:\n\n1. **Arduino-Independent Command Processing**\n   - Pure C implementation in `sketches/common/src/CommandProcessor.h/c`\n   - Shared parsing logic across all board types\n   - Comprehensive unit testing with Unity framework (17 test cases)\n\n2. **Board-Agnostic CLI Commands**\n   ```bash\n   # Same commands work on all boards with Universal protocol auto-conversion\n   cc-led led --color red -p COM3      # Auto-converts to appropriate format per board\n   cc-led led --blink -p COM3          # All boards blink\n   cc-led led --rainbow -p COM3        # Auto-adapts to board capabilities\n   ```\n\n3. **Clean Architecture with Dependency Injection**\n   - Interface-based testing with mock adapters\n   - No test interference between different phases\n   - 110+ test cases with full coverage\n\n### Arduino CLI Configuration Priority System\n\ncc-led now supports flexible configuration file management:\n\n**Priority Order** (highest to lowest):\n1. **CLI Parameter**: `--config-file \u003cpath\u003e` (explicit user specification)\n2. **Current Directory**: `./arduino-cli.yaml` (project-specific configuration)  \n3. **Auto-Generated**: Default configuration created in current directory\n\n```bash\n# Explicit config file\ncc-led --config-file /custom/config.yaml install\n\n# Uses ./arduino-cli.yaml if present\ncc-led install  # Searches current directory first\n\n# Auto-creates arduino-cli.yaml if none found\ncc-led install  # Creates default config in current directory\n```\n\n### Directory Management\n\n1. **Arduino CLI Configuration (`arduino-cli.yaml`)**\n   - Configures Arduino CLI to use `./.arduino/` for all installations\n   - Keeps Arduino libraries separate from Node.js dependencies\n   - Board packages install to `.arduino/data/packages/`\n   - **NEW**: Automatic configuration file resolution with priority system\n\n2. **Node.js Package**\n   - Self-contained Node.js CLI tool\n   - `node_modules/` stays local to the package\n   - Can be published to npm or used with `npx`\n\n3. **Arduino Sketches**\n   - Each sketch in its own directory at project root\n   - Compiled binaries go to `\u003csketch\u003e/.build/`\n   - Source remains separate from tools\n   - **NEW**: Universal LED control sketch works on all boards\n\n### Working Directory Behavior\n\nWhen you run `cc-led` from any directory, it creates:\n\n- **`.arduino/`**: Arduino environment (boards, libraries, tools) in current working directory\n- **`arduino-cli.yaml`**: Configuration file in current working directory with automatic priority resolution\n- **`.build/`**: Compilation output in the sketch directory (inside package)\n\nThis design allows each project to have its own isolated Arduino environment, similar to Python's `.venv`.\n\n### Why This Structure?\n\n- **Global Installation Ready**: Can be installed with `npm install -g` or used with `npx`\n- **Local Arduino Environment**: Each working directory gets its own `.arduino/` environment\n- **Board \u0026 Sketch Bundling**: All board configurations and sketches included in package\n- **Development Friendly**: Simple `npm link` for development, comprehensive test coverage\n\n## Claude Code Hooks Integration\n\nGet visual LED notifications for Claude Code events! Set up your Arduino board to light up when the AI agent starts, stops, or uses tools.\n\n**→ See [Claude Code Hooks Guide](docs/CLAUDE_CODE_HOOKS.md)** for complete setup instructions with both modern CLI and legacy PowerShell configurations.\n\n## 📖 Documentation\n\n- **[CLI-Serial Protocol Specification](docs/CLI-Serial-Protocol-Specification.md)** - Detailed specification of CLI options, serial commands, and response handling\n- **[Contributing Guide](docs/CONTRIBUTING.md)** - How to contribute to the project\n- **[Claude Code Hooks Guide](docs/CLAUDE_CODE_HOOKS.md)** - Integration with Claude Code editor\n- **[Legacy Documentation](docs/LEGACY.md)** - Information about the original PowerShell implementation\n- **[Requirements](docs/REQUIREMENTS.md)** - System requirements and dependencies\n\n## 🤝 Contributing\n\nWe welcome contributions! Whether you want to:\n\n- **Add support for a new Arduino board**\n- **Create new LED control sketches**\n- **Improve the CLI tool**\n- **Fix bugs or add features**\n\nPlease see our **[Contributing Guide](docs/CONTRIBUTING.md)** for detailed instructions on:\n\n- Adding new board support\n- Creating sketches\n- Testing guidelines  \n- Pull request process\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshortarrow%2Fcc-led","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshortarrow%2Fcc-led","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshortarrow%2Fcc-led/lists"}