MaxMatrix
Drive chained 8x8 LED dot matrix modules with MAX7219.
Loading...
Searching...
No Matches
Chain.h
Go to the documentation of this file.
1// Copyright 2026 Andreas Burnickl
2// SPDX-License-Identifier: GPL-3.0-or-later
3
11
12#ifndef MAXMATRIX_SRC_MAX7219_CHAIN_H_
13#define MAXMATRIX_SRC_MAX7219_CHAIN_H_
14
15#include "Arduino.h"
16#include "MaxMatrixAttributes.h"
17#include "MaxMatrixConfig.h"
18#include "Utility/Byte.h"
19#include "Utility/span.h"
20
21namespace max_matrix {
22
27namespace max7219 {
28
29/* the addresses of the registers */
31constexpr uint8_t kNoOpAddress{0x00};
33constexpr uint8_t kDigit0Address{0x01};
35constexpr uint8_t kDigit1Address{0x02};
37constexpr uint8_t kDigit2Address{0x03};
39constexpr uint8_t kDigit3Address{0x04};
41constexpr uint8_t kDigit4Address{0x05};
43constexpr uint8_t kDigit5Address{0x06};
45constexpr uint8_t kDigit6Address{0x07};
47constexpr uint8_t kDigit7Address{0x08};
49constexpr uint8_t kDecodeModeAddress{0x09};
51constexpr uint8_t kIntensityAddress{0x0A};
53constexpr uint8_t kScanLimitAddress{0x0B};
55constexpr uint8_t kShutdownAddress{0x0C};
57constexpr uint8_t kDisplayTestAddress{0x0F};
58
59/* the values of the decode mode register */
61constexpr uint8_t kDecodeModeNoDecode{0x00};
63constexpr uint8_t kDecodeModeCodeBDecodeDigit0{0x01};
65constexpr uint8_t kDecodeModeCodeBDecodeDigit3To0{0x0F};
67constexpr uint8_t kDecodeModeCodeBDecodeDigit7To0{0xFF};
68
69/* the values of the intensity register */
71constexpr uint8_t kIntensityMinValue{0x00};
73constexpr uint8_t kIntensityMaxValue{0x0F};
74
75/* the values of the scan limit register */
77constexpr uint8_t kScanLimitDisplayDigit0{0x00};
79constexpr uint8_t kScanLimitDisplayDigit0To1{0x01};
81constexpr uint8_t kScanLimitDisplayDigit0To2{0x02};
83constexpr uint8_t kScanLimitDisplayDigit0To3{0x03};
85constexpr uint8_t kScanLimitDisplayDigit0To4{0x04};
87constexpr uint8_t kScanLimitDisplayDigit0To5{0x05};
89constexpr uint8_t kScanLimitDisplayDigit0To6{0x06};
91constexpr uint8_t kScanLimitDisplayDigit0To7{0x07};
92
93/* the values of the shutdown register */
95constexpr uint8_t kShutdownModeShutdownMode{0x00};
97constexpr uint8_t kShutdownModeNormalOperation{0x01};
98
99/* the values of the display test register */
101constexpr uint8_t kDisplayTestNormalOperation{0x00};
103constexpr uint8_t kDisplayTestDisplayTestMode{0x01};
104
105} // namespace max7219
106
107namespace internal {
108
115class Chain {
116 private:
117 uint8_t data_in_pin_;
118 uint8_t chip_select_pin_;
119 uint8_t clock_pin_;
120 /*
121 * The port and the bit of each pin, looked up once in Init(): digitalWrite()
122 * looks both up in tables in flash on every call, which made a byte bit
123 * banged by shiftOut() take about 1500 cycles of the Uno's 16 MHz. The port,
124 * not its register: the core reads the register's address from flash with a
125 * statement expression, which decltype() cannot take outside a function, so
126 * it is read where it is written. Data in and clock only bit bang.
127 */
128 uint8_t chip_select_port_{0};
129 uint8_t chip_select_mask_{0};
130#if (MAXMATRIX_USE_SPI == STD_OFF)
131 uint8_t data_in_port_{0};
132 uint8_t data_in_mask_{0};
133 uint8_t clock_port_{0};
134 uint8_t clock_mask_{0};
135#endif
136
137 /*
138 * Not const, though they change no member: they change the chain this object
139 * stands for, and a const Chain that still sends would be a lie.
140 * transfer() is not static either, though with SPI it uses no member: bit
141 * banging needs the pins. clang-tidy reports all three, and each definition
142 * answers it with a NOLINT.
143 */
144 void StartTransmission();
145 void StopTransmission();
146 void Transfer(uint8_t register_address, uint8_t register_value);
147#if (MAXMATRIX_USE_SPI == STD_OFF)
148 void ShiftOut(uint8_t value);
149#endif
150 static void WritePin(uint8_t port, uint8_t mask, bool high);
151
152 public:
160 Chain(uint8_t data_in_pin, uint8_t chip_select_pin, uint8_t clock_pin);
161
163 MAXMATRIX_NODISCARD uint8_t GetDataInPin() const { return data_in_pin_; }
164
167 return chip_select_pin_;
168 }
169
171 MAXMATRIX_NODISCARD uint8_t GetClockPin() const { return clock_pin_; }
172
179 void SetDataInPin(uint8_t data_in_pin) { data_in_pin_ = data_in_pin; }
180
187 void SetChipSelectPin(uint8_t chip_select_pin) {
188 chip_select_pin_ = chip_select_pin;
189 }
190
197 void SetClockPin(uint8_t clock_pin) { clock_pin_ = clock_pin; }
198
206 void Init(uint8_t number_of_modules);
207
218 void WriteRegisterAll(uint8_t register_address, uint8_t register_value,
219 uint8_t number_of_modules);
220
234 void WriteRegisterEach(uint8_t register_address, span<Byte const> buffer,
235 uint8_t column);
236};
237
238} // namespace internal
239} // namespace max_matrix
240
241#endif // MAXMATRIX_SRC_MAX7219_CHAIN_H_
A byte of raw data, as a column of dots, which is no number.
The attributes of a later standard, as macros, where the compiler has them.
#define MAXMATRIX_NODISCARD
Marks a function whose result must not be dropped: the compiler warns where it is.
Definition MaxMatrixAttributes.h:37
Configuration of the MaxMatrix library.
MAXMATRIX_NODISCARD uint8_t GetDataInPin() const
Returns the pin DIN of the chain is connected to.
Definition Chain.h:163
MAXMATRIX_NODISCARD uint8_t GetClockPin() const
Returns the pin CLK of the chain is connected to.
Definition Chain.h:171
void SetChipSelectPin(uint8_t chip_select_pin)
Sets the pin CS of the chain is connected to.
Definition Chain.h:187
void WriteRegisterEach(uint8_t register_address, span< Byte const > buffer, uint8_t column)
Writes the same register of every MAX7219, each with its own value: one column of every module,...
MAXMATRIX_NODISCARD uint8_t GetChipSelectPin() const
Returns the pin CS of the chain is connected to.
Definition Chain.h:166
Chain(uint8_t data_in_pin, uint8_t chip_select_pin, uint8_t clock_pin)
Makes the chain at these pins; nothing is sent until Init().
void Init(uint8_t number_of_modules)
Sets the pins up, and every MAX7219 to drive an 8x8 matrix.
void SetDataInPin(uint8_t data_in_pin)
Sets the pin DIN of the chain is connected to.
Definition Chain.h:179
void SetClockPin(uint8_t clock_pin)
Sets the pin CLK of the chain is connected to.
Definition Chain.h:197
void WriteRegisterAll(uint8_t register_address, uint8_t register_value, uint8_t number_of_modules)
Writes the same register of every MAX7219, with the same value.
A view of size() elements that another owns: a font, a bitmap, a text or a buffer.
Definition span.h:64
The registers of the MAX7219 and their values, as Matrix::RegisterWrite() takes them.
Definition Chain.h:27
constexpr uint8_t kDecodeModeCodeBDecodeDigit7To0
Definition Chain.h:67
constexpr uint8_t kDigit5Address
Definition Chain.h:43
constexpr uint8_t kIntensityMinValue
Definition Chain.h:71
constexpr uint8_t kDisplayTestNormalOperation
Definition Chain.h:101
constexpr uint8_t kDigit3Address
Definition Chain.h:39
constexpr uint8_t kDecodeModeCodeBDecodeDigit0
Definition Chain.h:63
constexpr uint8_t kScanLimitAddress
Definition Chain.h:53
constexpr uint8_t kDisplayTestAddress
Definition Chain.h:57
constexpr uint8_t kDigit0Address
Definition Chain.h:33
constexpr uint8_t kScanLimitDisplayDigit0To5
Definition Chain.h:87
constexpr uint8_t kDecodeModeAddress
Definition Chain.h:49
constexpr uint8_t kShutdownModeNormalOperation
Definition Chain.h:97
constexpr uint8_t kDigit1Address
Definition Chain.h:35
constexpr uint8_t kScanLimitDisplayDigit0To6
Definition Chain.h:89
constexpr uint8_t kScanLimitDisplayDigit0
Definition Chain.h:77
constexpr uint8_t kDecodeModeCodeBDecodeDigit3To0
Definition Chain.h:65
constexpr uint8_t kIntensityAddress
Definition Chain.h:51
constexpr uint8_t kIntensityMaxValue
Definition Chain.h:73
constexpr uint8_t kShutdownModeShutdownMode
Definition Chain.h:95
constexpr uint8_t kDecodeModeNoDecode
Definition Chain.h:61
constexpr uint8_t kDisplayTestDisplayTestMode
Definition Chain.h:103
constexpr uint8_t kScanLimitDisplayDigit0To3
Definition Chain.h:83
constexpr uint8_t kDigit7Address
Definition Chain.h:47
constexpr uint8_t kScanLimitDisplayDigit0To4
Definition Chain.h:85
constexpr uint8_t kShutdownAddress
Definition Chain.h:55
constexpr uint8_t kDigit6Address
Definition Chain.h:45
constexpr uint8_t kScanLimitDisplayDigit0To2
Definition Chain.h:81
constexpr uint8_t kDigit4Address
Definition Chain.h:41
constexpr uint8_t kDigit2Address
Definition Chain.h:37
constexpr uint8_t kScanLimitDisplayDigit0To7
Definition Chain.h:91
constexpr uint8_t kNoOpAddress
Definition Chain.h:31
constexpr uint8_t kScanLimitDisplayDigit0To1
Definition Chain.h:79
Elements that lie elsewhere, reached by index within their size, as std::span.