MAX7219 7-Segment Display

The max7219 display platform allows you to use MAX7219 7-segment display drivers ( datasheet, hobbycomponents) with ESPHome. Please note that this integration is only for 7-segment display, not matrix configurations.

MAX7219 7-Segment Display.

As the communication with the MAX7219 is done using SPI for this integration, you need to have an SPI bus in your configuration with both the mosi_pin set (miso_pin is not required). Connect VCC to 3.3V (the manufacturer recommends 4+ V, but 3.3V seems to work fine), DIN to your mosi_pin and CS to your set cs_pin and finally GND to GND.

You can even daisy-chain multiple MAX7219s by connecting the DOUT of the previous chip in the chain to the next DIN. With more than ~3 chips the 3.3V will probably not be enough, so then you will have to potentially use a logic level converted.

# Example configuration entry
spi:
  clk_pin: D0
  mosi_pin: D1

display:
  - platform: max7219
    cs_pin: D2
    num_chips: 1
    lambda: |-
      it.print("01234567");

Configuration variables:

• cs_pin (Required, Pin Schema): The pin you have the CS line hooked up to.

• num_chips (Optional, int): The number of chips you wish to use for daisy chaining. Defaults to 1.

• intensity (Optional, int): The intensity with which the MAX7219 should drive the outputs. Range is from 0 (least intense) to 15 (the default).

• lambda (Optional, lambda): The lambda to use for rendering the content on the MAX7219. See Rendering Lambda for more information.

• update_interval (Optional, Time): The interval to re-draw the screen. Defaults to 1s.

• spi_id (Optional, ID): Manually specify the ID of the SPI Component if you want to use multiple SPI buses.

• id (Optional, ID): Manually specify the ID used for code generation.

• reverse_enable (Optional, boolean): For some displays the order of the chips is reversed so you’ll see “56781234” instead of “12345678”. This option will adjust the output to compensate. Defaults to false.

Rendering Lambda

The MAX7219 has a similar API to the fully fledged Display Rendering Engine, but it’s only a subset as the MAX7219 7-segment displays don’t have a concept of individual pixels. In the lambda you’re passed a variable called it as with all other displays. In this case however, it is an MAX7219 instance (see API Reference).

The most basic operation with the MAX7219 is wiring a simple number to the screen as in the configuration example at the top of this page. But even though you’re passing in a string (here "01234567"), ESPHome converts it into a representation that the MAX7219 can understand: The exact pixels that should be turned on. And of course, not all characters can be represented. You can see a full list of characters below.

Each of the three methods (print, printf and strftime) all optionally take a position argument at the beginning which can be used to print the text at a specific position. This argument is 0 by default which means the first character of the first MAX7219. For example to start the first character of your text at the end of the first MAX7219, you would write it.print(7, "0");.

Also note that the . (dot) character is special because when ESPHome encounters it in the string the dot segment of the previous position will be enabled.

display:
  - platform: max7219
    # ...
    lambda: |-
      // Print 0 at position 0 (left)
      it.print("0");
      // Result: "0       "

      // Print 1 at position 1 (second character)
      it.print(1, "1");
      // Result: "01      "

      // Let's write a sensor value (let's assume it's 42.1)
      it.printf(3, "%.1f", id(my_sensor).state);
      // Result: "01 42.1  " (the dot will appear on the "2" segment)

      // Overwrite the previous content with blank
      it.print("        ");
      // Print a right-padded sensor value with 0 digits after the decimal
      it.printf("SENS%4.0f", id(my_sensor).state);
      // Result: "SENS  42"

      // Print the current time
      it.print("        ");
      it.strftime("%H.%M.%S", id(esptime).now());
      // Result for 10:06:42 -> "10.06.42  "

      // Change the display intnsity based on another id.
      // Value should be from 0-15.
      it.set_intensity(id(my_brightness));

Please see Formatted Text for a quick introduction into the printf formatting rules and Displaying Time for an introduction into the strftime time formatting.

All 7-Segment Characters

MAX7219 Representation	Character
	(space)
	.
	!
	0, O
	1, I
	2, Z
	3
	4
	5, S, s
	6
	7
	8
	9
	H
	(, [, C
	{
	), ]
	}, T, t
	\`
	'
	"
	@
	?
	,, i
	%
	*
	:
	;
	A, a
	B, b
	D, d
	E, e
	F, f
	G, g
	J, j
	L, l
	N, n
	P, p
	Q
	R, r
	U, V
	W
	Y, y
	-
	_
	=
	|
	c
	h
	o
	u, v
	~

Note

Original 7-segment display base image taken from Wikipedia at https://de.wikipedia.org/wiki/Datei:7_Segment_Display.svg by user h2g2bob under Creative Commons BY-SA 3.0 and modified for this documentation.

See Also

• Display Component

• API Reference

• MAX7219 Library by Nick Gammon

• Edit this page on GitHub