TM1637 display/How it shows a number/07. Numbers, points and the colon
How it shows a number · 07 of 13

Numbers, points and the colon

showNumberDecEx takes a number, a bitmask for the points and a leading-zero flag. It also does three things nobody expects: it drops the top of a long number, it puts the minus sign in the middle, and with a zero it forgets the colon entirely.

The one function

display.showNumberDecEx(1234, 0b01000000, true);
//                       ^     ^           ^
//                       |     |           leading zeros
//                       |     which points, counted from the left
//                       the number

Everything else in the library is a shorthand for this. showNumberDec(n) is this with no dots and no leading zeros.

What the library sends
showNumberDecEx(1234, 0b01000000, false)
The number
The dots argument
Leading zeros
On a clock panel
12:34
On a digit panel
12.34
Digits written
4, leftmost first
The dots argument is a bitmask, counted from the left. Bit 7 is the first digit, bit 6 the second, and so on — which is why the colon, being the second digit’s point, is 0b01000000. The number and the dots are independent: the same four bytes go out, and what you see depends on which panel is fitted.

Work the controls through the six numbers. Three of the combinations are not what you would expect, and all three cost somebody an evening at some point.

Zero loses its dots

With the number 0 and leading zeros off, the library takes a separate path — it blanks three digits, writes a single 0, and never applies the dots at all.

So a 24-hour clock written without leading zeros loses its colon for the whole of the minute after midnight. It is a genuine bug, it was fixed on the project's master branch in June 2020, and that fix has never been released: the version the Library Manager installs is still the one from 2018.

You do not need a patched library. Pass true for leading zeros and the special case never runs.

Long numbers lose their top

The library asks for four digits, takes them off the bottom of the number, and says nothing about what it dropped. 12345 shows as 2345 — not as an error, not as ----, just quietly wrong.

Four digits is 0 to 9999, and −999 to 9999 if you need the minus. Clamp in your own code:

if (value < 0 || value > 9999) display.setSegments(DASHES);
else display.showNumberDec(value);

The minus sign takes a digit

There is no separate minus; it is written into the first digit that would otherwise be blank. So −5 is -5, and −1234 has nowhere to put the sign and shows 1234 — a positive-looking number for a negative reading, which on a thermometer is the worst possible failure.

Together those two limits give a thermometer's real range on this display: −999 to 9999 in whole units, or −99.9 to 999.9 with a point.

And the points are independent

The number and the mask have nothing to do with each other. The same four bytes go out either way; the mask just sets bit 7 on the digits you name. Which is why 0b01000000 is a colon on one panel and a decimal point on the other, and why the same call can mean 12:34 or 12.34 depending on nothing but which display is soldered to the board.

When it does not work

The colon goes out at exactly 00:00

A real bug in the released library. showNumberDecEx with the number 0 and leading zeros off takes a shortcut that never applies the dots, so the colon disappears for a whole minute at midnight. Pass true for leading zeros — which a 24-hour clock wants anyway — and it cannot happen.

My number over 9999 shows the wrong digits

It shows the last four. The library asks for four digits and takes them off the bottom of the number with no warning, so 12345 arrives as 2345. Check the range in your own code before you send it.

A negative number shows as 00-5

Leading zeros and negative numbers do not mix, and the library's own documentation says so. The minus sign is written into the first blank position, and leading zeros mean there are no blanks, so it lands in the middle of the zeros. For anything that can go negative, leave leading zeros off.

The point is one digit off from where I want it

The mask is counted from the left: bit 7 is the first digit, bit 6 the second, bit 5 the third, bit 4 the fourth. It is easy to read 0b01000000 as the second bit rather than the second digit — write it out in binary and count from the left end.

Where this goes next

Why levels 0, 1 and 2 look so different from 3 to 7, and why setBrightness on its own seems to do nothing.

Eight steps of brightness

Edit this page — content/books/tm1637-display/numbers-points-and-the-colon.mdx

Community

Questions about this product

See what other owners have asked, and read their solutions.

This page covers several products. Choose yours to see the right discussions.

Discuss this article

Ask about this page. The answer stays here, on the page it belongs to, for whoever hits the same wall next.

Browse Modules and blocks on the forum