GRIT Hub for Home Assistant

GRIT Hub for Home Assistant is an unofficial Home Assistant custom component for GRIT Hub gates, RFID readers, GRITLock, collectors, and hub controls. It combines the authenticated GRIT REST API with subscribe-only MQTT state updates and is designed for installation through HACS as a custom integration.

Release status: v0.1.2 is the latest prepared release and is ready for publication after successful two-system live acceptance. It is not yet tagged or published. The published v0.1.1 release is superseded but remains the latest published release until v0.1.2 publication. This project remains a HACS Custom Repository and is not a default-catalogue listing.

This project is experimental, provided as-is, and is not affiliated with, endorsed by, or supported by GRIT or GRIT Automation.

Caution

GRIT equipment can operate gates and physical access-control devices. This integration must not be relied upon as the sole security or access-control mechanism. Maintain independent safety devices, physical controls, and manual access procedures. It is not a safety, security, or life-safety system.

Features

• Gate covers with bounded request/response startup hydration, immediate MQTT updates, and post-command MQTT confirmation.
• One RFID lock entity per reader, using authoritative individual REST state and event-driven MQTT invalidation refresh.
• One system-wide GRITLock entity using one continuous bounded MQTT observed- state channel. gls=1 means locked and gls=0 means unlocked. Live /gl bursts use their fresh gte=1 subset, or all fresh observations when every gte=0; REST never supplies displayed state or redefines a live burst.
• Collector, solenoid, latch, and powerbank switches, with deterministic individual-detail confirmation for collectors.
• Hub connectivity, software, device-count, MQTT, and per-device diagnostics.
• System LED brightness, service restart, hub reboot, refresh, and locate controls.
• Config-entry reconfiguration for API token rotation and MQTT settings.

How it works

The integration has two required data paths:

• REST API: authenticated discovery, bounded reconciliation, and explicit device commands.
• Direct MQTT: config-flow validation subscribes to the exact hub-scoped topic. The dedicated runtime Paho MQTT v3.1.1 client subscribes at QoS 0 to grit/+/+/+/#, then the coordinator accepts only the configured hub ID. It never publishes.

Home Assistant's MQTT integration is not required. HACS installs only this custom integration; it does not provide or configure a broker. See Architecture for the source-of-truth and confirmation rules.

After the exact runtime subscription is ready, the integration makes bounded authenticated telemetry requests. Gates retain a per-request /sts or /tel response boundary, and their compact p position may be numeric or numeric text; /req-tel is never state. GRITLock instead opens one bounded current-connection snapshot as soon as MQTT is ready. Strict trigger /sts or /tel gls received during that window may hydrate state without being caused by one particular REST request; messages without gls are ignored. A complete REST participant set is exact only when every member reports current gls; otherwise the bounded observed reporters settle after 250 ms quiet, without waiting for the full five-second window. Refresh requests are best-effort stimuli. Startup status and naturally settled live /gl bursts publish through the same displayed-state field, but only a fresh live_gl observation newer than a pre-command sequence boundary can confirm explicit Lock or Unlock. There are no command generation IDs or retained command-result map. The integration does not publish MQTT or operate equipment during startup hydration.

Entity summary

Platform	Main entities
cover	One gate cover per discovered gate
lock	System GRITLock and one lock per RFID reader
switch	Collector, solenoid, latch, and powerbank controls
number	System LED brightness
button	Refresh, locate, GRIT service restart, and disabled-by-default hub reboot
binary_sensor	REST, internet, MQTT, physical-button, and device connectivity
sensor	Hub information, device count, device status, RSSI, firmware, and last-received diagnostics

The complete entity and authority reference is in Entities. Some buttons, switches, covers, locks, and services can cause physical activity. Review the target and site conditions before using them.

Requirements

• Home Assistant 2026.3.0 or newer.
• A reachable GRIT API base URL.
• A raw bearer token accepted by authenticated GET /api/hub.
• A broker reachable from Home Assistant, with access to the discovered GRIT hub topic.

The minimum Home Assistant version matches hacs.json and the local custom integration brand-image support used by this repository.

Install with HACS

This repository is not in the default HACS catalogue. To install it as a HACS Custom Repository:

1. In HACS, open Custom repositories.
2. Paste the verified final repository URL: https://github.com/GoDeeGo-Productions/home-assistant-grit-hub.
3. Select Integration as the category.
4. Add the repository and install GRIT Hub.
5. Restart Home Assistant.
6. Go to Settings > Devices & services > Add integration and choose GRIT Hub.

The repository transfer to GoDeeGo Productions and the final URL are verified. v0.1.1 is the latest published release. v0.1.2 is prepared after successful two-system live acceptance but has not yet been tagged or published. See the full Installation guide.

Manual installation

1. Download a trusted copy of this repository.
2. Copy custom_components/grit_hub to /config/custom_components/grit_hub.
3. Restart Home Assistant.
4. Add GRIT Hub from Settings > Devices & services.

Configuration overview

The normal first page asks only for:

• GRIT API base URL, such as https://your-grit-server.example;
• the raw bearer token, without a Bearer prefix;
• whether to verify the API TLS certificate.

Setup authenticates with GET /api/hub, retains its documented 32-character hub ID, and uses a valid returned Ethernet address as the MQTT broker. If no usable address is returned, setup asks only for the missing LAN hostname or IP address. It retains internal defaults: port 1883, TLS off, certificate verification on where applicable, keepalive 60, default REST interval 30, and the provisional vendor-default read-only MQTT credentials.

MQTT readiness requires connection, a successful subscribe call, and the exact matching successful SUBACK for grit/<hub-id>/+/+/#. Setup never publishes, scans the network, or creates the entry before validation succeeds. Advanced settings provide broker, topic hub ID, credentials, TLS, keepalive, and polling overrides. The API token and MQTT password remain secret fields.

Documentation

• Installation and removal
• Entity reference
• Architecture and state authority
• Troubleshooting and safe log redaction
• v0.1.2 acceptance report
• v0.1.2 release checklist
• Superseded v0.1.1 acceptance report
• Superseded v0.1.1 patch-release checklist
• Historical v0.1.0 acceptance report
• Historical v0.1.0 release checklist
• Changelog
• Security policy
• Contributing

Known limitations

• This is an experimental custom integration, not Home Assistant Core and not a default HACS catalogue entry.
• Direct MQTT readiness is mandatory; REST-only operation is not supported.
• The provisional read-only MQTT defaults are pending confirmation from GRIT's author. Installations that differ must use Advanced overrides.
• MQTT is QoS 0 and has no per-device staleness timer.
• A hub-level GRITLock change may occasionally fail to propagate to an individual downstream trigger. That separate propagation-reliability issue is outside v0.1.2 and is not treated as corrected by this release.
• One config entry represents one API and MQTT hub identity; multi-hub behavior has not been broadly validated.
• Dynamic device entity addition and removal requires an integration reload.
• Gate state has no unproven REST fallback. Startup waits for a fresh requested MQTT status response, but a missing device does not erase state already obtained for another device. RFID state comes from individual REST detail, not collection state or MQTT payload values.
• Collector-grade transition confirmation does not apply to solenoid, latch, or powerbank switches.
• The imported/generated endpoint catalogue remains broad and contains routes not used by the integration.

Privacy and security

Config entries and protected backups may contain API and MQTT secrets. Never share .storage, backups, databases, raw API or MQTT payloads, unredacted logs, private addresses, hub/device identifiers, or customer and personal data. Runtime data and entity attributes use bounded allowlists; raw REST and MQTT objects are not exposed as entity attributes. The integration has no Home Assistant diagnostics-download implementation.

Read Security before reporting a security issue. The approved channel is GitHub Private Vulnerability Reporting through Security > Report a vulnerability. It must be enabled and verified before publication; never place vulnerability details or installation data in a public issue.

Support and contributing

For a reproducible bug, use the repository bug-report form and include versions, installation method, affected entity, expected and actual behavior, restart behavior, and only redacted log lines. General protocol changes require evidence for both states and both transitions, plus deterministic network-free tests. See Contributing.

Licence

Licensed under the approved MIT License. The included icon is a temporary, neutral project asset with no vendor logo or text.