.. module:: ssd1306

**************
SSD1306 Module
**************

This Module exposes all functionalities of Solomon SSD1306 OLED Display driver (`datasheet <https://www.olimex.com/Products/Modules/LCD/MOD-OLED-128x64/resources/SSD1306.pdf>`_).
.. class: SSD1306(drv, cs, rst, dc, clock=8000000):

    Creates an intance of a new SSD1306 using SPI.

    SSD1306SPI must be set to 'true' in the configuration yml

    :param spidrv: SPI Bus used '( SPI0, ... )'
    :param cs: Chip Select
    :param rst: Reset pin
    :param dc: Data/Command control pin
    :param clk: Clock speed, default 8MHz

    Example: ::

        from solomon.ssd1306 import ssd1306

        ...

        oled = ssd1306.SSD1306SPI(SPI0,D17,D16,D6)
        oled.init()
        oled.on()
    
.. class: SSD1306(drv, rst, clock=400000):

    Creates an intance of a new SSD1306 using I2C.
    
    SSD1306I2C must be set to 'true' in the configuration yml

    :param drv: I2C Bus used '( I2C0, ... )'
    :param rst: Reset pin, optional
    :param sa0: Device address bit, default 0
    :param clk: Clock speed, default 400kHz

    Example: ::

        from solomon.ssd1306 import ssd1306

        ...

        oled = ssd1306.SSD1306(I2C0,rst=D17,clock=400000)
        oled.init()
        oled.on(
    
.. method:: init(screen_width=96, screen_height=40)

        Initialize the SSD1306 setting all internal registers and the display dimensions in pixels.

        :param screen_width: width in pixels of the display (max 128); default 96
        :param screen_height: height in pixels of the display (max 64); default 40
        
        
.. method:: on()

        Turns on the display.

        
.. method:: off()

        Turns off the display.

        
.. method:: invert()

        Sets the display in complementary mode.

        
.. method:: normal()

        Sets the display in normal mode.

        
.. method:: set_contrast(contrast=0x7F)

        Sets the contrast of the display.

        :param contrast: value of the contrast to be set (from 0 to 255), default 0x7F

        
.. method:: clear()

        Clears the display.

        
.. method:: fill_screen()

        Fills the entire display (white screen in normal mode).

        
.. method:: fill_rect(x, y, w, h, fill=True)

        Draws a filled rectangular area in the screen.

        :param x: x-coordinate for left high corner of the rectangular area
        :param y: y-coordinate for left high corner of the rectangular area
        :param w: width of the rectangular area
        :param h: height of the rectangular area
        :param fill(*bool*): flag for filling the rectagnular area. If True draws white area, otherwise black area (in normal mode); default True

        .. note:: If the display is set in complementary mode (see :func:`invert()` function), fill flag set to True will draw black area and set to False will draw a white area.

        
.. method:: draw_img(image, x, y, w, h, fill=True)

        Draws the image passed in bytearray format as argument.

        :param bytes: bytearray composing the image to draw in the oled display
        :param x: x-coordinate for left high corner of the image
        :param y: y-coordinate for left high corner of the image
        :param w: width of the image
        :param h: height of the image
        :param fill(*bool*): flag for filling the image. If True draws image in standard color, otherwise draws the image in inverted color (display in normal mode); default True.

        .. note:: If the display is set in complementary mode (see :func:`invert()` function), fill flag set to True will draw the image in inverted color and set to False will draw the image in normal color.

        .. note :: To obtain a converted image in hex array format, you can go and use this `online tool <http://www.digole.com/tools/PicturetoC_Hex_converter.php>`_.
                   
                   After uploading your image, you can resize it setting the width and height fields; you can also choose the code format (HEX:0x recommended) and the color format
                   ("Black/White for all draw image function" recommended).
                   
                   Clicking on the "Get C string" button, the tool converts your image with your settings to a hex string that you can copy and paste inside a bytearray in your project and privide to this function.

        
.. method:: draw_pixel(x, y, fill=True)

        Draws a single pixel in the screen.

        :param x: pixel x-coordinate
        :param y: pixel y-coordinate
        :param fill(*bool*): flag for filling the pixel. If True draws white pixel, otherwise black pixel (in normal mode); default True

        .. note:: If the display is set in complementary mode (see :func:`invert()` function), fill flag set to True will draw black pixel and set to False will draw a white pixel.
        
        
.. method:: draw_text(text, x=None, y=None, w=None, h=None, align=None, fill=True)

        Prints a string inside a text box in the screen.

        :param text: string to be written in the display
        :param x: x-coordinate for left high corner of the text box; default None
        :param y: y-coordinate for left high corner of the text box; default None
        :param w: width of the text box; default None
        :param h: height of the text box; default None
        :param align: alignment of the text inside the text box (1 for left alignment, 2 for right alignment, 3 for center alignment); default None
        :param fill(*bool*): flag for filling the text. If True draws white text in black background, otherwise black text in white background (in normal mode); default True

        .. note:: If the display is set in complementary mode (see :func:`invert()` function), fill flag set to True will draw black text in white background and set to False will draw a white text in black background.
        
        .. note:: If only text argument is provided, an automatic text box is created with the following values:

                    * x = 0
                    * y = 0
                    * w = min text width according to the font
                    * h = max char height according to the font
                    * align = 3 (centered horizontally)
                    * fill = True