Displaying Images

FREE-WILi allows you to display images on the screen. FREE-WILi has some built in images but a more interesting user interface can be done with custom images.

Custom images can be loaded into the FREE-WILi display processor file system. Then, using the API they can be displayed on command. The images should be stored in the "images" directory.

Converting Images to FWI Format

Custom images must be converted to the FREE-WILi Image (FWI) format, which is a bitmap compatible with the 565 color display used. This direct compatibility allows fast display of images without runtime conversion.

There are two ways to convert your images:

1. Use the Web-Based PNG to FWI Converter

Easily convert your .png files using our online tool:
👉 https://freewili.com/png-to-fwi-converter/

2. Use the Python Script (fw_image.py)

A Python script named fw_image.py is available on the FREE-WILi GitHub. It allows you to convert .jpg or .png images into .fwi files.

Syntax of fw_image.py:

python3 fw_image.py source_image.png output_image.fwi

Displaying Images from the ROM

The FREE-WILi ROM contains a number of images you can use for your own applications. The following file lists the ROM images available.

FwRomAssets.pdf

pdf

Displaying Images from the API

The GUIAPI has a function for displaying images from files or ROM. Here we display cookie.fwi in the images directory.

obGUIAPI.addControlPictureFromFile(iPanelNumber,PANEL_PICTURE_COOKIE,20,160,"cookie",1 );

Cookie.fwi shown on FREE-WILi screen.

To Display from ROM you can use this API

void addControlPicture(int iPanelIndex, int iControlIndex, int iX, int iY,
                   int iPictureId, int iVisible)

Structure of Image File

The file consists of a binary header describing the file and the pixels. The pixels are stored in 16 bit 565 format. The 565 16 bit color format is a common format in embedded systems. There are a number of resources online that discuss this format. The best way to understand the format is to review the source code of fw_image.py

Binary Header

The beginning of the file is below. Ints are 32 bit here and shorts are 16 bit.

char szOut[8] = { "FW01IMG" };
unsigned int iImageFlags;
unsigned int iImageTotalPixelCount;
unsigned short iImageWidth;
unsigned short iImageHeight;
unsigned short iImageTransparentColor;
unsigned short iImageId;

Pixel Data

The pixel data is described below. A 16 bit unsigned short contains the pixel with varying intensities for Red, Green, and Blue. The final value is byte swapped.

rgb = (int(R)<<11) | (int(G)<<5) | int(B)
rgb = ((rgb << 8) & 0xFF00) | ((rgb >> 8) & 0xFF);