mirror of https://github.com/cassandra/home-information.git synced 2026-04-17 13:08:36 -04:00

Files

Thiago Trautwein Santos 10444fc165 Feature/234 homebox integration (#249 )

* finished Items and Locations
* finish maintenance, labels and start notifier
* finish v1 of HomeBox Client API
* sync now creates and updates entities and entities attributes
* create sync for homebox item attachments
* finish homebox integration
* finish test implementation

* Improve Homebox API client quality and pattern conformance

Align the Homebox integration with patterns established by the existing
Home Assistant (HASS) integration, and fix several minor issues found
during code review of PR #249:

- Assert required API options in HbClient.__init__ instead of silently
  logging a warning, matching the HASS client's defensive pattern
- Add warning log when login response lacks a token to aid debugging
- Translate Portuguese log message to English for consistency
- Reference HbClient constants in factory instead of magic strings
- Initialize all cache lists in HomeBoxManager.__init_singleton__
- Update factory test to work with constant references on mock class

* Fix sync bugs and remove dead code in Homebox converter

- Fix attachment order_id overlap: fields and attachments each
  enumerated from 0 independently, causing interleaved display since
  EntityAttribute orders by order_id. Attachments now start after the
  last field index.
- Fix variable shadowing in _sync_helper_entity_attributes where the
  loop variable 'hb_attachment' was immediately reassigned by tuple
  unpacking on the next line.
- Remove unused _create_entity_attributes_from_hb_fields method, which
  was superseded by the sync code using hb_item_to_attribute_field_list.

* Fix entity edit dialog for externally managed entities

HomeBox entities have non-editable attributes with disabled HTML form
fields. Browsers omit disabled fields from POST data, which caused
AttributeForm.clean() to see empty values and raise spurious validation
errors when updating the EntityType.

- Skip validation for non-editable attributes in AttributeForm.clean(),
  since save() already short-circuits without writing for these
- Add suppress_add_new property to AttributeForm to control whether the
  "Add New" attribute card is shown, following the existing pattern of
  display-hint properties (suppress_history, show_as_editable, etc.)
- Pass can_add_custom_attributes through form_kwargs in the entity
  formset so the form can suppress the add-new card for externally
  managed entities even after a bound form re-render

* Add HomeBox integration to documentation

Add HomeBox alongside Home Assistant and ZoneMinder across all
user-facing and developer documentation: Integrations guide, Features,
FAQ, Installation, architecture overview, integration guidelines, and
service patterns.

Also remove stale reference to non-existent hi.services.weather module
from integration guidelines example list.

---------

Co-authored-by: Anthony Cassandra <github@cassandra.org>

2026-03-28 09:53:46 -05:00

3.3 KiB

Raw Permalink Blame History

Integration Guidelines

Architecture Overview

Each integration is a Django app in hi/services/ directory. The hi.integration app provides management interfaces and base classes.

Key Concepts

integration_id: Unique identifier for each integration type
integration_key: Associates entities/sensors with external systems
detail_attrs: Opaque data blob - only the integration uses this data

Responsibility Boundaries

Integrations create SensorResponse objects which become Event objects with duration. The Event duration is the only accessible duration data - Event objects don't know about underlying integration specifics.

Integration Setup Process

1. Create Django App

cd src/hi/services
../../manage.py startapp myintegration

2. Configure App

Set fully qualified name in apps.py: name = 'hi.services.myintegration'
Add to INSTALLED_APPS in hi/settings/base.py

3. Define Integration Type

Add to IntegrationType enum in appropriate enums file

4. Create Gateway Class

Implement IntegrationGateway with required methods:

activate(integration_instance) - Setup and validation
deactivate(integration_instance) - Cleanup and shutdown
manage(request, integration_instance) - Management interface

5. Register with Factory

Add gateway mapping in hi/integrations/integration_factory.py

Gateway Implementation Patterns

Gateway Methods

activate(): Validate config, test connection, initialize resources deactivate(): Clean up entities, close connections, update status manage(): Handle POST actions (sync, test, config), render management UI

Return Format

All gateway methods return dict with:

status: 'success' or 'error'
message: User-friendly status message
redirect: Optional redirect URL

Integration Patterns

API Integration

HTTP Client: Use requests.Session with retry strategies and circuit breakers
WebSocket: Async connection handling with reconnection logic
Authentication: Bearer tokens, API keys, custom headers

Data Synchronization

Entity Sync: Map external entities to internal Entity models
State Sync: Update EntityState objects from external data
Cleanup: Remove entities no longer in external system

Error Handling

Custom exception hierarchy:

IntegrationError - Base class
ConnectionError - Network/connectivity issues
AuthenticationError - Auth/authorization failures
DataValidationError - Invalid data from external source

Key Base Classes & Modules

Core Classes

hi.integration.integration_gateway.IntegrationGateway - Base gateway class
hi.utils.singleton.Singleton - Singleton pattern for gateways
hi.integrations.enums.IntegrationStatus - Status enumeration

Factory Pattern

hi.integrations.integration_factory.py - Gateway registration
hi.integrations.exceptions.py - Custom exception classes

Example Integrations

hi.services.hass/ - Home Assistant integration
hi.services.zoneminder/ - ZoneMinder integration
hi.services.homebox/ - HomeBox integration

3.3 KiB Raw Permalink Blame History