gree-rc-encoder

Python library to encode and decode Gree air-conditioner IR remote-control signals (pulse timings ↔ high-level state).

• GitHub: https://github.com/ClusterM/gree-rc-encoder
• PyPI: https://pypi.org/project/gree-rc-encoder/
• License: GPLv3

Install

From PyPI:

pip install gree-rc-encoder

From a local checkout (editable, with test deps):

pip install -e ".[dev]"

Quick start

from gree_rc import (
    GreeState,
    Mode,
    FanSpeed,
    encode_control,
    encode_temperature,
    decode,
    to_ir_ctl,
)

state = GreeState(
    is_on=True,
    mode=Mode.COOL,
    temperature=24,
    fan_speed=FanSpeed.AUTO,
    light_on=True,
)

timings = encode_control(state)       # list[int] durations in microseconds
print(to_ir_ctl(timings))             # "+9000 -4500 +655 ..." for ir-ctl

result = decode(timings)
assert result.state.temperature == 24

# I Feel: remote sensor reading (sent periodically while ifeel_mode is on)
temp_frame = encode_temperature(27)
assert decode(temp_frame).temperature == 27

API overview

The library performs no I/O and does not print; raise GreeEncodeError, GreeDecodeError, or GreeValidationError on failure.

GreeState fields

Fields marked model-dependent exist only on some units (the remote protocol still carries the bits; unsupported hardware ignores them). Per the manual: wifi_on / wifi_reset, cold_plasma, uvc_lamp, soft_sound, fast_cool, start_auto_clean, fresh_air.

Hardware demo

Real receive/transmit via ir-ctl lives in examples/ir_ctl_demo.py:

python3 examples/ir_ctl_demo.py receive
python3 examples/ir_ctl_demo.py send --dry-run
python3 examples/ir_ctl_demo.py temperature --dry-run

Tests

pytest

Protocol notes

Control frame

A typical control frame is four subsignals (139 timings each) separated by ~40 ms spaces. Each subsignal carries 16 nibbles (LSB-first bits), a 0,1,0 delimiter with a 20 ms space in the middle, a marker nibble, and a CRC nibble.

Markers identify the logical signal index (0..4). Captures may include more than four subsignals and may list them in any order; the decoder places each subsignal into a fixed 5-slot array by marker before parsing GreeState.

I Feel (ambient temperature)

When I Feel is enabled (GreeState.ifeel_mode), the remote periodically sends a short 35-sample frame with a different leading pulse. That frame carries the reading from the remote’s built-in temperature sensor so the indoor unit can hold the setpoint at the remote’s location rather than only at the AC.

Sleep mode level 3

sleep_mode_level values 1–2 are fixed sleep curves. Level 3 lets the user program an automatic temperature change every hour for up to eight hours. That schedule needs an extra subsignal (logical slot 4 / ~699-sample capture). This library decodes the level flag and will accept/arrange the extra subsignal by marker, but encoding and full parsing of the eight hourly setpoints is not implemented yet.