DOCSEARCHbyAlgolia
Submit Docs

AC Infinity Home Assistant Integration

repository·main·Indexed 41 days ago

https://github.com/dalinicus/homeassistant-acinfinity

A Home Assistant custom component that integrates AC Infinity UIS Controller devices via the AC Infinity cloud. Supports Controller 69 Wifi, Controller 69 Pro, Controller 69 Pro+, and Controller AI+. Provides control and monitoring of sensors, settings, and device ports through the AC Infinity API.

Tokens
4.5K
Snippets
9
Records
24
Agent score
53%

What's inside AC Infinity

  1. Compatible AC Infinity UIS Controllers

    main

    This integration supports the following UIS Controllers, provided they are connected to Wi-Fi and can sync to the UIS Cloud:

    • Controller 69 Wifi
    • Controller 69 Pro
    • Controller 69 Pro+
    • Controller AI+

    Note: Bluetooth-only devices (such as Controller 67 or the base model Controller 69) are not compatible because they do not sync directly to the UIS Cloud.

  2. Understand the Entity Unique ID format

    main

    Entity unique IDs follow a specific pattern to ensure uniqueness across controllers, ports, and data types:

    {domain}_{mac_address}_{port_specifier}_{data_key}

    Examples:

    • Controller-level (no port): ac_infinity_2B120D62DC00_temperature
    • Device on a specific port: ac_infinity_2B120D62DC00_port_1_loadState
    • Sensor on a specific port: ac_infinity_2B120D62DC00_sensor_1_co2Sensor

  3. Understand the AC Infinity data model hierarchy

    main

    The integration organizes data into three distinct levels of abstraction:

    1. ACInfinityController: Represents a physical UIS hub (identified by MAC address). It manages the device list and sensor arrays (for AI+ models).
    2. ACInfinityDevice: Represents a specific USB-C port on a controller. It tracks port-specific state, settings, and online status.
    3. ACInfinitySensor: Represents environmental sensor arrays (temperature, humidity, CO2, etc.) found on AI+ controllers, connected via USB-C ports.

  4. Understand the project architecture and component structure

    main

    The integration uses a layered architecture to bridge the AC Infinity cloud API with Home Assistant entities:

    Home Assistant Entity Platforms $\rightarrow$ Entity Layer (core.py) $\rightarrow$ Service Layer (core.py) $\rightarrow$ HTTP Client Layer (client.py)

    Component Directory Map

    • __init__.py: Integration entry point and lifecycle.
    • client.py: Async aiohttp client for AC Infinity API.
    • core.py: Data models, service layer, coordinator, and entity base classes.
    • const.py: Constants and API field definitions.
    • config_flow.py: ConfigFlow and OptionsFlow implementations.
    • manifest.json: Integration metadata.
    • strings.json: UI labels and translations.
    • translations/: Localized strings.
    • sensor.py, switch.py, select.py, number.py, time.py, binary_sensor.py: Platform-specific implementations.

  5. Understand the Entity and Service layers

    main

    Entity Architecture

    All entities extend CoordinatorEntity[ACInfinityDataUpdateCoordinator] using specialized base classes:

    • ACInfinityControllerEntity: For entities tied to a specific controller.
    • ACInfinityDeviceEntity: For entities tied to a specific port.
    • ACInfinitySensorEntity: For entities tied to environmental sensors.

    Service Layer (ACInfinityService)

    This layer manages data within Home Assistant's coordinator pattern:

    • Data Caching: Stores API responses in structured dictionaries to minimize redundant calls.
    • Coordinator Integration: Updated by ACInfinityDataUpdateCoordinator during refresh cycles.
    • Entity Query Interface: Provides typed accessor methods for entity description callbacks.
    • Update Operations: Handles write operations to the AC Infinity API with built-in retry logic and error handling.

  6. Manage API constants in const.py

    main

    To ensure consistency and avoid hardcoding, all API field names must be centralized in const.py using plain Python classes.

    Rule: Never hardcode API field strings outside of const.py.

    class ControllerPropertyKey:
    DEVICE_ID = "devId"
    MAC_ADDR = "devMacAddr"
    DEVICE_NAME = "devName"

class DevicePropertyKey:
    PORT = "port"
    NAME = "portName"
    ONLINE = "online"
    STATE = "loadState"

  7. Set up a local development environment

    main

    To develop the homeassistant-acinfinity component, you need to set up a local Python environment and a Docker-based Home Assistant instance. This allows you to test changes to the custom_components directory in real-time.

    Prerequisites

    • Python 3.14
    • Git
    • Docker
    • A valid AC Infinity account

    Installation Steps

    1. Clone the repository:
      git clone https://github.com/your-org/homeassistant-acinfinity.git
cd homeassistant-acinfinity
    2. Install dependencies:
      pip install -r requirements.txt
    3. Start local Home Assistant:
      docker-compose up homeassistant

    Access the instance at http://localhost:8123. The custom_components directory is volume-mounted, so changes are reflected immediately.

    git clone https://github.com/your-org/homeassistant-acinfinity.git
cd homeassistant-acinfinity
pip install -r requirements.txt
docker-compose up homeassistant

  8. Group sensors into physical device entities

    main

    Physical USB-C sensor accessories are represented as child devices in Home Assistant. Grouping is handled in ACInfinitySensor.__get_device_info in core.py.

    To add a new physical sensor device:

    1. Add the SensorType constants in const.py.
    2. Add a new case block in ACInfinitySensor.__get_device_info in core.py. Group all types from the same hardware under one DeviceInfo. Use a lowercase identifier slug matching the model suffix (e.g., _hds3).
    3. Register the sensor types in SENSOR_DESCRIPTIONS in sensor.py.

  9. Initial Setup of AC Infinity

    main

    After installation, add the integration via the Home Assistant Integrations UI. You must provide the following credentials:

    • Email: The email address registered with your AC Infinity account.
    • Password: The password for your AC Infinity account.

    During setup, you will be prompted to select which entities should be enabled for each controller associated with your account.

  10. Implement mutually exclusive sensor pairs

    main

    Some sensors (like Temperature or EC) report measurements in two different units (e.g., Celsius vs Fahrenheit). To prevent creating two separate Home Assistant entities for the same physical measurement, use a shared SensorReferenceKey.

    By assigning both SensorType entries the same key in SENSOR_DESCRIPTIONS, only the type present in the device's sensor array at runtime will be registered. The other is silently ignored.

    Steps to add a new pair:

    1. Add both constants to SensorType in const.py.
    2. Add a single shared key to SensorReferenceKey in const.py.
    3. Register both types in SENSOR_DESCRIPTIONS in sensor.py using the same key and translation_key.
    # 1. const.py
class SensorType:
    MY_SENSOR_UNIT_A = 42
    MY_SENSOR_UNIT_B = 43

class SensorReferenceKey:
    MY_SENSOR = "mySensor"

# 2. sensor.py
SensorType.MY_SENSOR_UNIT_A: ACInfinitySensorSensorEntityDescription(
    key=SensorReferenceKey.MY_SENSOR,
    native_unit_of_measurement="unit_a",
    translation_key="my_sensor",
    ...
),
SensorType.MY_SENSOR_UNIT_B: ACInfinitySensorSensorEntityDescription(
    key=SensorReferenceKey.MY_SENSOR,
    native_unit_of_measurement="unit_b",
    translation_key="my_sensor",
    ...
),

  12. Explore the AC Infinity API using Bruno

    main

    The repository includes a Bruno API collection in the .bruno/ directory to help you inspect real API payloads.

    Setup Instructions

    1. Open Collection: In the Bruno desktop application, select Open Collection and point to the .bruno/ folder in the repo root.
    2. Configure Environment: Select the default environment in the Environments panel and set the following secret variables:
      • EMAIL: Your AC Infinity account email.
      • PASSWORD: Your AC Infinity account password.
    3. Authenticate: Run the Login request. Copy the appId from the response and set it as the USER_ID environment variable. This USER_ID is used as the token header for all subsequent requests.
    4. Identify Devices: Run the Get Devices List request. Use the response to populate these environment variables:
      • DEVICE_ID: The ID for a standard (non-AI+) controller.
      • AI_DEVICE_ID: The ID for an AI+ controller.