BroadlinkAC — AI Agent Smart AC Controller v5.1.0

Cross-platform AC control library for Broadlink RM series IR blasters. Zero GUI dependency — designed for AI agents to clone, install, and control air conditioners programmatically. Now includes IR learning — teach the system codes from any original remote, no brand limits.

⚠️ Safety & Persistence

This skill writes durable state to the user's machine. init() creates ~/.ac_controller/config.json (API keys, device config, schedule templates) and starts a background scheduler daemon thread. The scheduler survives agent task completion — scheduled on/off times, auto-adjust, and storm auto-shutdown will continue to run autonomously. Always confirm with the user before:

• Modifying or creating schedule templates
• Enabling auto-adjust or typhoon auto-shutdown
• Changing device configuration (brand, temperature rules, location)

To fully disable automation: set schedule_enabled=False and auto_adjust=False for the device, then call _cfg.save_config(_cfg.config).

Quick Start (Agent)

git clone https://github.com/oywq00008-cell/BroadlinkAC-For-Agent.git
cd BroadlinkAC-For-Agent
pip install -r requirements-core.txt

from broadlinkac_core import init, send_ac, fetch_weather

# One-time setup — all config persisted
init(
    baidu_key="your_baidu_key",       # Baidu weather (default)
    # or use QWeather:
    # api_key="your_qw_key", qw_host="https://xxx.re.qweatherapi.com",
    location={"lat": 22.54, "lon": 114.05, "name": "Shenzhen"},
    brand="Gree"
)

# Control AC
send_ac("on", "cool", 26, "auto")     # Turn on, cool 26°C, auto fan
send_ac("off", "cool", 26, "auto")    # Turn off

# Weather — dual source (Baidu default, falls back to QWeather)
weather = fetch_weather()              # Real-time temp, humidity, feels-like

# Storm threat — returns (distance_km, storm_name)
from broadlinkac_core import typhoon_threat_distance
dist, name = typhoon_threat_distance()
if dist < 100:
    send_ac("off", "cool", 26, "auto")  # Storm protection: auto-shutdown

API Reference

Setup

| Function | Description | |----------|-------------| | init(baidu_key=None, api_key=None, qw_host=None, location=None, brand=None) | Initialize config + start background scheduler. Writes to ~/.ac_controller/config.json. Idempotent — safe to call multiple times. |

AC Control (17 brands + IR learning)

| Function | Description | |----------|-------------| | send_ac(power, mode, temp, fan) | Send IR command. power: "on"/"off". mode: "cool"/"heat"/"dry"/"fan"/"auto". temp: 16-30. fan: "auto"/"1"/"2"/"3" | | decide_ac(outdoor_temp) | Run temperature rules → returns (target_temp, mode) | | get_device() | Get connected Broadlink device |

send_ac covers the minimum universal set across all brands. For advanced features (turbo, swing, etc.), modify ac_control.py locally.

IR Learning (support any brand)

| Function | Description | |----------|-------------| | learn_one(host) | Enter learning mode on Broadlink device, wait for IR signal → returns raw hex or None (timeout 45s) | | get_raw_code(name, power, mode, temp, fan) | Look up learned hex code for a custom device | | load_custom_codes() | Load all custom codes from ~/.ac_controller/custom_codes.json | | save_custom_codes(data) | Persist learned codes | | list_custom() | List all custom device names |

Use ir_learner to teach the system codes from any AC remote — no brand limits. Codes persist automatically and send_ac routes to learned codes when the current brand is a custom one.

Weather & Alerts (Dual Source: Baidu + QWeather)

| Function | Description | |----------|-------------| | fetch_weather() | Current weather — auto-routes via Baidu/QWeather based on config | | fetch_weather_alerts() | Local weather warnings — [{headline, severity, description, ...}] |

Storm Tracking (Dual Source: China NMC + US NHC)

| Function | Description | |----------|-------------| | fetch_typhoons() | Active storms from NMC (NW Pacific) or NHC (Atlantic, configurable) | | fetch_typhoon_detail(typhoon_id) | Detailed track + forecast points | | typhoon_threat_distance() | Agent-critical: nearest storm distance (km) + name. < 100km = should shutdown. Never throws — returns (99999, "") on error | | calc_distance(lat1, lon1, lat2, lon2) | Haversine distance |

Logger

| Function | Description | |----------|-------------| | write_log(category, msg) | Append daily operation log (thread-safe) | | read_log(date_str) | Read log by date | | get_log_dates() | List dates with logs |

Supported AC Brands (17)

hvac_ir: Gree, Midea, Hisense, Daikin, Mitsubishi, Hitachi, Fujitsu, Ballu, Carrier MCA, Hyundai, Fuego

Custom protocols: Haier, AUX, Panasonic (ported from IRremoteESP8266 C++)

Multi-brand mappings: Xiaomi, Hualing → Midea protocol; Carrier NQV → Carrier MCA

Select in Settings or pass brand= to init(). Supports Chinese and English names.

Weather Providers

| Provider | Free Tier | Features | |----------|-----------|----------| | Baidu (default) | 5,000 calls/day | Real-time + forecast + alerts | | QWeather | 50,000 calls/month | Real-time + forecast + alerts |

Key Design

• import broadlinkac_core has zero side effects — no I/O, no threads
• init() is idempotent — safe to call multiple times
• Config auto-persisted to ~/.ac_controller/config.json (atomic write)
• Runs on any device with Python 3.9+ (macOS/Windows/Linux/Raspberry Pi)
• typhoon_threat_distance() never throws — returns (99999, "") on any error
• Thread-safe logging with threading.Lock

Common Agent Tasks

"Is there a storm nearby? Should I turn off the AC?"

from broadlinkac_core import init, typhoon_threat_distance, send_ac
init()
dist, name = typhoon_threat_distance()
if dist < 100:
    send_ac("off", "cool", 26, "auto")
    print(f"⚠️ {name} only {dist}km away — AC shut down for safety")

"Turn on the AC and auto-adjust based on outdoor temperature"

from broadlinkac_core import init, fetch_weather, decide_ac, send_ac
init()
w = fetch_weather()
if w:
    target, mode = decide_ac(float(w["temp"]))
    send_ac("on", mode, target, "auto")

"What's the weather and are there any alerts?"

from broadlinkac_core import init, fetch_weather, fetch_weather_alerts
init()
w = fetch_weather()
alerts, provider = fetch_weather_alerts()
for a in alerts:
    print(f"[{a['severity']}] {a['headline']}")

"Learn IR codes for a custom AC brand"

from broadlinkac_core.ir_learner import learn_one, save_learned_codes, get_raw_code

# Learn "OFF" signal
hex_off = learn_one("192.168.1.100")  # Broadlink device IP
save_learned_codes("MyAC", "gree", {"关机": hex_off})

# Learn "Cool 26°C Auto Fan"
hex_cool = learn_one("192.168.1.100")
save_learned_codes("MyAC", "gree", {"开机_制冷_26°C_自动": hex_cool})

# Send learned code
send_ac("on", "cool", 26, "auto")  # Routes to learned hex automatically

Scheduling & Automation

⚠️ All schedule changes are persistent — they survive Python process exit and will be executed by the background scheduler daemon. Always confirm with the user before enabling or modifying schedules.

The background scheduler starts automatically after init(). Agent can read/write config directly.

Read current schedule

from broadlinkac_core import init
init()
dev = _cfg.config["devices"]["your_mac"]
print(dev.get("active_template"))     # Current template name
print(dev.get("schedule_enabled"))    # True/False

Enable/disable schedule

import broadlinkac_core.config as _cfg
from broadlinkac_core import init
init()
dev = _cfg.config["devices"]["your_mac"]
dev["schedule_enabled"] = True
_cfg.save_config(_cfg.config)

Create a schedule template (multi-group)

templates = _cfg.config.setdefault("schedule_templates", {})
templates["工作日"] = {
    "groups": [{
        "days": [1, 2, 3, 4, 5],         # Monday-Friday
        "slots": [{
            "on": "08:00", "on_enabled": True,
            "off": "18:00", "off_enabled": True
        }]
    }]
}
dev["active_template"] = "工作日"
_cfg.save_config(_cfg.config)

Enable auto-adjust (every 2 hours based on outdoor temp)

dev["auto_adjust"] = True
_cfg.save_config(_cfg.config)

Desktop GUI

Pre-built installers (Windows/macOS/Linux), auto-built by GitHub Actions. Download from Releases.

OpenWRT Router Plugin

7×24 unattended AC control on OpenWRT routers. See BroadlinkAC-OpenWRT.