A lightweight Arduino library for controlling MAX7219 LED driver ICs with 7-segment displays. Optimized for memory-constrained microcontrollers like CH32V003 and other Arduino-compatible boards.

The main objective of this library is to provide a simple, efficient, and memory-optimized interface for controlling MAX7219 7-segment displays on resource-constrained microcontrollers.

This library is specifically designed for developers working with limited flash and RAM, such as the CH32V003 microcontroller, while maintaining compatibility with standard Arduino boards. It offers a clean API that handles both hardware (BCD decode) and software (no-decode) display modes, making it easy to display numbers, text, time, and custom patterns.

• Memory Efficient: Optimized for microcontrollers with limited flash and RAM
• Easy to Use: Simple, intuitive API for common display tasks
• Flexible: Supports both hardware and software display modes
• Feature Rich: Includes animations, alignment options, and special formats
• Well Documented: Comprehensive Doxygen documentation
• Production Ready: Follows Arduino library best practices

• 🎯 Dual Display Modes: BCD decode mode (hardware) and no-decode mode (software)
• 📐 Flexible Alignment: Left, right, and center alignment options
• 🔢 Multiple Formats: Numbers (int, long, float), text, time (HH:MM, HH:MM:SS), hex, binary
• 🎬 Animations: Blink, fade, scroll, chase, and count animations
• 🎛️ Brightness Control: 16-level brightness control (0-15)
• ⚡ Power Management: Turn display on/off programmatically
• 🔧 Low-Level Control: Direct segment and raw digit manipulation
• 📖 Well Documented: Comprehensive API documentation with examples
• 💾 Memory Optimized: Designed for memory-constrained microcontrollers
• 🎯 Production Ready: Tested and optimized for CH32V003

The MAX7219_CH32 library is compatible with the following platforms:

• ✅ CH32V003: Tested and optimized (primary target platform)
• ✅ Arduino Uno/Nano: Full support with standard Arduino pins
• ✅ Arduino Mega: Full support with standard Arduino pins
• ✅ ESP32: Compatible (may require pin adjustments)
• ✅ ESP8266: Compatible (may require pin adjustments)
• ✅ Other Arduino-compatible boards: Should work with proper pin configuration

1. Open Arduino IDE
2. Go to Tools → Manage Libraries
3. Search for "MAX7219_CH32"
4. Click Install

1. Download or clone this repository
2. Copy the MAX7219_CH32 folder to your Arduino libraries directory:
   • Windows: Documents\Arduino\libraries\
   • macOS: ~/Documents/Arduino/libraries/
   • Linux: ~/Arduino/libraries/
3. Restart Arduino IDE

• MAX7219 LED driver IC
• 7-segment display module (common cathode)
• Arduino-compatible microcontroller
• 3 digital pins for SPI communication (DIN, CLK, CS)
• 5V power supply

MAX7219 DIN → PC6
MAX7219 CLK → PC5
MAX7219 CS  → PC4
MAX7219 VCC → 5V
MAX7219 GND → GND

MAX7219 DIN → Pin 12
MAX7219 CLK → Pin 11
MAX7219 CS  → Pin 10
MAX7219 VCC → 5V
MAX7219 GND → GND

#include <MAX7219_CH32.h>

// Create display instance: DIN, CLK, CS, number of digits
MAX7219 display(12, 11, 10, 8);

void setup() {
  // Initialize display in BCD decode mode
  display.begin(MAX7219_MODE_DECODE);
  display.setBrightness(8);  // Medium brightness (0-15)
}

void loop() {
  // Display a number
  display.display(12345);
  delay(1000);
  
  // Display text (switch to no-decode mode)
  display.setMode(MAX7219_MODE_NO_DECODE);
  display.display("HELLO");
  delay(1000);
}

#include <MAX7219_CH32.h>

MAX7219 display(12, 11, 10, 8);

void setup() {
  display.begin();
  
  // BCD decode mode (hardware handles 0-9)
  display.setMode(MAX7219_MODE_DECODE);
  display.display(12345678);  // Perfect for numbers
  
  delay(2000);
  
  // No-decode mode (software handles display)
  display.setMode(MAX7219_MODE_NO_DECODE);
  display.display("HELLO");   // Perfect for text and letters
}

#include <MAX7219_CH32.h>

MAX7219 display(12, 11, 10, 8);

void setup() {
  display.begin(MAX7219_MODE_DECODE);
  
  // Right alignment (default)
  display.setAlignment(MAX7219_ALIGN_RIGHT);
  display.display(12345);
  
  delay(2000);
  
  // Left alignment
  display.setAlignment(MAX7219_ALIGN_LEFT);
  display.display(12345);
  
  delay(2000);
  
  // Center alignment
  display.setAlignment(MAX7219_ALIGN_CENTER);
  display.display(12345);
}

#include <MAX7219_CH32.h>

MAX7219 display(12, 11, 10, 8);

void setup() {
  display.begin(MAX7219_MODE_DECODE);
  display.setBrightness(8);
}

void loop() {
  // Display time in HH:MM format
  display.displayTime(12, 34);
  delay(2000);
  
  // Display time in HH:MM:SS format
  display.displayTime(12, 34, 56);
  delay(2000);
}

#include <MAX7219_CH32.h>

MAX7219 display(12, 11, 10, 8);

void setup() {
  display.begin(MAX7219_MODE_DECODE);
  display.setBrightness(8);
}

void loop() {
  // Blink animation
  display.display("BLINK");
  display.blink(3, 500);
  
  // Scroll text
  display.setMode(MAX7219_MODE_NO_DECODE);
  display.scroll("SCROLLING TEXT", 100);
  
  // Chase animation
  display.setMode(MAX7219_MODE_DECODE);
  display.chase(100);
  
  // Count up
  display.countUp(0, 9999, 50);
}

MAX7219(uint8_t dinPin, uint8_t clkPin, uint8_t csPin, uint8_t numDigits = 8)

Creates a MAX7219 display instance.

Parameters:

• dinPin: Data input pin (MOSI)
• clkPin: Clock pin (SCK)
• csPin: Chip select pin (CS/SS)
• numDigits: Number of digits (1-8, default: 8)

Example:

MAX7219 display(12, 11, 10, 8);  // 8-digit display
MAX7219 display(12, 11, 10, 4);  // 4-digit display

Initialize the display with default mode (BCD decode).

display.begin();

Initialize the display with specific mode.

display.begin(MAX7219_MODE_DECODE);      // BCD decode mode
display.begin(MAX7219_MODE_NO_DECODE);   // No-decode mode

Set the display decode mode.

display.setMode(MAX7219_MODE_DECODE);     // Hardware decode (0-9)
display.setMode(MAX7219_MODE_NO_DECODE);  // Software decode (text/patterns)

Get the current display mode.

uint8_t mode = display.getMode();

Set text/number alignment.

display.setAlignment(MAX7219_ALIGN_LEFT);    // Left-aligned
display.setAlignment(MAX7219_ALIGN_RIGHT);   // Right-aligned (default)
display.setAlignment(MAX7219_ALIGN_CENTER);  // Center-aligned

Get the current alignment setting.

uint8_t alignment = display.getAlignment();

Set display brightness (0-15, where 0 is dimmest and 15 is brightest).

display.setBrightness(8);   // Medium brightness
display.setBrightness(15);  // Maximum brightness

Turn display on or off.

display.setPower(true);   // Turn on
display.setPower(false);  // Turn off (power save mode)

Clear all digits on the display.

display.clear();

Display a text string.

display.display("HELLO");
display.display("12345");  // In decode mode, tries to parse as number

Display an integer.

display.display(12345);
display.display(-1234);  // Negative numbers supported

Display a long number.

display.display(12345678L);

Display a floating point number.

display.display(12.34, 2);    // 12.34
display.display(123.456, 3);  // 123.456

Display a value at a specific position.

display.displayAt(0, 5);           // Display 5 at position 0
display.displayAt(3, 7, true);     // Display 7 with decimal point at position 3

Display a character at a specific position.

display.displayAt(0, 'H');
display.displayAt(1, 'E');
display.displayAt(2, 'L');

Display time in HH:MM format.

display.displayTime(12, 34);  // Displays "12:34"

Display time in HH:MM:SS format.

display.displayTime(12, 34, 56);  // Displays "12:34:56"

Display a value in hexadecimal format.

display.displayHex(0x1234);  // Displays "1234" in hex

Display a value in binary format (requires 8 digits).

display.displayBinary(0b10101010);  // Displays "10101010"

Blink the display.

display.blink(3, 500);      // Blink 3 times with 500ms delay
display.blink(5, 200);      // Blink 5 times with 200ms delay

Fade in animation (brightness 0 to current).

display.fadeIn(50);  // Fade in with 50ms steps

Fade out animation (current to 0).

display.fadeOut(50);  // Fade out with 50ms steps

Scroll text across the display.

display.scroll("SCROLLING TEXT", 100);  // Scroll with 100ms delay

Scroll a number across the display.

display.scroll(123456, 100);

Chase animation (digit-by-digit).

display.chase(100);  // Chase with 100ms delay

Count up animation.

display.countUp(0, 9999, 50);  // Count from 0 to 9999 with 50ms delay

Count down animation.

display.countDown(9999, 0, 50);  // Count from 9999 to 0 with 50ms delay

Set raw segment pattern at a specific position.

display.setSegments(0, 0b00110111);  // Display 'H' (segment pattern)

Set raw digit value at a specific position.

display.setRawDigit(0, 5);        // Display 5
display.setRawDigit(2, 7, true);  // Display 7 with decimal point

• MAX7219_MODE_DECODE - BCD decode mode (hardware handles 0-9 display)
• MAX7219_MODE_NO_DECODE - No decode mode (software handles display)

• MAX7219_ALIGN_LEFT - Left-aligned (position 0 = leftmost)
• MAX7219_ALIGN_RIGHT - Right-aligned (position 0 = rightmost, default)
• MAX7219_ALIGN_CENTER - Center-aligned (proportional to content size)

The library includes several example sketches:

• BasicExample: Simple demonstration showing basic number and text display
• AdvancedExample: Comprehensive demonstration of all library features including alignment, modes, animations, and special formats

The BasicExample is perfect for beginners and demonstrates the most common usage:

1. Display Numbers: Shows how to display integers
2. Display Text: Shows how to display text strings
3. Mode Switching: Demonstrates switching between decode and no-decode modes
4. Clear Display: Shows how to clear the display

This example is ideal for:

• Learning the basics of the library
• Testing your hardware setup
• Understanding the fundamental display functions
• Quick start guide for new users

Watch the demo video above to see all features in action!

The AdvancedExample demonstrates all major features of the MAX7219_CH32 library:

1. Alignment: Shows left, right, and center alignment options
2. Display Modes: Demonstrates BCD decode and no-decode modes
3. Number Display: Shows integer, negative, and floating point numbers
4. Text Display: Demonstrates character and string display
5. Position Display: Shows how to display at specific positions
6. Time Display: Demonstrates HH:MM and HH:MM:SS formats
7. Hex & Binary: Shows hexadecimal and binary display
8. Brightness Control: Demonstrates brightness adjustment
9. Power Control: Shows display on/off functionality
10. Animations: Demonstrates blink, scroll, chase, and count animations
11. Low-Level Control: Shows direct segment and digit manipulation

This example is ideal for:

• Learning all library features
• Testing your hardware setup
• Understanding different display modes
• Verifying library installation
• Seeing practical usage examples

This library is optimized for memory-constrained microcontrollers:

• Flash: ~6-8 KB (varies by compiler and optimization settings)
• RAM: ~200-300 bytes (depends on display configuration and number of digits)

1. Use BCD decode mode when displaying only numbers (more efficient)
2. Use no-decode mode only when displaying text or custom patterns
3. Avoid using floating point if not necessary
4. Use appropriate number of digits for your display

• Check wiring connections: Verify DIN, CLK, and CS pins are correctly connected
• Verify power supply: Ensure 5V is properly connected and stable
• Check CS pin: Ensure chip select pin is correctly connected
• Increase brightness: Try display.setBrightness(15) to ensure it's not too dim
• Verify initialization: Ensure begin() is called in setup()

• Check mode: Verify you're using the correct mode (DECODE vs NO_DECODE)
• Verify alignment: Check alignment settings match your expectations
• Check digit count: Ensure number of digits matches your display configuration
• Verify data: Check that the data you're sending is valid

• Check power supply: Ensure stable 5V power supply with adequate current
• Verify SPI timing: Library uses software SPI - ensure no interference
• Reduce brightness: Try reducing brightness to display.setBrightness(8)
• Check connections: Ensure all connections are solid and properly soldered

• Check mode switching: Ensure you set the correct mode before displaying
• Verify text format: In no-decode mode, only A-Z, 0-9, and some special chars are supported
• Check alignment: Incorrect alignment can make text appear garbled

The library is designed to be extensible. Future versions may include:

• Multiple Display Support: Cascade multiple MAX7219 chips
• Custom Characters: User-defined character patterns
• Display Modes: Additional display modes and effects
• Performance: Further memory and speed optimizations
• SPI Hardware Support: Optional hardware SPI for faster communication
• Interrupt Support: Non-blocking animations

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

This library is licensed under the MIT License. See the LICENSE file for details.

Rithik Krisna M (@me-RK)

• v1.0.0 (2025):

  🎉 Initial release
  ✅ Basic display functionality with BCD decode and no-decode modes
  📐 Alignment options (left, right, center)
  🎬 Animation support (blink, fade, scroll, chase, count)
  🔢 Multiple display formats (numbers, text, time, hex, binary)
  💾 Memory optimized for CH32V003 and other constrained microcontrollers
  📖 Comprehensive Doxygen documentation
  🎯 Production ready with Arduino library best practices
  

API documentation can be generated using Doxygen. See DOCUMENTATION.md for instructions on generating the documentation.

To generate the documentation:

doxygen Doxyfile

The documentation will be available in the docs/html/ directory.

Online documentation is available at: https://me-rk.github.io/MAX7219_CH32/

If you encounter any issues or have questions:

1. Check the examples folder
2. Review the documentation
3. Open an issue
4. Check the Arduino Forum

Note: This library is designed for educational and development purposes. For production applications, ensure proper testing and validation for your specific use case.