Arduino on Schallbert's Blog

🎄 Breadboard Fireplace

Schallbert — Mon, 01 Jan 0001

Project stats

Difficulty: beginner 1/5
Cost: 8…25€
Time: ~1h

Abstract

This is a quick and easy project that demonstrates how to use an embedded device and some LEDs to create a warm and comfortable living room environment. Tied to a powerbank, this little thing will glow all evening and create a warm and comfy atmosphere. I borrowed parts of the idea for this project from a book called “Tiny AVR for the evil Genius” which I read when I started with embedded software design in C years ago.

Project cost varies on the components you choose. If you take an original Arduino, it will be on the upper end - but in this case you pay tribute to the hard-working developers and engineers at Arduino, creating open source solutions for all of us 🥳

The Hardware

Of course, you can use any microcontroller board that supports at least 8 digital outputs and 1 analog input. In my example I’m using an Arduino Nano replica board I had flying around somewhere. Time to upgrade to the “original”… You should have a small breadboard, a couple of wires and eight LEDs at the ready. I recommend using 5 warm-white LEDs, 2 yellow LEDs, and 1 red LED with similar brightness (lumen count) to yield colors that are similar to a real fire.

The Software

The software creates a flickering lights effect with varying update speed.

Setup

On startup, in setup() I define pins the LEDs are connected to as outputs. I make it read an open analog pin once and takes its (undefined) value as seed for the pseudo random number generator discussed later.

Loop

In the infinite loop, the program calculates a new random number and then hands this number over to the downstream functions. Here, a random number generator creates value which is then used to

determine which of the eight LEDs should be on
set the time for which this LED status shall be maintained.

Finally, the LEDs are set accordingly and the loop repeats at the beginning.

Linear Feedback Shift Register

The Random Number Generator is implemented as a so-called linear feedback shift register (LSFR) with a length of 32bit (repeats its pattern after max. 2^32 steps). This implementation uses the “Galois type” of LFSRs.

Galois LFSR implementation

void loop() 
{
 iRandNum = (iRandNum >> 1) ^ (-(iRandNum & 1u) & 0xd0000001u);
 [...]
}

There’s a lot going on in this line of code, so please let me explain it down to the core.

Essential to this sort of random number generators is the XOR operation indicated by a ^ in the center of the code line. XOR means “eXclusive OR”, which outputs logic 1 only when logic inputs A and B are different. When A and B are both 0, or both 1, this gate will output 0.

Example binary XOR:

 A B Out
0b00001111 ^ 0b00110011 = 00111100

Left to the XOR operator, the current randum number is shifted to the right (>>) by 1. All of its contents is made less significant by one bit. In numerical terms it means that a value is integer-divided by two.

Example binary SHIFT:

 A B Out numerical:
0b00001111 >> 1 = 0b00000111 15 >> 1 = 7

OK, let’s further analyze the above code line. Right to the XOR operator, there’s another operation taking place: A logic AND (&) between our current random number and 1u which means “unsigned 1”. What it does is masking all higher bits of the randum number generator, the result of this action is a simple 0 in case the number has a 0 as its least significant bit and vice versa.

Example binary AND:

 A B Out 
0b00001111 & 1 = 0b00000001

The negation at the beginning of this term means that, when the result of the before & was 0, the whole term will be 0b00000000... again. If it’s -1, the 2’s complement binary code will instead look like this: 0b1111111....

This is an easy way to apply a single boolean value to any longer data type without branching logic like using an if() clause.

And finally, there’s another logic AND between this term and a fixed bitmask 0xd0000001u. The latter are the “taps” of the LFSR, i.e. which bits of the current value are fed back into the system. Unravelling this hex value to boolean shows: 0xd = 0b1101 so the bits 32, 31, 29, and 1 are &‘ed with the current random number, leaving only their values untouched while all others are set to 0.

Galois LFSR Summary

Whew, that was a lot. It’s time for a couple of minutes break. Then please read the summary below for the beloved code line

iRandNum = (iRandNum >> 1) ^ (-(iRandNum & 1u) & 0xd0000001u);

Meaning: “If the least significant bit of the current random number is zero, then just shift the random number to the right. Else, in addition XOR with the tapped bits of the current random number.”

LFSRs are widely used in wireless communication technology, they are interesting for checksum calculations, cryptographers and can even be useful when programming games, e.g. for procedural map generation. LFSRs are easy to implement (as you can see they even may only use a single line fo code!) and don’t use many resources. Here’s an excellent blog post dealing with LFSRs in depth if you’re more the visual type (and less the logic one). On the down side, their “quality of randomness” is bad because they are deterministic. All in all I found it a very interesting topic which is why I decided to manually implement an LFSR here instead of using Arduino’s stock random() function.

Pitfall! Game scene: procedural level design with LFSR ^[1]

Possible issue

Well, if you fully understood the code line, you see what happens if the random number contains only 0s.

It will never get out of this state again 💀

That’s why you should never initialize this type of LFSR with 0.

Driving the LEDs

The rest of the software has much more lines, but also does much more boring stuff. It takes the generated 32-bit random value and runs it past the 8 LED outputs, i.e. every LED “sees” each bit of the value. Between each of these iterations, a randomized delay is used so the flickering speed is limited to a change rate we still can perceive.

The Hardware

Thankfully, the hardware is more easy to explain than the software:

An Arduino Nano board is connected to a prototyping board.
Eight LED’s anodes (+) are connected to the digital outputs D2...D9.
Their cathodes are bridged with jumpers and connected to the Arduino’s GND.

This is the simplest design I could think of to do the job.

Improvements

Each LED should get a series resistor.
- In my design, the current is only limited by the maximum current the Arduino Pin is able to drive.
- Either the LED can handle well above 40mA peak current or it will inevitably break down at some point in time.
- Resistor calculation should happen with the LED datasheet in mind as different LED colours have different voltages.
- Example resistor calculation @5V supply: Warm-White LED: 20mA @ 3.1V --> R = U/I = (Usup-Uled) / I = 1.9 / 0.02 = 95Ohm. Take 100Ohm.
Each LED could get a parallel capacitor.
- This would smooth the flickering effect.
- I could take videos in which the camera wasn’t irritated by LED flickering. That would be nice.
- Example Capacitor calculation: Average current when switched “off” 20mA, allowed voltage drop 0.6V within 1ms. Proposed Capacitance is then 20mA * 1ms / 0.6V = 33uF

You want a DIY replica?

Here you go! Breadboard Fireplace DIY instructions

ClickEncoder

Schallbert — Mon, 01 Jan 0001

Project stats

Difficulty: medium 3/5
Cost: 0€
Time: ~6h

Abstract

Library for the Arduino Framework, written in c++.

It is lightweight because the source code itself is a few hundred lines only, and powerful, because of the improved algorithm uses less calculations while providing a better state interpretation than the original project this is forked from. It is officially released on PlatformIO IDE and hosted on Github. It contains examples both for Arduino and PlatformIO IDEs and provides unittests that can be run upon customization.

Motivation

I used the original library published by 0xPIT at first but that one caused some compiler warnings for me, plus the encoder readings were not flawless and sometimes there was jitter or bouncing I didn’t want to happen.

Solution

As the repo looked unmaintained, I decided to fix these issues by rewriting some code. For my project at that time, I also needed a “repeat” signal when a button is pressed continuously, so I added this, too. And finally, I separated the encoder algorithm from the button handling and provided separate classes so that, if needed, any combination of button and encoder could be used, each with configurable behavior.

Encoder Algorithm explained

API

ClickEncoder’s API is simple and easy to understand: service() runs the business logic and does the state interpretation. It has to be run regularly to check if the encoder has been moved since its last call, into which direction, how many steps, and has these values saved in an accumulator variable. getIncrement() returns the encoder step changes since its last call. getAccumulate() returns the sum of steps taken since startup. getButton() returns the current Button state.

void service();
int16_t getIncrement();
int16_t getAccumulate();
Button::eButtonStates getButton();

Encoder state

The encoder uses a Gray Code to encode the steps. getBitCode() converts this code transmitted via the Encoder’s hardware pins A and B to a 0...3 notch interpretation, numbers increasing when turning right, and decreasing when turning left. This is done efficiently without use of if() or other branching logic.

uint8_t Encoder::getBitCode()
{
 // GrayCode convert
 // !A && !B --> 0
 // !A && B --> 1
 // A && B --> 2
 // A && !B --> 3
 uint8_t currentEncoderRead = digitalRead(pinA);
 currentEncoderRead |= (currentEncoderRead << 1);
 
 // invert result's 0th bit if set
 currentEncoderRead ^= digitalRead(pinB);
 return currentEncoderRead;
}

I used a trick here, so you may have to look at the code snippet above several times. The state of PinA is written to bit1 of currentEncoderRead by me shifting it to the left with the << operation. But at the same time the state of the 0th bit is preserved by |=. If I now bind PinB simply by logical &=, then I would violate the Gray code, after which A&&B=2 should be and not 3.

So if A and B are both not set, the result remains 0, because 00^00=00=0. If only A is set, but B is not, the result is 11^00=11=3. If B is set, but A is not, the result is 00^01=01=1. If both are set, finally 11^01=10=2.

For more information about how logical binary operators work, please refer to my LED fireplace project

State interpretation

After the bit code is read, rawMovement variable is set that tells us how much the encoder has been turned between two runs of the service() routine. Here you can see the time criticality because there will be aliasing errors if the encoder changes notches in a time similarly short to the service interval.

void Encoder::handleEncoder()
{
 uint8_t encoderRead = getBitCode();
 // bit0 set = status changed, bit1 set = "overflow 3" where it goes 0->3 or 3->0
 uint8_t rawMovement = encoderRead - lastEncoderRead;
 lastEncoderRead = encoderRead;
 // This is the uint->int magic, converts raw to: -1 counterclockwise, 0 no turn, 1 clockwise
 int8_t signedMovement = ((rawMovement & 1) - (rawMovement & 2));

 encoderAccumulate += signedMovement;
 encoderAccumulate += handleAcceleration(signedMovement);
}

Here is another trick: signedMovement is calculated by converting the movement into a signed integer representing 0 as “not rotated, -1 as “rotated left” and 1 as “rotated right”. This exploits the integer overflow behavior, in combination with the interpretation of signedness.

Finally, the accumulation is performed and the acceleration, if configured, is added to the accumulator depending on how fast the encoder is rotated.

To program these two methods without branching took me several evenings of grubbling and practically half a pad of squared paper. Frankly, these few lines of code have brought me to the edge of my brain’s capacity. I am just not a “real” programmer 😅

The getAccumulate() method

It’s really simple, it just returns the internal accumulated value accounted to the encoder’s configuration about how many notches make a step.

int16_t Encoder::getAccumulate()
{
 return (encoderAccumulate / stepsPerNotch);
}

The getIncrement() method

Returns how much the encoder’s values have changed since its last call.

int16_t Encoder::getIncrement()
{
 int16_t accu = getAccumulate();
 int16_t encoderIncrements = accu - lastEncoderAccumulate;
 lastEncoderAccumulate = accu;
 return (encoderIncrements);
}

Button state calculation explained

The handleButton() method

All button states derive from the two basic states: pressed or not pressed. This is reflected in the logic as well:

void Button::handleButton()
{
 if (lastGetButtonCount < ENC_BUTTONINTERVAL)
 {
 return;
 }
 lastGetButtonCount = 0;

 if (digitalRead(pinBTN) == pinActiveState)
 {
 handleButtonPressed();
 }
 else
 {
 handleButtonReleased();
 }

 if (doubleClickTicks > 0)
 {
 --doubleClickTicks;
 }
}

The button can be configured to be read less often than the encoder. If this is the case, this method will be left without any action.

Button pressed:

handleButtonPressed() can either return Closed, Held, or LongPressRepeat depending on how the button is configured and how long it has been pressed already.

Button not pressed:

handleButtonReleased() can either return Clicked, Released, or Doubleclicked depending on button configuration and click count within a certain time.

Library configuration

The encoder/button detection behavior can be modified in the encoder.h file using the constants shown below. The values have been tweaked already and feel natural to me, at least. They should be modified if you choose to use a different service interval than 1ms because those values all take this interval as reference.

// ----------------------------------------------------------------------------
// Acceleration configuration (for 1ms calls to ::service())
//
constexpr uint8_t ENC_ACCEL_START = 150; // The smaller this value, the quicker you must turn to activate acceleration.
constexpr uint8_t ENC_ACCEL_SLOPE = 75; // the smaller this value, the stronger the acceleration will manipulate values.

// Button configuration (values for 1ms timer service calls)
//
constexpr uint8_t ENC_BUTTONINTERVAL = 20; // check button every x ms, also debouce time
constexpr uint16_t ENC_DOUBLECLICKTIME = 400; // second click within x ms
constexpr uint16_t ENC_LONGPRESSREPEATINTERVAL = 200; // reports repeating-held every x ms
constexpr uint16_t ENC_HOLDTIME = 1200; // report held button after x ms
// ----------------------------------------------------------------------------

Use it in your project!

The library is open source software, using the MIT license.
PlatformIO user? Easy, just search it in the ‘Libraries’ view, Tags are Arduino, Encoder, Schallbert. It’s then just one more click to add it to your solution
Alternatively, just clone or fork the repository and use the header/cpp file as you deem fit.
Contribute? Maybe you have a more efficient state calculation of the button? I’d be happy to review your pull request :)