Homebridge Toyama DALI Plugin

A comprehensive Homebridge plugin that bridges Apple HomeKit with Toyama DALI Master lighting systems. Control your DALI lights through Siri, the Home app, and automation.

Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Device Types
• API Reference
• Troubleshooting
• Development
• License

Features

Core Functionality

• Auto-Discovery: Automatically discovers DALI controllers via mDNS (_toyama._tcp)
• Manual Configuration: Option to manually specify controller IP address
• Device Management: Add devices manually or via auto-discovery with type overrides
• Real-time Status: UDP listener on port 56000 for instant status updates
• HTTP API: RESTful communication with DALI controller on port 8900

Supported DALI Device Types

| Device Type | Features | HomeKit Service | |------------|----------|----------------| | DT6 Basic | On/Off control | Lightbulb | | DT6 Dimmer | On/Off + Brightness (0-100%) | Lightbulb | | DT8 WWCW | Brightness + Color Temperature (2700K-6500K) | Lightbulb | | DT8 RGB | Brightness + Full RGB Color | Lightbulb |

DALI Commands Supported

Light Control

• ✅ ON / OFF - Power control
• ✅ LEVEL - Set brightness (0-100%)
• ✅ STEPUP / STEPDOWN - Incremental brightness
• ✅ MAXLEVEL / MINLEVEL - Set to extremes

Color Control (DT8)

• ✅ CW - Color temperature in Kelvin
• ✅ RGB - RGB color values [r, g, b]

System Commands

• ✅ SCAN - Discover devices
• ✅ BLINK - Identify all lights
• ✅ IDENTIFY - Identify specific device
• ✅ RESET - Reset device

Broadcast Commands

• ✅ All commands support address 255 for broadcast

Requirements

• Node.js: >= 16.15.1
• Homebridge: >= 1.3.5
• Network: Same local network as DALI controller
• DALI Controller: Toyama DALI Master with firmware supporting HTTP API

Installation

Option 1: Via Homebridge UI

1. Open Homebridge UI in your browser
2. Go to Plugins tab
3. Search for "Toyama DALI"
4. Click Install

Option 2: Via NPM

npm install -g homebridge-toyama-dali-plugin

Option 3: Development Installation

git clone https://github.com/toyama-controls/homebridge-toyama-dali-plugin.git
cd homebridge-toyama-dali-plugin
npm install
npm run build
npm link

Configuration

Via Homebridge UI (Recommended)

1. Go to Plugins → Toyama DALI → Settings
2. Configure discovery method and device settings
3. Restart Homebridge

Manual Configuration (config.json)

Add to your config.json:

{
  "platforms": [
    {
      "platform": "ToyamaDali",
      "name": "Toyama DALI Plugin",
      "discoveryMethod": "mdns",
      "port": 8900,
      "udpPort": 56000,
      "pollingInterval": 30,
      "enableDiscovery": true,
      "manualDevices": [],
      "deviceOverrides": []
    }
  ]
}

Configuration Options

Basic Settings

| Option | Type | Default | Description | |--------|------|---------|-------------| | name | string | "Toyama DALI Plugin" | Plugin display name | | discoveryMethod | string | "mdns" | Discovery: "mdns" or "manual" | | manualIp | string | - | Controller IP (manual mode) | | port | number | 8900 | HTTP port of DALI controller | | udpPort | number | 56000 | UDP port for status updates | | pollingInterval | number | 30 | Status poll interval (seconds) | | enableDiscovery | boolean | true | Auto-discover new devices |

Manual Devices

Manually add specific DALI devices:

{
  "manualDevices": [
    {
      "address": 5,
      "name": "Living Room Light",
      "deviceType": "dt6",
      "supportsDimming": true
    },
    {
      "address": 10,
      "name": "Kitchen RGB Strip",
      "deviceType": "dt8Rgb"
    },
    {
      "address": 15,
      "name": "Bedroom WWCW",
      "deviceType": "dt8Wwcw"
    }
  ]
}

Manual Device Fields:

| Field | Type | Required | Description | |-------|------|----------|-------------| | address | number (0-63) | ✅ | DALI device address | | name | string | ❌ | Custom device name | | deviceType | string | ✅ | "dt6", "dt8Wwcw", or "dt8Rgb" | | supportsDimming | boolean | ❌ | For DT6 dimmable lights |

Device Type Overrides

Override auto-discovered device types:

{
  "deviceOverrides": [
    {
      "address": 3,
      "deviceType": "dt8Wwcw",
      "supportsDimming": false
    },
    {
      "address": 7,
      "deviceType": "dt8Rgb"
    }
  ]
}

Complete Configuration Examples

Example 1: Auto-Discovery Only

{
  "platforms": [
    {
      "platform": "ToyamaDali",
      "name": "Toyama DALI Plugin",
      "discoveryMethod": "mdns",
      "enableDiscovery": true,
      "pollingInterval": 30
    }
  ]
}

Example 2: Manual Controller + Mixed Devices

{
  "platforms": [
    {
      "platform": "ToyamaDali",
      "name": "Toyama DALI Plugin",
      "discoveryMethod": "manual",
      "manualIp": "192.168.1.100",
      "port": 8900,
      "enableDiscovery": true,
      "manualDevices": [
        {
          "address": 0,
          "name": "Hallway Light",
          "deviceType": "dt6",
          "supportsDimming": false
        },
        {
          "address": 1,
          "name": "Dining Room",
          "deviceType": "dt6",
          "supportsDimming": true
        }
      ],
      "deviceOverrides": [
        {
          "address": 5,
          "deviceType": "dt8Wwcw"
        }
      ]
    }
  ]
}

Example 3: Full RGB Setup

{
  "platforms": [
    {
      "platform": "ToyamaDali",
      "name": "Toyama DALI Plugin",
      "discoveryMethod": "mdns",
      "manualDevices": [
        {
          "address": 10,
          "name": "RGB Strip 1",
          "deviceType": "dt8Rgb"
        },
        {
          "address": 11,
          "name": "RGB Strip 2",
          "deviceType": "dt8Rgb"
        },
        {
          "address": 12,
          "name": "RGB Strip 3",
          "deviceType": "dt8Rgb"
        }
      ]
    }
  ]
}

Device Types

DT6 - Basic Light

Simple on/off control. No brightness or color support.

HomeKit Features:

• Power (On/Off)

Use Case: Simple switches, non-dimmable bulbs

DT6 Dimmer

On/off with brightness control (0-100%).

HomeKit Features:

• Power (On/Off)
• Brightness (0-100%)

Use Case: Dimmable LED drivers, dimmable bulbs

DT8 WWCW (Warm White / Cool White)

Brightness + adjustable color temperature.

HomeKit Features:

• Power (On/Off)
• Brightness (0-100%)
• Color Temperature (2700K-6500K)

Use Case: Tunable white LEDs, circadian lighting

DT8 RGB

Full color control with RGB.

HomeKit Features:

• Power (On/Off)
• Brightness (0-100%)
• Hue (0-360°)
• Saturation (0-100%)

Use Case: RGB LED strips, color-changing fixtures

API Reference

The plugin communicates with the DALI controller via HTTP REST API on port 8900 and listens for status updates on UDP port 56000. For full API documentation, please refer to the Toyama DALI Controller documentation.

Troubleshooting

Controller Not Found

Symptoms: Plugin can't discover the DALI controller

Solutions:

1. Verify controller is powered on
2. Check network connection (ping the controller IP)
3. Try manual IP configuration
4. Ensure mDNS is not blocked by router/firewall
5. Check controller web interface: http://<ip>:8900/status

Devices Not Responding

Symptoms: Lights don't respond to HomeKit commands

Solutions:

1. Check DALI bus wiring
2. Verify device addresses match configuration
3. Test with Flutter app to confirm hardware works
4. Check Homebridge logs for errors
5. Verify UDP port 56000 is not blocked

Connection Issues

Symptoms: Intermittent connectivity

Solutions:

1. Check WiFi signal strength (should be > -70 dBm)
2. Reduce polling interval
3. Verify no IP conflicts
4. Check router settings for multicast support
5. Restart DALI controller

HomeKit "No Response"

Symptoms: Devices show "No Response" in Home app

Solutions:

1. Restart Homebridge
2. Check plugin logs for errors
3. Verify controller is accessible
4. Remove and re-add accessory in Home app
5. Check network firewall settings

Debug Logging

Enable debug logging in Homebridge:

{
  "debug": true,
  "platforms": [
    {
      "platform": "ToyamaDali",
      "name": "Toyama DALI Plugin"
    }
  ]
}

Or set environment variable:

DEBUG=* homebridge

Development

Setup

# Clone repository
git clone https://github.com/toyama-controls/homebridge-toyama-dali-plugin.git
cd homebridge-toyama-dali-plugin

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch for changes
npm run watch

# Run linter
npm run lint

# Fix linting issues
npm run lint -- --fix

Project Structure

src/
├── index.ts              # Plugin entry point
├── settings.ts           # Constants
├── platform.ts           # Main platform class
├── models.ts             # TypeScript interfaces
├── dali-service.ts       # HTTP/UDP communication
├── mdns-discovery.ts     # mDNS discovery service
└── accessories/
    ├── dali-light.ts     # DT6 basic light
    ├── dali-dimmer.ts    # DT6 dimmable light
    ├── dali-wwcw.ts      # DT8 warm/cool white
    ├── dali-rgb.ts       # DT8 RGB color
    └── index.ts          # Exports

Testing

# Link for local testing
npm link

# In Homebridge directory
npm link homebridge-toyama-dali-plugin

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Comparison with Flutter App

This plugin implements all critical features from the Flutter DALI app:

| Feature | Flutter App | This Plugin | |---------|-------------|-------------| | HTTP API | ✅ | ✅ | | UDP Status | ✅ | ✅ | | Auto-Discovery (mDNS) | ✅ | ✅ | | Manual IP | ✅ | ✅ | | Light On/Off | ✅ | ✅ | | Brightness Control | ✅ | ✅ | | Color Temperature | ✅ | ✅ | | RGB Color | ✅ | ✅ | | Device Scan | ✅ | ✅ | | Broadcast Commands | ✅ | ✅ |

Missing (not needed for HomeKit):

• Scene management (store/recall/remove)
• Relative brightness (INC/DEC)
• Device assignment/deletion

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: This README and inline code comments

License

Apache-2.0 © Toyama Controls

Acknowledgments

• Homebridge - HomeKit support for the impatient
• HAP-NodeJS - Node.js implementation of HomeKit Accessory Protocol
• Toyama Controls - DALI Master hardware

Made with ❤️ for smart lighting enthusiasts