Diff: IRRemote/IRTransmitter.h

Revision:

77:0b96f6867312

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/IRRemote/IRTransmitter.h	Fri Mar 17 22:02:08 2017 +0000
@@ -0,0 +1,509 @@
+// IR Remote Transmitter
+//
+// This class lets you control an IR emitter LED connected to a GPIO port 
+// to transmit remote control codes using numerous standard and proprietary 
+// protocols.  You can use this to send remote codes to any device with
+// a typical IR remote, such as A/V equipment, home automation devices, etc.
+// You can also use this with the companion IR Receiver class running on
+// a separate KL25Z to send IR commands to the other device.
+//
+// We do all of our transmissions with specific protocols rather than raw
+// IR signals.  Every remote control has its own way of representing a
+// string of data bits as a series of timed IR flashes.  The exact mapping
+// between data bits and IR flashes is the protocol.  There are some quasi
+// industry standard protocols, where several companies use the same format
+// for their codes, but there are many proprietary protocols as well.  We
+// have handlers for the most widely used protocols:  NEC, Sony, Philips RC5
+// and RC6, Pioneer, Panasonic, and several others.  If your device isn't
+// covered yet, it could probably be added, since we've tried to design
+// the system to make it easy to add new protocols.
+//
+// When you transmit a code, you specify it in terms of the protocol to use 
+// and the "code" value to send.  A "code" is just the data value for a
+// particular key on a particular remote control, usually expressed as a 
+// hex number.  There are published tables of codes for many remotes, but
+// unfortunately they're not very consistent in how they represent the hex
+// code values, so you'll often see the same key represented with different
+// hex codes in different published tables.  We of course have our own way
+// of mapping the hex codes; we've tried to use the format that the original
+// manufacturer uses in their tales, if they publish them at all, but these
+// may or may not be consistent with what you find in any tables you consult.
+// So your best bet for finding the right codes to use here is usually to 
+// "learn" the codes using our companion class IRReceiver.  That class has a 
+// protocol decoder for each protocol transmitter we can use here, so if you
+// set that up and point a remote at it, it will tell you the exact code we
+// use for the key.
+//
+// The transmitter class provides a "virtual remote control" interface.
+// This gives you an imaginary remote control keypad, with a set of
+// virtual buttons programmed for individual remote control commands.
+// You specify the protocol and command code for each virtual button.
+// You can use different protocols for different buttons.
+//
+//
+// How to use the software
+//
+// First, create an instance of IRTransmitter, telling it which pin the
+// IR emitter is connected to (see below for wiring instructions) and how
+// many virtual remote control keys you want.  The pin must be PWM capable.
+//
+//    IRTransmitter *tx = new IRTransmitter(PTC9, 32);
+//
+// Next, program the virtual remote keys.  For each key, set the IR protocol
+// to use (an IRPRO_xxx code from IRProtocolID.h), the "ditto" mode (more on
+// this below), and the hex code for the command.
+//
+//    // program virtual button #0 with Sony 20-bit code 0x123, no dittos
+//    tx->programButton(0, IRPRO_SONY20, false, 0x123);
+//
+// Now you're set up to transmit.  In your main loop, decide when it's time
+// to transmit a button, such as by monitoring a physical pushbutton via a
+// GPIO DigitalIn pin.  When you want to transmit a code, just tell the
+// transmitter that your virtual button is pressed, by calling pushButton()
+// with the virtual button ID (corresponding to a virtual button ID you
+// previously programmed wtih programButton()) and a status of 'true',
+// meaning that the button is pressed.
+//
+//    tx->pushButton(0, true);  // push virtual button #0
+//
+// This starts the transmission and returns immediately.  The transmission
+// proceeds in the background (via timer interrupts), so your main loop can
+// go about its other business without waiting for the transmission to
+// finish.  Most remote codes take 50ms to 100ms to transmit, and you don't
+// usually want to stall an MCU app for that long.
+//
+// If a prior transmission is still in progress when you call pushButton(), 
+// the new transmission doesn't interrupt the previous one.  Every code is
+// sent as a complete unit to ensure data integrity, so the old one has to
+// finish before the new one starts.  Some protocols have minimum repeat
+// counts, and the transmitter takes this into account as well.  For example,
+// the Sony protocols require each command to be sent at least three times,
+// even if the button is only tapped for a brief instant.  So if you send
+// a Sony code, a new command won't start transmitting until the last command
+// has been sent completely, not just once, but at least three times.
+//
+// Once the transmitter starts sending the code for a new button, it keeps
+// sending the same code on auto-repeat until you either un-press the
+// virtual button or press a new virtual button.  Handling auto-repeat
+// in the transmitter like this has an important benefit, besides just making
+// the API simpler: it allows the transmitter to use the proper coding for
+// the repeats according to the rules of the protocol.  Some protocols use
+// a different format for the first code of a key press and auto-repeats
+// of the same key.  Some protocols also have other repetition features,
+// such as "toggle bits" or sequence counters.  The protocol handlers use
+// the appropriate handling for their protocols, so you only have to think
+// in terms of when the virtual buttons are pressed and un-pressed, without
+// worrying about whether a toggle bit or a "ditto" code or a sequence
+// counter is needed.
+//
+// When the button is no longer pressed, call pushButton() again with a
+// status of 'false':
+//
+//    tx->pushButton(0, false);
+//
+// Multiple button presses use simple PC keyboard-like semantics.  At any
+// given time, there can be only one pressed button.  When you call 
+// pushButton(N, true), N becomes the pressed button, which means that the
+// previous pressed button (if any) is forgotten.  As mentioned above, this
+// doesn't cancel the previous transmission if it's still in progress.  The
+// transmitter continues with the last code until it's finished.  When it
+// finishes with a code, the transmitter looks to see if the same button is
+// still pressed.  If so, it starts a new transmission for the same button,
+// using the appropriate repeat code.  If a new button is pressed, the
+// transmitter starts transmitting the new button's code.  If no button is
+// pressed, the transmitter stops sending and becomes idle until you press
+// another button.
+//
+// Note that button presses aren't queued.  Suppose you press button #0
+// (while no other code is being sent): this starts transmitting the code
+// for button #0 and returns.  Now suppose that a very short time later, 
+// while that first send is still in progress, you briefly press and release
+// button #1.  Button #1 will never be sent in this case.  When you press
+// button #1, the transmitter is still sending the first code, so all it
+// does at this point is mark button #1 as the currently pressed button,
+// replacing button #0.  But as explained above, this doesn't cancel the
+// button #0 code transmission in progress.  That continues until the
+// complete code has been sent.  At that point, the transmitter looks to
+// see which button is pressed, and discovers that NO button is pressed:
+// you already told it button #1 was released.  So the transmitter simply
+// stops sending and becomes idle.
+//
+//
+// How to determine command codes and the "ditto" mode
+//
+// Our command codes are expressed as 64-bit integers.  The code numbers
+// are in essence the data bits transmitted in the IR signal, but the mapping
+// between the IR data bits and the 64-bit code value is different for each
+// protocol.  We've tried to make our codes match the numbers shown in the
+// tables published by the respective manufacturers for any given remote,
+// but you might also find third-party tables that have completely different
+// mappings.  The easiest thing to do, really, is to ignore all of that and
+// just treat the codes as arbitrary, opaque identifiers, and identify the
+// codes for the remote you want to use by "learning" them.  That is, set up
+// a receiver with our companion class IRReceiver, point your remote at it,
+// and see what IRReceiver reports as the decoded value for each button. 
+// Simply use the same code value for each button when sending.
+//
+// The "ditto" flag is ignored for most protocols, but it's important for a
+// few, such as the various NEC protocols.  This tells the sender whether to
+// use the protocol's special repeat code for auto-repeats (true), or to send
+// send the same key code repeatedly (false).  The concept of dittos only
+// applies to a few protocols; most protocols just do the obvious thing and
+// send the same code repeatedly when you hold down a key.  But the NEC
+// protocols and a few others have special coding for repeated keys.  It's 
+// important to use the special coding for devices that expect it, because 
+// it lets them distinguish auto-repeat from multiple key presses, which
+// can affect how they respond to certain commands.  The tricky part is that 
+// manufacturers aren't always consistent about using dittos even when it's
+// a standard part of the protocol they're using, so you have to determine
+// whether or not to use it on a per-device basis.  The easiest way to do
+// this is just like learning codes: set up a receiever with IRReceiver and
+// see what it reports.  But this time, you're interested in what happens
+// when you hold down a key.  You'll always get one ordinary report first,
+// but check what happens for the repeats.  If IRReceiver reports the same 
+// code repeatedly, set dittos = false when sending those codes.  If the
+// repeats have the "ditto bit" set, though, set dittos = true when sending.
+//
+//
+// How to wire an IR emitter
+//
+// Any IR LED should work as the emitter.  I used a Vishay TSAL6400 for my
+// reference/testing implementation.  The TSAL6400 is quite bright, so it
+// should send signals well across fairly large distances.
+//
+// WARNING!  DON'T connect the LED directly to the GPIO pin.  KL25Z GPIO
+// pins have very low current limits - a typical IR emitter LED draws
+// enough current to damage or destroy the KL25Z.  You'll need to build a
+// simple transistor circuit to interface with the LED.  You'll need a
+// common small signal NPN transistor (such as a 2222 or 2N4401), a 2.2K
+// resistor, the IR LED, of course, and a current-limiting resistor for
+// the LED.  Choose the current-limiting resistor by plugging your LED's
+// specs into an LED resistor calculator, using a 5V supply voltage.  Now
+// connect the GPIO pin to the current-limiting resistor, connect the
+// resistor to the LED anode (+), connect the LED cathode (-) to the NPN
+// collector, connect the NPN emitter to ground, connect the NPN base to
+// the 2.2K resistor, and connect the 2.2K resistor to the GPIO pin.
+// It's simple enough for a schematic rendered in ASCII art:
+//
+//       +5V   (from the KL25Z +5V pin, or directly from
+//        |     the KL25Z's power supply)
+//        <
+//        >  R1 - use an LED resistor calculator to choose
+//        <       the resistor size based on your selected 
+//        |       LED's forward current & voltage and 5V source
+//       ---  +
+//       \ /  LED - Infrared emitter (e.g., Vishay TSAL6400)
+//       ---  -
+//        |
+//        |
+//         \|     2.2K
+//          |-----/\/\/\---> to this GPIO pin
+//         /|
+//        v
+//        |
+//      -----
+//       ---   Ground (KL25Z GND pin, or ground on the
+//        -            KL25Z's power supply)
+//
+// If you want to be able to see the transmitter in action, you can connect
+// another LED (a blue one, say) and its own current-limiting resistor in
+// parallel with the R1 + IR LED circuit.  Let's call the blue LED's
+// resistor R2.  Connect R2 to +5V, connect the other end of R2 to the
+// blue LED (+), and connect the blue LED (-) to the NPN collector.  This
+// will make the blue LED flash in sync with the IR LED.  IR remote control
+// codes are slow enough that you'll be able to see the blue LED come on
+// and flicker during each transmission, although the "bits" are too fast
+// to see individually with the naked eye.  The detector shouldn't be 
+// bothered by the extra light since these sensors have optical filters 
+// that block most of the incoming light outside of the IR band the sensor 
+// is looking for.
+
+#ifndef _IRTRANSMITTER_H_
+#define _IRTRANSMITTER_H_
+
+#include <mbed.h>
+
+#include "NewPwm.h"
+#include "IRRemote.h"
+#include "IRCommand.h"
+#include "IRProtocols.h"
+
+
+// IR Remote Transmitter
+class IRTransmitter
+{
+public:
+    // Construct.  
+    //
+    // 'pin' is the GPIO pin controlling the IR LED.  The pin must be 
+    // PWM-capable.  (Note also that each PWM channel on the KL25Z is 
+    // shared among multiple pins, so be sure you're using a pin connected 
+    // to a channel that isn't already used elsewhere in your application.)
+    // Don't connect the LED directly to this pin; see the circuit diagram
+    // at the top of the file for details of how to connect it through a
+    // transistor to safely boost the current to LED levels.
+    //
+    // 'nButtons' is the number of virtual button slots to allocate.  Each
+    // slot represents a virtual remote control button that can be programmed
+    // with a remote code to transmit.  Allocate as many slots as you need
+    // for unique commands or buttons.  Note that the caller is responsible
+    // for deciding when a button is pressed; if you want to tie these to
+    // physical buttons, you'll need to create your own DigitalIn objects
+    // for the pins, monitor them, and call pushButton() to press and
+    // release virtual buttons when the physical button states change.
+    IRTransmitter(PinName pin, int nButtons) : ledPin(pin)
+    {
+        // make sure the protocol singletons are allocated
+        IRProtocol::allocProtocols();
+        
+        // no command is active
+        curBtnId = -1;
+        
+        // allocate the command list
+        buttons = new ButtonCmd[nButtons];
+        
+        // the transmitter "thread" isn't yet running
+        txRunning = false;
+        txBtnId = -1;
+        txProtocol = 0;
+    }
+    
+    ~IRTransmitter()
+    {
+        delete[] buttons;
+    }
+    
+    // Program the command code for a virtual button
+    void programButton(int buttonId, int protocolId, bool dittos, uint64_t cmdCode)
+    {
+        ButtonCmd &btn = buttons[buttonId];
+        btn.pro = protocolId;
+        btn.dittos = dittos;
+        btn.cmd = cmdCode;
+    }
+    
+    // Push a virtual button.
+    // 
+    // When this is called, we'll start transmitting the command code
+    // associated with the button immediately if no other transmission
+    // is already in progress.  On the other hand, if a transmission of
+    // a prior command code is already in progress, the previous command
+    // isn't interrupted; we always send whole commands, and never
+    // interrupt a command in progress.  Instead, the new button is
+    // set as pending.  As soon as the prior transmission finishes,
+    // the pending button becomes the current button and we start
+    // transmitting its code - but only if the button is still pressed
+    // when the previous code finishes.  This means that if you both 
+    // press and release a button during the time that another 
+    // transmission is in progress, the new button will never be 
+    // transmitted.  We operate this way to keep things simple and
+    // consistent when it comes to more than just one pending button.
+    // This way we don't have to consider queues of pending buttons
+    // or create mechanisms for canceling pending commands.
+    //
+    // If the button is still down when its first transmission ends,
+    // and no other button has been pressed in the meantime, the button
+    // will auto-repeat.  This continues as long as the button is still
+    // pressed and no other button has been pressed.
+    // 
+    // Only one code can be transmitted at a time, obviously.  The
+    // semantics for multiple simultaneous button presses are like those
+    // of a PC keyboard.  Suppose you press button A, then a while later,
+    // while A is still down, you press B.  Then a while later still,
+    // you press C, continuing to hold both A and B down.  We transmit
+    // A repeatedly until you press B, at which point we finish sending
+    // the current repeat of A (we never interrupt a code in the middle:
+    // once started, a code is always finished whole) and start sending
+    // B.  B continues to repeat until you press C, at which point we
+    // finish the last repetition of B and start sending C.  Once A or
+    // B have been superseded, it makes no difference whether you continue
+    // to hold them down or release them.  They'll never start repeating
+    // again, even if you then release C while A and B are still down.
+    void pushButton(int id, bool on)
+    {
+        if (on)
+        {
+            // make this the current command
+            curBtnId = id;
+
+            // start the transmitter
+            txStart();
+        }
+        else
+        {
+            // if this is the current command, cancel it
+            if (id == curBtnId)
+                curBtnId = -1;
+        }
+    }
+    
+    // Is a transmission in progress?
+    bool isSending() const { return txRunning; }
+    
+
+protected:
+    // Start the transmitter "thread", if it's not already running.  The
+    // thread is actually just a series of timer interrupts; each interrupt
+    // sets the next interrupt at an appropriate interval, so the effect is
+    // like a thread.
+    void txStart()
+    {
+        if (!txRunning)
+        {
+            // The thread isn't running.  Note that this means that there's
+            // no possibility that txRunning will change out from under us
+            // asynchronously, since there's no pending interrupt handler
+            // to change it.  Mark the thread as running.
+            txRunning = true;
+            
+            // Directly invoke the thread handler for the first call.  It
+            // will normally run in interrupt context, but since there's
+            // no pending interrupt yet that would re-enter it, we can
+            // launch it first in application context.  If there's work
+            // pending, it'll kick off the transmission and schedule the
+            // next timer interrupt to continue the thread.
+            txThread();
+        }
+    }
+    
+    // Transmitter "thread" main.  This handles the timer interrupt for each
+    // event in a transmission.
+    void txThread()
+    {
+        // if we're working on a command, process the next step
+        if (txProtocol != 0)
+        {
+            // Determine if the virtual button for the current transmission
+            // is still pressed.  It's still pressed if we have a valid 
+            // transmitting button ID, and the current pressed button is the 
+            // same as the transmitting button.
+            txState.pressed = (txBtnId != -1 && txBtnId == curBtnId);
+
+            // Perform the next step via the protocol handler.  The handler
+            // returns a positive time value for the next timeout if it still
+            // has more work to do.
+            int t = txProtocol->txStep(&txState);
+            
+            // check if the transmission is done
+            if (t > 0)
+            {
+                // The handler returned a positive time value, so it has
+                // more work to do.  That means we're done here - just set
+                // the next timeout and exit the interrupt handler.
+                txTimeout.attach_us(this, &IRTransmitter::txThread, t);
+                return;
+            }
+            else
+            {
+                // The transmission is done.  Clear the send data.
+                txBtnId = -1;
+                txProtocol = 0;
+            }
+        }
+        
+        // If we made it here, the transmitter is now idle.  Check to
+        // see if we have a new virtual button press.
+        if (curBtnId != -1)
+        {
+            // load the command
+            txBtnId = curBtnId;
+            txCmd = buttons[curBtnId];
+            txProtocol = IRProtocol::senderForId(txCmd.pro);
+            
+            // If we found a protocol handler, start the transmission
+            if (txProtocol != 0)
+            {
+                // fill in the transmission state object with the new command
+                // details
+                txState.cmdCode = txCmd.cmd;
+                txState.protocolId = txCmd.pro;
+                txState.dittos = txCmd.dittos;
+                txState.pin = &ledPin;
+                txState.pressed = true;
+                
+                // reset the transmission step counters
+                txState.step = 0;
+                txState.bit = 0;
+                txState.bitstep = 0;
+                txState.rep = 0;
+                
+                // this is a new transmission, so toggle the toggle bit
+                txState.toggle ^= 1;
+                
+                // Turn off the IR and set the PWM frequency of the IR LED to
+                // the carrier frequency for the chosen protocol
+                ledPin.write(0);
+                ledPin.getUnit()->period(txProtocol->pwmPeriod(&txState));
+
+                // start the transmission timer
+                txState.txTime.reset();
+                txState.txTime.start();
+                
+                // initiate the transmission
+                int t = txProtocol->txStart(&txState);
+                
+                // set the timer for the next step of the transmission, then
+                // we're done
+                txTimeout.attach_us(this, &IRTransmitter::txThread, t);
+                return;
+            }
+        }
+        
+        // If we made it here, there's no transmission in progress,
+        // so the thread is no longer running.
+        txRunning = false;
+    }
+
+    // LED output pin controlling the IR LED.  The pin must be PWM-capable.
+    // WARNING!  Don't connect the IR LED directly to the pin.  See wiring
+    // diagram at the top of the file.
+    NewPwmOut ledPin;
+    
+    // Virtual button slots.  Each slot represents a virtual remote control
+    // button, containing a preprogrammed IR command code to send when the 
+    // button is pressed.  Program a button by calling programButton().
+    // Press a button by calling pushButton().
+    struct ButtonCmd
+    {
+        uint64_t cmd;           // command code
+        uint8_t pro;            // protocol ID (IRPRO_xxx)
+        uint8_t dittos : 1;     // use "ditto" codes for auto-repeat
+    } __attribute__ ((packed));
+    ButtonCmd *buttons;
+    
+    // Current active virtual button ID.   This is managed in application
+    // context and read in interrupt context.  This represents the currently 
+    // pushed button.
+    int curBtnId;
+    
+    // Is the transmitter "thread" running?  This is true when a timer is
+    // pending, false if not.  The timer interrupt handler clears this
+    // before exiting on its last run of a transmission.
+    //
+    // Synchronization: if txRunning is false, no timer interrupt is either
+    // running or pending, so there's no possibility that anyone else will
+    // change it, so it's safe for the application to test and set it.  If
+    // txRunning is true, only interrupt context can change it, so application
+    // context can only read it.
+    volatile bool txRunning;
+    
+    // Transmitter thread timeout
+    Timeout txTimeout;
+    
+    // Command ID being transmitted in the background "thread".  The thread
+    // loads this from curBtnID whenever it's out of other work to do.
+    int txBtnId;
+    
+    // Protocol for the current transmission
+    IRProtocol *txProtocol;
+    
+    // Command value we're currently transmitting
+    ButtonCmd txCmd;
+    
+    // Protocol state.  This is for use by the individual protocol
+    // classes to keep track of their state while the transmission
+    // proceeds.
+    IRTXState txState;
+};
+
+#endif