homebridge-particle-fan

Homebridge plugin for a ceiling fan controlled by a Particle Photon + CC1101 RF bridge (see ceiling_fan_rf_bridge.ino).

Exposes one Homebridge accessory per fan, which iOS renders as a single ceiling-fan tile containing:

| Control | HomeKit type | Commands | |---|---|---| | Fan on/off | Fanv2 → Active | FAN_LOW (on) / FAN_OFF | | Speed slider | Fanv2 → RotationSpeed | FAN_LOW 33% · FAN_MEDIUM 66% · FAN_HIGH 100% | | Light on/off | Lightbulb → On | LIGHT_ON / LIGHT_OFF | | Color Mode | Switch (momentary) | LIGHT_COLOR | | All Off | Switch (momentary) | ALL_OFF |

Installation

# from your Homebridge machine
npm install -g /path/to/homebridge-particle-fan
# or, once published to npm:
npm install -g homebridge-particle-fan

Restart Homebridge after installing.

Configuration

Add to the accessories array in ~/.homebridge/config.json:

{
  "accessories": [
    {
      "accessory":    "ParticleCeilingFan",
      "name":         "Bedroom Fan",
      "deviceId":     "YOUR_PARTICLE_DEVICE_ID",
      "accessToken":  "YOUR_PARTICLE_ACCESS_TOKEN"
    }
  ]
}

If you use Homebridge UI (the web interface), the plugin will appear in the Plugins tab with a graphical config form — no manual JSON editing needed.

Getting your credentials

Device ID — from console.particle.io, or:

particle list

Access Token — create a token that never expires so the plugin doesn't silently stop working:

particle token create --never-expires

How the tile looks in the Home app

iOS groups a Fanv2 service and a Lightbulb service on the same accessory into a single ceiling-fan tile automatically. Long-pressing (or tapping ›) reveals the full control surface:

┌─────────────────────────────────┐
│  🔘  Bedroom Fan          [OFF] │
│      ──────────────────         │  ← fan on/off + speed slider
│      ●  Low  Medium  High       │
├─────────────────────────────────┤
│  💡  Bedroom Fan Light    [OFF] │  ← light on/off
├─────────────────────────────────┤
│  ⚡  Bedroom Fan Color Mode     │  ← momentary; fires LIGHT_COLOR
│  ⚡  Bedroom Fan All Off        │  ← momentary; fires ALL_OFF
└─────────────────────────────────┘

Fan speed mapping

The RotationSpeed slider (0–100 %) snaps to three discrete positions:

| Slider position | Snaps to | Command sent | |---|---|---| | 1 – 33 % | 33 % | FAN_LOW | | 34 – 66 % | 66 % | FAN_MEDIUM | | 67 – 100 % | 100 % | FAN_HIGH |

Dragging to 0 % turns the fan off (FAN_OFF). Turning the fan on from the Active toggle sends the last-used speed.

Siri examples

"Hey Siri, turn on the bedroom fan"
"Hey Siri, set the bedroom fan to medium"
"Hey Siri, turn off the bedroom fan light"
"Hey Siri, turn off everything in the bedroom"   ← triggers All Off

Troubleshooting

Commands appear to send but nothing happens

• Check the Particle event log (particle subscribe fan/ --device YOUR_ID) — you should see fan/sent events with the correct command name.
• Verify ceiling_fan_rf_bridge.ino is flashed and fan/status: CC1101 OK was published on boot.

"HTTP 401" errors in Homebridge log

• Your access token has expired. Run particle token create --never-expires and update config.json.

Fan responds to Flipper replay but not to Homebridge

• This is almost always a timing issue in the firmware, not the plugin. Check the .sub captures as described in the firmware README.

Color Mode and All Off tiles appear as separate accessories

• This can happen if Homebridge previously cached the accessory without those services. Clear the Homebridge cache (~/.homebridge/accessories/cachedAccessories) and restart.