A library for using the TM1637
LED driver control IC to drive a 4 x 7-segment display from Raspberry Pi OS (Raspbian). Includes a small say
utility to scroll some text.
This library does not access the GPIO pins itself. Instead, it has been designed to allow the use of different 'backend' GPIO libraries through the use of polymorphism and dynamic loading to provide a runtime choice of GPIO library. The currently supported GPIO libraries include:
By default, libgpiod
will be used.
You must ensure you have installed the GPIO library that you wish to use
(see Prerequisites below), but your program does not have to link
to any GPIO library at build time. The GPIO library is dynamically loaded at runtime using
dlopen()
.
- Show any combination of segments on up to four digits controlled by the TM1637.
- Independent control over the 'colon' character.
- Independent control over the display brightness.
- APIs to show numerical literals in both decimal (e.g.
1234
) & hexadecimal (e.g.0xabcd
).
You will need cmake v3.9 or higher and the necessary C++ development tools installed in order to build and install the library:
sudo apt install build-essential cmake
If you wish to use libgpiod
for GPIO access, you will need to install the gpiod
package:
sudo apt install gpiod
If you wish to use the pigpio
library and/or pigpiod
for GPIO access, you may need to install the pigpiod
package
(although it may already be included by default in your OS image):
sudo apt install pigpiod
When using the pigpio
'library interface' your app will need to run as the 'root
' user (or under 'sudo
')
to have permission to access the GPIO pins. You must also ensure that pigpiod
is NOT currently running.
When using the pigpiod
daemon, the library will connect to the daemon on localhost
by default.
If you wish to connect to a daemon on a different interface (or machine) you can do this by setting
the PIGPIO_ADDR
and PIGPIO_PORT
environment variables as described in the documentation for
pigpio_start()
wiringPi
was removed from v11 ('Bullseye') of Raspberry Pi OS packages. If you wish to use wiringPi
for GPIO access you will need to build & install it manually by following the
instructions.
Create a new directory somewhere, clone the
source and build & install:
git clone --depth 1 https://github.com/WiringPi/WiringPi.git
cd WiringPi
./build
ldconfig
From this repo's root directory, create and change to a new build
directory:
mkdir build
cd build
By default the library will be configured to build as a shared library (.so) which is the recommended usage:
cmake -G"Unix Makefiles" ..
If you prefer to configure the library to build as a static library (.a) then you must declare BUILD_SHARED_LIBS
as OFF
when calling cmake
. e.g.
cmake -DBUILD_SHARED_LIBS=OFF -G"Unix Makefiles" ..
If you wish to change the configuration options above, be sure to delete the CMakeCache.txt
file before calling cmake
again. It's also wise to perform a 'make clean
' before rebuilding:
make clean
rm CMakeCache.txt
After configuring the build, you can build and install the library by simply invoking
make
from the build
directory:
sudo make install
You may or may not need to use the sudo
prefix this command depending on your user permissions:
For ease of use the library installs with pkg-config
support.
This means you can automatically find all the required compiler command line options for using the library by issuing the command:
pkg-config --libs --cflags libTM1637Pi
An example of how to compile & link your program against the library:
g++ -Wall -std=c++11 myprogram.cpp -o myprogram $(pkg-config --libs --cflags libTM1637Pi)
The library makes use of C++11 features, so you will need to include
the relevant flag when invoking your compiler. e.g. for (modern versions of) GCC (g++
) you would use '-std=c++11
'
The library's public headers are installed into the system default directory (e.g. /usr/local/include
).
Add the following to your CPPFLAGS
when invoking the compiler, ONLY if you are not using pkg-config
:
-I/usr/local/include
The library is installed into the system default directory (e.g. /usr/local/lib
).
Add the following options when invoking your compiler, ONLY if you are not using pkg-config
:
-L/usr/local/lib -lTM1637Pi -ldl
The public API is included in the public header file tm1637.h
which will be installed into the system default includes directory (e.g. /usr/local/include
).
See the example code in the example
directory for a demonstration of the library's features. The example can be built and run with the following commands from the top level dir of this repo:
cd example
./build_for_gpiod.sh
# or ./build_for_wiringpi.sh
# or ./build_for_pigpio_interface.sh
# or ./build_for_pigpio_daemon.sh
./tm1637_example
A simple utility using lib_tm1637_rpi
to scroll some text on a TM1637 display is included as part of the build. The cmake install
action will also install it into the default binary installation directory which should be already included in your $PATH
Running tm1637_say
without any arguments, or with --help
will display help & usage information:
$ tm1637_say
tm1637_say utility - © 2023 Neil Davis
See LICENSE at https://github.com/neildavis/lib_tm1637_rpi/blob/main/LICENSE
Usage: tm1637_say [OPTIONS] <message>
Available OPTIONS:
-h [ --help ] Show usage information
-c [ --scl ] arg (=3) GPIO pin to use for clock
-d [ --sda ] arg (=2) GPIO pin to use for data
-g [ --gpio-lib ] arg (=GpioGPIOD) GPIO library
-t [ --delay-time ] arg (=250) Delay time between characters (ms)
-n [ --count ] arg (=1) Repeat the message <arg> number of times
-v [ --verbose ] [=arg(=1)] (=0) Enable/Disable verbose output
e.g. the following invocation uses the wiringPi library with BCM pin numbering, pins 23 & 24 for SCL
& SDA
respectively, and displays a message faster than the default three times over :
tm1637_say -c 23 -d 24 -g GpioWiringPiBCM -t 100 -n 3 "HELLO WORLD"