homebridge-magic-blue-bulb

KO | EN

gitlite — search

#python #react #llm #go #android #rust #docker #macos #nodejs #windows #cli #kubernetes #ios #open-source

homebridge-magic-blue-bulb

(★ 8)

MagicBlue LED Lightbulb Plugin

homebridge-magic-blue-bulb 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Homebridge Magic Blue Bulb

This plugin enables you to control your MagicBlue LED light bulbs through HomeKit via Homebridge using a dynamic platform plugin.

## Installation

```bash
npm install -g homebridge-magic-blue-bulb
```

You may need to use `sudo` with that command.

## Configuration

Add this platform to your homebridge `config.json`:

```json
{
    "platforms": [
        {
            "name": "Magic Blue Bulbs",
            "platform": "MagicBlueBulbPlatform",
            "bulbs": [
                {
                    "name": "Living Room Light",
                    "mac": "aa:bb:cc:dd:ee:ff",
                    "handle": 12,
                    "manufacturer": "Magic Blue",
                    "model": "RGB Bulb",
                    "serial": "MB001"
                },
                {
                    "name": "Bedroom Light",
                    "mac": "ff:ee:dd:cc:bb:aa",
                    "handle": 12,
                    "manufacturer": "Magic Blue",
                    "model": "RGB Bulb",
                    "serial": "MB002"
                }
            ]
        }
    ]
}
```

## Configuration Validation

This plugin uses **Zod** for runtime configuration validation, providing enhanced error reporting and type safety:

- **MAC Address Validation**: Ensures MAC addresses follow the correct format (e.g., `AA:BB:CC:DD:EE:FF` or `aa-bb-cc-dd-ee-ff`)
- **Required Fields**: Validates that essential fields like `name` and `mac` are present and non-empty
- **Type Safety**: Ensures numeric fields like `handle` are proper integers
- **Clear Error Messages**: Provides detailed error messages when configuration is invalid

### Example Validation Errors

If you provide an invalid configuration, you'll see helpful error messages in the Homebridge logs:

```
[Magic Blue Bulbs] Configuration validation failed: mac: Invalid MAC address format, name: Bulb name is required
```

### Platform Configuration Options

| Key        | Description                                        |
| ---------- | -------------------------------------------------- |
| `name`     | Required. The name of this platform instance       |
| `platform` | Required. Must be "MagicBlueBulbPlatform"          |
| `bulbs`    | Required. Array of bulb configurations (see below) |

### Bulb Configuration Options

| Key            | Description                                                                                           |
| -------------- | ----------------------------------------------------------------------------------------------------- |
| `name`         | Required. The name of this bulb in your HomeKit app                                                   |
| `mac`          | Required. The MAC address of your Magic Blue bulb                                                     |
| `handle`       | Optional. BLE handle for commands. Use 46 for newer bulbs, defaults to 12 (0x000c) for older versions |
| `manufacturer` | Optional. Manufacturer name, defaults to "Light"                                                      |
| `model`        | Optional. Model name, defaults to "Magic Blue"                                                        |
| `serial`       | Optional. Serial number, defaults to "5D4989E80E44"                                                   |

## Migration from v1.x

If you're upgrading from v1.x, you'll need to update your configuration from an accessory-based setup to a platform-based setup:

### Old Configuration (v1.x)

```json
{
    "accessories": [
        {
            "accessory": "magic-blue-bulb",
            "name": "Magic Blue Bulb",
            "mac": "aa:bb:cc:dd:ee:ff"
        }
    ]
}
```

### New Configuration (v2.x)

```json
{
    "platforms": [
        {
            "name": "Magic Blue Bulbs",
            "platform": "MagicBlueBulbPlatform",
            "bulbs": [
                {
                    "name": "Magic Blue Bulb",
                    "mac": "aa:bb:cc:dd:ee:ff"
                }
            ]
        }
    ]
}
```

## Benefits of Platform Plugin

The new platform plugin architecture provides several advantages:

- **Multiple Bulbs**: Easily manage multiple Magic Blue bulbs from a single platform configuration
- **Better Performance**: Improved caching and accessory management
- **Future-Proof**: Uses Homebridge's recommended modern architecture
- **Easier Management**: Centralized configuration for all your Magic Blue devices

## Finding Your Bulb's MAC Address

The light bulb uses Bluetooth Low Energy. To discover your bulb's MAC address, install bluez and run:

```bash
sudo hcitool lescan
```

Look for a device named "LEDBLE-" followed by some characters - that's your Magic Blue bulb.

Example output:

```
LE Scan ...
FF:FF:C8:5D:68:9E Eve
FF:FF:C8:5D:68:9E Eve Thermo
33:03:44:44:AA:5C (unknown)
33:03:44:44:AA:5C Eve Door
aa:bb:cc:dd:ee:ff (unknown)
22:20:7B:99:D3:AF (unknown)
aa:bb:cc:dd:ee:ff LEDBLE-A582661F    <--- this is your light bulb
22:20:7B:99:D3:AF (unknown)
```

## Development

This project is written in TypeScript and built with [tsdown](https://tsdown.dev/). To develop and contribute:

### Setup

```bash
npm install
```

Requires Node.js **22.18+** for building (tsdown) and **22.12+** or **24+** at runtime.

### Build

```bash
npm run build
```

### Watch mode (for development)

```bash
npm run watch
```

Link the plugin into your local Homebridge install:

```bash
npm link
```

The TypeScript source files are in `src/` and the compiled output is in `dist/` (`index.mjs`, `index.cjs`, and type declarations).

### Project Structure

```
homebridge-magic-blue-bulb/
├── src/
│   ├── index.ts              # Plugin registration and entry point
│   ├── platform.ts           # Main platform class
│   ├── accessory.ts          # Individual bulb accessory implementation
│   ├── constants.ts          # BLE commands and default values
│   ├── rgbConversion.ts      # HSL/RGB color conversion utilities
│   └── types.ts              # TypeScript type definitions and validation
├── dist/                     # Compiled JavaScript output
├── tsconfig.json            # TypeScript configuration
└── package.json             # Dependencies and scripts
```

## Requirements

- Node.js `^22.12.0` or `^24.0.0`
- Homebridge `^1.8.0` or `^2.0.0`
- Bluetooth LE support on your system

## Homebridge v2.0 Compatibility

This plugin supports Homebridge v2.0 and remains compatible with Homebridge v1.8+ on Node 22+. It uses:

- Modern dynamic platform plugin architecture
- Current HAP-NodeJS APIs (no deprecated patterns)
- TypeScript with strict typing
- Zod validation for enhanced configuration safety
- Dual ESM/CJS build output via tsdown

Users on Homebridge v2 will see a green checkmark in the UI readiness check once this plugin version is installed.

## Issues

This software comes with no warranty. It works for me and it might for you. If you encounter issues, please open an [issue](https://github.com/lucavb/homebridge-magic-blue-bulb/issues/new) on GitHub.

## Credits

- Bluetooth protocol discovered by the author of [this post](https://bene.tweakblogs.net/blog/12447/connect-a-bluetooth-lightbulb-to-philips-hue) and used in [this repository](https://github.com/b0tting/magicbluehue)
- Color conversion methods by Garry Tan - [see his post here](http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c)

## License

GPL-3.0

homebridge-magic-blue-bulb

homebridge-magic-blue-bulb 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

homebridge-magic-blue-bulb

homebridge-magic-blue-bulb 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README