AceSegment

An adjustable, configurable, and extensible framework for rendering seven segment LED displays on Arduino platforms. The library supports many types of LED displays:

• modules using the TM1637 controller chip over its custom 2-wire protocol
• modules using the TM1638 controller chip over its custom 3-wire protocol
• modules using the MAX7219/MAX7221 controller chip over SPI
• modules using the HT16K33 controller chip over I2C
• modules using two 74HC595 shift register chips over SPI
• modules using a hybrid of one 74HC595 chip and direct GPIO connections
• modules directly connected to the GPIO pins, no controller chips

The first 5 types are readily available from retail outlets such as Amazon and eBay, in multiple colors and sizes. They look like these:

TM1637

TM1638

MAX7219

HT16K33

74HC595

The final 2 types of modules (hybrid and directly connected) are usually custom creations. Here is an example of an LED module that I built myself a few years ago using a single 74HC595 chips and 4 transistors:

Hybrid

Here is another one which uses only 4 transistors without any controller chip. The 8 segment lines and the 4 digit lines are controlled directly by 12 GPIO pins of the microcontroller:

Direct

The AceSegment library hopes to support as many seven-segment displays as practical within a single framework. Different types of seven-segment LED modules using different controller chips are similar enough to each other that code at the application layer can be mostly agnostic to the hardware differences. The library is organized into hardware-dependent components and hardware-independent components to allow application code to be written without worrying too much about the low-level details of the specific LED module.

This library is designed to ensure that client applications pay only for what they use. Most of the code is written as C++ templates to avoid creating static resources that cannot be optimized away. No virtual methods are used in this library, making the code size smaller and execution speed a little faster. There is no direct dependency to the <Wire.h>, <SPI.h>, <AceWire.h>, <AceSPI.h>, or <AceTMI.h> libraries from this library. (On AVR processors, simply adding #include <Wire.h> increases flash usage by about 1100 bytes even if nothing is used from the <Wire.h> library.)

Version: 0.13.0 (2023-03-15)

Status: First public release at 0.9.1.

Changelog: CHANGELOG.md

Table of Contents

• Installation
  • Source Code
  • Dependencies
• Documentation
  • Examples
• High Level Overview
  • Classes
  • Dependency Diagram
  • Digit and Segment Addressing
  • Remap Arrays
  • Hello Tm1637Module
  • Hello Tm1638Module
  • Hello Max7219Module
  • Hello Ht16k33Module
  • Hello Hc595Module
• Usage
  • Include Header and Namespace
  • LedModule
  • Tm1637Module
    • TM1637 Module With 4 Digits
    • TM1637 Module With 6 Digits
    • TM1637 Module With 6 Digits and 6 Buttons
  • Tm1638Module
    • TM1638 Module With 8 Digits and 8 Buttons
    • TM1638 Module With 8 Digits and 16 Buttons
  • Max7219Module
    • MAX7219 Module With 8 Digits
  • Ht16k33Module
    • HT16K33 Module With 4 Digits
  • Hc595Module
    • 74HC595 Module With 8 Digits
    • 74HC595 Module With 4 Digits
    • Rendering the Hc595Module
  • HybridModule
  • DirectModule
• Advanced Usage
  • TM1637 Capacitor Removal
  • DigitalWriteFast on AVR
  • Multiple SPI Buses
  • ScanningModule
• Resource Consumption
  • SizeOf Classes
  • Flash And Static Memory
  • CPU Cycles
• System Requirements
  • Hardware
  • Tool Chain
  • Operating System
• Bugs And Limitations
• Alternative Libraries
• License
• Feedback and Support
• Authors

<a name="Installation"></a>

Installation

The latest stable release is available in the Arduino IDE Library Manager. Search for "AceSegment". Click install.

The development version can be installed by cloning the GitHub repository, checking out the default develop branch, then manually copying over to or symlinking from the ./libraries directory used by the Arduino IDE. (The result is a directory or a link named ./libraries/AceSegment.)

The master branch contains the stable releases.

<a name="SourceCode"></a>

Source Code

The source files are organized as follows:

• src/AceSegment.h - main header file
• src/ace_segment/ - implementation files
• src/ace_segment/testing/ - internal testing files
• tests/ - unit tests which require AUnit
• examples/ - example sketches
• docs/ - contains the doxygen docs and additional manual docs

<a name="Dependencies"></a>

Dependencies

This library library has a direct dependency on:

• AceCommon (https://github.com/bxparks/AceCommon)

The following libraries are listed in the depends clause of library.properties so that they are automatically installed by the Arduino Library Manager for convenience. However these libraries are pulled into the executable only when the client application explicitly uses them.

• AceSPI (https://github.com/bxparks/AceSPI)
  • Needed by Hc595Module, Max7219Module, and HybridModule
• AceTMI (https://github.com/bxparks/AceTMI)
  • Needed by Tm1637Module and Tm1638Module
• AceWire (https://github.com/bxparks/AceWire)
  • Needed by Ht16k33Module

The following library is a companion library to AceSegment that provides more powerful and convenient "Writer" classes. It is not listed in the depends clause, so must be installed manually:

• AceSegmentWriter (https://github.com/bxparks/AceSegmentWriter)
  • Provides more powerful and convenient classes to write quantities (numbers, characters, strings, etc) to the LED module.

The unit tests depend on:

• AUnit (https://github.com/bxparks/AUnit)

Some of the examples may depend on:

• TimerOne (https://github.com/PaulStoffregen/TimerOne)
• one of the DigitalWriteFast libraries, for example:
  • https://github.com/watterott/Arduino-Libs/tree/master/digitalWriteFast
  • https://github.com/NicksonYap/digitalWriteFast

<a name="Documentation"></a>

Documentation

• this README.md file
• DEVELOPER.md
  • Internal technical notes to developers of the library.
• scanning_module.md
  • Information about ScanningModule and LedMatrix classes. These are the implementation classes for Hc595Module, HybridModule and DirectModule.
• capacitor_removal.md
  • Removing the 10 nF capacitors on certain TM1637 LED modules
• Doxygen docs
  • On Github pages.

<a name="Examples"></a>

Examples

The following example sketches are provided:

• Basic
  • HelloTm1637.ino
  • HelloTm1638.ino
  • HelloMax7219.ino
  • HelloHt16k33.ino
  • HelloHc595.ino
• Intermediate
  • Tm1637Demo.ino
  • Tm1638Demo.ino
  • Tm1638AnodeDemo.ino
  • Max7219Demo.ino
  • Ht16k33Demo.ino
  • Hc595Demo.ino
• Advanced
  • DirectDemo.ino
    • Demo of an LED module with no controller, all digit and segment pins wired directly to the microcontroller
    • Uses DirectModule class
  • DirectFast4Demo.ino
    • same as DirectDemo but using DirectFast4Module which uses digitalWriteFast()
  • HybridDemo.ino
    • Demo of an LED module that uses a single 74HC595 shift register on the segment pins, but the digit pins are wired directly to the microcontroller