(For Arduino and Energia)
This library is adaptation from https://github.com/MartyMacGyver/OLED_SSD1322
This library provides support for the HGS2561281 256x128 display which uses two SSD1322 chips to control two 256x64 OLED displays. Currently only SPI is supported. This library also contains an application to convert images to 4-bit image useable by this display. The application can also generate a font. The application can be found under ImgToOledBitmap/release/ folder.
- Drawing a rectangle with colors from 0x0 to 0xF
- Drawing a string of characters with user defined font
- Drawing images
- X coordinates must be in multiple of 4, this affects X position and width of images, fonts, and shapes - rectangles. Y coordinates are not affected. (For example, drawing a rectangle on position [50, 50] will not be displayed properly (50 mod 4 != 0) instead draw it on [48, 50])
- Download HGS2561281 library
- Find "HGS2561281-master" folder inside the ZIP archive and copy it to
My Documents\Arduino\libraries
- Rename "HGS2561281-master" to "HGS2561281"
- Download HGS2561281 library
- Find "HGS2561281-master" folder inside the ZIP archive and copy it to
My Documents\Energia\libraries
- Rename "HGS2561281-master" to "HGS2561281"
#include <SPI.h> // Sometimes Arduino and Energia forgets to include SPI dir if this line is not present
#include <HGS2561281.h>
// Instance to our LCD
// You will need to replace the arguments
// with the correct pin numbers
HGS2561281 lcd(RESET, CS1, CS2, DC, WR);
void setup(){
// This may be needed by Energia...
pinMode(CSLK_PIN, OUTPUT);
pinMode(SDIN_PIN, OUTPUT);
// Initialise the display
lcd.init();
// Clear pixels
lcd.clear();
// Now we can draw things!
// Set the draw color to 0xF (15)
// 0xF is a default color
lcd.setDrawColor(0xF);
// Draw single rectangle at pos [16, 10] with a size of [32, 12]
lcd.drawRectangle(16, 10, 32, 12);
}
void loop(){
}
To display an image, you will need to convert your image to a grayscale 4-bit unsigned char
array. Each unsigned char
must contain two pixels. You can use to following Python script to convert any image to a grayscale 4-bit array that will appear in the stdout.
# Install PIL as:
# python3 -m pip install Pillow
from PIL import Image
import sys
HEX = ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f']
def main():
if len(sys.argv) != 2:
print('Invalid number of arguments!')
print(f'Usage: {sys.argv[0]} input.png')
sys.exit(1)
img = Image.open(sys.argv[1]).convert('L')
pixels = img.load()
width, height = img.size
if width % 2 != 0:
print('Image width must be multiple of 2')
for y in range(0, height):
for x in range(0, width, 2):
a = pixels[x, y] >> 4
b = pixels[x + 1, y] >> 4
print(f'0x{HEX[a]}{HEX[b]}, ', end='')
print('')
if __name__ == "__main__":
main()
Usage of above script:
> python convert_to_4bit.py letter_a.png > output.txt
Then, define your image in your source code as:
// Assuming the image is 16x16 pixels in size
// sizeof = width * height / 2
// We divide by 2 because one byte contains two 4-bit pixels!
static const unsigned char pixels[ 16 * 16 / 2 ] = {
// the stdout from the python script above
};
And render your image as:
// Assuming the image is 16x16 pixels in size
lcd.drawPixels(posX, posY, 16, 16, pixels)
You can find more information in this issue: HGS2561281/issues/2
(An example is provided in the example folder)
First we need to generate 4-bit image... for that we need the convertor!
- Find "ImgToOledBitmap/release" folder inside the library folder.
- Copy or move it to a safe place.
To generate 4-bit image with:
- Open Command Line Terminal (CMD)
- Use CD command to go to the directory where
ImgToOledBitmap.exe
is located - Run:
ImgToOledBitmap.exe -i path_to_image/your_image_name.png
(notice the -i option!) - A new file will be generated
your_image_name-oledimg.txt
containing 4-bit pixel array - Copy this pixel array
static const char your_image_name_pixels[] = { ... };
found in the generated txt file to your Arduino/Energia sketch. - Use
lcd.drawPixels(posX, posY, width, height, pointer to pixel array)
function to draw the pixels. Note that the width and height are the dimensions of the image. For example, if the original image dimensions are 128x128, the pixel array will be size of 128x128 / 2 bytes, then to draw the image at [0, 0], use it like this:lcd.drawPixels(0, 0, 128, 128, your_image_name_pixels);
Supported image formats: PNG, BMP, PBM, TGA, TIFF Supported pixel formats: 8bpp (Grayscale), 24bpp (RGB), 32bpp (RGBA)
RGB/RGBA images will be automatically converted to grayscale
(An example is provided in the example folder)
This process works almost the same as generating an image... First, you need to generate an image containing all characters of your font. (Google "bitmap font"). This image needs to be 16x16 or 16x8 grid of ASCII characters. The characters must start from 0 (left top) up to 255 (bottom right) and needs to be placed in the grid. The generated bitmap dimensions need to be in power of two! (For example, 128x128, 256x256, 512x512).
To generate 4-bit pixel array out of bitmap font:
- Open Command Line Terminal (CMD)
- Use CD command to go to the directory where
ImgToOledBitmap.exe
is located - Run:
ImgToOledBitmap.exe -f path_to_font/your_font.png
(notice the -f option!) - A new file will be generated
your_font-oledfont.txt
containing 4-bit pixel array - Copy this pixel array
static const char your_font_font[] = { ... };
found in the generated txt file to your Arduino/Energia sketch. - Use
lcd.drawString(posX, posY, fontPixels, charWidth, string)
to draw a string. Note that the "charWidth" is the width of a single character (width_of_your_bitmap_font / 16 = char_width, for example, if you are converting a 128x128 bitmap font, then the charWidth is 8 pixels).