{"id":34520682,"url":"https://github.com/aitjcize/ha-blockbluelight","last_synced_at":"2026-06-01T05:31:58.346Z","repository":{"id":328495058,"uuid":"1115757881","full_name":"aitjcize/ha-blockbluelight","owner":"aitjcize","description":"HomeAssistant custom integration for BlockBlueLight devices","archived":false,"fork":false,"pushed_at":"2025-12-22T12:04:26.000Z","size":39,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-23T23:13:54.939Z","etag":null,"topics":["blockbluelight","homeassistant","homeassistant-integration","red-light-therapy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aitjcize.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-12-13T13:48:00.000Z","updated_at":"2025-12-22T12:04:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aitjcize/ha-blockbluelight","commit_stats":null,"previous_names":["aitjcize/ha-blockbluelight"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aitjcize/ha-blockbluelight","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aitjcize%2Fha-blockbluelight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aitjcize%2Fha-blockbluelight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aitjcize%2Fha-blockbluelight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aitjcize%2Fha-blockbluelight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aitjcize","download_url":"https://codeload.github.com/aitjcize/ha-blockbluelight/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aitjcize%2Fha-blockbluelight/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33762215,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"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":["blockbluelight","homeassistant","homeassistant-integration","red-light-therapy"],"created_at":"2025-12-24T04:54:25.766Z","updated_at":"2026-06-01T05:31:58.342Z","avatar_url":"https://github.com/aitjcize.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BlockBlueLight - Home Assistant Integration\n\n[![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://github.com/custom-components/hacs)\n[![GitHub release](https://img.shields.io/github/release/aitjcize/ha-blockbluelight.svg)](https://github.com/aitjcize/ha-blockbluelight/releases)\n[![License](https://img.shields.io/github/license/aitjcize/ha-blockbluelight.svg)](LICENSE)\n\nA Home Assistant custom integration for controlling BlockBlueLight red light therapy devices via Bluetooth LE.\n\n## Features\n\n- 🔍 **Automatic Discovery** - Finds your device automatically via Bluetooth\n- 🔌 **ESPHome Bluetooth Proxy Support** - Works with your existing proxies\n- 💡 **Switch Control** - Simple ON/OFF control\n- ⏱️ **Built-in Auto-off Timer** - Set duration (1-60 minutes) for therapy sessions\n- 🔋 **Smart Connection** - Connects on-demand, auto-disconnects after 2 minutes\n- 🎨 **Config Flow UI** - No YAML configuration needed\n\n## Quick Start\n\n### Requirements\n\n- Home Assistant 2024.1.0 or newer\n- Bluetooth support (built-in adapter or ESPHome Bluetooth Proxy)\n- BlockBlueLight device in Bluetooth range\n\n### Installation via HACS (Recommended)\n\n1. Open HACS in Home Assistant\n2. Go to **Integrations**\n3. Click the **⋮** menu (top right) → **Custom repositories**\n4. Add repository URL: `https://github.com/aitjcize/ha-blockbluelight`\n5. Category: **Integration**\n6. Click **Add**\n7. Click **+ Explore \u0026 Download Repositories**\n8. Search for \"BlockBlueLight\"\n9. Click **Download**\n10. Restart Home Assistant\n11. Go to **Settings** → **Devices \u0026 Services** → **Add Integration**\n12. Search for \"BlockBlueLight\" and configure\n\n### Manual Installation\n\n1. Copy the `custom_components/blockbluelight` folder to your Home Assistant `config/custom_components/` directory\n2. Restart Home Assistant\n3. Go to **Settings** → **Devices \u0026 Services** → **Add Integration**\n4. Search for \"BlockBlueLight\" and configure\n\n## Usage\n\nAfter installation, you'll have two entities:\n\n### Light Entity\n- **Entity ID**: `light.block3cab725ef522` (based on device name)\n- **Controls**: Turn the device ON/OFF\n- **Type**: Red light therapy light\n\n### Timer Duration Entity\n- **Entity ID**: `number.block3cab725ef522_timer_duration`\n- **Range**: 1-60 minutes (default: 15)\n- **Purpose**: Set how long the device stays on before automatically turning off\n- **Perfect for**: Red light therapy sessions (typically 10-20 minutes)\n\n## Automation Examples\n\n### Basic: Turn on at sunset (auto-off after timer)\n```yaml\nautomation:\n  - alias: \"Red light therapy at sunset\"\n    trigger:\n      - platform: sun\n        event: sunset\n    action:\n      - service: light.turn_on\n        target:\n          entity_id: light.block3cab725ef522\n```\n\n### Set custom timer duration\n```yaml\nautomation:\n  - alias: \"20-minute therapy session\"\n    trigger:\n      - platform: time\n        at: \"20:00:00\"\n    action:\n      - service: number.set_value\n        target:\n          entity_id: number.block3cab725ef522_timer_duration\n        data:\n          value: 20\n      - service: light.turn_on\n        target:\n          entity_id: light.block3cab725ef522\n```\n\n### Morning and evening sessions\n```yaml\nautomation:\n  - alias: \"Morning therapy - 10 minutes\"\n    trigger:\n      - platform: time\n        at: \"07:00:00\"\n    action:\n      - service: number.set_value\n        target:\n          entity_id: number.block3cab725ef522_timer_duration\n        data:\n          value: 10\n      - service: light.turn_on\n        target:\n          entity_id: light.block3cab725ef522\n\n  - alias: \"Evening therapy - 15 minutes\"\n    trigger:\n      - platform: time\n        at: \"21:00:00\"\n    action:\n      - service: number.set_value\n        target:\n          entity_id: number.block3cab725ef522_timer_duration\n        data:\n          value: 15\n      - service: light.turn_on\n        target:\n          entity_id: light.block3cab725ef522\n```\n\n## Lovelace Card Examples\n\n### Simple entities card\n```yaml\ntype: entities\ntitle: Red Light Therapy\nentities:\n  - entity: light.block3cab725ef522\n    name: Power\n  - entity: number.block3cab725ef522_timer_duration\n    name: Session Duration\n```\n\n### Button card with timer\n```yaml\ntype: vertical-stack\ncards:\n  - type: light\n    entity: light.block3cab725ef522\n    name: Red Light Therapy\n  - type: entities\n    entities:\n      - entity: number.block3cab725ef522_timer_duration\n        name: Auto-off Timer\n```\n\n## Troubleshooting\n\n### Device Not Discovered\n\n1. **Check Bluetooth is enabled** in Home Assistant\n2. **Verify ESPHome Bluetooth Proxy** is working:\n   - Go to **Settings** → **Devices \u0026 Services** → **ESPHome**\n   - Check your proxy device is online\n3. **Check device is in range** of the Bluetooth proxy\n4. **Restart Home Assistant** and wait a few minutes for discovery\n\n### Connection Issues\n\n1. **Check logs**: Go to **Settings** → **System** → **Logs**\n2. Look for errors related to `blockbluelight`\n3. Try removing and re-adding the integration\n4. Make sure no other device is connected to the BlockBlueLight device\n\n### Enable Debug Logging\n\nAdd to `configuration.yaml`:\n\n```yaml\nlogger:\n  default: info\n  logs:\n    custom_components.blockbluelight: debug\n    homeassistant.components.bluetooth: debug\n```\n\nThen restart Home Assistant and check the logs.\n\n## Device Details\n\n### BLE Protocol Information\n\n- **Device Name Pattern**: `BLOCK` followed by MAC address (e.g., `BLOCK3CAB725EF522`)\n- **Service UUID**: 0000fff0-0000-1000-8000-00805f9b34fb\n- **Write Characteristic**: 0000fff2-0000-1000-8000-00805f9b34fb (FFF2)\n- **Notify Characteristic**: 0000fff1-0000-1000-8000-00805f9b34fb (FFF1)\n\n**Note**: Characteristic naming is opposite of typical convention - FFF2 is for writing, FFF1 is for notifications.\n\n### Commands\n\n- **Turn ON**: `3A 01 20 00 01 01 23 0A`\n- **Turn OFF**: `3A 01 20 00 01 00 22 0A`\n- **Status Query**: `3A 01 10 00 00 11 0A`\n- **Set Timer**: `3A 01 31 00 02 [timer_high] [timer_low] [checksum] 0A`\n\n## Repository Structure\n\n- **`custom_components/blockbluelight/`** - Home Assistant integration\n- **`analysis/`** - Protocol reverse engineering materials\n  - `BLE_PROTOCOL_ANALYSIS.md` - Complete protocol documentation\n  - `btsnoop_hci.log` - Captured HCI log\n  - Python scripts for testing and analysis\n\n## For Developers\n\n### Publishing to HACS\n\n1. **Create GitHub repository** named `ha-blockbluelight`\n2. **Push code**:\n   ```bash\n   git init\n   git add .\n   git commit -m \"Initial release v1.0.0\"\n   git remote add origin https://github.com/YOUR_USERNAME/ha-blockbluelight.git\n   git branch -M main\n   git push -u origin main\n   ```\n\n3. **Create release** on GitHub:\n   - Tag: `v1.0.0`\n   - Title: `v1.0.0 - Initial Release`\n   - Copy description from `CHANGELOG.md`\n\n4. **Add to HACS** as custom repository:\n   - HACS → Integrations → ⋮ → Custom repositories\n   - Add: `https://github.com/YOUR_USERNAME/ha-blockbluelight`\n   - Category: Integration\n\n### Updating the Integration\n\n1. Update version in `custom_components/blockbluelight/manifest.json`\n2. Update `CHANGELOG.md`\n3. Commit and push changes\n4. Create new release on GitHub\n\nHACS will automatically detect new releases and notify users.\n\n### File Structure\n\n```\ncustom_components/blockbluelight/\n├── __init__.py           # Integration setup\n├── config_flow.py        # Config flow for UI setup\n├── const.py              # Constants (UUIDs, commands)\n├── coordinator.py        # BLE communication coordinator\n├── manifest.json         # Integration metadata\n├── light.py              # Light entity implementation\n├── number.py             # Timer duration entity\n├── strings.json          # UI strings\n└── translations/\n    └── en.json          # English translations\n```\n\n### Key Components\n\n- **Coordinator**: Manages BLE connection, sends commands, handles notifications\n- **Light Entity**: Provides ON/OFF control in Home Assistant UI\n- **Number Entity**: Timer duration configuration\n- **Config Flow**: Handles device discovery and setup\n\n## Known Limitations\n\n- Only supports ON/OFF control (no brightness, color, etc.)\n- Requires Bluetooth to be in range\n- One device connection at a time\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file for details\n\n## Credits\n\nProtocol reverse-engineered from Android HCI logs using Wireshark and Python. See `analysis/` directory for complete reverse engineering details.\n\n## Disclaimer\n\nThis is an unofficial integration and is not affiliated with or endorsed by the device manufacturer. Use at your own risk.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faitjcize%2Fha-blockbluelight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faitjcize%2Fha-blockbluelight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faitjcize%2Fha-blockbluelight/lists"}