Version: 1.0
This is a library for MAX7219 and 7-segments displays (no led matrix) to be used with Microchip(R) PIC(R) microcontrollers.
Library is licensed under AGPLv3 license.
You can read how MAX7219 works on my blog in this page => It's in italian language but I've included a translation service on the right bar where you can select your language.
Folowing this link you can read an article, in italian language, about this library. If you don't speak italian this link is not necessary since usage instructions in english are just here.
This is a video showing the demo:
The demo is made using the PIC16F15376 Curiosity Nano. You can download the demo here
Library is tested with Microchip PIC Microcontrollers up to 32MHz. The critical part is that MAX7219 needs a minimum pulse duration of 50nS. With a 32MHz 8bit PIC there are about 125nS pulse durations.
Istruction cycle of a PIC12/16/18 is 4 clock cycles (4/Fosc). Assuming Fosc=32MHz we have T=31.25nS so instruction cycle is 4 * T=125nS.
In this case, assuming an instruction cycle of 4/Fosc, I think library may work up to 80MHz. If you notice library does not work with your PIC microcontroller (16 or 32 bit, or 8bit with a Fosc greater than 32MHz), make some calculations as I've done above and if your instruction cycle is less than 50nS, insert delays in the MAX7219_send function between and after any pulse.
MAX7219 needs 3 GPIOs (General Purpose Input/Output).
Library is currently tested for a single MAX7219 (8 Digits) and only for 7-segment displays. Led Matrix are not supported.
Digits are numbered from right (1) to left (8), so digits are 1-based index (MAX7219 starts from digit 1).
Strings are normally left-aligned. You can pad strings using the function MAX7219_lputs instead of MAX7219_puts.
Numbers are right-aligned. You can pad numbers using a parameter in the function that prints number.
It's reccomended to use the MPLAB(R) Code Configurator. Choose 3 pins, make them digital outputs and rename them as: MAX_DAT, MAX_CLK and MAX_LAT:
- MAX_DAT : connected to MAX7219 DIN pin (pin n°1)
- MAX_CLK : connected to MAX7219 CLK pin (pin n°13)
- MAX_LAT : connected to MAX7219 LOAD/!CS pin (pin n°12)
Library uses the PIN_SetLow() and PIN_SetHigh() functions created by the Code Configurator, so the main library file (MAX7219sz.c) includes the "mcc_generated_files/pin_manager.h" file. The device_config.h file is also included because in this header is defined the XTAL_FREQ value, used by XC8 builtin delay functions.
If you've never used the MPLAB Code Configurator it's the good time for start. You can read a tutorial I've made about it
After you've defined pins, you can include MAX7219sz.h and MAX7219.c in your project and make changes in the header library file (MAX7219sz.h):
- change DIGITS value to fit your display. Actually the library is tested only for 8 digits. If your display uses less than 8 digits, you must be aware about the limit resistor and intensity register, in other cases your display and MAX7219 can be damaged.
- change MAXINTENSITY value. The maximum value is 9. If you use less than 8 digits is better lower this value.
- if you want to use different delay libraries, change DELAYCURSOR, DELAYSCROLL and DELAYBLINK macros that are used respectively for the speed of cursor effect in the MAX7219_puts function, the scrolling speed in the MAX7219_scroll function and the blinking speed in the MAX7219_blink function. You can also change the delay values in those macros if you desire different writing/scrolling/blinking speeds.
- change eventually SCROLLBUFFER value if you want to use scrolling effect with less chars and then saving some memory. See MAX7219_scroll function description for further informations.
void MAX7219_init(void)Initialize the MAX7219 using the number of digits defined by constant DIGITS in library header file, NODECODE mode, max brightness.
This function also turns off the Test mode, so if you want to start your application performing a display test (as the demo does) you can use the MAX7219_test function first, give some delay and then call this initialization function.
void MAX7219_clear(void)Clears all digits for both DECODE and NODECODE modes.
Display remains turned on: only internal shift register of MAX7219 is erased.
void MAX7219_clearc(void)Clears all digits using the cursor effect from right to left starting from the most right used digit.
This function is used only in the NODECODE mode.
Display remains ON: only internal shift register of MAX7219 is erased.
void MAX7219_lclearc(uint8_t startpos)Clears all digits using the cursor effect from right to left starting from the most right used digit until starpos digit.
This function is used only in the NODECODE mode.
Display remains ON: only internal shift register of MAX7219 is erased.
This function is used for deleting text inserted by the MAX7219_lputs function.
void MAX7219_send(uint8_t reg, uint8_t dat)Sends a byte to the selected register.
- reg: MAX7219 register to write in
- dat: data to be written in the register
This function is also used for writing symbols in the NODECODE mode: in that case the dat value must define wich segments must be turned on. Example:
MAX7219_send(8,SEGA|SEGB|SEGF|SEGG|SEGE|SEGC) => writes the A letter on the 8th digit (the most-left digit) by turning all segments but segment D and comma/point.
void MAX7219_putch(uint8_t digit, char ch, bool point)Writes a single ASCII char on the selected digit.
- digit: digit number to write on (from 1 to 8)
- ch: char to write (ex.: 'g', '1', '.' ecc) - you must use single quote mark (ASCII 39)
- point: will turn on (true) or off (false) the comma/decimal point on the selected digit
You can use both uppercase and lowercase letters, in every case letters will be converted to use the defined font in the library header. You can write all letters but W,X that can't be effectively rendered on 7-segments displays. Some other chars will look a bit weird (ex.: the 'Z' is rendered as 2) but..hey... it's a 7-segment display!
void MAX7219_numch(uint8_t digit, uint8_t n, bool point)Writes a number as char on the selected digit.
- digit: digit number to write on (from 1 to 8)
- n: number to write, inserted as integer from 0 to 9
- point: will turn on (true) or off (false) the comma/decimal of the selected digit
void MAX7219_setDecode(void)Turns on the DECODE Mode (BCD Code B). After you've called this function you can't use the user-defined font and you can only use the MAX7219_send function for writing numbers from 0 to 9 and H,E,L,P letters and minus sign. See the attached datasheet for further informations.
void MAX7219_setNoDecode(void)Turns on the NODECODE mode (you must use chars and numbers as defined in the library header). This is the default mode.
void MAX7219_setIntensity(uint8_t val)Set the display brightness. Any value higher than MAXINTENSITY will be converted in MAXINTENSITY. A value of 0 does not turns off the display visualization: digits are still visibile even them appears faint. If you want to slowly lower the luminosity making display disappearing, you must use the MAX7219_shutdown function at the final point. See the MAX7219_glow function for further informations.
- val: integer value from 0 (lowest) to MAXINTENSITY (highest)
void MAX7219_test(void)Activate the test mode (all leds on). For exiting the test mode you must recall the MAX7219_init function since the test mode overwrites all settings.
void MAX7219_shutdown(bool yesno)Turns on or off the display visualization. After turning off, MAX7219 shift register content is not deleted, so digits data are retained and will appear again after you turn on the display, the MAX7219_blink function uses this feature.
- yesno: turns off (true) or on (false) the display visualization
void MAX7219_puts(const char *s, bool cursor)Writes a constant string on the display using the font defined in the library header, using or no the cursor visual effect, starting from the most-left digit. The string will be printed from left to right and the last used digit will be saved in RAM memory for the MAX7219_clearc and MAX7219_lclearc functions.
- s: string to write (ex.: "hello") - you must use the double quotation mark (ASCII 34)
- cursor: display the string using the cursor effect (true) or make string appearing immediately without visual effects (false)
If string is bigger than DIGITS chars, will be truncated.
void MAX7219_lputs(const char *s, bool cursor, uint8_t startpos)Writes a constant string on the display using the font defined in the library header, using or no the cursor visual effect, starting from a specified digit. The string will be printed from left to right and the last used digit will be saved in RAM memory for the MAX7219_clearc and MAX7219_lclearc functions.
- s: string to write (ex.: "hello") - you must use the double quotation mark (ASCII 34)
- cursor: display the string using the cursor effect (true) or make string appearing immediately without visual effects (false)
- startpos: digit from which starting to print
String is truncated after the digit 1.
uint8_t MAX7219_putn(int32_t num, uint8_t decimals, uint8_t rightspace)Writes an integer by eventually turning on the comma/decimal point on a certain digit for showing a decimal number and eventually leaving some space on the right if you want to put a simbol or simply left-align the number. The minus sign will added near the most-left digit if needed. Function uses a 32bit signed integer but actually the number of visualized digits is limited in the library to 8 digits.
- num: integer from -9'999'999 to 99'999'999, bigger or lower numbers will not be properly visualized since library is limited to 8 digits
- decimals: if this parameter is greater than 0 function will turn on the comma/decimal point leaving this number of digits after the comma/decimal point. Set this parameter to 0 if you don't want to visualize a decimal number.
- rightspace: places to leave free on the most-right position. Put 0 if you want to right-align the number.
- Returns: position of most-left printed digit (minus sign included).
Numbers are right-aligned, you can use rightspace parameter for move them on the left or for add a symbol (ex.: °C) on the right of displayed number.
decimals is used for fixed-point decimal notation. So if you must print a decimal number, you can multiply it by a power of 10 to transform it in an integer and then set the number of decimals to show. Example: if you must print 24.1, you must print 241 and set decimals to 1. If you must print 0.002, you must print 2 and set decimals to 3.
Function will also delete previous digits if the current number to be printed is smaller than previous one: if you print "99999" and after this you print "1" in other cases you'll visualize 99991 since normally the previous digits are retained in the MAX7219 shift register; the library keeps in mind the most-left used digit when printing numbers and will remove all previous digits until the new ones but without performing a display clear since this will cause flickering: only previous unused digits are cancelled.
uint8_t MAX7219_putun(uint32_t num, uint8_t decimals, uint8_t rightspace)This function is the same as MAX7219_putn but is used only for unsigned integers. Since the number of digits is limited to display width the advice is to use exclusively the MAX7218_putn function for every kind of number: better have only one function for avoiding confusion. This function will remain for future implementations (I hope) using more than one MAX7219 and is however recalled by the MAX7219_putn function for printing the integer part.
MAX7219_scroll(const char *s, bool appear, bool disappear)Writes a constant string using scrolling effect, from right to left
- s: String
- appear: choose to make appear immediately the first DIGITS chars of the string (false) or start the scroll with a blank display (or previous chars visualized that will be overwrited) making the string appear from the right one char at time (true)
- disappear: choose to make string scrolling out of the display leaving it blank (true) or make last DIGITS chars of the string remain visualized (false)
The maximum amount of string chars is given by:
SCROLLBUFFER-1-(DIGITS * appear)-(DIGITS * disappear).
If appear==true then DIGITS spaces will be added on the left of the string and other DIGITS spaces will be added on the right if you use the disappear flag. So if SCROLLBUFFER is 80, your display has 8 digits and you use both appear and disappear flags, you can write max 63 chars. One char is used for the '\0' string terminator.
void MAX7219_glow(uint8_t times)Glows the display using both Intensity and Shutdown registers.
- times: number of glowing cycles.
One glowing cycle is made of those events:
- start from maximum brightness (MAXINTENSITY)
- slowly decrement the brightness arriving to the minimum value (0)
- turn off the display visualization
- turn on the display visualization
- start from minimum brightness (0)
- slowly increment the brightness arriving to the maximum value (MAXINTENSITY)
void MAX7219_blink(uint8_t times)Blinks the display using the Shutdown register.
- times: number of blinking cycles.
A single blink is made turning off and then on the display.
If you want to support my free work, you can make me a gift from my amazon wishlist or give a reading here
Microchip, MPLAB, PIC are registered trademarks property of Microchip Technology Inc. Here is a list of Microchip Technology Inc. trademarks.
Maxim is a registered trademark property of Maxim Integrated Products Inc. Here is a list of Maxim Integrated Products trademarks.
All other brands or product names are property of their respective holders.