guidance : how to implement a simple low latency protocol?

[LeSuedois]

hello,
I do a update on my MARIOKARTON game/installation/performance and one of the most wanted features is a laps counter and starting lights.
I have some custom ESP32 boards laying around to control the starting lights (works fine) and I added a IR receiver.
The Karts got a ATTINY85 addon sending IR. This works fine and is so cheap...
So I was looking for a low latency IR protocol without succes and ended up sending RAW.
But I have problems identifying the raw data. Is there a guide to implement a new protocol somewhere?
My raw data looks like this:
uint16_t rawData[7] = {2500, 1500, 650, 550, 650, 1650, 450};
and is sent every 50ms.
Yes I have only 2 bit's of data since this is a maximum 4 Player Game. Sometimes I get the right Data from the ESP32, but not often.. most time IRrecvDemoV3 tells me it received 20-40 bits of information, sometimes it tells right...
Did anyone already did something like this or is my approach hopeless?

Thank you for your answer!
Simon

[crankyoldgit]

But I have problems identifying the raw data. Is there a guide to implement a new protocol somewhere?

Yes. See: https://github.com/crankyoldgit/IRremoteESP8266/wiki/Adding-support-for-a-new-IR-protocol

My raw data looks like this:
uint16_t rawData[7] = {2500, 1500, 650, 550, 650, 1650, 450};
and is sent every 50ms.

Sending it every 50ms will be a significant issue with the default configuration.
You will need to lower how long the library waits for a there to be no more incoming IR signal. That's how the library determines when a message is finished.
See:

IRremoteESP8266/src/IRrecv.h

Lines 39 to 49 in fae62c8

	// How long (ms) before we give up wait for more data?
	// Don't exceed kMaxTimeoutMs without a good reason.
	// That is the capture buffers maximum value size. (UINT16_MAX / kRawTick)
	// Typically messages/protocols tend to repeat around the 100ms timeframe,
	// thus we should timeout before that to give us some time to try to decode
	// before we need to start capturing a possible new message.
	// Typically 15ms suits most applications. However, some protocols demand a
	// higher value. e.g. 90ms for XMP-1 and some aircon units.
	const uint8_t kTimeoutMs = 15; // In MilliSeconds.
	#define TIMEOUT_MS kTimeoutMs // For legacy documentation.
	const uint16_t kMaxTimeoutMs = kRawTick * (UINT16_MAX / MS_TO_USEC(1));

&

IRremoteESP8266/examples/IRrecvDumpV2/IRrecvDumpV2.ino

Lines 54 to 88 in fae62c8

	// kTimeout is the Nr. of milli-Seconds of no-more-data before we consider a
	// message ended.
	// This parameter is an interesting trade-off. The longer the timeout, the more
	// complex a message it can capture. e.g. Some device protocols will send
	// multiple message packets in quick succession, like Air Conditioner remotes.
	// Air Coniditioner protocols often have a considerable gap (20-40+ms) between
	// packets.
	// The downside of a large timeout value is a lot of less complex protocols
	// send multiple messages when the remote's button is held down. The gap between
	// them is often also around 20+ms. This can result in the raw data be 2-3+
	// times larger than needed as it has captured 2-3+ messages in a single
	// capture. Setting a low timeout value can resolve this.
	// So, choosing the best kTimeout value for your use particular case is
	// quite nuanced. Good luck and happy hunting.
	// NOTE: Don't exceed kMaxTimeoutMs. Typically 130ms.
	#if DECODE_AC
	// Some A/C units have gaps in their protocols of ~40ms. e.g. Kelvinator
	// A value this large may swallow repeats of some protocols
	const uint8_t kTimeout = 50;
	#else // DECODE_AC
	// Suits most messages, while not swallowing many repeats.
	const uint8_t kTimeout = 15;
	#endif // DECODE_AC
	// Alternatives:
	// const uint8_t kTimeout = 90;
	// Suits messages with big gaps like XMP-1 & some aircon units, but can
	// accidentally swallow repeated messages in the rawData[] output.
	//
	// const uint8_t kTimeout = kMaxTimeoutMs;
	// This will set it to our currently allowed maximum.
	// Values this high are problematic because it is roughly the typical boundary
	// where most messages repeat.
	// e.g. It will stop decoding a message and start sending it to serial at
	// precisely the time when the next message is likely to be transmitted,
	// and may miss it.

You can specify that time in when you create the capture object. e.g.

IRremoteESP8266/examples/IRrecvDumpV2/IRrecvDumpV2.ino

Lines 120 to 121 in fae62c8

	// Use turn on the save buffer feature for more complete capture coverage.
	IRrecv irrecv(kRecvPin, kCaptureBufferSize, kTimeout, true);

also see the documentation: https://crankyoldgit.github.io/IRremoteESP8266/doxygen/html/classIRrecv.html#a8fe4d26ef1f863db1db9994fed5fc209

For a message sent every 50 ms, you're going to have a gap of 50000 - 2500 - 1500 - 2 * (650 + 1650) - 450 = 40650 uSeconds. Approx 41ms. Thus, you will need to set the timeout argument to at most 40 ms to capture individual messages.

As you want "low latency", a timeout of 4 ms should probably do what you want. i.e. it will wait for a gap of 4000us of no transmission to consider a message finished. 4000us is safe because none of your pulses are that long. Thus you'll have captured something approximately every 9350us + 4000us = 13350us. That's assuming no random IR noise etc.

To lower the processing/decoding time, I'd recommend disabling every protocol other than your own new one. That will cut down on time lost to processing and lower your latency (and code/memory usage too).

Tweaking your "protocol" a little by making the end "mark" the same as the bit mark, and the header space larger than the bit space, so I can use the automated tools. e.g.

uint16_t rawData[7] = {2500, 2000, 650, 550, 650, 1650, 650};

Using tools/auto_analyse_raw_data.py -f /tmp/MarioKarton.raw -g -n MarioKarton -r 100 will generate template boilerplate code:

// Copyright 2020 David Conran (crankyoldgit)
/// @file
/// @brief Support for MarioKarton protocol

// Supports:
//   Brand: MarioKarton,  Model: TODO add device and remote

#include "IRrecv.h"
#include "IRsend.h"
#include "IRutils.h"

// WARNING: This probably isn't directly usable. It's a guide only.

// See https://github.com/crankyoldgit/IRremoteESP8266/wiki/Adding-support-for-a-new-IR-protocol
// for details of how to include this in the library.
const uint16_t kMarioKartonHdrMark = 2500;
const uint16_t kMarioKartonBitMark = 650;
const uint16_t kMarioKartonHdrSpace = 2000;
const uint16_t kMarioKartonOneSpace = 1650;
const uint16_t kMarioKartonZeroSpace = 550;
const uint16_t kMarioKartonFreq = 38000;  // Hz. (Guessing the most common frequency.)
const uint16_t kMarioKartonBits = 2;  // Move to IRremoteESP8266.h
const uint16_t kMarioKartonOverhead = 3;

#if SEND_MARIOKARTON
// Function should be safe up to 64 bits.
/// Send a MarioKarton formatted message.
/// Status: ALPHA / Untested.
/// @param[in] data containing the IR command.
/// @param[in] nbits Nr. of bits to send. usually kMarioKartonBits
/// @param[in] repeat Nr. of times the message is to be repeated.
void IRsend::sendMarioKarton(const uint64_t data, const uint16_t nbits, const uint16_t repeat) {
  enableIROut(kMarioKartonFreq);
  for (uint16_t r = 0; r <= repeat; r++) {
    uint64_t send_data = data;
    // Header
    mark(kMarioKartonHdrMark);
    space(kMarioKartonHdrSpace);
    // Data Section #1
    // e.g. data = 0x1, nbits = 2
    sendData(kMarioKartonBitMark, kMarioKartonOneSpace, kMarioKartonBitMark, kMarioKartonZeroSpace, send_data, 2, true);
    send_data >>= 2;
    // Footer
    mark(kMarioKartonBitMark);
    space(kDefaultMessageGap);  // A 100% made up guess of the gap between messages.
  }
}
#endif  // SEND_MARIOKARTON

#if DECODE_MARIOKARTON
// Function should be safe up to 64 bits.
/// Decode the supplied MarioKarton message.
/// Status: ALPHA / Untested.
/// @param[in,out] results Ptr to the data to decode & where to store the decode
/// @param[in] offset The starting index to use when attempting to decode the
///   raw data. Typically/Defaults to kStartOffset.
/// @param[in] nbits The number of data bits to expect.
/// @param[in] strict Flag indicating if we should perform strict matching.
/// @return A boolean. True if it can decode it, false if it can't.
bool IRrecv::decodeMarioKarton(decode_results *results, uint16_t offset, const uint16_t nbits, const bool strict) {
  if (results->rawlen < 2 * nbits + kMarioKartonOverhead - offset)
    return false;  // Too short a message to match.
  if (strict && nbits != kMarioKartonBits)
    return false;

  uint64_t data = 0;
  match_result_t data_result;

  // Header
  if (!matchMark(results->rawbuf[offset++], kMarioKartonHdrMark))
    return false;
  if (!matchSpace(results->rawbuf[offset++], kMarioKartonHdrSpace))
    return false;

  // Data Section #1
  // e.g. data_result.data = 0x1, nbits = 2
  data_result = matchData(&(results->rawbuf[offset]), 2,
                          kMarioKartonBitMark, kMarioKartonOneSpace,
                          kMarioKartonBitMark, kMarioKartonZeroSpace);
  offset += data_result.used;
  if (data_result.success == false) return false;  // Fail
  data <<= 2;  // Make room for the new bits of data.
  data |= data_result.data;

  // Footer
  if (!matchMark(results->rawbuf[offset++], kMarioKartonBitMark))
    return false;

  // Success
  results->decode_type = decode_type_t::MARIOKARTON;
  results->bits = nbits;
  results->value = data;
  results->command = 0;
  results->address = 0;
  return true;
}
#endif  // DECODE_MARIOKARTON

You can obviously tweak-back the modified values in the generated code to match what your actual values are.
You will want to change space(kDefaultMessageGap); // A 100% made up guess of the gap between messages. as that's way to long.
Probably to:

const uint16_t kMarioKartonGap = 41000;  // uSeconds
...
space(kMarioKartonGap);

But you don't need sending code really, as you have that sorted.

Once you have the capture code working, you can probably trim it down to:

/// Decode the supplied MarioKarton message.
/// Status: ALPHA / Untested.
/// @param[in,out] results Ptr to the data to decode & where to store the decode
/// @param[in] offset The starting index to use when attempting to decode the
///   raw data. Typically/Defaults to kStartOffset.
/// @param[in] nbits The number of data bits to expect.
/// @param[in] strict Flag indicating if we should perform strict matching.
/// @return A boolean. True if it can decode it, false if it can't.
bool IRrecv::decodeMarioKarton(decode_results *results, uint16_t offset, const uint16_t nbits, const bool strict) {
  if (strict && nbits != kMarioKartonBits)
    return false;  // We expect MarioKarton to be a certain sized message.

  uint64_t data = 0;

  // Match Header + Data + Footer
  if (!matchGeneric(results->rawbuf + offset, &data,
                    results->rawlen - offset, nbits,
                    kMarioKartonHdrMark, kMarioKartonHdrSpace,
                    kMarioKartonBitMark, kMarioKartonOneSpace,
                    kMarioKartonMark, kMarioKartonSpace,
                    kMarioKartonBitMark, kMarioKartonGap, true)) return false;
  // Success
  results->decode_type = decode_type_t::MARIOKARTON;
  results->bits = nbits;
  results->value = data;
  results->command = 0;
  results->address = 0;
  return true;
}

Docs on matchGeneric() can be found here: https://crankyoldgit.github.io/IRremoteESP8266/doxygen/html/classIRrecv.html#ab783f52acc2ff4052313d6947563e4fd

Hope that helps you.

[LeSuedois]

Hello @crankyoldgit
Thank you very much for your answer. It looks like you almost made all the work for me!
Hope I have some time to try this today.
Give me a sign if you come to Paris, I will organize a race for you!

[LeSuedois]

Hello I added the "protocol" this night and it works like a charm!
Maybe I will make some independent CC project out of it since commercial IR laps counter are out of price.
Thank you very much!

[crankyoldgit]

Glad to be of help. If you do end up using it and producing a product, please send at PR so we can officially support it. ;-)