1  # The MIT License (MIT)
  2  #
  3  # Copyright (c) 2016 Philip R. Moyer and Radomir Dopieralski for Adafruit Industries.
  4  #
  5  # Permission is hereby granted, free of charge, to any person obtaining a copy
  6  # of this software and associated documentation files (the "Software"), to deal
  7  # in the Software without restriction, including without limitation the rights
  8  # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  9  # copies of the Software, and to permit persons to whom the Software is
 10  # furnished to do so, subject to the following conditions:
 11  #
 12  # The above copyright notice and this permission notice shall be included in
 13  # all copies or substantial portions of the Software.
 14  #
 15  # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16  # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17  # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18  # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19  # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 20  # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 21  # THE SOFTWARE.
 22  """
 23  `adafruit_max7219.max7219` - MAX7219 LED Matrix/Digit Display Driver
 24  ========================================================================
 25  CircuitPython library to support MAX7219 LED Matrix/Digit Display Driver.
 26  This library supports the use of the MAX7219-based display in CircuitPython,
 27  either an 8x8 matrix or a 8 digit 7-segment numeric display.
 28  
 29  See Also
 30  =========
 31  * matrices.Maxtrix8x8 is a class support an 8x8 led matrix display
 32  * bcddigits.BCDDigits is a class that support the 8 digit 7-segment display
 33  
 34  Beware that most CircuitPython compatible hardware are 3.3v logic level! Make
 35  sure that the input pin is 5v tolerant.
 36  
 37  * Author(s): Michael McWethy
 38  
 39  Implementation Notes
 40  --------------------
 41  **Hardware:**
 42  
 43  * Adafruit `MAX7219CNG LED Matrix/Digit Display Driver -
 44    MAX7219 <https://www.adafruit.com/product/453>`_ (Product ID: 453)
 45  
 46  **Software and Dependencies:**
 47  
 48  * Adafruit CircuitPython firmware for the ESP8622 and M0-based boards:
 49    https://github.com/adafruit/circuitpython/releases
 50  
 51  * Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
 52  
 53  **Notes:**
 54  #.  Datasheet: https://cdn-shop.adafruit.com/datasheets/MAX7219.pdf
 55  """
 56  # MicroPython SSD1306 OLED driver, I2C and SPI interfaces
 57  import digitalio
 58  from adafruit_bus_device import spi_device
 59  from micropython import const
 60  import adafruit_framebuf as framebuf
 61  
 62  __version__ = "0.0.0-auto.0"
 63  __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_MAX7219.git"
 64  
 65  # register definitions
 66  _DIGIT0 = const(1)
 67  _INTENSITY = const(10)
 68  
 69  
 70  class MAX7219:
 71      """
 72      MAX2719 - driver for displays based on max719 chip_select
 73  
 74      :param int width: the number of pixels wide
 75      :param int height: the number of pixels high
 76      :param object spi: an spi busio or spi bitbangio object
 77      :param ~digitalio.DigitalInOut chip_select: digital in/out to use as chip select signal
 78      :param baudrate: for SPIDevice baudrate (default 8000000)
 79      :param polarity: for SPIDevice polarity (default 0)
 80      :param phase: for SPIDevice phase (default 0)
 81      """
 82  
 83      def __init__(
 84          self, width, height, spi, cs, *, baudrate=8000000, polarity=0, phase=0
 85      ):
 86  
 87          self._chip_select = cs
 88          self._chip_select.direction = digitalio.Direction.OUTPUT
 89  
 90          self._spi_device = spi_device.SPIDevice(
 91              spi, cs, baudrate=baudrate, polarity=polarity, phase=phase
 92          )
 93  
 94          self._buffer = bytearray((height // 8) * width)
 95          self.framebuf = framebuf.FrameBuffer1(self._buffer, width, height)
 96  
 97          self.width = width
 98          self.height = height
 99  
100          self.init_display()
101  
102      def init_display(self):
103          """Must be implemented by derived class (``matrices``, ``bcddigits``)"""
104  
105      def brightness(self, value):
106          """
107          Controls the brightness of the display.
108  
109          :param int value: 0->15 dimmest to brightest
110          """
111          if not 0 <= value <= 15:
112              raise ValueError("Brightness out of range")
113          self.write_cmd(_INTENSITY, value)
114  
115      def show(self):
116          """
117          Updates the display.
118          """
119          for ypos in range(8):
120              self.write_cmd(_DIGIT0 + ypos, self._buffer[ypos])
121  
122      def fill(self, bit_value):
123          """
124          Fill the display buffer.
125  
126          :param int bit_value: value > 0 set the buffer bit, else clears the buffer bit
127          """
128          self.framebuf.fill(bit_value)
129  
130      def pixel(self, xpos, ypos, bit_value=None):
131          """
132          Set one buffer bit
133  
134          :param xpos: x position to set bit
135          :param ypos: y position to set bit
136          :param int bit_value: value > 0 sets the buffer bit, else clears the buffer bit
137          """
138          bit_value = 0x01 if bit_value else 0x00
139          self.framebuf.pixel(xpos, ypos, bit_value)
140  
141      def scroll(self, delta_x, delta_y):
142          """Srcolls the display using delta_x,delta_y."""
143          self.framebuf.scroll(delta_x, delta_y)
144  
145      def write_cmd(self, cmd, data):
146          # pylint: disable=no-member
147          """Writes a command to spi device."""
148          # print('cmd {} data {}'.format(cmd,data))
149          self._chip_select.value = False
150          with self._spi_device as my_spi_device:
151              my_spi_device.write(bytearray([cmd, data]))