lex-campbell/centsys_remote

Purpose and Runtime

This is a Home Assistant custom integration for controlling and monitoring Centurion/CenSys gate operators through Centurion’s cloud API. It runs inside Home Assistant (2024.1+), is installed through HACS or copied under custom_components, and exposes each linked operator as an HA device with cover, button, switch, sensor, and binary-sensor entities.

Core integration package: custom_components/centsys_remote/

HA integration metadata/dependencies: custom_components/centsys_remote/manifest.json

Home Assistant Entry and Lifecycle

Home Assistant loads the integration through custom_components/centsys_remote/__init__.py. That module owns config-entry setup/unload and wires shared runtime objects into the entry before forwarding platforms.

User onboarding is implemented as a HA config flow in custom_components/centsys_remote/config_flow.py: country/local phone input, WhatsApp/SMS OTP request, OTP verification, and persisted login data. Country dialing rules are defined in custom_components/centsys_remote/countries.py.

Cloud API and Authentication Boundary

The API layer encapsulates the unofficial Centurion cloud protocol and shields HA entity code from HTTP/MQTT details.

• custom_components/centsys_remote/api/client.py is the authenticated cloud client and likely performs OTP/session/device operations.

• custom_components/centsys_remote/api/models.py carries typed operator, telemetry, and remote/output data between transport and HA layers.

• custom_components/centsys_remote/api/packets.py and custom_components/centsys_remote/api/enums.py define protocol representations/status vocabulary.

• custom_components/centsys_remote/api/certs/centsys_ca.pem supplies a bundled CA certificate for secure service communication.

External dependencies are Centurion’s OTP delivery and cloud service, plus its real-time MQTT-style remote channel.

Device Discovery, Refresh, and Live State

custom_components/centsys_remote/coordinator.py is the central synchronization stage. It fetches linked operators, maintains current operator state, schedules normal versus slower deep-telemetry updates, and distributes changes to entities.

Real-time control/status delivery is isolated in custom_components/centsys_remote/api/mqtt_remote.py. This supports live opening/closing transitions while the coordinator supplies periodic steady-state and diagnostic refreshes. The system must tolerate no linked gates initially, offline operators, delayed telemetry, and different SMART Wi-Fi versus GSM/ULTRA capabilities.

Domain Abstraction and Entity Mapping

custom_components/centsys_remote/entity.py provides the common HA entity base and coordinator integration. custom_components/centsys_remote/const.py centralizes integration/domain constants.

Platform modules project capability-aware operator models into HA domains:

• Gate control and state semantics: custom_components/centsys_remote/cover.py

• SMART pedestrian and GSM momentary auxiliary controls: custom_components/centsys_remote/button.py

• GSM latching outputs: custom_components/centsys_remote/switch.py

• Diagnostics and operator status: custom_components/centsys_remote/sensor.py

• Online/fault flags and GSM feedback inputs: custom_components/centsys_remote/binary_sensor.py

Controls call the API boundary; incoming coordinator/MQTT state updates drive HA entity state rather than entities polling independently.

Device-Type Behavior

The architecture supports two operational families through shared models plus conditional entity creation. SMART Wi-Fi operators expose live cover movement, pedestrian action, and broad telemetry. GSM/ULTRA devices use pulse-style commands, optional feedback inputs, and configurable auxiliary outputs; absent feedback produces assumed cover state. Protocol-specific errors are normalized through custom_components/centsys_remote/api/exceptions.py.

User-Facing Contract

HA labels, config-flow copy, and localization are maintained in custom_components/centsys_remote/strings.json and custom_components/centsys_remote/translations/en.json. This integration deliberately stores credentials in HA config entries and communicates only outbound to Centurion infrastructure.