Skip to content

Adding support for a new AC protocol

Jump to bottom
David Conran edited this page Sep 2, 2019 · 21 revisions

Work in Progress

Not ready for prime time use yet.

Here is a rough outline of the steps required to add a new Air Conditioner protocol to the library.

Preparation

0. See if it is already supported first.

Take a look at the Supported Protocols document. See if we've already documented support for your Air Conditioner/Heat Pump. Obtain a IR Demodulator Hardware component, and build this circuit, and then compile and run the IRrecvDumpV2 example code on your ESP device. Monitor the serial output from the ESP module. The output should tell you what it knows about your protocol if it is supported, or list it as UNKNOWN if it doesn't know what it is.

1. Obtain the make & model number of the A/C unit AND the IR remote.

We will need that information later. Do some research to see if you can find any/all of the following:

  • The operation manual.
  • The specification for the IR protocol.
  • Links to any other implementations and projects that support your air conditioner.
  • Photos of the remote control etc.

2. Read the FAQ first

See & read the FAQ on this topic to see/understand what you are asking/attempting.

Getting the basics

3. Capture some "Raw" IR messages from the remote.

Use the circuit and program (IRrecvDumpV2) described above to capture a few simple messages for the Air Conditioner.

  • Include the entire text of the output of the IRrecvDumpV2 program for the given messages. e.g. Including the timestamp, library version, and most importantly, the uint16_t rawData[] = {...}; line. Add to that text (please, no screen shots) a description of every setting on the remote at the time. e.g. "Power button was pressed. Remote went from 'off' to 'on' and Cool mode, with Fan at auto, no fan swing, no filters were on, led display on the aircon was on, timers were all off/disabled, the clock on the remote was at '12:00', the temperature was 25C ..." etc for EACH message.

3. (a) Bonus step.

Run the uint16_t rawData[] = {...}; output through the auto_analyse_raw_data.py program and provide that output. It's a basic tool to do some rough analysis of the protocol and make some guesses to it's structure and parameters.

4. Log an issue (or fork your own branch and send a PR) to add experimental support for the protocol.

Report all the information you've collected in a new issue. If I've got all that information, I can fairly quickly add rudimentary support for your protocol, or ask you for more information. The end result of that step is typically "Basic" support for the protocol will be added. That means, you can capture IR messages and they will be converted to a long, single hexidecimal code for your protocol, and you should be able to recreate the same signal using that hex code using the newly added sendBlah() routine. NOTE: This is still a preliminary/experimental hex code. Don't rely on it just yet.

5. Raw Data should no longer be needed.

Once we have a working decode routine. You should no longer need to record the full output of IRrecvDumpV2. You only need the uint64_t data = ...; or the uint8_t state[] = {...}; lines to fully detail what the message is. i.e. The protocol number/type (e.g. 70 or DAIKIN152) and the data/state lines should be all anyone needs to reproduce the message. We no longer need to care about the micro-details of timings if it is successfully detected. If it is still coming up as UNKNOWN then, yes, collecting the raw data is necessary.

6. Determining the bit order of the protocol.

Most AirCon protocols have two distinct formats which significantly affect the hex code for the protocol. That is, if the code is transmitted in Least Significant Bit First (LSB or LSBF), or Most Significant Bit First (MSB or MSBF) bit order. To try work out which order your protocol uses, we use a fairly simple process.

  • Set the remote to what ever modes produce the most about of zeros in the hex code as currently captured. e.g. Clock to "00:00", Auto modes, or Cool modes typically.
  • Capture & Record the the ENTIRE temperature range starting from the lowest temperature the remote/aircon can do, and step up every smallest temperature increment you can until you reach the highest temp.
  • Try to find which part of the hex code changes when you do this. Typically the last byte (the last two hexidecimal numbers) are often the checksum for the message. It is often safe to ignore those for the moment for now.
  • Look to see how the numbers change with each temperature increment. If they are linear with the temperature (e.g. the increase by 1 for each degree etc) then we've probably got the bit ordering of the protocol correct. It's a 50/50 chance. If not, odds are we need to swap the bit ordering in the code.
  • Once we've confirmed we have the bit ordering correct only then can you proceed on to trying to work out what bits and bytes control which aspects of the AirCon.

Adding detailed support

This is where things get hard, and you have to a lot of analysis work. I'll break things up in to sections to attack but you don't have to do them in any particular order.

The most important features you need to target are:

  • Power control (i.e. Turning the unit On and Off. See: Binary Settings.)
  • Mode control (i.e. Cool, Heat, Fan Only, Auto, Dry etc. See: Value ranges)
  • Temperature control (Which you should probably have worked out by now. See earlier. See: Value ranges)
  • Fan Speed control (How fast the fan is to run. See: Value ranges) & potentially, the hardest to decode:
  • The message checksum(s) (Often Air Conditioner remotes are long and to make sure the message hasn't been corrupted they have some verification code built into the message. If a/c messages have a checksum(s), then working out how to calculate it will be required to be able to dynamically create a new valid A/C message. Thus, it's a requirement if you want the library to be able to create and send a new A/C message. It isn't required to just decode a message.

Binary Settings

These are A/C settings that are typically controlled by a single "bit" in the hex code. e.g. An option that can only be "on" or "off". For instance, "Health", "Ion Filter", or "Turbo" settings are often a Binary Settings controlled by a single bit in the message. "Power" is often a binary setting too, but some A/Cs have special messages that either toggle the A/C unit from off to on and on to off with the exact same bit in a message, or even have an entirely different and unique message for controlling this. The best way to detect these is to try to have the remote produce a code that has the least number of bits set to 1 (on). e.g. a 0 bit is typically off, or the default for a setting. The more 0s in a code the better for making these settings stand out easier.

Clone this wiki locally