homebridge-boxzilla

Homebridge plugin for the Boxzilla LoRa mailbox notifier.

Polls the Boxzilla receiver's HTTP endpoint and exposes two HomeKit services:

• Contact Sensor — open when mail is detected, closed when cleared
• Battery Service — sender battery level, charging state, low battery warning

Installation

npm install -g homebridge-boxzilla

Or search for "boxzilla" in the Homebridge UI plugin tab.

Configuration

Configure via the Homebridge UI settings form, or add manually to config.json:

{
    "accessory": "Boxzilla",
    "name": "Mailbox",
    "host": "boxzilla.local",
    "pollInterval": 30,
    "timeout": 5000,
    "lowBatteryThreshold": 10
}

| Key | Description | Default | |-----|-------------|---------| | accessory | Must be Boxzilla | — | | name | Name in Home app | Mailbox | | host | Hostname or IP of the receiver | boxzilla.local | | pollInterval | Seconds between polls | 30 | | timeout | HTTP timeout in milliseconds | 5000 | | lowBatteryThreshold | Battery % to trigger low battery warning | 10 |

The plugin automatically polls http://<host>/status.json.

Expected JSON Response

The receiver endpoint must return:

{
    "ContactSensorState": 0,
    "BatteryLevel": 72,
    "BatteryCharging": 0,
    "BatteryLow": 0
}

| Field | Values | |-------|--------| | ContactSensorState | 0 = no mail, 1 = mail detected | | BatteryLevel | 0–100 percentage | | BatteryCharging | 0 = not charging, 1 = charging | | BatteryLow | 0 = normal, 1 = low |

Hardware

• Sender: Heltec LoRa32 V3 in mailbox, deep sleep with reed switch wake
• Receiver: Heltec LoRa32 V3 at home, USB powered, runs web server

License

MIT