homebridge-parkeye

A Homebridge plugin that adds a "Check Parking" button and a "Parking Available" sensor to HomeKit, backed by an existing ParkEye server. Pressing the button runs a live check (the server pulls a fresh camera snapshot and runs YOLO detection) and updates the sensor with the result — so you can also get a push notification when a spot frees up.

How it works

[Home app]  ──press──▶  [homebridge-parkeye]  ──POST──▶  [ParkEye server]
    ▲                                                         │
    └────────── "Parking Available" sensor ◀── has_free_slot ─┘

The plugin calls POST http://<host>:<port>/api/automation/check-and-run with an X-API-Key header and maps the response's has_free_slot field onto an Occupancy Sensor: free spot → "Occupancy Detected", none → "Not Detected".

It exposes two separate accessories (HomeKit reliably shows one tile per accessory):

• Check Parking — a momentary Switch that triggers a live check and then resets itself to off.
• Parking Available — an Occupancy Sensor that reflects the latest result.

Requirements

• A running, reachable ParkEye server with a camera source configured and public parking slots calibrated. If PARKEYE_AUTOMATION_API_KEY is set on the server, use the same value as the plugin's apiKey.
• Node.js 18+ and Homebridge 1.6+.

Installation

Install through Homebridge Config UI X → Plugins, or from the command line:

npm install -g homebridge-parkeye

Configuration

Add to the platforms array in config.json (or fill in the settings form in the UI):

{
  "platform": "ParkEye",
  "name": "ParkEye",
  "host": "192.168.68.20",
  "port": 3225,
  "apiKey": "",
  "useHttps": false,
  "timeoutSeconds": 20,
  "pollingIntervalSeconds": 0
}

| Field | Default | Description | |-------|---------|-------------| | host | — (required) | IP / hostname of the ParkEye server | | port | 3225 | Port (Docker = 3225, local dev = 8000) | | apiKey | — | Value of PARKEYE_AUTOMATION_API_KEY; leave empty if the server has none | | useHttps | false | Enable only if the server is behind an HTTPS reverse proxy | | timeoutSeconds | 20 | Request timeout (YOLO inference can be slow on small machines) | | pollingIntervalSeconds | 0 | 0 = button-only; a positive value also refreshes the sensor in the background |

Getting push notifications

1. Open the Home app → long-press the Parking Available tile → settings.
2. Under Status and Notifications, enable a notification (e.g. "when occupancy is detected").
3. Now a check that finds a free spot will trigger a push notification.

Security

• The API key is read from Homebridge's config.json and sent as an X-API-Key header. The plugin never writes the key to the log.
• Traffic is plain HTTP by default — intended for a trusted local network. For encryption, put ParkEye behind an HTTPS reverse proxy and enable useHttps.

Troubleshooting

• HTTP 401 — the plugin's key doesn't match PARKEYE_AUTOMATION_API_KEY.
• HTTP 400 — no public parking slots are calibrated in ParkEye.
• HTTP 404 / 502 / 504 — no image / camera unreachable / check timed out.
• ECONNREFUSED / timeout — check host/port and that the server is reachable from the Homebridge machine.

License

MIT