TapHome

Gree U-Match Air Conditioning

Modbus TCP
Submitted by
Last updated: 03. 2026

Requires external gateway

Gree / TD metal Modbus Gateway (TD GUD 30/01) or Modbus Gateway(Mini) ME30-24/E6(M)

Gree U-Match Air Conditioning

The Gree U-Match series are commercial/residential air conditioning units (duct-type, cassette, floor/ceiling) with R32 refrigerant. TapHome connects to each indoor unit via Modbus RTU over RS-485, using the Gree Modbus Gateway (TD GUD 30/01 or Mini ME30-24/E6) installed inside the indoor unit.

The template provides power on/off control, operating mode selection (cooling, heating, drying, fan only, auto), thermostat setpoint adjustment, fan speed control (auto, 5 speeds, turbo), vertical and horizontal swing, and ambient/outdoor temperature monitoring.

Enabling Modbus communication

Before TapHome can communicate with the indoor unit, Modbus must be activated using the wired controller XK117 (Z4K351GJ).

Activating Modbus on the indoor unit
  1. With the unit in OFF state, hold FUNCTION and TIMER buttons for more than 5 seconds to enter the settings menu
Gree XK117 wired controller in OFF state — hold FUNCTION and TIMER to enter settings
  1. Press MODE multiple times to reach the 10th settings parameter (middle number), use the arrow buttons to select option 01 and confirm by pressing SWING/ENTER
Gree XK117 wired controller — select 10th parameter value 01 and confirm with SWING/ENTER
Setting the indoor unit address

When multiple gateways share the same RS-485 bus, each indoor unit must have a unique address. Otherwise, keep the default address 1.

  1. With the unit in OFF state, hold FUNCTION and MODE buttons for more than 5 seconds
Gree XK117 wired controller in OFF state — hold FUNCTION and MODE to enter address setting
  1. Use the arrow buttons to choose the unit address and confirm by pressing SWING/ENTER
Gree XK117 wired controller — select unit address and confirm with SWING/ENTER

Hardware connection

Each indoor unit requires its own Modbus Gateway module. The gateway connects to the indoor unit mainboard via the included 6-pin communication cable and provides an RS-485 interface for the Modbus bus.

Gateway to indoor unit
  1. Plug the 6-pin communication cable into the brownish red socket labeled COM-BMS (connector 9) on the indoor unit mainboard
Gree duct-type indoor unit mainboard — COM-BMS socket location for Modbus Gateway connection
  1. Connect the other end to the Modbus Gateway socket labeled UNIT
Gree Modbus Gateway (Mini) module — UNIT socket and RS-485 terminals (A, B, GND)
RS-485 bus wiring

Connect TapHome Core to the gateway’s RS-485 terminals:

TerminalFunction
ARS-485 Data+
BRS-485 Data-
GNDSignal ground

One twisted pair connects A and B, the remaining line(s) connect GND.

RS-485 twisted pair wiring to A+, B- and GND terminals on Gree Modbus Gateway
  • Cable: Shielded twisted pair, 0.2-0.32 mm² (24-22 AWG), EIA-485 compliant (e.g. Belden 3016A)
  • Topology: Bus (daisy-chain) only — star, ring, or triangle connections are not supported
  • Max length: 500 meters
  • Termination: 120 ohm resistor between A and B on the first and last device on the bus
  • Shielding: Attach cable shield to chassis ground on one end only (preferably the outermost indoor unit)
RS-485 daisy-chain bus topology with shielding grounded on one end

The RS-485 bus must use a bus (daisy-chain) topology. Star, ring or triangle wiring will cause communication failures.

Configuration

  • Protocol: Modbus RTU (wrapped in Modbus TCP by TapHome)
  • Baud rate: 9,600 bit/s
  • Data bits: 8, parity: none, stop bits: 1
  • Default Slave ID: 1

When importing the template in TapHome, provide:

  • IP Address — the TapHome Modbus TCP gateway address
  • Slave ID — Modbus slave address of the indoor unit (default: 1)

When controlling multiple indoor units, each gateway must have a unique slave address. Set the address via the wired controller before connecting to the bus.

Device capabilities

The template exposes the following devices:

Power control
  • Power On/Off — switch to turn the air conditioning unit on or off. Uses register H:2 with non-standard values: 0xAA = ON, 0x55 = OFF.
Operating mode
  • Mode (multi-value switch) — select from: Cooling, Heating, Drying, Fan Only, Auto. Uses register H:17 (UInt16). The available modes depend on the outdoor unit’s capabilities — for example, if the outdoor unit supports cooling only, heating modes will be ineffective.
Thermostat
  • Thermostat — reads indoor ambient temperature from register H:4 (value / 10) and reads/writes the desired temperature setpoint at register H:20. Range: 16–30 °C.
Fan speed
  • Fan Speed (multi-value switch) — set fan speed via register H:19: Auto, Speed 1–5, or Turbo. Under drying mode, low fan speed is compulsory. Turbo is available in cooling/heating modes only.
Swing control
  • Swing Vertically — toggle up-down swing on/off via register H:22. The service action “Set up & down swing” provides finer 11-position control (0–11).
  • Swing Horizontally — toggle left-right swing on/off via register H:23. The service action “Set left & right swing” provides finer 8-position control (0–8).
Temperature monitoring
RegisterSensorDescriptionIn template
H:4Indoor ambientRoom temperature (value / 10)Yes
H:49OutdoorOutdoor temperature (sign-bit encoded)Yes
Word 115Air outletSupply air temperature (value + 100 offset)No
Service attributes

The template also exposes diagnostic attributes readable in TapHome’s service view:

AttributeRegisterDescription
IDU Addr.H:5Indoor unit address on the gateway bus
Fresh air valve statusH:24Fresh air valve open/close
Sleep modeH:25Sleep mode status (0=off, 1=on)
Contamination gradeH:34Filter contamination level
Ambient temp sensor selectionH:39Active ambient temperature sensor
DRED functionH:77Demand response enabling device status
Return air temperatureH:82Temperature at the air return port
Light board temperatureH:83Light board temperature sensor
Additional capabilities

The Gree Modbus protocol also exposes registers for energy saving limits (cooling/heating/dehumidifying temperature bounds), quiet mode, sleep mode, 8°C heating (absence mode), X-Fan, and filter cleaning reset. These can be added to the TapHome template in a future update.

Troubleshooting

No Modbus communication
  1. Verify that Modbus communication was activated on the indoor unit via the wired controller XK117 (10th parameter set to 01)
  2. Check the RS-485 wiring: A, B and GND terminals must be connected correctly
  3. Confirm the baud rate is set to 9,600 in TapHome
  4. Ensure the slave ID in TapHome matches the address configured on the indoor unit
Mode changes not applied

The outdoor unit’s operating mode takes priority. If the outdoor unit supports cooling only, setting heating mode via Modbus will be ineffective. Error code 0x04 indicates a communication failure between the gateway and the indoor unit — check the 6-pin cable connection to the COM-BMS socket.

Temperature setpoint ignored

When the energy saving function is enabled, temperature commands outside the configured limits will be rejected. Verify the energy saving temperature bounds (Word 106–108) or disable energy saving via the indoor unit’s controls.

Available devices

Gree U-Match AC Module
Service Attributes
IDU Addr.indoor unit address on the gateway bus
Fresh air valve statusfresh air valve open/close status
Sleep modesleep mode status; 0=off, 1=on (protocol Bit 301)
Contamination gradefilter contamination grade
Selection of ambient temp sensorwhich ambient temperature sensor is active
DRED functiondemand response enabling device (DRED) function status
Ambient temp at the port of air returnreturn air temperature; value multiplied by 10 in script (raw x10)
Ambient temp of light boardlight board temperature sensor; value multiplied by 10 in script (raw x10)
Up & down swingup-down swing position readback (multi-value); mirrors device #7
Left & right swingleft-right swing position readback (multi-value); mirrors device #6
Service Actions
Set up & down swingset vertical swing to specific position; parameter \'val\' 0–11 maps to binary position codes (0000–1011)
Set left & right swingset horizontal swing to specific position; parameter \'val\' 0–8 maps to binary position codes (0000–1101)

Gree_AC

Service Attributes
IDU Addr.
modbusr(H,5,uint16)
Fresh air valve status
modbusr(H,24,uint16)
Sleep mode
modbusr(H,25,uint16)
Contamination grade
modbusr(H,34,uint16)
Selection of ambient temp sensor
modbusr(h,39,uint16)
DRED function
modbusr(h,77,uint16)
Ambient temp at the port of air return
modbusr(h,82,int16)*10
Ambient temp of light board
modbusr(h,83,int16)*10
Up & down swing
modbusr(h,22,uint16)
Left & right swing
modbusr(h,23,uint16)
Service Actions
Set up & down swing
Parameters: value (0–11 val)
modbusw(h,22, uint16, switch(val, 1, "0001",
2,"0010",
3, "0011",
4,"0100",
5, "0101",
6, "0110",
7,"0111",
8,"1000",
9, "1001",
10, "1010",
11, "1011",
"0000"))
Set left & right swing
Parameters: value (0–8 val)
modbusw(h,22, uint16, switch(val, 1, "0001",
2,"0010",
3, "0011",
4,"0100",
5, "0101",
6, "0110",
7,"1100",
8,"1101",
"0000"))
Ambient Temperature Temperature Sensor Read-only

Indoor room temperature — value divided by 10

Register: H:4 UInt16 Unit: °C numeric

Ambient Temperature

Read temperature
var v := MODBUSR(H, 4, UInt16);

if (GETBIT(v,15))
    RETURN ((-(V & 0x7FFF))/10);
ELSE
    return(v/10);
END
Fan Speed Multi-value Switch

Fan speed selector — Auto, Speed 1–5, Turbo

Register: H:19 UInt16 numeric
Values / States: Auto · Speed 1 · Speed 2 · Speed 3 · Speed 4 · Speed 5 · Turbo

Fan Speed

Read switch state
MODBUSR(H, 19, UInt16)
Write switch state
MODBUSWNE(H, 19, UInt16, Mu)
Mode Multi-value Switch

Operating mode selector — Cooling, Heating, Drying, Fan Only, Auto

Register: H:17 UInt16 numeric
Values / States: Cooling · Cooling · Heating · Drying · Fan Only · Auto

Mode

Read switch state
MODBUSR(H, 17, UInt16)
Write switch state
MODBUSWNE(H, 17, UInt16, Mu)
Outdoor Temperature Temperature Sensor Read-only

Outdoor ambient temperature with sign-bit encoding

Register: H:49 Int16 Unit: °C numeric

Outdoor Temperature

Read temperature
var v := MODBUSR(H, 49, Int16);

if (GETBIT(v,15))
    RETURN (-(V & 0x7FFF));
ELSE
    return(v);
END
Power On/Off Switch

Unit power switch — 0xAA=ON, 0x55=OFF

Register: H:2 UInt16 numeric

Power On/Off

Read switch state
SWITCH(MODBUSR(H, 2, UInt16), 85,0,170,1,0)
Write switch state
MODBUSWNE(H, 2, UInt16, SWITCH(St, 0,85,1,170,85))
Thermostat Thermostat

Temperature setpoint 16–30 °C with indoor ambient reading

Register: H:4 (current), H:20 (desired) → H:20 UInt16 Unit: °C numeric

Thermostat

Read temperature
MODBUSR(H, 4, UInt16) / 10
Read desired temperature
MODBUSR(H, 20, UInt16)
Write desired temperature
MODBUSWNE(H, 20, UInt16, Se)
Swing Horizontally Switch

Left-right air swing toggle — service action for 8-position control

Register: H:23 Int16 numeric
Values / States: SWING · OFF

Swing Horizontally

Read switch state
MODBUSR(H, 23, int16)
Write switch state
MODBUSW(H, 23, int16, St)
Swing Vertically Switch

Up-down air swing toggle — service action for 11-position control

Register: H:22 Int16 numeric
Values / States: SWING · OFF

Swing Vertically

Read switch state
MODBUSR(H, 22, int16)
Write switch state
MODBUSW(H, 22, int16, St)
Connection: Modbus TCP • Slave ID: $[SlaveId]
Possible improvements (14)
  • Word 106 Lower Limit Temp of Cooling Energy Saving — UInt16, value x10, range 16.0–30.0°C, R/W
  • Word 107 Upper Limit Temp of Heating Energy Saving — UInt16, value x10, range 16.0–30.0°C, R/W
  • Word 108 Lower Limit Temp of Dehumidifying Energy Saving — UInt16, value x10, range 16.0–30.0°C, R/W
  • Word 115 Air Outlet Temperature — UInt16, value + 100, range -30 to 138°C, read-only
  • Word 117 Gate Control Status — UInt16, 0=invalid, 1=without, 2=insert card, 3=disconnect card
  • Word 119 Category of Indoor Unit Model — UInt16, 1=Duct, 2=Cassette, 3=Wall, 4=Floor ceiling, etc.
  • Word 123 Rated Capacity of Indoor Unit — UInt16, hectowatt, read-only
  • Bit 296 Energy Saving — Coil, 0=off, 1=on, R/W
  • Bit 300 Dry Mode — Coil, 0=off, 1=on, R/W
  • Bit 301 Sleep Mode (coil) — Coil, 0=off, 1=on, R/W — currently read-only via service attribute
  • Bit 302 Quiet Mode — Coil, 0=off, 1=on, R/W
  • Bit 303 Ventilation — Coil, 0=off, 1=on, R/W
  • Bit 308 8°C Heating Function — Coil, 0=cancel, 1=start, R/W
  • Word 3302 Upper Limit Capacity of Outdoor Unit — UInt16, 30–100%, R/W, system-level
Download Template

Sources