MAX7219_CH32.h

Go to the documentation of this file.

/*
 * MAX7219_CH32.h - MAX7219 7-Segment Display Library for Arduino
 * 
 * A lightweight library for controlling MAX7219 LED driver ICs with 7-segment displays.
 * Optimized for memory-constrained microcontrollers like CH32V003.
 * 
 * Features:
 * - BCD decode mode (hardware handles 0-9 display)
 * - No-decode mode (software handles numbers, letters, patterns)
 * - Configurable alignment (left, right, center)
 * - Animation support (blink, fade, scroll, chase, count)
 * - Simple display functions for numbers, text, time, hex, binary
 * 
 * Author: Rithik Krisna M
 * License: MIT License
 * Version: 1.0.0
 * Created: 2025
 */
 
#ifndef MAX7219_CH32_H
#define MAX7219_CH32_H
 
#include <Arduino.h>
 
// ========================================
// Display Modes
// ========================================
#define MAX7219_MODE_DECODE     0xFF  // BCD decode for all digits (hardware mode)
#define MAX7219_MODE_NO_DECODE  0x00  // No decode (software handles display)
 
// ========================================
// Alignment Options
// ========================================
#define MAX7219_ALIGN_LEFT      0     // Left-aligned (position 0 = leftmost)
#define MAX7219_ALIGN_RIGHT     1     // Right-aligned (position 0 = rightmost)
#define MAX7219_ALIGN_CENTER    2     // Center-aligned (proportional to content size)
 
// ========================================
// MAX7219 Register Addresses
// ========================================
#define MAX7219_REG_NOOP        0x00
#define MAX7219_REG_DIGIT0      0x01
#define MAX7219_REG_DIGIT1      0x02
#define MAX7219_REG_DIGIT2      0x03
#define MAX7219_REG_DIGIT3      0x04
#define MAX7219_REG_DIGIT4      0x05
#define MAX7219_REG_DIGIT5      0x06
#define MAX7219_REG_DIGIT6      0x07
#define MAX7219_REG_DIGIT7      0x08
#define MAX7219_REG_DECODE      0x09
#define MAX7219_REG_INTENSITY   0x0A
#define MAX7219_REG_SCANLIMIT   0x0B
#define MAX7219_REG_SHUTDOWN    0x0C
#define MAX7219_REG_DISPLAYTEST 0x0F
 
// ========================================
// MAX7219 Class
// ========================================
class MAX7219 {
public:
  MAX7219(uint8_t dinPin, uint8_t clkPin, uint8_t csPin, uint8_t numDigits = 8);
  
  // ========================================
  // Initialization
  // ========================================
  void begin();
  
  void begin(uint8_t mode);
  
  // ========================================
  // Configuration
  // ========================================
  void setMode(uint8_t mode);
  
  uint8_t getMode();
  
  void setAlignment(uint8_t alignment);
  
  uint8_t getAlignment();
  
  void setBrightness(uint8_t level);
  
  void setPower(bool on);
  
  void clear();
  
  // ========================================
  // Display Functions (Mode-Aware)
  // ========================================
  void display(const char* text);
  
  void display(int number);
  
  void display(long number);
  
  void display(double number, uint8_t decimals = 2);
  
  void displayAt(uint8_t position, uint8_t value, bool dp = false);
  
  void displayAt(uint8_t position, char character, bool dp = false);
  
  // ========================================
  // Special Formats
  // ========================================
  void displayTime(uint8_t hours, uint8_t minutes);
  
  void displayTime(uint8_t hours, uint8_t minutes, uint8_t seconds);
  
  void displayHex(uint32_t value);
  
  void displayBinary(uint8_t value);
  
  // ========================================
  // Animations
  // ========================================
  void blink(uint8_t times = 3, uint16_t delayMs = 500);
  
  void fadeIn(uint16_t delayMs = 50);
  
  void fadeOut(uint16_t delayMs = 50);
  
  void scroll(const char* text, uint16_t delayMs = 200);
  
  void scroll(long number, uint16_t delayMs = 200);
  
  void chase(uint16_t delayMs = 100);
  
  void countUp(long from, long to, uint16_t delayMs = 100);
  
  void countDown(long from, long to, uint16_t delayMs = 100);
  
  // ========================================
  // Low-Level Control
  // ========================================
  void setSegments(uint8_t position, uint8_t segments);
  
  void setRawDigit(uint8_t position, uint8_t value, bool dp = false);
  
private:
  // Pin configuration
  uint8_t _dinPin;
  uint8_t _clkPin;
  uint8_t _csPin;
  
  // Display configuration
  uint8_t _numDigits;
  uint8_t _mode;
  uint8_t _alignment;
  uint8_t _brightness;
  
  // Internal functions
  void sendCommand(uint8_t address, uint8_t data);
  void sendByte(uint8_t data);
  void sendBit(uint8_t bit);
  uint8_t getPhysicalPosition(uint8_t logicalPosition);
  uint8_t charToSegments(char c);
  uint8_t digitToSegments(uint8_t digit);
  void displayNumberInternal(long number, bool leadingZeros = false);
  void displayFloatInternal(double number, uint8_t decimals);
  void displayTextInternal(const char* text);
};
 
#endif // MAX7219_CH32_H