# Gree VRF Air Conditioning — UART Protocol Documentation

Reverse-engineered from **TextParser v1.5.4** (Gree monitoring software, ~2013).

## Table of Contents

1. [Overview](#1-overview)
2. [Physical Layer](#2-physical-layer)
3. [Frame Structure](#3-frame-structure)
4. [Checksum Algorithm](#4-checksum-algorithm)
5. [Protocol Auto-Detection](#5-protocol-auto-detection)
6. [Supported Unit Types](#6-supported-unit-types)
7. [Data Fields — Outdoor Unit (ODU)](#7-data-fields--outdoor-unit-odu)
8. [Data Fields — Indoor Unit (IDU)](#8-data-fields--indoor-unit-idu)
9. [Data Fields — DC Inverter Extension](#9-data-fields--dc-inverter-extension)
10. [Data Fields — 1-to-64 Modular Extension](#10-data-fields--1-to-64-modular-extension)
11. [Data Fields — Heat Recovery / Water Heater Extension](#11-data-fields--heat-recovery--water-heater-extension)
12. [Operating Modes & Enumerations](#12-operating-modes--enumerations)
13. [Frame-to-Field Byte Mapping](#13-frame-to-field-byte-mapping)
14. [Database Schema](#14-database-schema)
15. [Software Architecture](#15-software-architecture)
16. [Hardware Setup](#16-hardware-setup)

---

## 1. Overview

The Gree TextParser tool monitors VRF (Variable Refrigerant Flow) multi-split air conditioning
systems by passively sniffing the UART bus between outdoor units (ODU), indoor units (IDU),
wired controllers (handlers), and convertor boards. It parses binary frames, extracts operating
parameters, and displays them in real-time as text/curves while logging to a database.

The communication bus carries 9 distinct frame types identified by address bytes. Each protocol
variant (1-to-16, 1-to-64, DC inverter, etc.) uses a subset of these frames with different
byte layouts.

---

## 2. Physical Layer

| Parameter | Value |
|---|---|
| **Bus** | RS-485 (half-duplex, multi-drop) |
| **PC connection** | RS-485 → RS-232 via optoelectronic isolated converter |
| **Converter power** | 12–30 VDC, 800 mA |
| **Baud rate** | Configurable (stored in `SerialPort/Baud`) |
| **Data bits** | Configurable (stored in `SerialPort/DataBits`) |
| **Stop bits** | Configurable (stored in `SerialPort/StopBits`) |
| **Parity** | Configurable (stored in `SerialPort/CheckBits`) |

### Wiring

- **ODU mainboard** → Blue (3-pin) or Red (4-pin) terminal
- **Terminal board** → White (4-pin) for ODU, White (3-pin) for IDU / monitoring
- **IDU mainboard** → White (3-pin) for terminal board / monitoring, Blue (4-pin) for wired controller
- **RS-485 lines**: A connects to R+/D+, B connects to R-/D-
- Converter DIP switches 1 and 2 must be set to OFF

### Addressing

The bus uses a master/slave addressing scheme with three address roles visible in the software:
- `nTransmitAddr` — transmitter address
- `nMainODUAddr` — main outdoor unit address
- `nCurTransmitAddr` — current transmitting device address

---

## 3. Frame Structure

Nine frame types are identified by their first byte (address/type byte):

| Frame ID | Hex   | Role / Direction | Notes |
|----------|-------|------------------|-------|
| Frame_8F | `0x8F` | ODU → bus | Outdoor unit status broadcast |
| Frame_F8 | `0xF8` | Bus → ODU | Commands/responses to outdoor unit |
| Frame_7E | `0x7E` | IDU → bus | Indoor unit data; has enhanced checksum logging |
| Frame_6E | `0x6E` | IDU → bus | Indoor unit related |
| Frame_BB | `0xBB` | Handler → bus | Wired controller / handler data |
| Frame_AF | `0xAF` | Unknown | Possibly convertor board |
| Frame_0A | `0x0A` | Unknown | Possibly convertor board |
| Frame_AC | `0xAC` | Unknown | Additional frame type |
| Frame_BC | `0xBC` | Unknown | Additional frame type |

### Generic Frame Layout (tentative)

```
Byte 0:    Frame type / address byte (0x8F, 0xF8, 0x7E, etc.)
Byte 1..N: Frame length or fixed-size payload (varies by frame type)
           Data bytes containing unit parameters
Last byte: XOR checksum
```

The software checks `QByteArray.size()` (frame length) before accessing specific byte offsets,
indicating frames may have variable or protocol-dependent lengths.

---

## 4. Checksum Algorithm

**XOR checksum** across data bytes within the frame.

From disassembly of the Frame_8F handler (`0x431C00` in TextParser.exe):

```
// Pseudocode for Frame_8F checksum verification
if (frame.length > 8)
    byte_8 = frame[8];    // data byte
else
    byte_8 = 0;

if (frame.length > 10)
    byte_A = frame[10];   // data byte
else
    byte_A = 0;

if (frame.length > 11)
    byte_B = frame[11];   // data byte
else
    byte_B = 0;

if (frame.length > 12)
    byte_C = frame[12];   // check byte
else
    byte_C = 0;

computed = byte_8 ^ byte_A ^ byte_B;
if (computed != byte_C) {
    // Frame_8F check error
    emit frameCheckSum(frameType, unitIndex, isError=true);
} else {
    // Valid frame — pass to protocol parser plugin
    emit frameCheckSum(frameType, unitIndex, isError=false);
}
```

The exact byte offsets for the checksum vary per frame type. Frame_7E logs both expected
and actual checksum: `CorrectCheck:%1, RealCheck:%2`.

Signal chain on frame validation:
```
Serial data → frame boundary detection (by address byte) →
  onFrameCheckSum(int frameType, int unitIndex, bool isError) →
    if valid: newParseValue(CommonData*) →
      plugin parses bytes → field values extracted →
        stored to DB + displayed in UI
```

---

## 5. Protocol Auto-Detection

The software maintains bitmasks tracking which frame types appear on the bus:

- `_preProtFrameBits` — previous protocol frame bitmask
- `_curProtFrameBits` — current protocol frame bitmask

By comparing observed frame types against known protocol signatures, the software
auto-detects which unit type is connected, then dynamically loads the appropriate
plugin DLL. This can be enabled via Settings → OtherSettings → ProtAutoDetect.

If the protocol changes mid-session:
```
"Num %1: Protocol is Changed, Wait a moment!"
```

---

## 6. Supported Unit Types

Each protocol variant is implemented as a separate plugin DLL:

| Plugin DLL | Protocol Name | Description |
|---|---|---|
| Protocol1_16.dll | 1to16 protocol | 1-to-16 unit (incl. EVI) |
| Protocol1_16Dc.dll | DC Inverter protocol | 1-to-16 DC inverter |
| Protocol1_16Ht.dll | 1to16Ht protocol | 1-to-16 heat recovery / water heater |
| Protocol1_16SF.dll | SF protocol | 1-to-16 smart frequency conversion |
| Protocol1_64.dll | 1to64Digit protocol | 1-to-64 digital modular (2C/3C/4C) |
| Protocol900.dll | S900 protocol | Single unit 900 (up to 6 compressors) |
| ProtocolACS.dll | SAC protocol | Air-Cooled Screw |
| ProtocolBF.dll | BF protocol | Unknown variant |
| ProtocolCS.dll | CS protocol | CS type unit |
| ProtocolDCI.dll | — | DC Inverter (single) |
| ProtocolDCFC.dll | DCFC protocol | DC Frequency Conversion |
| ProtocolDCFHWU.dll | DCFHWU protocol | DC Freq Heat Water Unit |
| ProtocolDM.dll | DM protocol | DM type unit |
| ProtocolHHP.dll | Hanging Heat Pump | Hanging heat pump |
| ProtocolHt.dll | Constant temp/humidity | Constant temperature & humidity |
| ProtocolHrCS.dll | Hr protocol | Heat Recovery CS |
| ProtocolHWHS.dll | — | Hot Water Heat System |
| ProtocolIM.dll | — | Intelligent Multi-connected |
| ProtocolWHPD.dll | Water Heat Pump-DP | Water heat pump (dual pump) |
| ProtocolWHPS.dll | Water Heat Pump-SP | Water heat pump (single pump) |
| ProtocolWU.dll | Wall Units protocol | Wall units |
| Protocol2DCFHWU.dll | 2DCFHWU protocol | 2-system DCFHWU |
| Protocol2HrCS.dll | 2 CS Hr protocol | 2-system Heat Recovery CS |
| Protocol4UMatch.dll | 4UMatch protocol | 4-unit matching |

### Protocol1_64 Sub-types

The 1-to-64 protocol supports multiple compressor configurations:
- `Digi_2C` — Digital 2-compressor
- `VFreq_2C` — Variable frequency 2-compressor
- `Digi_3C` / `VFreq_3C` — 3-compressor variants
- `Digi_4C` / `VFreq_4C` — 4-compressor variants
- `VFreq_1C` — Variable frequency single compressor

### Protocol1_16Dc Sub-types (Compressor type)

- `FixFreq` — Fixed frequency
- `ACVFreq` — AC variable frequency
- `Digital` — Digital
- `DCVFreq` — DC variable frequency

### Protocol1_16Dc Fan types

- `timing Board` — Speed control board
- `three grades` — 3-grade fan
- `AC Fan` — AC fan motor
- `DC Fan` — DC fan motor

---

## 7. Data Fields — Outdoor Unit (ODU)

### 7.1 Temperatures

| Field Name | Chinese | Description |
|---|---|---|
| `DiDLTemp` | 数码排气 | Digital compressor discharge (exhaust) temperature |
| `FiDLTemp` / `FiDLTemp1..4` | 定频排气 | Fixed-freq compressor discharge temperature (1–4) |
| `DiOilTemp` | 数码油温 | Digital compressor oil temperature |
| `FiOilTemp` / `FiOilTemp1..4` | 定频油温 | Fixed-freq compressor oil temperature (1–4) |
| `InletTemp` / `InletTemp1..2` | 入管温度 | Inlet pipe temperature (condenser/evaporator) |
| `MidTemp` / `MidTemp1..2` | 中管温度 | Middle pipe temperature |
| `OutletTemp` / `OutletTemp1..2` | 出管温度 | Outlet pipe temperature |
| `EnvTemp` / `EnvTemp1` | 环境温度 | Ambient / environment temperature |
| `AmbientTemp1` / `AmbTemp` | — | Ambient temperature (alias) |
| `DriveBoardEnvTemp` | — | Drive board ambient temperature |
| `ElectricBoxTemp` | — | Electric box temperature |

### 7.2 Temperature Sensor Status

| Field Name | Chinese | Description |
|---|---|---|
| `DiDLTSor` | 数排感温包 | Digital discharge temp sensor status |
| `FiDLTSor1` | 定排感温包 | Fixed-freq discharge temp sensor status |
| `DiOilTSor` | 数油感温包 | Digital oil temp sensor status |
| `FiOilTSor1` | 定油感温包 | Fixed-freq oil temp sensor status |
| `InletTSor1..2` | 入管感温包 | Inlet pipe temp sensor (1–2) |
| `MidTSor1..2` | 中管感温包 | Middle pipe temp sensor (1–2) |
| `OutletTSor1..2` | 出管感温包 | Outlet pipe temp sensor (1–2) |
| `EnvTSor1` | 环境感温包 | Environment temp sensor |
| `HPSensor` / `HPSor` | 高压传感器 | High pressure sensor status |
| `LPSensor` / `LPSor` | 低压传感器 | Low pressure sensor status |

### 7.3 Pressures

| Field Name | Chinese | Description |
|---|---|---|
| `HP` | 高压 | High pressure |
| `LP` | 低压 | Low pressure |
| `RTHP` | 实时高压 | Real-time high pressure (1-to-64 protocol) |
| `RTLP` | 实时低压 | Real-time low pressure (1-to-64 protocol) |

### 7.4 Compressor

| Field Name | Chinese | Description |
|---|---|---|
| `DiCompsor` | 数码压机 | Digital compressor state (Running/Stop) |
| `FiCompsor` | 定频压机 | Fixed-freq compressor state |
| `Compressor1..6` | 压缩机1..6 | Compressor on/off (up to 6 in Protocol900) |
| `Compsor1..4` | 压缩机1..4 | Compressor shorthand |
| `Capability` / `CurCap` | 能力/当前能力 | Current capacity |
| `CapPert` | 能力% | Capacity percentage |
| `DigitCapa` | — | Digital capacity |
| `UnitCapa` / `ODUCapa` | — | Unit / ODU capacity |

### 7.5 EXV (Electronic Expansion Valve)

| Field Name | Chinese | Description |
|---|---|---|
| `EXVSteps` / `EXVSteps1..2` | EXV步 | EXV step position |
| `OEXVSteps` | EXV步 | Outdoor EXV steps |
| `EVIEXVSteps` | — | EVI EXV steps |
| `EXVA` / `EXVB` | — | EXV A/B positions |

### 7.6 Fan

| Field Name | Chinese | Description |
|---|---|---|
| `OFanSpeed` / `FanSpeed` | 风速 | Outdoor fan speed |
| `FanSpeed1..2` | — | Fan speed 1/2 |
| `Fan1Speed` / `Fan2Speed` | — | Fan 1/2 speed |
| `FanFreq` | — | Fan frequency |
| `Fan1RunningFre` / `Fan2RunningFre` | — | Fan 1/2 running frequency |
| `Fan1BusCurr` / `Fan2BusCurr` | — | Fan 1/2 bus current |
| `Fan1BusVolt` / `Fan2BusVolt` | — | Fan 1/2 bus voltage |
| `Fan1ModuleTemp` / `Fan2ModuleTemp` | — | Fan 1/2 module temperature |

### 7.7 Valves

| Field Name | Chinese | Description |
|---|---|---|
| `FourWayValve` / `QValveAct` | 四通阀 | 4-way (reversing) valve |
| `CValve1..2` | 制冷剂阀 | Refrigerant valves |
| `OiValve1..2` | 油平衡阀 | Oil balance valves |
| `ByValve1..3` | 旁通阀 | Bypass valves |
| `EMValve1..4` | — | Electromagnetic valves |
| `EVIValve1..4` | — | EVI valves |
| `LiquidBypass1..4` | 液旁通 | Liquid bypass valves |
| `SolenoidValve1` | — | Solenoid valve |
| `PressureBalancedValve` | — | Pressure balance valve |
| `HPValve` / `LPValve` | — | High/low pressure valves |
| `ReversValve1..2` | — | Reversing valves |
| `GasBy_passValve` | — | Gas bypass valve |
| `LiquidBy_passValve` | — | Liquid bypass valve |

### 7.8 Protections / Errors

| Field Name | Chinese | Description |
|---|---|---|
| `HPProt` / `HPProtection` | 高压保护 | High pressure protection |
| `LPProt` / `LPProtection` | 低压保护 | Low pressure protection |
| `OverCurrProt` / `OverCurr` | 过流 | Over-current protection |
| `DLTProt` / `DLTProtection` | 排气保护 | Discharge temp protection |
| `Thawing` | 化霜 | Defrost active |
| `OCommErr` / `CommErr` | 通讯 | ODU communication error |
| `CommuErrWithMainFrame` | — | Communication error with main frame |
| `CommuErrWithTank` | — | Communication error with tank |
| `FreezeProt` | 防冻保护 | Freeze protection |
| `OilHTProt` / `OilTempProt` | 高油温保护 | Oil high temp protection |
| `HTempProt` / `HTProt` | 高温保护 | High temperature protection |
| `WaterFullProt` / `WaterFull` | 水满保护 | Water full protection |
| `SorLinkProt` / `SorConnectProt` | — | Sensor connection protection |
| `TempExcursionProt` | — | Temperature excursion protection |
| `ShortFreonProt` | — | Short freon protection |
| `ScarceRefrigerantProt` | — | Scarce refrigerant protection |
| `ACCProt` | — | ACC protection |
| `StepOverHight` | — | Step over height |

### 7.9 Status / Flags

| Field Name | Chinese | Description |
|---|---|---|
| `OFreon` | 过氟 | Over-freon (excess refrigerant) |
| `SFreon` | 欠氟 | Short-freon (low refrigerant) |
| `SOCooler` | 缺冷媒标志 | Low refrigerant flag |
| `GArea` | 绿色保护区 | Green protection zone |
| `YArea` | 黄色排气区 | Yellow exhaust zone |
| `ForceRunMode` | — | Force run mode |
| `UnitRunMode` | — | Unit run mode |
| `MachType` | 机型 | Machine type code |
| `CapCode` | 容量拨码 | Capacity DIP switch code |
| `CompTypeCode` | — | Compressor type code |
| `ProtocolVer` | — | Protocol version |
| `WholeMode` | 整机模式 | Whole unit mode |

---

## 8. Data Fields — Indoor Unit (IDU)

| Field Name | Chinese | Description |
|---|---|---|
| `IduAddr` / `IDU Addr` | 内机地址 | Indoor unit address |
| `IEXVSteps` | EXV步 | IDU electronic expansion valve steps |
| `IInTemp` | 入管温度 | IDU inlet pipe temperature |
| `IMidTemp` | 中管温度 | IDU middle pipe temperature |
| `IOutTemp` | 出管温度 | IDU outlet pipe temperature |
| `IEnvTemp` / `IAmbTemp` | 环境温度 | IDU environment / ambient temperature |
| `ISettedTemp` / `ISetTemp` | 设定温度 | Set temperature |
| `ICap` | 能力 | IDU capability / demand |
| `IMode` | 模式 | Operating mode |
| `IModeComp` / `ModeCompact` | 模式冲突 | Mode conflict flag |
| `ISwing` | 扫风 | Swing (air direction) |
| `IFan` / `FanSpeed` | 风速 | Fan speed |
| `IWaterFull` | 水满保护 | Water full protection |
| `IFreeze` / `FreezeProt` | 防冻保护 | Freeze protection |
| `IHighTemp` / `HTempProt` | 高温保护 | High temperature protection |
| `ICommErr` / `ComErr` | 通讯 | IDU communication error |
| `IduValveA` | 阀A | IDU valve A state |
| `IduValveB` | 阀B | IDU valve B state |
| `AssistHeat` | — | Auxiliary heater |
| `DoorForbid` | — | Door forbid (louver lock) |
| `EnableHeat` | — | Heating enable |
| `Type` | — | IDU type |

### IDU Grouping

IDUs are organized into groups (A through E) per outdoor unit:
- `IDU_A`, `IDU_B`, `IDU_C`, `IDU_D`, `IDU_E`

Multiple ODUs can be present:
- `Fir_ODU` (1st), `Sec_ODU` (2nd), `Thr_ODU` (3rd), `Fou_ODU` (4th)
- Each with A/B sub-groups: `FirODU_A`, `FirODU_B`, etc.

---

## 9. Data Fields — DC Inverter Extension

Additional fields in Protocol1_16Dc:

### Inverter Drive

| Field Name | Chinese | Description |
|---|---|---|
| `SettedFreq` / `SeFreq` | 设定频率 | Set (target) frequency |
| `RunningFreq` / `RuFreq` | 运行频率 | Running frequency |
| `DcBusCurr` | 母线电流 | DC bus current |
| `DcBusVolt` | 母线电压 | DC bus voltage |
| `CompCurr` | 压机电流 | Compressor current |
| `DecFreqAcce` | 降频加速度 | Deceleration rate |
| `AddFreqAcce` | 升频加速度 | Acceleration rate |
| `Comp1STTemp` / `Comp2STTemp` | 壳顶温度 | Compressor 1/2 shell top temperature |
| `RediatorTemp` | 散热片温度 | Heatsink (radiator) temperature |
| `ACPowerPhaseVolt` | — | AC power phase voltage |

### Inverter Drive Status

| Field Name | Chinese | Description |
|---|---|---|
| `CompCount` | 压机数 | Compressor count |
| `Comp1Type` / `Comp2Type` | 压机类型 | Compressor 1/2 type |
| `FanType` | 风机类型 | Fan type |
| `DevStatus` | 设备状态 | Device status |

### Inverter Protections

| Field Name | Chinese | Description |
|---|---|---|
| `DriverReset` | 驱动模块复位 | Driver module reset |
| `PhaseLost` | 欠相 | Phase loss |
| `IPMErr` | IPM异常 | IPM module error |
| `RFCErr` | PFC异常 | PFC error |
| `ACCurrProt` | AC电流保护 | AC current protection |
| `RediatorSor` | 散热片传感器 | Heatsink sensor error |
| `MotorLock` / `RotorLock` | 堵转 | Motor lock / rotor lock |
| `StepLost` | 失步 | Step loss |
| `CurrDetect` | 电流检测 | Current detection circuit error |
| `LVoltProt` | 低电压保护 | Low voltage protection |
| `DCVoltHigh` / `DCVoltLow` | — | DC voltage high/low |

---

## 10. Data Fields — 1-to-64 Modular Extension

Additional fields in Protocol1_64:

### Inverter Module

| Field Name | Chinese | Description |
|---|---|---|
| `RingFreq` / `CurRFreq` | 运行频率/实际运行频率 | Running / actual frequency |
| `DBVolt` / `CurDcBusVolt` | 母线电压/当前母线电压 | DC bus voltage |
| `UCpCurr` / `UPCompCurr` | U相压机电流 | U-phase compressor current |
| `WCpCurr` / `WPCompCurr` | W相压机电流 | W-phase compressor current |
| `RediTemp` | 散热片温度 | Heatsink temperature |
| `IPMRediatorTemp` | — | IPM heatsink temperature |
| `PFCRediatorTemp` | — | PFC heatsink temperature |

### Module Status

| Field Name | Chinese | Description |
|---|---|---|
| `ResetF` / `Reset` | 复位完成 | Reset complete |
| `QValCurr` / `QValveCur` | 四通阀得电 | 4-way valve energized |
| `Failure` | 故障 | Failure flag |
| `RediErr` | 散热片故障 | Heatsink fault |
| `CurrSor` / `CurrSorErr` | 电流传感器 | Current sensor error |
| `CutForCur` / `CutCurr` | 切断电流 | Cutoff current |
| `OVolt` / `OverVolt` | 过电压 | Over-voltage |
| `ModExcep` | 模块异常 | Module exception |
| `FanComm` / `FanCommErr` | 风机通讯 | Fan communication error |
| `ModComm` / `ModCommErr` | 模块通讯 | Module communication error |
| `IPMShCut` | IPM短路 | IPM short circuit |
| `P7Err`..`P10Err` | P7..P10异常 | Port 7–10 errors |

---

## 11. Data Fields — Heat Recovery / Water Heater Extension

Additional fields in Protocol1_16Ht:

### Heat Recovery

| Field Name | Chinese | Description |
|---|---|---|
| `HrEXV2` / `HrEXV3` / `HrExv4` | — | Heat recovery EXV 2/3/4 |
| `CoolCapReq` / `CoolCapHr` | 制冷能力需求 | Cooling capacity requirement |
| `HeatCapReq` / `HeatCapHr` | 制热能力需求 | Heating capacity requirement |
| `ValveA..E` | 阀A..E | Heat recovery valves A through E |
| `HearRecoverySetTemp` | — | Heat recovery set temperature |
| `htCallBack` | 热回收 | Heat recovery flag |

### Water Heater

| Field Name | Chinese | Description |
|---|---|---|
| `WtWaterTemp` | — | Water temperature |
| `WtBackWaterTemp` | — | Return water temperature |
| `WtUpperWaterTemp` | — | Upper water temperature |
| `WTCapacity` | — | Water tank capacity |
| `WtSetTemp` | — | Water set temperature |
| `WtFreezeProt` | — | Water freeze protection |
| `BushingInletWaterTemp` | — | Bushing inlet water temperature |
| `BushingOutletWaterTemp` | — | Bushing outlet water temperature |
| `BackWaterBump` / `WaterPump` | — | Water pump state |
| `FloorHeaterCapa` | — | Floor heater capacity |
| `BottomBandHeater` | — | Bottom band heater |
| `CompreBandHeater` | — | Compressor band heater |

### Additional Inverter (Heat Recovery)

| Field Name | Chinese | Description |
|---|---|---|
| `CompreRunningFre` | — | Compressor running frequency |
| `CompreRunningCur` | — | Compressor running current |
| `CompreGeneratrix` | — | Compressor generatrix (bus voltage) |
| `CompreSettingFre` | — | Compressor setting frequency |
| `ReduceFreSpeed` | — | Reduce frequency speed |
| `RiseFreSpeed` | — | Rise frequency speed |
| `ODUCapacity` | — | ODU capacity |
| `RunningCapability` | — | Running capability |
| `TargetCapability` | — | Target capability |

---

## 12. Operating Modes & Enumerations

### IDU Mode (`IMode`)

| Value | English | Chinese |
|---|---|---|
| 0 | Closed | 关 |
| 1 | Cooling | 制冷 |
| 2 | Drying | 抽湿 |
| 3 | Fan | 风扇 |
| 4 | Heating | 制热 |
| — | Auto | 自动 |

### IDU Fan Speed (`IFan`)

| Value | English | Chinese |
|---|---|---|
| — | Auto | 自动 |
| — | Low | 低 |
| — | Middle | 中 |
| — | High | 高 |

### ODU Fan Speed (Protocol1_16)

| Value | English | Chinese |
|---|---|---|
| 0 | Stopped | 停 |
| 1 | LowestSpeed | 超低速 |
| 2 | LowSpeed | 低速 |
| 3 | MidSpeed | 中速 |
| 4 | HighSpeed | 高速 |
| 5 | HighestSpeed | 超高速 |

### Whole Mode (Heat Recovery)

| Value | English | Chinese |
|---|---|---|
| — | Fan | 风扇 |
| — | WholeCool | 整机制冷 |
| — | HostCool | 主机制冷 |
| — | HostHeat | 主机制热 |
| — | WholeHeat | 整机制热 |

### Common Status Values

| Value | English | Chinese | Usage |
|---|---|---|---|
| — | Running | 运行 | Compressor/unit state |
| — | Stop | 停止 | Compressor/unit state |
| — | Protect | 保护 | Protection active |
| — | Thawing | 化霜 | Defrost active |
| — | NoThaw | 非化霜 | No defrost |
| — | Err | 异常 | Error / abnormal |
| — | NoErr | 正常 | Normal |
| — | Correct | 正确 | Correct / OK |
| — | Open | 开 | Valve / switch open |
| — | Close / Closed | 关 | Valve / switch closed |
| — | Failure | 故障 | Fault |
| — | Reset | 复位完成 | Reset complete |

---

## 13. Frame-to-Field Byte Mapping

### 13.1 Internal Data Model

Each protocol plugin defines its fields using an internal structure with these properties:

```c
struct FieldDefinition {
    QString name;           // +0x00: Field name (e.g. "InletTemp")
    int     fieldType;      // +0x04: 1 = data field
    int     dataType;       // +0x08: 0 = boolean/enum, 1 = numeric value
    int     byteIndex;      // +0x0C: Byte position in frame data payload
    int     bitPosition;    // +0x10: Bit position within byte (for bitfields)
    uint32  convFactor;     // +0x14: Conversion/scaling factor (for numeric fields)
    int     subIndex;       // +0x24: Secondary index
    int     reserved;       // +0x28: Reserved
    int     seqNumber;      // +0x34: Sequential field counter
    void*   enumTable;      // +0x38: Pointer to enum value table (for bool/enum fields)
    int     frameType;      // +0x34: Which frame this field is extracted from
    int     displayFlags;   // +0x30: Display control flags
};
```

### 13.2 Frame Byte Parsing Pattern (from disassembly)

The frame parser reads bytes from a `QByteArray` (the raw frame) using `movsx` (sign-extend
byte) instructions. The pattern observed in Protocol1_16.dll at `0x1008d900`:

```
Frame byte[1]:  movsx eax, byte [buffer + 1]   → lower 4 bits (AND 0x0F) = address/unit index
Frame byte[2]:  movsx eax, byte [buffer + 2]   → bitfield: individual bits = boolean flags
                  bit 0 (>> 0, AND 1): flag 1
                  bit 1 (>> 1, AND 1): flag 2
                  bit 2 (>> 2, AND 1): flag 3
                  bit 3 (>> 3, AND 1): flag 4
                  bit 4 (>> 4, AND 1): flag 5
                  bit 5 (>> 5, AND 1): flag 6 (not always used)
                  bit 6 (>> 6, AND 1): flag 7
                  bit 7 (>> 7, AND 1): flag 8
Frame byte[3]:  movsx ecx, byte [buffer + 3]   → combined with byte[4] for 16-bit values
Frame byte[4]:  movsx eax, byte [buffer + 4]   → high byte (SHL 8) + byte[3] = 16-bit value
                  Also parsed as bitfield (SHR 1..7 for individual flags)
Frame byte[5]:  movsx eax, byte [buffer + 5]   → bitfield: individual bits for boolean flags
                  bit 7 (>> 7): flag
                  bit 5 (>> 5): flag
                  bit 4 (>> 4): flag
                  bit 3 (>> 3): flag
                  bit 2 (>> 2): flag
                  bit 1 (>> 1): flag
```

Multi-byte values (temperatures, pressures) are reconstructed as:
```
value_16bit = (byte[N+1] << 8) | byte[N]    // little-endian 16-bit
```

### 13.3 ProtocolCS — Complete Field Map (Water-Cooled Screw)

Frame type: Settings/command frame for CS (Water-Cooled Screw) units.

| Seq | Byte | Field Name              | Type      | Description |
|-----|------|-------------------------|-----------|-------------|
| 0   | 0    | ON_OFF                  | bool/enum | Unit on/off (OFF=0, ON=1) |
| 1   | 1    | RunMode                 | enum      | Run mode (Cooling=1, Heating=2, Defrost=3) |
| 2   | 2    | CoolInWaterTempSet      | numeric   | Cooling inlet water temp setpoint |
| 3   | 3    | HeatInWaterTempSet      | numeric   | Heating inlet water temp setpoint |
| 4   | 4    | HeatReInWaterTempSet    | numeric   | Heat recovery inlet water temp setpoint |
| 5   | 5    | DefrostOnTemp           | numeric   | Defrost on temperature |
| 6   | 6    | DefrostOffTemp          | numeric   | Defrost off temperature |
| 7   | 7    | DefrostInterval         | numeric   | Defrost interval |
| 8   | 8    | DefrostDuration         | numeric   | Defrost duration |
| 9   | 9    | IniAntiFreWaterTemp     | numeric   | Initial anti-freeze water temp |
| 10  | 10   | AntiOverHotWaterTemp    | numeric   | Anti-overheat water temp |
| 11  | 11   | AuxiHeatOnTemp          | numeric   | Auxiliary heater on temperature |
| 12  | 12   | AuxiHeatOffTemp         | numeric   | Auxiliary heater off temperature |
| 13  | 13   | TempChangeRate          | numeric   | Temperature change rate |
| 14  | 14   | CompActInterval         | numeric   | Compressor activation interval |
| 15  | 15   | WinAntiFreEnabled       | bool      | Winter anti-freeze enabled |
| 16  | 16   | AuxiHeatEnabled         | bool      | Auxiliary heater enabled |
| 17  | 17   | QuietMode               | bool      | Quiet mode |
| 18  | 18   | EnergySaveMode          | bool      | Energy save mode |
| 19  | 19   | ClearErrs               | bool      | Clear errors |
| 20  | 20   | DisTempSorLock          | bool      | Discharge temp sensor lock |
| 21  | 21   | HasHeatReModule         | bool      | Has heat recovery module |
| 22  | 22   | QuickTestMode           | bool      | Quick test mode |
| 23  | 23   | LangDisplay             | enum      | Language (Chinese=0, English=1) |
| 24  | 24   | HasCompRun              | bitfield  | Compressor running status |
| 25  | 25   | HasUnrecoverErr         | bitfield  | Unrecoverable error flag |
| 26  | 26   | HasRecoverErr           | bitfield  | Recoverable error flag |
| 27–43 | 27–43 | M16..M1ReqOnPump    | bitfield  | Module 1–16 pump request status |
| 44  | 44   | ACinWaterAveTemp        | numeric   | AC inlet water average temp |
| 45  | 45   | HotWaterInAveTemp       | numeric   | Hot water inlet average temp |
| 46  | 46   | CompOnSequence          | numeric   | Compressor on sequence |
| 47  | 47   | CompOffSequence         | numeric   | Compressor off sequence |
| 48  | 48   | ProgramVersion          | numeric   | Program version |

### 13.4 Protocol1_64 — ODU Field Parse Order (Digital Modular)

Fields extracted from the ODU status frame (0x8F), in parse order.
Boolean/bitfield flags are packed into bytes, numeric values span 1-2 bytes.

**Bitfield group 1** (status flags, parsed from a single byte with SHR):
| Bit | Field Name    | Description |
|-----|---------------|-------------|
| 0   | CapCode       | Capacity DIP code |
| 1   | BackOil       | Oil return active |
| 2   | EqulOil       | Oil equalization active |
| 3–6 | (reserved)    | — |
| 7   | CurRCap       | Current running capacity |

**Bitfield group 2** (protection/valve flags):
| Bit | Field Name    | Description |
|-----|---------------|-------------|
| 0   | FreProt       | Freeze protection |
| 1   | OilHTProt     | Oil high temp protection |
| 2   | Reset         | Reset complete |
| 3   | OFreon        | Over-freon |
| 4   | SFreon        | Short-freon |
| 5   | CValve1       | Refrigerant valve 1 |
| 6   | CValve2       | Refrigerant valve 2 |
| 7   | OValve1       | Oil balance valve 1 |

**Bitfield group 3** (more valves/status):
| Bit | Field Name    | Description |
|-----|---------------|-------------|
| 0   | OValve2       | Oil balance valve 2 |
| 1   | GasByValve    | Gas bypass valve |
| 2   | DiLiqByValve  | Digital liquid bypass |
| 3   | FiLiqBypass1  | Fixed-freq liquid bypass 1 |
| 4   | QValveAct     | 4-way valve action |
| 5   | SCooler       | Short cooler/low refrigerant |
| 6   | GArea         | Green protection zone |
| 7   | YArea         | Yellow exhaust zone |

**Bitfield group 4** (fan/fault status):
| Bit | Field Name       | Description |
|-----|------------------|-------------|
| 0   | Failure          | Fault flag |
| 1   | FanBusVolt       | Fan bus voltage status |
| 2   | FanModuleTemp    | Fan module temp status |
| 3   | FanBusCurr       | Fan bus current status |
| 4   | FanCommu         | Fan communication status |
| 5   | FanVoltProt      | Fan voltage protection |
| 6   | FanModuleProt    | Fan module protection |
| 7   | FanMotorHighTemp | Fan motor high temp |

**Bitfield group 5** (compressor fault/error flags):
| Bit | Field Name         | Description |
|-----|--------------------|-------------|
| 0   | FanModuleHighTemp  | Fan module high temp |
| 1   | FanCurrProt        | Fan current protection |
| 2   | CompOverCurr       | Compressor over-current |
| 3   | OverSpeed          | Over-speed |
| 4   | LostStep           | Step loss |
| 5   | RotorLock          | Rotor lock |
| 6   | CommuErr           | Communication error |
| 7   | RediatorTempHigh   | Heatsink temp high |

**Numeric fields** (parsed as full byte or 16-bit values):
| Order | Field Name      | Size   | Description |
|-------|-----------------|--------|-------------|
| —     | OduAddr         | 1 byte | ODU address |
| —     | MachType        | 1 byte | Machine type |
| —     | RTHP            | 2 bytes| Real-time high pressure |
| —     | RTLP            | 2 bytes| Real-time low pressure |
| —     | EnvTemp         | 1 byte | Environment temperature |
| —     | CompCurr        | 1 byte | Compressor current |
| —     | RunningFreq     | 1 byte | Running frequency |
| —     | CurDcBusVolt    | 1 byte | Current DC bus voltage |
| —     | UPCompCurr      | 1 byte | U-phase compressor current |
| —     | VPCompCurr      | 1 byte | V-phase compressor current |
| —     | IPMRediTemp     | 1 byte | IPM heatsink temperature |
| —     | Compressor1..4  | 1 bit each | Compressor 1–4 on/off |
| —     | DLTemp1..3      | 1 byte each | Discharge temperatures |
| —     | OilTemp1..4     | 1 byte each | Oil temperatures |
| —     | InletPipeTemp1..2 | 1 byte each | Inlet pipe temperatures |
| —     | MidPipeTemp1    | 1 byte | Middle pipe temperature |
| —     | OutPipeTemp1..2 | 1 byte each | Outlet pipe temperatures |
| —     | AmbientTemp1    | 1 byte | Ambient temperature |
| —     | EXVSteps1       | 2 bytes| EXV step position |
| —     | HP / LP         | 2 bytes each | High/low pressure |
| —     | HPProtection    | 1 bit  | High pressure protection |
| —     | LPProtection    | 1 bit  | Low pressure protection |
| —     | OverCurr        | 1 bit  | Over-current |
| —     | DLTProtection   | 1 bit  | Discharge temp protection |
| —     | Thawing         | 1 bit  | Defrost active |
| —     | FanSpeed        | 1 byte | Fan speed |

### 13.5 Protocol1_16 — Frame 0x8F ODU Data (from disassembly at 0x1008d900)

The main ODU frame parser reads bytes sequentially. Based on the `movsx` instruction
analysis at addresses `0x1008d950`–`0x1008dd50`:

```
byte[1]:  AND 0x0F → lower nibble = unit identifier / address field
byte[2]:  bitfield (8 boolean flags, extracted with SHR 0..7)
            - bit 0: status flag 1 (e.g. compressor state)
            - bit 1..7: additional boolean status flags
byte[3]:  value byte (part of 16-bit pair with byte[4])
byte[4]:  bitfield OR high byte for 16-bit value
            - As bitfield: SHR 1..7 for individual flags
            - As 16-bit: (byte[4] << 8) | byte[3]
byte[5]:  bitfield (boolean flags)
            - SHR 1..7 for individual flags
```

### 13.6 Notes on Temperature Encoding

Temperature values appear to be stored as **signed bytes** (using `movsx` = sign-extend),
suggesting they are stored as degrees Celsius offset. The software mentions `SensorRes`
(sensor resistance) affecting exhaust and oil temperatures — default is 10kΩ since 2007.

Pressure values can be displayed as temperature or pressure depending on the `PresValue`
setting, and the `CoolerType` setting (refrigerant type: R22, R410A, etc.) affects the
pressure-to-temperature conversion.

### 13.7 How to Build Your Own Parser

1. **Connect** to the RS-485 bus via an RS-232↔RS-485 converter
2. **Listen** for frame start bytes: `0x8F`, `0xF8`, `0x7E`, `0x6E`, `0xBB`, `0xAF`, `0x0A`, `0xAC`, `0xBC`
3. **Read** the complete frame (length depends on protocol variant)
4. **Validate** XOR checksum: XOR specific data bytes and compare with check byte
5. **Parse** data bytes using the field maps above
6. **Convert** raw values:
   - Boolean/enum: check individual bits using AND/SHR
   - Temperatures: sign-extend byte, may need sensor resistance correction
   - Pressures: 16-bit little-endian, convert using refrigerant type
   - EXV steps: 16-bit little-endian (after-service edition shows in steps of 10)

**Key unknowns** (require live bus capture to confirm):
- Exact frame length for each frame type
- Exact byte positions beyond byte[5] — the largest parser functions (30-45KB) 
  exceeded decompiler timeout limits
- Whether frames have a fixed header beyond the type byte
- Exact baud rate and serial parameters for your specific unit model

---

## 14. Database Schema

Data is stored in Microsoft Access (`.mdb`) files at `C:\DataFiles\{YYYY-MM}\{DD-MM-YYYY}\`.

### Tables

```sql
-- Outdoor unit data (one table per ODU, one row per sample)
CREATE TABLE ODU (...)
CREATE TABLE ODU1 (...)  -- for multi-ODU systems
CREATE TABLE ODU2 (...)

-- Indoor unit data (one table per IDU address)
CREATE TABLE IDU_1 (...)
CREATE TABLE IDU_2 (...)
-- etc.
```

### Insert pattern

```sql
INSERT INTO ODU (...field names matching data fields above...)
INSERT INTO IDU_1 (...field names matching IDU data fields above...)
```

The software uses ODBC with Microsoft Access Driver:
```
DRIVER={Microsoft Access Driver (*.mdb)};FIL={MS Access};DBQ=%1
```

---

## 15. Software Architecture

```
TextParser.exe (Qt4 GUI)
├── SerialPortThread — reads COM port data
├── DocumentParser — splits byte stream into frames by address bytes
├── ProtSchedule — protocol auto-detection, frame validation
│   ├── analyseProtID() — identifies protocol from frame bitmask
│   └── initProtFrameBits() — initializes expected frame patterns
├── Plugin interface: com.gree.TextParser.ProtocolParserInterface/1.0
│   └── Each Protocol*.dll implements:
│       ├── Frame parsing (byte → field extraction)
│       ├── Text GUI (real-time text display)
│       ├── Curve GUI (real-time curve display)
│       ├── Database storage (Access .mdb)
│       └── IDU/ODU unit management
├── CurveGUI — plotting widget
├── TreeWidget — unit tree (IDUs, ODUs, Convertors)
└── TestEnvInfoWidget — communication info display
```

### Plugin Interface

Plugin ID: `com.gree.TextParser.ProtocolParserInterface/1.0`

Key signals/slots:
- `newParseValue(CommonData*)` — emitted when new field values are parsed
- `sglFrameCheckSum(int, int, bool)` — frame checksum result signal
- `sglMainODUAddr(int, int, int)` — main ODU address signal

---

## 16. Hardware Setup

### Required Equipment

1. Computer with RS-232 COM port (or USB-to-serial adapter)
2. Optoelectronic isolated RS-232 to RS-485 converter (94×72×23 mm)
3. Communication cable with DB9 connectors (female + male)
4. 12–30VDC power supply for converter (800mA)

### Connection Diagram

```
┌──────────┐   DB9 cable    ┌──────────────┐   RS-485 (A,B)   ┌──────────────┐
│ Computer │ ──────────────► │ RS232-RS485  │ ────────────────► │ ODU          │
│ COM port │   RS-232        │ Converter    │                   │ Mainboard    │
└──────────┘                 └──────────────┘                   └──────┬───────┘
                              DIP 1,2 = OFF                            │
                              Power: 12-30VDC                    RS-485 (A,B)
                                                                       │
                                                                ┌──────┴───────┐
                                                                │ Terminal     │
                                                                │ Board        │
                                                                └──────┬───────┘
                                                                       │
                                                                 RS-485 (A,B)
                                                                       │
                                                                ┌──────┴───────┐
                                                                │ IDU          │
                                                                │ Mainboard    │
                                                                └──────────────┘
```

**Important:** A/B wires from terminal board must connect to IDU A/B in matching order.