Troubleshooting Guide

Things to try before reporting a new Issue

Here are some of the things we expect you to try to solve problems yourself before asking us for help.

General

1. ESP-01 modules are tricky. We suggest you use a module with more GPIOs for your first time. e.g. An ESP-12 or NodeMCU board etc.
2. Avoid using the following pins on an ESP8266 unless you really know what you are doing:
   • Pin 0/D3: Can interfere with the boot/program mode & support circuits.
   • Pin 1/TX/TXD0: Any serial transmissions from the ESP8266 will interfere.
   • Pin 3/RX/RXD0: Any serial transmissions to the ESP8266 will interfere.
   • Pin 16/D0: Has no interrupts on the ESP8266, so can't be used for IR receiving with this library.
   • Avoid I2C pins for IR sending or receiving if you are using I2C.
3. Check what version of the library you are using. Update &/or try using the latest master release of the library. There have been bugs over time. Your issue might already have been fixed.
4. Check you are using the correct sized variables & values. Unlike your PC/Linux box, integers (int) on this platform are 16bit, longs are only 32bit. If you need more than 32 bits, you need 'long long's which are 64 bit. If you are using a constant in your code append a 'L' for longs or 'LL' for long longs.
5. Check that you are using unsigned values. Most codes used by the send routines are 'unsigned long's (uint32_t). Some arduino routines do not play nice with unsigned longs or unsigned long longs. e.g. toInt() only handles 'long's, not 'unsigned long' values. e.g. Use strtoul() instead. This is a common mistake made even by advanced users. Same goes for constants; Use a suffix of 'UL' or 'ULL' for those values.
6. Check you are using the correct Baud rate on your serial terminal/monitor. i.e. Most of the examples use 115200/8-N-1. If you don't use the same Baud as the code is sending you may get no output or garbage output.

Sending an IR signal

Basic

1. Make sure you've connected the IR LED to the same pin as specified in your code.
2. If you are just connecting the IR LED directly to the pin, the GPIO pin doesn't supply enough current. The IR LED will unlikely be bright enough for your device to see. You will typically need to drive the IR LED via a transistor that is controlled by a GPIO.
3. Check you have the IR LED polarity correct. If you have the IR LED around the wrong way, it won't illuminate.
4. Use a digital camera or modern smart phone to check if the IR LED is flashed.
   • May not work if it is an iPhone camera.
   • You can temporarily replace the IR LED with a normal LED if you don't have a digital camera when debugging.
5. Simplify your circuit. Complexity is our enemy when debugging. Please try to eliminate everything else that could possibly interfere. We strongly suggest you use this basic circuit when testing.
6. Make sure the IR LED has direct line of sight to the device you're trying to send to. LEDs typically have cone of light coming out of top of them where the signal is strongest. So point the top of the LED directly at the receiver on the device.
7. IR LEDs don't have infinite range. Try bringing the IR LED closer to the device you want to send to.
8. Devices can be overpowered by a bright IR LED. There is a such a thing as too close. People have reported problems where IR signals that should just work but don't only because they were too close to the receiver module.
9. Double check where you think the IR receiver is on the device you are trying to control.
10. Try a different IR LED. Some times you get a dud. It's uncommon, but not unheard of. LEDs are fairly easy to burn out if you've over driven them with too much current or voltage for too long. The example circuit does overdrive the IR LED on purpose. It is typically okay-ish to do this for very short periods of time in the realms of milli-seconds which is what happens in typical IR code operation. Doing so will reduce the expected lifetime of the LED by a small amount with the trade off of a much brighter (better) output. If you've put too much current or voltage for too long (seconds to minutes to hours depending) you've likely fried the LED.
11. You are using an IR LED right? A 940nm IR LED is what we are expecting you to use and works in most cases. Cheap clear ones off ebay work fine.
12. Use the basic example code.
13. Check you are using the correct bit size/length for the protocol and the code you are trying to send. e.g. NEC codes are all 32bit, whereas Sony has 12, 15 & 20 bit protocols. A wrong bit size is an easy way to screw up sending a code. Almost all bit lengths max out at 32 bits for most common protocols. There are exceptions of course.

Advanced

1. Check you're satisfying the specifications of the IR LED with your circuit.
2. Use a second ESP8266 or an arduino board with an IR receiver of the correct frequency and capture a rawData dump and/or decode result to see what is being sent.
3. If you have access to an oscilloscope, consider using that to see how the IR LED is being driven.
4. Some IR LEDs have an appreciable lag when firing up. Very rare, but not unheard of.
5. Check the current and voltage values at the IR LED.
6. Try sending the code using sendRaw() or sendGC().
7. The ESP8266 is not a highly accurate timing device. We've tried to chose the correct timing values based on the best available data, and from user feedback, and our experience with the ESP8266 timing quirks. Not all devices are the same. You may need to tweak some of the protocol values yourself to get the best results for the device you are trying to communicate too.

Receiving an IR signal

Basic

1. Find out and check what make & model of IR receiver module you have. Unlike IR LEDs, they are typically frequency specific. 38kHz ones are the common ones. However, a lot of devices and protocols use different frequencies. e.g. 36kHz, 40Khz, etc. It is possible the problem you are experiencing is a frequency mismatch.
2. Double check you have the pin outs of the module wired correctly. While most modules look the same, there are different variants. Some swap the position of the Vs and GND pins. e.g. TSOP44.. & TSOP48.. vs. TSOP22.. & TSOP24..
3. Check you are supplying the correct voltage to the IR receiver module. Also check what voltage it is sending on it's output pin. Remember that ESP8266s only work at 3.3V & 5V levels, and ESP32s only work with 3.3V. Anything more might fry your GPIO pin/ESP module. Some IR receiver modules only work with a Vcc of 5V. Thus they may work fine on a Ardunio Uno board, but not on the ESP, unless you power them from the Vcc pin, not from a GPIO, or the 3V3 pin.
4. Are you using a VS1838b IR demodulator? If so, see the FAQ on this item. TL;DR: It works poorly if the conditions are not optimal.
5. Are you sure the remote control unit is sending properly?
   • Replace/Check the batteries.
   • Use a digital camera to check the IR LED in the remote is illuminating.
6. Use an appropriate distance between the transmitter and the receiver. A receiver module can easily be overpowered and produce a corrupt signal if you have the IR source too close. A range of less than ~30mm is often enough to confuse the receiver.
7. Simplify the circuit. Complexity is our enemy when debugging. We suggest using this circuit until you're sure you've got things working.

Advanced

1. Perform the capture in a dark room, with no fluorescent lights, and no direct sunlight. Often environmental Intra-Red & electronic noise can cause significant interference with the IR signal.
2. Use a second ESP or Arduino to send a known good signal. e.g. sendNEC(0x1234, 32);
3. Check what the IR receiver is sending to the ESP with an oscilloscope.
4. Use a capacitor of value 470uf between positive and negative terminal of IR sensor.

Problems decoding

1. Air conditioner protocols tend to be quite large, regularly larger than the default size specified by kRawBuf in src/IRrecv.h. Try upping it to 512 or larger. See also bufsize in the IRrecv class initialisation.
2. The library example code doesn't handle quickly repeating IR codes well. If it detects a code is finished, it will stop listening until it is re-armed. The time it takes to decode & print out over serial what it saw, and re-enable receiving it can often re-arm in the middle of a subsequent code. Some protocols require multiple codes sent together. e.g. Sony & Sherwood. It's possible these situations can confuse the decoder, or you might miss part or all of a subsequent remote code in some situations.
3. Trust the rawData more than anything else.
4. When it detects it as UNKNOWN, the NN-bit code value reported is useless for sending purposes. In fact, it's pretty poor as a unique value for decoding too. In short, don't rely on it for anything.
5. We don't have decoders for some protocols. Some that we do have are not enabled by default. Check the code to see what's available and enabled by default.

Reporting an Issue.

Okay. You've tried all the basic stuff above, and it still doesn't work. Sounds like it's a legitimate issue. You've probably hit a bug or have an oddball case. Here are some of the things you can do to save you time in getting a useful response from us. Please please log an issue, so we can fix it for you and for other people.

1. More data & info == more better. The more information we have from you, the better and faster we can help you.
2. Tell us which version/revision of the library you are using, and when you last updated it etc. Are you using an up-to-date master clone? This helps us identify what might have been a known issue and/or if it has already been fixed.
3. Try using the example code wherever possible. It helps us know what we are dealing with.
4. Simplify your code if possible. Try to reduce your code to the smallest subset that still causes the issue. That will save us time trying to sift through your code to find what might be wrong or be a bug etc.
5. Post your reduced code somewhere for us to look at. We are not mind readers. We work best when we can see what's going wrong. "In Code We Trust.", everything else is hearsay. Posting the code in the issue is fine. Git gist, pastebin, or git repo etc are all fine too. Bonus points if the formatting is correct.
6. Give us a copy of your circuit diagram or point us to what one you are using. This is library is a hardware and software combination. We need both halves to be able to help iron out any issues that you are having.
7. Feel free to tell us your skill level. e.g. "I'm an uber programmer, but this is my first time with arduino/embedded stuff, and I don't really understand this electronics stuff.", "I'm a complete newbie at software, but I've got a PhD in Electrical Engineering", or "If found this via some cool link on SlashLifeHackerNewsDotRedit, and I have no idea how magnets work!!one! Lolz". We won't judge you, but it will help us by letting us know what area we probably need to focus on, and how verbose or terse we can be when trying to help you.
8. Moar data & info == more better. Yes, I'm repeating this. It really is that important. Be verbose.
9. Issues reported in English are prefered and appreciated. We understand not everyone is fluent in English, but it is the language of default in the realm of tech. You'll probably get more help and faster if it is in English. We won't judge you or your issue by your level of English. Most of the world doesn't speak it. We understand that. Please forgive us if we don't speak your native tongue, or if we use English you don't understand. Feel free to ask for clarification. For everything else, use (or we will) Google Translate or similar.
10. Tell us what you've tried or that you've tried the above troubleshooting steps. This will allow us to make sure you've tried to fix the problem yourself and have eliminated some of the common mistakes.
11. When appropriate & possible, also include a rawData capture of the protocol/signal you're trying to send or receive. This is one of the best bits of data that helps us diagnose what's going on.
12. Can haz moar info plz? Seriously, I can't stress enough how giving us more information up front, and at each response is best. Please err on the side of being verbose. The less questions we have to ask of you, the faster your fix will be and the more eager we will be to help you.
13. Tell us what you've tried and what has or hasn't worked each time etc.
14. Issues with Pull Requests(PR) that have fixes will get more favourable treatment. ;-)

Things we are unlikely to help you with

• Your homework. Your taxes. Your plan for world domination that don't involve IR commands.
• Help you build parts of your complex project that's going to make you rich and/or Internet famous that have nothing to do with IR protocols. If they do, then we'll probably help.
• "Please write code for me to control my Air Conditioner. kthxbye.". Air Con unit protocols & remotes are notoriously complex. It can take weeks to crack how they work in some cases. You're potentially asking for weeks of free labor. Add to that it often takes having access to the AirCon unit & remote control to be able to reverse engineer the protocol. Odds are not in your favour unless you write the code yourself, decode the protocol yourself, or can point us to a project where this has already been done.
• Designing your circuits. Designing circuits is really out of scope for us, and is really up to you to solve.
• Sending or receiving IR codes via I2C. Kind of out of scope for this library, but we won't say no to PRs that implement it.
• Teaching you how to write Arduino C/C++ code.
• Fixing code in some other maintained project that includes our library, unless you're one of the maintainers of that project. You should probably report an issue with them instead of us.
• Getting this library to work on some other platform. Honestly, we'd probably love to do that, but it's kind of out of scope for us at the moment. In the future, it's a definite maybe.