{"id":35631687,"url":"https://github.com/johnf/actron-air-esphome","last_synced_at":"2026-03-09T02:15:15.233Z","repository":{"id":328440380,"uuid":"1115563912","full_name":"johnf/actron-air-esphome","owner":"johnf","description":"Actron Air ESP32 Keypad Component for ESPHome","archived":false,"fork":false,"pushed_at":"2026-03-07T04:59:25.000Z","size":1035,"stargazers_count":2,"open_issues_count":5,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-07T09:53:34.110Z","etag":null,"topics":["actronair","esphome-component","home-assistant","home-automation","homeassistant","homeassistant-custom-component"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-13T05:12:21.000Z","updated_at":"2026-03-07T04:59:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/johnf/actron-air-esphome","commit_stats":null,"previous_names":["johnf/esphome-actron-air-keypad"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/johnf/actron-air-esphome","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnf%2Factron-air-esphome","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnf%2Factron-air-esphome/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnf%2Factron-air-esphome/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnf%2Factron-air-esphome/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnf","download_url":"https://codeload.github.com/johnf/actron-air-esphome/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnf%2Factron-air-esphome/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30280381,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T01:43:35.720Z","status":"online","status_checked_at":"2026-03-09T02:00:08.011Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actronair","esphome-component","home-assistant","home-automation","homeassistant","homeassistant-custom-component"],"created_at":"2026-01-05T09:11:15.044Z","updated_at":"2026-03-09T02:15:15.209Z","avatar_url":"https://github.com/johnf.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Actron Air ESPHome Integration for Home Assistant\n\nAn ESPHome external component for reading and decoding pulse trains from the\nActron Air ESP32 keypad display, plus a Home Assistant integration with climate\nentity and custom Lovelace card.\n\n## Key Features\n\n- **Interrupt-driven reading**: Accurate pulse train capture\n- **40-bit decoding**: Full status from keypad display\n- **Temperature display**: 7-segment decoder for setpoint\n- **18 binary sensors**: Mode, fan, zones, timers\n- **Error tracking**: Bit count for monitoring reliability\n- **Type-safe config**: ESPHome validation for all settings\n- **Climate entity**: Full HVAC control with zone presets\n- **Custom Lovelace card**: Retro keypad-style control interface\n\n## Hardware Requirements\n\n- ESP32 (ESP-IDF framework)\n- GPIO pin for pulse train input\n- Connection to air conditioner keypad display output\n- MCP4725 or MCP4726 DAC (I2C) for keypad button emulation\n- BC548 NPN transistor\n- Resistors: 20kΩ, 4.7kΩ, 1.2kΩ (0.5W or higher)\n\nSee the [forum thread](https://community.home-assistant.io/t/actron-aircon-esp32-controller-help/609062)\nfor detailed build instructions and wiring diagrams.\n\n## Compatible Systems\n\nThis integration works with Actron Air ducted systems that use the older-style\nwall controllers with a 4-wire interface (SENS, KEY, COMM, POWER).\n\n### Wall Controllers\n\n| Controller | Status | Notes |\n|------------|--------|-------|\n| LM24 | Confirmed | Multi-zone controller |\n| LM7 / LM7-2W / LM7-2G | Community reported | 7-day programmable, up to 8 zones |\n| LM7-D | Community reported | Ultima Zone Control Master |\n| AM7 | Community reported | Original older controller |\n\n### Air Conditioner Systems\n\n**Compatible:**\n\n- SRA series (e.g., SRA22C, SRA25C) - older multi-zone ducted systems\n- SRD series (e.g., SRD175C, SRD22C) - older ducted systems\n- ESP Plus, ESP Platinum, ESP Ultima with LM7/LM24 controllers\n- Classic series (SRG models) with LM7/LM24 controllers\n\n**Not compatible:**\n\n- Systems with QUE controllers (different architecture)\n- Systems with ActronConnect/ACM WiFi modules (post-2013)\n- Serene Series with Easy Connect app\n\n## Installation\n\nThis project has two parts:\n\n1. **ESPHome component** - Runs on your ESP32 to read the keypad and control the AC\n2. **Home Assistant integration** - Provides climate entity and Lovelace card\n\n**Set up the ESPHome device first**, then install the Home Assistant integration.\n\n### Step 1: ESPHome Device Setup\n\nSee [ESPHome Configuration](#esphome-configuration) below for detailed setup instructions.\nThe quickest way is to use the ESPHome package - just copy\n[example_actron_air_keypad.yaml](example_actron_air_keypad.yaml) and customise for your setup.\n\n### Step 2: Home Assistant Integration\n\nOnce your ESPHome device is running, install the integration:\n\n#### HACS (Recommended)\n\n[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=johnf\u0026repository=actron-air-esphome\u0026category=integration)\n\nOr manually:\n\n1. Open HACS in Home Assistant\n2. Go to \"Integrations\" section\n3. Click the three dots menu and select \"Custom repositories\"\n4. Add `https://github.com/johnf/actron-air-esphome` with category \"Integration\"\n5. Install \"Actron Air ESPHome\"\n6. Restart Home Assistant\n7. Go to Settings \u003e Devices \u0026 Services \u003e Add Integration\n8. Search for \"Actron Air ESPHome\" and configure\n\nThe integration will automatically register the Lovelace card.\n\n#### Manual Installation\n\n1. Copy the `custom_components/actron_air_esphome` folder to your Home Assistant `config/custom_components/` directory\n2. Restart Home Assistant\n3. Go to Settings \u003e Devices \u0026 Services \u003e Add Integration\n4. Search for \"Actron Air ESPHome\" and configure\n\n## Lovelace Card Usage\n\n![Actron Air Card](images/actron_air_card.png)\n\nAdd the card to your dashboard:\n\n```yaml\ntype: custom:actron-air-esphome-card\nentity_prefix: actron_air\n```\n\n### Card Configuration Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `entity_prefix` | string | **required** | Prefix for ESPHome entities (e.g., `actron_air`) |\n| `name` | string | - | Card title (optional) |\n| `show_timer` | boolean | `true` | Show timer controls |\n| `show_zones` | boolean | `true` | Show zone buttons |\n| `zone_count` | number | `4` | Number of zones to display (1-7) |\n| `zones` | array | - | Custom zone names |\n\n### Full Configuration Example\n\n```yaml\ntype: custom:actron-air-esphome-card\nentity_prefix: actron_air\nname: Air Conditioning\nshow_timer: true\nshow_zones: true\nzone_count: 4\nzones:\n  - name: Bedrooms\n  - name: Living Room\n  - name: Kitchen\n  - name: Office\n```\n\n### Expected Entity Names\n\nThe card expects entities with the following naming pattern based on your `entity_prefix`:\n\n**Sensors:**\n\n- `sensor.{prefix}_setpoint_temperature`\n\n**Switches:**\n\n- `switch.{prefix}_power`\n- `switch.{prefix}_zone_1` through `switch.{prefix}_zone_8`\n\n**Binary Sensors:**\n\n- `binary_sensor.{prefix}_cool`\n- `binary_sensor.{prefix}_heat`\n- `binary_sensor.{prefix}_auto`\n- `binary_sensor.{prefix}_run`\n- `binary_sensor.{prefix}_fan_low`\n- `binary_sensor.{prefix}_fan_mid`\n- `binary_sensor.{prefix}_fan_high`\n- `binary_sensor.{prefix}_fan_continuous`\n- `binary_sensor.{prefix}_inside`\n- `binary_sensor.{prefix}_timer`\n- `binary_sensor.{prefix}_zone_1` through `binary_sensor.{prefix}_zone_8`\n\n**Buttons:**\n\n- `button.{prefix}_mode`\n- `button.{prefix}_fan`\n- `button.{prefix}_temp_up`\n- `button.{prefix}_temp_down`\n- `button.{prefix}_timer`\n- `button.{prefix}_timer_up`\n- `button.{prefix}_timer_down`\n\n## ESPHome Configuration\n\nThe easiest way to get started is to use the ESPHome package, which includes all\nsensors, DAC controls, and button definitions. See\n[example_actron_air_keypad.yaml](example_actron_air_keypad.yaml) for a complete example.\n\n### Quick Start (Using Package)\n\n```yaml\npackages:\n  actron_air: github://johnf/actron-air-esphome/actron_air_keypad.yaml@main\n\nesphome:\n  name: \"my-aircon\"\n  friendly_name: My Air Conditioner\n\nwifi:\n  ssid: !secret wifi_ssid\n  password: !secret wifi_password\n\n# Enable auto-discovery in Home Assistant\nmdns:\n  services:\n    - service: \"_actron_air\"\n      protocol: \"_tcp\"\n      port: 6053\n      txt:\n        version: \"1.0.0\"\n        name: \"my-aircon\"\n```\n\nThat's it! The package includes everything you need:\n\n- All 7 zones (remove unused ones with `!remove` if desired)\n- DAC output for button emulation\n- All binary sensors, switches, and buttons\n- Configurable GPIO pins and voltage calibration via substitutions\n\n### Customising the Package\n\nOverride any defaults by adding a `substitutions` section before the package:\n\n```yaml\nsubstitutions:\n  gpio_keypad_pin: \"GPIO32\"    # Pin for keypad signal\n  gpio_i2c_sda: \"GPIO21\"       # I2C SDA pin\n  gpio_i2c_scl: \"GPIO22\"       # I2C SCL pin\n  dac_output_address: \"0x60\"   # MCP4725 DAC I2C address\n  # Voltage calibration (millivolts)\n  voltage_zone_1: \"725.0\"\n  voltage_zone_2: \"663.0\"\n  # ... see actron_air_keypad.yaml for all options\n\npackages:\n  actron_air: github://johnf/actron-air-esphome/actron_air_keypad.yaml@main\n```\n\n### Removing Unused Zones\n\nIf you have fewer than 7 zones, you can remove the unused ones:\n\n```yaml\npackages:\n  actron_air: github://johnf/actron-air-esphome/actron_air_keypad.yaml@main\n\n# Remove zones 5-8 for a 4-zone system\nswitch:\n  - id: !remove zone_5_switch\n  - id: !remove zone_6_switch\n  - id: !remove zone_7_switch\n  - id: !remove zone_8_switch\n\n  - id: !remove zone_5\n  - id: !remove zone_6\n  - id: !remove zone_7\n  - id: !remove zone_8\n```\n\n### Manual Configuration (Without Package)\n\nIf you prefer more control, you can use the external component directly:\n\n```yaml\nexternal_components:\n  - source:\n      type: git\n      url: https://github.com/johnf/actron-air-esphome\n      ref: main\n    components: [actron_air_esphome]\n\nactron_air_esphome:\n  pin: GPIO32\n\nsensor:\n  - platform: actron_air_esphome\n    setpoint_temp:\n      name: \"Temperature\"\n\nbinary_sensor:\n  - platform: actron_air_esphome\n    cool:\n      name: \"Cool Mode\"\n    heat:\n      name: \"Heat Mode\"\n    fan_high:\n      name: \"Fan High\"\n    zone_1:\n      name: \"Zone 1\"\n    zone_2:\n      name: \"Zone 2\"\n```\n\n## Climate Entity\n\nThe Home Assistant integration provides a climate entity with:\n\n- **HVAC Modes**: Off, Cool, Heat, Auto, Fan Only\n- **Fan Modes**: High, Medium, Low, High Cont, Medium Cont, Low Cont, Off\n- **Zone Presets**: Individual zones and \"All Zones\"\n- **Optional**: Current temperature and humidity from external sensors\n\nConfigure via Settings \u003e Devices \u0026 Services after installing the integration.\n\n## Available ESPHome Sensors\n\n### Numeric Sensors (`sensor` platform)\n\n- `setpoint_temp` - Temperature from 7-segment display (C)\n- `error_count` - Error counter for monitoring\n\n### Status Sensors (`binary_sensor` platform)\n\n- **Mode**: `cool`, `heat`, `auto_mode`, `run`\n- **Fan**: `fan_high`, `fan_mid`, `fan_low`, `fan_cont`\n- **Zones**: `zone_1` through `zone_8`\n- **Other**: `inside`, `timer`\n\n### Debug Sensors (`text_sensor` platform)\n\n- `bit_string` - Raw 40-bit pulse train (internal use)\n\n## How It Works\n\n### Wires\n\nThere are 4 wires inside the wall unit that connect to the main supply:\n\n- SENS - sensor line is directly connected to a thermistor\n- KEY - connected to the keypad, it changes resistance to a different value\n  when keys are pressed. This drops the voltage from 5V to different levels\n- COMM - ground\n- POWER - 19V and also data line that gets shifted into the LED. The protocol\n  in this wire is quite simple: Data is transmitted every 200ms or so. It starts\n  with a 16V-\u003e0V transition, followed by 41 other pulses, a zero or a one is\n  determined by the time between the pulses. Each value is then shifted through\n  the leds in the board.\n\n### Pulse Train Decoding\n\n1. An interrupt handler captures falling edges on the ADC pin\n2. Timing between edges determines if the pulse represents a '0' or '1'\n3. 40 bits are collected to form a complete frame\n4. The frame is decoded to extract display and LED status\n5. Changes are published to Home Assistant sensors\n\n## Circuit Diagrams\n\nThe circuit connects the ESP32 to the Actron Air keypad interface. Fritzing source\nfiles are available in the [fritzing/](fritzing/) directory.\n\n### Schematic\n\n![Circuit Schematic](images/circuit.png)\n\n### Veroboard Layout\n\n![Veroboard Layout](images/veroboard.png)\n\n## Troubleshooting\n\n### No data received\n\n- Check ADC pin connection\n- Verify pulse train voltage levels\n- Monitor `error_count` sensor for errors\n\n### Incorrect temperature readings\n\n- Check 7-segment wiring/decoding\n- Look at `bit_string` for raw data\n- Verify display is showing temperature\n\n### Compile errors\n\n- Ensure ESP-IDF framework is selected\n- Check all Python files are present\n- Validate YAML indentation\n\n### Card not showing\n\n- Clear browser cache\n- Check browser console for errors\n- Verify the resource is loaded in Settings \u003e Dashboards \u003e Resources\n\n---\n\n**Need Help?**\n\n- Check ESPHome logs: `esphome logs your-device.yaml`\n- Validate config: `esphome config your-device.yaml`\n- Review example_actron_air_keypad.yaml for complete setup\n\n## License\n\nMIT License - Feel free to use and modify\n\n## Thanks\n\nThis builds on the work of many others:\n\n- \u003chttps://community.home-assistant.io/t/actron-aircon-esp32-controller-help/609062\u003e\n- \u003chttps://github.com/kursancew/actron-air-wifi\u003e\n- \u003chttps://github.com/brentk7/Actron-Keypad\u003e\n- \u003chttps://github.com/cjd/Actron-Keypad\u003e\n- \u003chttps://github.com/LaughingLogic/Actron-Keypad\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnf%2Factron-air-esphome","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnf%2Factron-air-esphome","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnf%2Factron-air-esphome/lists"}