IRremoteESP8266: irutils Namespace Reference

IRremoteESP8266

Functions
irutils Namespace Reference

Namespace for covering common functions & procedures for advancd protocol handlers. More...

## Functions

String | addLabeledString (const String value, const String label, const bool precomma)
| Create a String with a colon separated "label: value" pair suitable for Humans. More...
String | addBoolToString (const bool value, const String label, const bool precomma)
| Create a String with a colon separated flag suitable for Humans. e.g. "Power: On". More...
String | addIntToString (const uint16_t value, const String label, const bool precomma)
| Create a String with a colon separated labeled Integer suitable for Humans. e.g. "Foo: 23". More...
String | modelToStr (const decode_type_t protocol, const int16_t model)
| Generate the model string for a given Protocol/Model pair. More...
String | addModelToString (const decode_type_t protocol, const int16_t model, const bool precomma)
| Create a String of human output for a given protocol model number. e.g. "Model: JKE". More...
String | addTempToString (const uint16_t degrees, const bool celsius, const bool precomma)
| Create a String of human output for a given temperature. e.g. "Temp: 25C". More...
String | addTempFloatToString (const float degrees, const bool celsius, const bool precomma)
| Create a String of human output for a given temperature. e.g. "Temp: 25.5C". More...
String | addModeToString (const uint8_t mode, const uint8_t automatic, const uint8_t cool, const uint8_t heat, const uint8_t dry, const uint8_t fan)
| Create a String of human output for the given operating mode. e.g. "Mode: 1 (Cool)". More...
String | addDayToString (const uint8_t day_of_week, const int8_t offset, const bool precomma)
| Create a String of the 3-letter day of the week from a numerical day of the week. e.g. "Day: 1 (Mon)". More...
String | addFanToString (const uint8_t speed, const uint8_t high, const uint8_t low, const uint8_t automatic, const uint8_t quiet, const uint8_t medium, const uint8_t maximum)
| Create a String of human output for the given fan speed. e.g. "Fan: 0 (Auto)". More...
String | addSwingHToString (const uint8_t position, const uint8_t automatic, const uint8_t maxleft, const uint8_t left, const uint8_t middle, const uint8_t right, const uint8_t maxright, const uint8_t off, const uint8_t leftright, const uint8_t rightleft, const uint8_t threed, const uint8_t wide)
| Create a String of human output for the given horizontal swing setting. e.g. "Swing(H): 0 (Auto)". More...
String | addSwingVToString (const uint8_t position, const uint8_t automatic, const uint8_t highest, const uint8_t high, const uint8_t uppermiddle, const uint8_t middle, const uint8_t lowermiddle, const uint8_t low, const uint8_t lowest, const uint8_t off, const uint8_t swing, const uint8_t breeze, const uint8_t circulate)
| Create a String of human output for the given vertical swing setting. e.g. "Swing(V): 0 (Auto)". More...
String | htmlEscape (const String unescaped)
| Escape any special HTML (unsafe) characters in a string. e.g. anti-XSS. More...
String | msToString (uint32_t const msecs)
| Convert a nr. of milliSeconds into a Human-readable string. e.g. "1 Day 6 Hours 34 Minutes 17 Seconds". More...
String | minsToString (const uint16_t mins)
| Convert a nr. of minutes into a 24h clock format Human-readable string. e.g. "23:59". More...
uint8_t | sumNibbles (const uint8_t *const start, const uint16_t length, const uint8_t init)
| Sum all the nibbles together in a series of bytes. More...
uint8_t | sumNibbles (const uint64_t data, const uint8_t count, const uint8_t init, const bool nibbleonly)
| Sum all the nibbles together in an integer. More...
uint8_t | bcdToUint8 (const uint8_t bcd)
| Convert a byte of Binary Coded Decimal(BCD) into an Integer. More...
uint8_t | uint8ToBcd (const uint8_t integer)
| Convert an Integer into a byte of Binary Coded Decimal(BCD). More...
bool | getBit (const uint64_t data, const uint8_t position, const uint8_t size)
| Return the value of `position`th bit of an Integer. More...
bool | getBit (const uint8_t data, const uint8_t position)
| Return the value of `position`th bit of an Integer. More...
uint64_t | setBit (const uint64_t data, const uint8_t position, const bool on, const uint8_t size)
| Return the value of an Integer with the `position`th bit changed. More...
uint8_t | setBit (const uint8_t data, const uint8_t position, const bool on)
| Return the value of an Integer with the `position`th bit changed. More...
void | setBit (uint8_t *const data, const uint8_t position, const bool on)
| Alter the value of an Integer with the `position`th bit changed. More...
void | setBit (uint32_t *const data, const uint8_t position, const bool on)
| Alter the value of an Integer with the `position`th bit changed. More...
void | setBit (uint64_t *const data, const uint8_t position, const bool on)
| Alter the value of an Integer with the `position`th bit changed. More...
void | setBits (uint8_t *const dst, const uint8_t offset, const uint8_t nbits, const uint8_t data)
| Alter an uint8_t value by overwriting an arbitrary given number of bits. More...
void | setBits (uint32_t *const dst, const uint8_t offset, const uint8_t nbits, const uint32_t data)
| Alter an uint32_t value by overwriting an arbitrary given number of bits. More...
void | setBits (uint64_t *const dst, const uint8_t offset, const uint8_t nbits, const uint64_t data)
| Alter an uint64_t value by overwriting an arbitrary given number of bits. More...
uint8_t * | invertBytePairs (uint8_t *ptr, const uint16_t length)
| Create byte pairs where the second byte of the pair is a bit inverted/flipped copy of the first/previous byte of the pair. More...
bool | checkInvertedBytePairs (const uint8_t *const ptr, const uint16_t length)
| Check an array to see if every second byte of a pair is a bit inverted/flipped copy of the first/previous byte of the pair. More...
uint8_t | lowLevelSanityCheck (void)
| Perform a low level bit manipulation sanity check for the given cpu architecture and the compiler operation. Calls to this should return 0 if everything is as expected, anything else means the library won't work as expected. More...

## Detailed Description

Namespace for covering common functions & procedures for advancd protocol handlers.

## Function Documentation

## ◆ addBoolToString()

String irutils::addBoolToString | ( | const bool | value,
|  | const String | label,
|  | const bool | precomma
| ) |  |

Create a String with a colon separated flag suitable for Humans. e.g. "Power: On".

Parameters

  [in] | value | The value to come after the label.
  [in] | label | The label to precede the value.
  [in] | precomma | Should the output string start with ", " or not?

Returns
  The resulting String.

## ◆ addDayToString()

String irutils::addDayToString | ( | const uint8_t | day_of_week,
|  | const int8_t | offset,
|  | const bool | precomma
| ) |  |

Create a String of the 3-letter day of the week from a numerical day of the week. e.g. "Day: 1 (Mon)".

Parameters

  [in] | day_of_week | A numerical version of the sequential day of the week. e.g. Saturday = 7 etc.
  [in] | offset | Days to offset by. e.g. For different day starting the week.
  [in] | precomma | Should the output string start with ", " or not?

Returns
  The resulting String.

## ◆ addFanToString()

String irutils::addFanToString | ( | const uint8_t | speed,
|  | const uint8_t | high,
|  | const uint8_t | low,
|  | const uint8_t | automatic,
|  | const uint8_t | quiet,
|  | const uint8_t | medium,
|  | const uint8_t | maximum
| ) |  |

Create a String of human output for the given fan speed. e.g. "Fan: 0 (Auto)".

Parameters

  [in] | speed | The numeric speed of the fan to display.
  [in] | high | The numeric value for High speed.
  [in] | low | The numeric value for Low speed.
  [in] | automatic | The numeric value for Auto speed.
  [in] | quiet | The numeric value for Quiet speed.
  [in] | medium | The numeric value for Medium speed.
  [in] | maximum | The numeric value for Highest speed. (if > high)

Returns
  The resulting String.

## ◆ addIntToString()

String irutils::addIntToString | ( | const uint16_t | value,
|  | const String | label,
|  | const bool | precomma
| ) |  |

Create a String with a colon separated labeled Integer suitable for Humans. e.g. "Foo: 23".

Parameters

  [in] | value | The value to come after the label.
  [in] | label | The label to precede the value.
  [in] | precomma | Should the output string start with ", " or not?

Returns
  The resulting String.

## ◆ addLabeledString()

String irutils::addLabeledString | ( | const String | value,
|  | const String | label,
|  | const bool | precomma
| ) |  |

Create a String with a colon separated "label: value" pair suitable for Humans.

Parameters

  [in] | value | The value to come after the label.
  [in] | label | The label to precede the value.
  [in] | precomma | Should the output string start with ", " or not?

Returns
  The resulting String.

## ◆ addModelToString()

String irutils::addModelToString | ( | const decode_type_t | protocol,
|  | const int16_t | model,
|  | const bool | precomma
| ) |  |

Create a String of human output for a given protocol model number. e.g. "Model: JKE".

Parameters

  [in] | protocol | The IR protocol.
  [in] | model | The model number for that protocol.
  [in] | precomma | Should the output string start with ", " or not?

Returns
  The resulting String.

## ◆ addModeToString()

String irutils::addModeToString | ( | const uint8_t | mode,
|  | const uint8_t | automatic,
|  | const uint8_t | cool,
|  | const uint8_t | heat,
|  | const uint8_t | dry,
|  | const uint8_t | fan
| ) |  |

Create a String of human output for the given operating mode. e.g. "Mode: 1 (Cool)".

Parameters

  [in] | mode | The operating mode to display.
  [in] | automatic | The numeric value for Auto mode.
  [in] | cool | The numeric value for Cool mode.
  [in] | heat | The numeric value for Heat mode.
  [in] | dry | The numeric value for Dry mode.
  [in] | fan | The numeric value for Fan mode.

Returns
  The resulting String.

## ◆ addSwingHToString()

String irutils::addSwingHToString | ( | const uint8_t | position,
|  | const uint8_t | automatic,
|  | const uint8_t | maxleft,
|  | const uint8_t | left,
|  | const uint8_t | middle,
|  | const uint8_t | right,
|  | const uint8_t | maxright,
|  | const uint8_t | off,
|  | const uint8_t | leftright,
|  | const uint8_t | rightleft,
|  | const uint8_t | threed,
|  | const uint8_t | wide
| ) |  |

Create a String of human output for the given horizontal swing setting. e.g. "Swing(H): 0 (Auto)".

Parameters

  [in] | position | The numeric position of the swing to display.
  [in] | automatic | The numeric value for Auto position.
  [in] | maxleft | The numeric value for most left position.
  [in] | left | The numeric value for Left position.
  [in] | middle | The numeric value for Middle position.
  [in] | right | The numeric value for Right position.
  [in] | maxright | The numeric value for most right position.
  [in] | off | The numeric value for Off position.
  [in] | leftright | The numeric value for "left right" position.
  [in] | rightleft | The numeric value for "right left" position.
  [in] | threed | The numeric value for 3D setting.
  [in] | wide | The numeric value for Wide position.

Returns
  The resulting String.

## ◆ addSwingVToString()

String irutils::addSwingVToString | ( | const uint8_t | position,
|  | const uint8_t | automatic,
|  | const uint8_t | highest,
|  | const uint8_t | high,
|  | const uint8_t | uppermiddle,
|  | const uint8_t | middle,
|  | const uint8_t | lowermiddle,
|  | const uint8_t | low,
|  | const uint8_t | lowest,
|  | const uint8_t | off,
|  | const uint8_t | swing,
|  | const uint8_t | breeze,
|  | const uint8_t | circulate
| ) |  |

Create a String of human output for the given vertical swing setting. e.g. "Swing(V): 0 (Auto)".

Parameters

  [in] | position | The numeric position of the swing to display.
  [in] | automatic | The numeric value for Auto position.
  [in] | highest | The numeric value for Highest position.
  [in] | high | The numeric value for High position.
  [in] | uppermiddle | The numeric value for Upper Middle position.
  [in] | middle | The numeric value for Middle position.
  [in] | lowermiddle | The numeric value for Lower Middle position.
  [in] | low | The numeric value for Low position.
  [in] | lowest | The numeric value for Low position.
  [in] | off | The numeric value for Off position.
  [in] | swing | The numeric value for Swing setting.
  [in] | breeze | The numeric value for Breeze setting.
  [in] | circulate | The numeric value for Circulate setting.

Returns
  The resulting String.

## ◆ addTempFloatToString()

String irutils::addTempFloatToString | ( | const float | degrees,
|  | const bool | celsius,
|  | const bool | precomma
| ) |  |

Create a String of human output for a given temperature. e.g. "Temp: 25.5C".

Parameters

  [in] | degrees | The temperature in degrees.
  [in] | celsius | Is the temp Celsius or Fahrenheit. true is C, false is F
  [in] | precomma | Should the output string start with ", " or not?

Returns
  The resulting String.

## ◆ addTempToString()

String irutils::addTempToString | ( | const uint16_t | degrees,
|  | const bool | celsius,
|  | const bool | precomma
| ) |  |

Create a String of human output for a given temperature. e.g. "Temp: 25C".

Parameters

  [in] | degrees | The temperature in degrees.
  [in] | celsius | Is the temp Celsius or Fahrenheit. true is C, false is F
  [in] | precomma | Should the output string start with ", " or not?

Returns
  The resulting String.

## ◆ bcdToUint8()

uint8_t irutils::bcdToUint8 | ( | const uint8_t | bcd | ) |

Convert a byte of Binary Coded Decimal(BCD) into an Integer.

Parameters

  [in] | bcd | The BCD value.

Returns
  A normal Integer value.

## ◆ checkInvertedBytePairs()

bool irutils::checkInvertedBytePairs | ( | const uint8_t *const | ptr,
|  | const uint16_t | length
| ) |  |

Check an array to see if every second byte of a pair is a bit inverted/flipped copy of the first/previous byte of the pair.

Parameters

  [in] | ptr | A pointer to the start of array to check.
  [in] | length | The byte size of the array.

Note
  A length of `<= 1` will always return true.

Returns
  true, if every second byte is inverted. Otherwise false.

## ◆ getBit() [1/2]

bool irutils::getBit | ( | const uint64_t | data,
|  | const uint8_t | position,
|  | const uint8_t | size
| ) |  |

Return the value of `position`th bit of an Integer.

Parameters

  [in] | data | Value to be examined.
  [in] | position | Nr. of the Nth bit to be examined. `0` is the LSB.
  [in] | size | Nr. of bits in data.

Returns
  The bit's value.

## ◆ getBit() [2/2]

bool irutils::getBit | ( | const uint8_t | data,
|  | const uint8_t | position
| ) |  |

Return the value of `position`th bit of an Integer.

Parameters

  [in] | data | Value to be examined.
  [in] | position | Nr. of the Nth bit to be examined. `0` is the LSB.

Returns
  The bit's value.

## ◆ htmlEscape()

String irutils::htmlEscape | ( | const String | unescaped | ) |

Escape any special HTML (unsafe) characters in a string. e.g. anti-XSS.

Parameters

  [in] | unescaped | A String containing text to make HTML safe.

Returns
  A string that is HTML safe.

## ◆ invertBytePairs()

uint8_t * irutils::invertBytePairs | ( | uint8_t * | ptr,
|  | const uint16_t | length
| ) |  |

Create byte pairs where the second byte of the pair is a bit inverted/flipped copy of the first/previous byte of the pair.

Parameters

  [in,out] | ptr | A pointer to the start of array to modify.
  [in] | length | The byte size of the array.

Note
  A length of `<= 1` will do nothing.

Returns
  A ptr to the modified array.

## ◆ lowLevelSanityCheck()

uint8_t irutils::lowLevelSanityCheck | ( | void |  | ) |

Perform a low level bit manipulation sanity check for the given cpu architecture and the compiler operation. Calls to this should return 0 if everything is as expected, anything else means the library won't work as expected.

Returns
  A bit mask value of potential issues. 0: (e.g. 0b00000000) Everything appears okay. 0th bit set: (0b1) Unexpected bit field/packing encountered. Try a different compiler. 1st bit set: (0b10) Unexpected Endianness. Try a different compiler flag or use a CPU different architecture. e.g. A result of 3 (0b11) would mean both a bit field and an Endianness issue has been found.

## ◆ minsToString()

String irutils::minsToString | ( | const uint16_t | mins | ) |

Convert a nr. of minutes into a 24h clock format Human-readable string. e.g. "23:59".

Parameters

  [in] | mins | Nr. of Minutes.

Returns
  A human readable string.

## ◆ modelToStr()

String irutils::modelToStr | ( | const decode_type_t | protocol,
|  | const int16_t | model
| ) |  |

Generate the model string for a given Protocol/Model pair.

Parameters

  [in] | protocol | The IR protocol.
  [in] | model | The model number for that protocol.

Returns
  The resulting String.

## ◆ msToString()

String irutils::msToString | ( | uint32_t const | msecs | ) |

Convert a nr. of milliSeconds into a Human-readable string. e.g. "1 Day 6 Hours 34 Minutes 17 Seconds".

Parameters

  [in] | msecs | Nr. of milliSeconds (ms).

Returns
  A human readable string.

## ◆ setBit() [1/5]

uint64_t irutils::setBit | ( | const uint64_t | data,
|  | const uint8_t | position,
|  | const bool | on,
|  | const uint8_t | size
| ) |  |

Return the value of an Integer with the `position`th bit changed.

Parameters

  [in] | data | Value to be changed.
  [in] | position | Nr. of the bit to be changed. `0` is the LSB.
  [in] | on | Value to set the position'th bit to.
  [in] | size | Nr. of bits in data.

Returns
  A suitably modified integer.

## ◆ setBit() [2/5]

uint8_t irutils::setBit | ( | const uint8_t | data,
|  | const uint8_t | position,
|  | const bool | on
| ) |  |

Return the value of an Integer with the `position`th bit changed.

Parameters

  [in] | data | Value to be changed.
  [in] | position | Nr. of the bit to be changed. `0` is the LSB.
  [in] | on | Value to set the position'th bit to.

Returns
  A suitably modified integer.

## ◆ setBit() [3/5]

void irutils::setBit | ( | uint32_t *const | data,
|  | const uint8_t | position,
|  | const bool | on
| ) |  |

Alter the value of an Integer with the `position`th bit changed.

Parameters

  [in,out] | data | A pointer to the 32-bit integer to be changed.
  [in] | position | Nr. of the bit to be changed. `0` is the LSB.
  [in] | on | Value to set the position'th bit to.

## ◆ setBit() [4/5]

void irutils::setBit | ( | uint64_t *const | data,
|  | const uint8_t | position,
|  | const bool | on
| ) |  |

Alter the value of an Integer with the `position`th bit changed.

Parameters

  [in,out] | data | A pointer to the 64-bit integer to be changed.
  [in] | position | Nr. of the bit to be changed. `0` is the LSB.
  [in] | on | Value to set the position'th bit to.

## ◆ setBit() [5/5]

void irutils::setBit | ( | uint8_t *const | data,
|  | const uint8_t | position,
|  | const bool | on
| ) |  |

Alter the value of an Integer with the `position`th bit changed.

Parameters

  [in,out] | data | A pointer to the 8-bit integer to be changed.
  [in] | position | Nr. of the bit to be changed. `0` is the LSB.
  [in] | on | Value to set the position'th bit to.

## ◆ setBits() [1/3]

void irutils::setBits | ( | uint32_t *const | dst,
|  | const uint8_t | offset,
|  | const uint8_t | nbits,
|  | const uint32_t | data
| ) |  |

Alter an uint32_t value by overwriting an arbitrary given number of bits.

Parameters

  [in,out] | dst | A pointer to the value to be changed.
  [in] | offset | Nr. of bits from the Least Significant Bit to be ignored
  [in] | nbits | Nr of bits of data to be placed into the destination.
  [in] | data | The value to be placed.

## ◆ setBits() [2/3]

void irutils::setBits | ( | uint64_t *const | dst,
|  | const uint8_t | offset,
|  | const uint8_t | nbits,
|  | const uint64_t | data
| ) |  |

Alter an uint64_t value by overwriting an arbitrary given number of bits.

Parameters

  [in,out] | dst | A pointer to the value to be changed.
  [in] | offset | Nr. of bits from the Least Significant Bit to be ignored
  [in] | nbits | Nr of bits of data to be placed into the destination.
  [in] | data | The value to be placed.

## ◆ setBits() [3/3]

void irutils::setBits | ( | uint8_t *const | dst,
|  | const uint8_t | offset,
|  | const uint8_t | nbits,
|  | const uint8_t | data
| ) |  |

Alter an uint8_t value by overwriting an arbitrary given number of bits.

Parameters

  [in,out] | dst | A pointer to the value to be changed.
  [in] | offset | Nr. of bits from the Least Significant Bit to be ignored
  [in] | nbits | Nr of bits of data to be placed into the destination.
  [in] | data | The value to be placed.

## ◆ sumNibbles() [1/2]

uint8_t irutils::sumNibbles | ( | const uint64_t | data,
|  | const uint8_t | count,
|  | const uint8_t | init,
|  | const bool | nibbleonly
| ) |  |

Sum all the nibbles together in an integer.

Parameters

  [in] | data | The integer to be summed.
  [in] | count | The number of nibbles to sum. Starts from LSB. Max of 16.
  [in] | init | Starting value of the calculation to use. (Default is 0)
  [in] | nibbleonly | true, the result is 4 bits. false, it's 8 bits.

Returns
  The 4/8-bit calculated result of all the nibbles and init value.

## ◆ sumNibbles() [2/2]

uint8_t irutils::sumNibbles | ( | const uint8_t *const | start,
|  | const uint16_t | length,
|  | const uint8_t | init
| ) |  |

Sum all the nibbles together in a series of bytes.

Parameters

  [in] | start | A ptr to the start of the byte array to calculate over.
  [in] | length | How many bytes to use in the calculation.
  [in] | init | Starting value of the calculation to use. (Default is 0)

Returns
  The 8-bit calculated result of all the bytes and init value.

## ◆ uint8ToBcd()

uint8_t irutils::uint8ToBcd | ( | const uint8_t | integer | ) |

Convert an Integer into a byte of Binary Coded Decimal(BCD).

Parameters

  [in] | integer | The number to convert.

Returns
  An 8-bit BCD value.