BroadlinkAC For Agent

🎮 AI Agent 智能空调控制核心库 — 零 GUI 依赖，import 即用。支持 17 大品牌空调（格力/美的/海尔/大金等），直连 Broadlink RM 红外遥控器。百度+和风双天气源，中央气象台+NHC 双风暴源，多日期组定时模板，Markdown 日志，故障诊断。适配树莓派/NAS/OpenWRT/桌面全平台。

KevinChan@oywq00008-cell

Install

openclaw skills install @oywq00008-cell/broadlinkac

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)

bash

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

python

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?"

python

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"

python

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?"

python

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"

python

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

python

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

python

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)

python

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)

python

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.

BroadlinkAC For Agent

Install

BroadlinkAC — AI Agent Smart AC Controller v5.1.0

⚠️ Safety & Persistence

Quick Start (Agent)

API Reference

Setup

AC Control (17 brands + IR learning)

IR Learning (support any brand)

Weather & Alerts (Dual Source: Baidu + QWeather)

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

Logger

Supported AC Brands (17)

Weather Providers

Key Design

Common Agent Tasks

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

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

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

"Learn IR codes for a custom AC brand"

Scheduling & Automation

Read current schedule

Enable/disable schedule

Create a schedule template (multi-group)

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

Desktop GUI

OpenWRT Router Plugin

Related skills