Eight steps of brightness

Eight levels, unevenly spaced

Brightness on this chip is not a voltage or a current — it is how much of each digit's turn the segments are actually lit for. The datasheet calls it the pulse width and gives eight of them: 1, 2, 4, 10, 11, 12, 13 and 14 sixteenths.

Those numbers are worth looking at twice. Levels 0, 1 and 2 are a quarter of the range between them, levels 3 to 7 share the rest, and the jump from level 2 to level 3 is bigger than the whole distance from 3 to 7.

Which is exactly backwards from how the control feels. Somebody turning brightness up a step at a time sees almost nothing happen between 3 and 7, and then finds the only real dimming available is down at the bottom of the range.

For a bedside clock, level 0 or 1 is the night setting. For a display that has to be read across a lit room, anything from 3 up, and the difference between 3 and 7 is mostly how much current it draws.

It is sent with the digits, not on its own

setBrightness() only changes a variable inside the library. The value reaches the chip as part of the next write, tacked on to the end of the digits.

display.setBrightness(1);
// nothing has changed on the display yet
display.showNumberDec(value);   // now it is dim

This trips people up in setup(), where a setBrightness after the last showNumberDec appears to be ignored. It is not ignored, it is queued, and it will appear the next time anything is written — possibly minutes later, which makes it look intermittent.

Off is a separate bit

display.setBrightness(4, false);   // queued, like the level
display.showNumberDec(value);      // now it is dark
display.setBrightness(4, true);
display.showNumberDec(value);      // and lit again

The second argument is the display-on bit. The chip itself can switch its outputs off and keep its digits, but this library never sends the on/off bit on its own: like the level, it goes out with the next lot of digits. So off is a write, and on again is another.

That is still the clean way to blink a whole display (an alarm, a value that has gone stale), because your sketch keeps writing the real number and only the bit changes. Blanking it with four empty digits instead means remembering what was there to put it back.

And brightness is current

Each step up is more time with the LEDs conducting, and a panel showing 8888 at level 7 is the most current this board will ever draw. One display on a USB port is nothing to worry about. Six of them at level 7, powered through an Uno's 5V pin, is worth measuring before you trust it — more than one display picks that up.