Infrared4Arduino

Infrared4Arduino is an object-oriented infrared library for the Arduino.

NEWS

Version 1.2.0 constitutes a rather extensive refactoring, in particular regarding memory allocation. It now uses some of the features of "modern C++" (restricted to C++-11 for Arduino compatibility) (#16 and #17), like move semantics. For the API user, this means that the duration data used to call the constructors of IrSequence and IrSignal are to be allocated using new, and are "moved" into the constructed objects. Also, MicroGirs has been removed. (The user should use AGirs instead.)

Introduction

The library was (with some exceptions detailed below) written from scratch by myself. It uses Michael Dreher's IrWidget (article in German), see also this forum contribution.

The main inspiration for the present work was the well-known library called IRremote, published by Ken Shirriff in his blog, now hosted on GitHub. Chris Young's IRLib, (GitHub repo), should also be mentioned as a source of inspiration, but not of code. The SAMD21 support (Arduino Zero and others) is based on issues in the IRremote repository, and in particular this pull request. I am also indebted to this thread in the Arduino forum. The ATMega4809 support (Arduino WiFi Rev 2 and Arduino Nano Every) is based upon this PR. The Arduino Due support is basically taken from this project, which is licensed under the LGPL 2.1 license. The Teensy 3.x support is based upon code in IRremote. The ESP32 support is based upon this pull request.

The classes IrWidget and IrWidgetAggregating are based on Michael's code. The classes IrReceiverSampler and IrSenderPwm, are adapted from Kevin's work. The remaining files are almost completely written from scratch.

This work is a low-level library (like IRremote and IRLib) that can be used in other projects, like AGirs, which is an high-level program taking commands interactively from a user or a program through a bi-directional Stream. The goal has been to provide a sound, object oriented basis for the fundamental basis, not to provide maximal functionality, the maximal number of protocols supported, or the most complete support of different hardware. A clean design and high readability, without being "too" inefficient, has been the highest priority. Dynamic memory allocation with new and delete is used extensively. The user who is afraid of this can create his required objects at the start of the run, and keep them. Most classes are immutable. The classes are const-correct.

Comparison with other infrared libraries

Here we list a (subjective!) selection of generic IR libraries for Arduino, with some (very personal) comments.

IRremote by Ken Shirriff and others.

The original, that spawned all the rest! Now hosted here. Was "stale" for several years, presently changes daily. License: MIT.

IRlib version 1 and version 2 by Ken Shirriff and Chris Young.

Subjectively, this is a cleaned-up and modernized version of IRremote. The basic structure is very similar, and it thus suffers from many of the basic problems of IRremote. It comes with a very ambitious PDF manual (125 pages!) entirely written by hand (not using a documentation system like Doxygen). It supports most 8 bit AVRs and SAMDs, but not ESPs. The libraries are not available in the Arduino library manager, however they are available on PlatformIO. Licenses: LGPL2.1 (IRLib), GPL3 (IRLib2).

IRremoteESP8266 by David Conran, Ken Shirriff, and others.

This library, as the name suggested, was created as a fork of IRremote, supporting ESP8266 and ESP32 only. Has evolved considerably since the fork new features, in particular, it also contains support for a large number of specialized protocols, like air conditioning protocols. License: LGPL2.1.

IRLremote by Nico Hood.

This "lightweight" library is written with the aim of minimal foot print on very small systems, like the ATTiny. License: MIT-like.

Forum

Feel free to open discussions and issues at Github should the need or desire arise. Other possible place to discuss are the Home automation or the Sensor sub-forums at the Arduino forum.

Examples

A fairly large numbers of examples are provided. Most of these are a straight-forward demonstration of a particular class, as indicated by the name.

API

admin Up-to-date API, generated by Doxygen.

Types

There are some project specific data typedefs in InfraredTypes.h. For durations in microseconds, the data type microseconds_t is to be used. If desired/necessary, this can be either uint16_t or uint32_t. For durations in milliseconds, use the type millisecons_t. Likewise, use frequency_t for modulation frequency in Hz (not kHz as in the IRremote/IRLib).

For "sizes", size_t, the standard C type, is used.

Implementation dependent types like int are used if and only if it is OK for the compiler to select any implementation allowed by the C++ language.

unsigned int is used for quantities that can "impossibly" be larger than 65535. It is believed that (unsigned) int is the fastest type for doing arithmetics, containing 16 bits or more.

IrSequences and IrSignals

An IrSequence is a vector of durations, i.e. sequence of interleaving on-periods (sometimes called marks or flashes) and off-periods (sometimes called spaces or gaps). It does not contain the modulation frequence. As opposed to IRremote and IRLib, our sequences always start with a on-period and end with an off-period. It is claimed to be a more relevant representation than the one of IRremote and IRLib.

An IrSignal consists of a modulation frequency and three IrSequences: intro-, repeat-, and ending sequence. All of these, but not all, can be empty. If repeat is empty, intro has to be non-empty and ending empty. The intro sequence is always sent first, then comes a zero or more repeat sequences, and finally the ending sequence. To send a signal n > 0 times shall mean the following: If the intro is non-empty, send intro, n - 1 repeats, and then the ending. If the intro is empty, send n repeats, and then then ending.

Signal data in flash memory.

The examples oppo_cooked and oppo_raw consist of IrScrutinizer exports of the infrared command set of the Oppo Bluray players, in parametrized and raw form respectively. The latter stores the raw signals in the flash area, "PROGMEM", (i.e. not taking up any (permanent) RAM storage) for which the API support is required. This is unfortunately not available with all architectures.

Class construction

For some receiving and transmitting classes, multiple instantiations are not sensible, for others, it may be. In this library, the classes that should only be instantiated once are implemented as singleton classes, i.e. with no public constructor, but instead a static "factory" method (newThing()) that delivers a pointer to a newly constructed instance of Thing, provided that Thing has not been instantiated before. The classes, where multiple instances is sensible, come with public constructors. (However, the user still has to take responsibility for avoiding pin- and timer-conflicts.)

Hardware configuration

Board specific hardware configuration is located in the class Board, and in the board specific files in src/boards.

However, IrWidgetAggregating is currently supported on the boards Uno/Nano (ATmega328P), Leonardo/Micro (ATmega32U4), and Mega2560 (ATmega2560).

Several of the sending and receiving classes take a GPIO pin as argument to the constructor. However, the sending pin of IrSenderPwm and the capture pin of IrWidgetAggregating are not configurable, but (due to hardware limitations) have to be taken from the following table:

                                       Sender Pin      Capture Pin
Uno/Nano (ATmega328P)                       3             8
Leonardo/Micro (ATmega32U4)                 9             4
Mega2560 (ATmega2560)                       9            49
Due                                         7           n/a
Uno WiFi Rev2/Nano Every (ATmega4809)       6           n/a
Zero/M0 Pro/Nano Every IOT (ATSAMD21)       8           n/a
Teensy 3.x                                  5           n/a
ESP32                                       5           n/a

In some cases, this can be relatively easily changed in the code. A later version of the library may support more elaborate configuration.

The pin used by the the receivers (not to be confused with capture pins) can in general be selected freely, as long as it does not conflict with other requirements.