epd4in2
=======

.. py:module:: epd4in2

.. autoapi-nested-parse::

   Driver for the Waveshare 4.2" e-Paper module V2 / Rev2.2 (SSD1683, 400x300 b/w).

   Command sequence follows Waveshare's epd4in2_V2 reference driver. The
   image is a MONO_HLSB buffer (bit set = white), e.g. a framebuf.FrameBuffer's
   bytearray, sent as is.

   Pins are injected machine.Pin-like objects, so the driver runs on the host
   against fakes. `pwr` is optional: Rev2.2 modules switch the panel supply
   with it, and `EPD.power_off` cuts it (see `defaults.DISPLAY_OFF_IN_SLEEP`).

   **Black/white RAM and "red RAM".** The SSD1683 controller has two image
   memories of one bit per pixel. The controller family also drives
   black/white/red panels, where the second memory holds the red layer;
   hence its name in the datasheet, "red RAM". On this black/white panel it
   has another use: a full refresh (`EPD.display`) only shows the
   black/white RAM, while a partial refresh (`EPD.display_partial`,
   `EPD.display_band`) treats the red RAM as the image the panel shows now
   and drives only the pixels in which the black/white RAM differs from it.
   That is why it flashes less and is faster, and why it goes wrong if the
   red RAM does not hold what the panel really shows: pixels the controller
   believes unchanged are left as they are.

   The red RAM cannot be relied on after `EPD.init`: on a Rev2.2 module it no
   longer held the previous image on the next wake (partial updates left old
   and new digits overlaid), whether through the reset or the deep sleep in
   between. A partial refresh therefore
   needs the image the panel shows passed in as the old one, which the driver
   writes into the red RAM first; the firmware keeps a copy on flash for that
   (`screen`). After each update the driver stores the new image in the red
   RAM as the old one for a following update without `EPD.init`.



Attributes
----------

.. autoapisummary::

   epd4in2.WIDTH
   epd4in2.HEIGHT
   epd4in2.BUFFER_SIZE


Classes
-------

.. autoapisummary::

   epd4in2.EPD


Module Contents
---------------

.. py:data:: WIDTH
   :value: 400


.. py:data:: HEIGHT
   :value: 300


.. py:data:: BUFFER_SIZE
   :value: 15000


.. py:class:: EPD(spi, cs, dc, rst, busy, pwr=None, sleep=time.sleep)

   Driver for the 4.2" SSD1683 panel on injected SPI and pins.


   .. py:attribute:: spi


   .. py:attribute:: cs


   .. py:attribute:: dc


   .. py:attribute:: rst


   .. py:attribute:: busy


   .. py:attribute:: pwr
      :value: None



   .. py:attribute:: sleep


   .. py:method:: wait_until_idle(timeout_s=30)

      Wait while BUSY is high, that is while the controller works.

      :raises OSError: If the controller stays busy for more than `timeout_s`.



   .. py:method:: reset()

      Reset the controller by its pin (this also ends its deep sleep).



   .. py:method:: init()

      Power up, reset and configure for full-screen updates.



   .. py:method:: display(buffer)

      Full refresh with `buffer` (BUFFER_SIZE bytes, MONO_HLSB).



   .. py:method:: display_band(old, new, y0, y1)

      Partial refresh of the full-width rows y0..y1 without flashing.

      `old` must be what the panel shows there now and `new` the target
      image, both (y1 - y0 + 1) * WIDTH // 8 bytes (MONO_HLSB). Rows
      outside the band are not touched.



   .. py:method:: display_partial(buffer, old=None)

      Refresh the whole screen without flashing.

      The update compares against the red RAM, which must hold what the
      panel shows. Pass that image as `old`: after `init` the red RAM is
      blank, and pixels would then only turn black, never back to white.
      Without `old` this works only for updates without an `init` since
      the previous one. Use a full `display` now and then against
      ghosting.

      :param buffer: The new image (BUFFER_SIZE bytes, MONO_HLSB).
      :param old: The image on the panel, if the controller lost it.

      :raises ValueError: If a buffer has the wrong size.



   .. py:method:: sleep_mode()

      Put the controller into deep sleep mode 1.

      The panel keeps its image. Call `init` before the next update; its
      red RAM may not hold the image any more afterwards.



   .. py:method:: power_off()

      Cut the panel supply (Rev2.2); the next update must be a full one.