A frambuffer driver for REPL console use; develop and debug display code without hardware.

[easytarget]

As part of testing v2 of my micropython font work I was doing a lot of work on my Laptop, and didnt want to carry a breadboard+devices about on the train etc.

So I wrote and evolved this REPL/console 'framebuffer display driver' based on the ubiquitous ssd1306.py driver.

You import and init() in place of your framebuffer driver, it logs out all calls to the display and shows an ascii-art represention of the frambuffer when show() is called and the framebuffer has changed.

This also turned out to be really useful for examining and testing alignment and positional stuff without needing to squint at a tiny display.. 👓. I'm sure others have done similar things before me, but it seems a shame not to share this

# Fremebuffer 'display' driver for REPL console
# 
# Emulates the interface of the 'classic' ssd1306.py display driver from:
#   https://github.com/stlehmann/micropython-ssd1306
# Provides a log output of all operations to the REPL console,
# Displays a ascii-art dump of the framebuffer when show() is called
# Allows debugging of display operations when running micropython on
#  desktop systems without needing an attached device (eg with thonny)
#
# Init requires just two options: width, height
# The screen will only be dumped when it has changed
#
# Four optional arguments are: 
# 'blocks=True' : use unicode blocks to do the display, otherwise use 'pure' ascii'
# 'clear=True'  : will send a clean screen sequence to the console before displaying.
# 'txt=False' : will suppress the ascii-art output completely.
# 'zero=<char>' and 'one=<char>' : will replace the ascii chars that represents zero and one.
#
# O.Carter, June 2024.
# This code is released as-is.
# The author disclaims any responsibility or liability arising from it's use.

from micropython import const
import framebuf

blks = ' ▄▀█'

class REPL_1306(framebuf.FrameBuffer):
    def __init__(self, width, height, txt=True, blocks=True, clear=False, zero='.', one='#'):
        self.width = width
        self.height = height
        self.txt = txt
        self._blocks = blocks
        self.clr = clear
        self.zero = zero
        self.one = one
        self.bytes = ((self.width - 1) // 8 ) + 1
        self.buffer = bytearray(self.bytes * self.height)
        self.lastbuf = ''
        self.format = framebuf.MONO_HLSB
        self._name = __name__
        super().__init__(self.buffer, self.width, self.height, self.format)
        self.init_display()

    def init_display(self):
        print('{}: init {}x{}'.format(self._name, self.width, self.height))
        self.fill(0)
        # self.show()

    def poweroff(self):
        print('{}: poweroff'.format(self._name))

    def poweron(self):
        print('{}: poweron'.format(self._name))

    def contrast(self, contrast):
        print('{}: contrast {}'.format(self._name, contrast))

    def invert(self, invert):
        print('{}: invert {}'.format(self._name, invert))

    def rotate(self, rotate):
        print('{}: rotate {}'.format(self._name, rotate))

    def show(self):
        if not self.txt:
            print('{}: show'.format(self._name))
            return
        if (self.buffer.hex() != self.lastbuf):
            if self.clr:
                print('\x1b[2J\x1b[H{}: show'.format(self._name))
            else:
                print('{}: show'.format(self._name))
            out = []
            for l in range(0,self.height):
                t = ''
                for p in range(0,self.bytes):
                    t += ('{:08b}'.format(self.buffer[(l*self.bytes)+p]))
                out.append(t[:self.width])
            self.lastbuf = self.buffer.hex()
            if self._blocks:
                if len(out) % 2 != 0:   # add a dummy height as needed
                    out.append('0' * self.width)
                for l in range(0,len(out),2):
                    for b in range(0,len(out[l])):
                        blk = out[l][b:b+1] + out[l+1][b:b+1]
                        print(blks[int(blk,2)],end='')
                    print()
            else:
                for l in out:
                    print(l.replace('0',self.zero).replace('1',self.one))
        else:
            if self.clr:
                print('show: ',end='')  # stop show() operations scrolling the screen when clear is set
            else:
                print('{}: show (framebuffer has not changed)'.format(self._name))

If you specify a large framebuffer it will obviously wreck havoc with your console output, I mostly used it with a 64x24 buffer, this produces an output that doesn't overflow the console everywhere.

There is an option to clear the console before the framebuffer is shown, and to change the zero character (default is ., good for debug work but a space looks better visually)

The source is in my repo at:
https://github.com/easytarget/microPyEZfonts/blob/main/drivers/repl_1306.py

Example

owen@sam: $ micropython
MicroPython v1.22.2 on 2024-03-22; linux [GCC 14.0.1] version
Use Ctrl-D to exit, Ctrl-E for paste mode
>>> import repl_1306
>>> d = repl_1306.REPL_1306(80,10)
repl_1306: init 80x10
repl_1306: show
................................................................................
................................................................................
................................................................................
................................................................................
................................................................................
................................................................................
................................................................................
................................................................................
................................................................................
................................................................................
>>> d.show()
repl_1306: show (framebuffer has not changed)
>>> d.text('Hello',10,2)
>>> d.show()
repl_1306: show
................................................................................
................................................................................
...........##..##...........###.....###.........................................
...........##..##............##......##.........................................
...........##..##...####.....##......##.....####................................
...........######..##..##....##......##....##..##...............................
...........##..##..######....##......##....##..##...............................
...........##..##..##........##......##....##..##...............................
...........##..##...#####...####....####....####................................
................................................................................
>>>

[easytarget]

While making unicode examples, and after seeing the use of block's in a similar function from @bdbarnett, I have added a (default) block mode for the screen representation: (it looks better in my terminal console than here in markdown)

$ micropython uniProj-repl.py 
repl_1306: init 80x37
my_b16_b = colors: 2, fg: 1, bg: 0, tr: -1, halign: center, valign: center, hgap: 2, vgap: 0
repl_1306: show
                          ▄▄ ▄▄            ▄▄                                   
                         ▄██ ██            ██   ▀▀▀▀▀██                         
                        ▄██ ██▀▀██▀▀██  ▄▄▄██▄▄▄   ▄█▀                          
                       ▄██ ▀▀▀  ██ ██▀    ██ ██   ▄█▀                           
                      ██▀█   ▄▄ ██ ▄▄     ██ ██▀▀▀██▀▀▀▀                        
                        ██   ██ ██ ██    ██▄▄█▀   ██                            
                        ██  ██▀ ██ ▀██   ▀▀▄█▀█▄  ██                            
                        ██      ██      ▄▄█▀      ██                            
                        ▀▀    ▀▀▀▀               ▀▀▀                            
                                                                                
               ▄▄▄▄▄▄                ▄▄      ██                                 
               ██   ██   ▄▄   ▄▄   ▄▄██▄▄    ██ ▄▄▄     ▄▄▄▄▄    ▄▄ ▄▄▄         
      ▄▄  ▄▄   ██▄▄▄█▀   ██   ██     ██      ██▀  ██   ██   ██   ██▀  ██        
      ██  ██   ██        ██   ██     ██      ██   ██   ██   ██   ██   ██        
      ██▄ ██   ██         ▀█▄█▀█     ██      ██   ██   ██   ██   ██   ██        
      ██ ▀ ▀   ▀▀             ██      ▀▀▀    ▀▀   ▀▀    ▀▀▀▀▀    ▀▀   ▀▀        
      ▀▀                  ▀▀▀▀▀                                                 

'pure' ascii output is still supported if the unicode blocks above give issues.

• Note; some devices (Andriod! I'm looking at you..) seem to have a funny definition of 'monospaced' that involves block characters being a different width to the space character. If the above looks wonky or crooked I'm afraid it's you.. not me ;-)

[Josverl]

looks quite useful for testing indeed.
Is there a simple way to compare against an expected output buffer, I hope that is just a str_a == str_b comparison ?

[easytarget]

That should be quite easy, yes. There is already a mechanism in there that saves the framebuffer as a string (using framebuffer.hex()) and then only re-displays when it's contents have changed.

the code that does that is super-simple

self.lastbuf = ''
#later
if (self.buffer.hex() != self.lastbuf):
    # show framebuffer
    self.lastbuf = self.buffer.hex()

(I probably should be using a bytearray for efficiency, but this works and is easy to comprehend)

So; you would need a to generate a 'target' framebuffer to compare with, and encode that to hex(), but otherwse adding a test for a expected buffer should be easy.

This is just using a standard framebuffer method; so it could also be added to any display driver or as a wrapper around display.show() in the code under test..