Stealthy Labs Blog

How to setup ZoneMinder on Ubuntu 24.04 LTS

Sun, 06 Oct 2024 00:00:00 -0400

If you are new to setting up your own video surveillance system for your home or office or a customer’s home or office, and want to truly own the setup, you want to use ZoneMinder, an open-source and free software that allows you to connect a variety of wired PoE cameras to a single software server that can manage all of them.

In this post, we outline how to set it up from scratch on Ubuntu 24.04 LTS.

REQUIREMENTS

For the server that runs ZoneMinder, you will need a minimum of 8GB RAM, 2-4 Intel CPUs, and a 1 TB hard drive. You can buy a used server on eBay and upgrade it, or use an older system that can run 24/7. We recommend using a server or workstation or desktop type product, since a laptop will run too hot and eventually die too early.

Disk is cheap, so buy the largest hard drives you can afford. Spinning hard drives are sufficient. You can optimize, like we did, where we used a smaller solid state drive (SSD) for the operating system and save the data such as video files and images to the regular hard drives.

Without 8GB RAM, ZoneMinder will struggle to process more than 2-3 cameras, especially, if you are setting them up for motion detection or record on motion detection.

INSTALLATION OF UBUNTU

If you have 2 or more disk drives in your server/workstation that will run ZoneMinder, and they are all of the same type, such as all of them are SSDs or spinning hard drives, then we recommend installing Ubuntu 24.04 LTS with LVM.

LVM will allow you to add more drives in the future without having to change the way the file system is.

If you have a single drive, we still recommend installing Ubuntu 24.04 LTS with LVM so that you can add more drives in the future.

If you have two separate drives, one SSD and one a spinning hard drive, we recommend installing Ubuntu 24.04 LTS on the SSD and then setting up LVM on the spinning hard drive(s), and we will configure ZoneMinder to use those hard drives for the storage of video files.

Guides for installing Ubuntu can be found here.

INSTALLING ZoneMinder

Once you have installed Ubuntu 24.04 LTS on your system and rebooted it, you can now install ZoneMinder.

Install Apache and MariaDB

The first step is to install apache2 and mariadb from the repository. Apache2 is a web server that will host the ZoneMinder code as a web application, and MariaDB is the database that ZoneMinder will use.

You will need root access to do this, and for now we will use the sudo command.

$ sudo apt -y install apache2 mariadb-server

Setup Users in MariaDB

We then setup a database user in MariaDB so that ZoneMinder can access it.

### login as root
$ sudo su -
#### login to mariadb
root$ mariadb
#### create the database that ZoneMinder needs
mariadb> CREATE DATABASE zm;
#### create a new user zmuser and a custom password for it
mariadb> CREATE USER zmuser@localhost IDENTIFIED BY 'change_this_passw0rd';
#### grant all privileges
mariadb> GRANT ALL PRIVILEGES ON zm.* TO zmuser@localhost;
mariadb> FLUSH PRIVILEGES;
#### exit
mariadb> exit;
root$ exit

NOTE: Make sure you note down what password you chose for the zmuser account as you will need to edit a configuration file later with that password.

Install ZoneMinder

Now we install the zoneminder package from the Ubuntu 24.04 LTS repository. As of this writing the version 1.36.33 gets installed from the Ubuntu package repositories. If you need newer versions please refer to the ZoneMinder website.

$ sudo apt -y install zoneminder
$ sudo chown -R www-data:www-data /usr/share/zoneminder/www/api

Configure ZoneMinder DB Password

Now you need to configure the MariaDB password you had set above for zmuser in the /etc/zm/zm.conf file. Change the variable ZM_DB_PASS=zmpass to be ZM_DB_PASS=change_this_passw0rd or whatever password you had chosen and save it.

Configure PHP Time Zone

On Ubuntu 24.04 LTS, as of this writing, the PHP version is 8.3.

Edit /etc/php/8.3/apache2/php.ini and change the date.timezone field to point to your time zone. Our timezone is America/New_York so we set it to the below. You may have to uncomment the default UTC timezone and change it.

date.timezone = America/New_York

Configure Apache2

When you installed ZoneMinder above using apt, the file /etc/apache2/conf-available/zoneminder.conf was created as part of it.

Edit this file and make it look like this so that all functionality regarding the API and the web interface work as expected:

ScriptAlias /zm/cgi-bin "/usr/lib/zoneminder/cgi-bin"
<Directory "/usr/lib/zoneminder/cgi-bin">
    Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
    AllowOverride All
    Require all granted
</Directory>

# Order matters. This alias must come first.
Alias /zm/cache "/var/cache/zoneminder"
<Directory "/var/cache/zoneminder">
    Options -Indexes +FollowSymLinks
    AllowOverride None
    <IfModule mod_authz_core.c>
       # Apache 2.4
       Require all granted
    </IfModule>
</Directory>

Alias /zm /usr/share/zoneminder/www
<Directory /usr/share/zoneminder/www>
  Options -Indexes +FollowSymLinks
  <IfModule mod_dir.c>
    DirectoryIndex index.php
  </IfModule>
</Directory>

# https://wiki.zoneminder.com/API#Example_Configuration_for_%2Fetc%2Fapache2%2Fconf-enabled%2Fzoneminder.conf
# For better visibility, the following directives have been migrated from the
# default .htaccess files included with the CakePHP project.
# Parameters not set here are inherited from the parent directive above.
<Directory "/usr/share/zoneminder/www/api">
   RewriteEngine on
   RewriteRule ^$ app/webroot/ [L]
   RewriteRule (.*) app/webroot/$1 [L]
   RewriteBase /zm/api
</Directory>

<Directory "/usr/share/zoneminder/www/api/app">
   RewriteEngine on
   RewriteRule ^$ webroot/ [L]
   RewriteRule (.*) webroot/$1 [L]
   RewriteBase /zm/api
</Directory>

<Directory "/usr/share/zoneminder/www/api/app/webroot">
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
    RewriteBase /zm/api
</Directory>

Now we enable the configurations in Apache2:

$ sudo su -
root$ a2enmod cgi
root$ a2enmod rewrite
root$ a2enmod expires
root$ a2enmod headers
root$ a2enconf zoneminder
root$ systemctl restart apache2.server
root$ systemctl enable zoneminder.service
root$ systemctl restart zoneminder.service
root$ systemctl status zoneminder.service
root$ netstat -vnatp | grep apache2
root$ exit

Web Interface

Now the web interface is setup and running, and you should be able to access it at http://localhost/zm/.

Once you are able to access it via the web browser, you can configure it for your needs by following the ZoneMinder documentation.

Configuring Additional Drives

If you chose the setup that we chose, where you install Ubuntu 24.04 LTS on an SSD and have several spinning hard drives where you want to save all the video files to, you have to follow the below steps.

We assume the external drives are setup using LVM. If you have not done that, then you can follow an LVM tutorial here.

Once your drive(s) have been created, mounted and available, make sure they are mounted at /zoneminder or a similar folder. For this example, we mounted the logical volumes at /zoneminder.

$ sudo su -
root$ ls /zoneminder
root$ mkdir -p /zoneminder/events
root$ mkdir -p /zoneminder/images
root$ chown -R www-data:www-data /zoneminder

Edit the /etc/zm/conf.d/01-system-paths.conf or similarly named file where the variable ZM_DIR_EVENTS is defined and change it to point to the folder created above. By default, it will point to /var/cache/zoneminder/events and we change it to /zoneminder/events.

ZM_DIR_EVENTS=/zoneminder/events

Restart everything.

root$ systemctl restart zoneminder

Using libev and libssd1306 to display a clock

Sun, 09 Aug 2020 00:00:00 -0400

In the earlier post demonstrating the use of libssd1306, we did not explain how one would use an event library such as libev to write an application that would use events to perform display changes. With this post we would like to show how to do that easily with a simple clock application that updates the OLED screen with the local time every second.

USING WITH `libev`

The example code is present in examples/libev_clock.c and is another application to test if the OLED screen is working or not. You can run it as below:

$ ./examples/test_libev_clock

This will run the application which will show that every second the local time in the format HH:MM:SS is being sent to the OLED screen using the I²C interface on the screen. With libssd1306 it is incredibly easy to make this display without handling any I²C commands yourself or even reading the datasheets.

UNDERSTANDING THE CODE

The code is well commented but we explain it in sections here.

Initializing the OLED screen

The first part of the main() function involves initializing the I²C device and initializing it. By default the device is assumed to be /dev/i2c-1 on the Raspberry Pi and the width x height is assumed to be 128x32 pixels. However, the user can pass the device path and the height as the command line arguments like below, for instance if they want to use a 128x64 pixel screen.

$ ./examples/test_libev_clock /dev/i2c-1 64

The initialization code will fail if the device path is incorrect or if the device is disconnected or other I²C failure has occurred. The application will exit if it cannot find the OLED screen on the I²C bus of the Raspberry Pi.

In addition to initializing the OLED screen, we also have to create a framebuffer object so that we can draw on the screen. Recall, from the earlier post, that we use a framebuffer object so that we can fill the screen contents in memory first before actually displaying it to the screen. This way we can support multiple framebuffer objects and are able to build several screens even before they have been displayed. This can be very useful for displaying games and motion picture images on the OLED screen. The I²C interface is slow, and being able to hold a lot of pre-drawn screens in memory can be very useful for good user experience.

Below is the section of the main() function doing the initialization of the display and also the creation of the framebuffer.

    ssd1306_i2c_t *oled = ssd1306_i2c_open(filename, 0x3c, 128, (uint8_t)height, NULL);
    if (!oled) {
        return -1;
    }
    /* initialize the I2C device */
    if (ssd1306_i2c_display_initialize(oled) < 0) {
        fprintf(stderr, "ERROR: Failed to initialize the display. Check if it is connected !\n");
        ssd1306_i2c_close(oled);
        return -1;
    }
    /* clear the display */
    ssd1306_i2c_display_clear(oled);
    /* create a framebuffer */
    ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(oled->width, oled->height, oled->err);

Setting up the event loop

We now need to setup the event loop and timer callback. We want the event loop to invoke a callback every 1 second. For our example code, we also have it timeout after 30 seconds so that we can run this application as part of our test suite by running make check.

The idea is that the callback will then calculate the local time in HH:MM:SS format, print it to the framebuffer and then display the framebuffer on the OLED screen all at once in the callback.

However, you may notice that the ssd1306 object is in the main() function and we need to make it available for the callback. One way is to make the object global, but we have used the void *data member of the ev_timer object to pass the pointers we need into the callback. This allows us to make the callback re-entrant.

A single void *data maybe good if we want to pass a single pointer variable, but if we want to pass multiple variables to the callback we need to create a local struct with all the variables and then pass a pointer to that struct to the callback. We do that by creating our own i2c_clock_t structure in the code.

typedef struct {
    ssd1306_i2c_t *oled; /* the libssd1306 I2C object */
    ssd1306_framebuffer_t *fbp; /* the framebuffer object */
    int call_count; /* for calculating the 30 second timeout */
} i2c_clock_t;

Then we create an object instance of this struct in the main() function, followed by the setup of the event loop and the timer object. We initialize the timer object, set the data pointer and call start on the timer to run each second.

    /* create an object to send to the callbacks */
    i2c_clock_t timer_data = {
        .oled = oled, /* the object created earlier */
        .fbp = fbp, /* created earlier */
        .call_count = 30 /* timeout after 30 seconds */
    };

    /* create the loop variable by using the default */
    struct ev_loop *loop = EV_DEFAULT;

    /* create the timer event object */
    ev_timer timer_watcher = { 0 };

    /* initialize the timer to update each second and invoke callback */
    /* here the callback name is onesec_timer_cb */
    ev_timer_init(&timer_watcher, onesec_timer_cb, 1., 1.);

    /* set the data pointer for the callback to use it */
    timer_watcher.data = &timer_data;

    /* start the timer */
    ev_timer_start(loop, &timer_watcher);
    ev_run(loop, 0);

    /* cleanup before exiting main() */
    ssd1306_framebuffer_destroy(fbp);
    ssd1306_i2c_close(oled);

In the end, following the ev_run call in the main() function, we also cleanup the ssd1306_* objects.

Defining the timer callback

As seen above, the timer callback is called onesec_timer_cb which follows the libev structure of callbacks for all its event types. We reproduce it below.

The callback first calculates the local time using localtime_r() function from the C library. We choose this function since it is re-entrant and it makes sense to use a re-entrant function in the callback, especially if you are going to be doing multi-threading. Then we print the time to a buffer of 16 bytes, even though the format HH:MM:SS needs no more than 8-bytes but just to be safe we use 16.

The w argument is the ev_timer object that we created in the main() function, and will have the void *data member point to the timer_data object of type i2c_clock_t that we had created above. So we cast the data pointer to the i2c_clock_t * type and access the ssd1306 objects for the OLED screen and the framebuffer.

We then print the text buffer to the framebuffer object using the default font, and then push it via I²C to the OLED screen so that it displays the time in HH:MM:SS format.

For the timeout, we count down until we time out, so after 30 seconds.

void onesec_timer_cb(EV_P_ ev_timer *w, int revents)
{
    /* calculate the local time */
    struct tm _tm = { 0 };
    time_t _tsec = time(NULL);
    localtime_r(&_tsec, &_tm);

    /* print it to a buffer safely */
    char buf[16] = { 0 };
    snprintf(buf, sizeof(buf) - 1, "%02d:%02d:%02d", _tm.tm_hour, _tm.tm_min,
_tm.tm_sec);
    
    /* log the time to console to verify that it is correct */
    printf("INFO: Time is %s\n", buf);

    if (w) {
        /* retrieve the object that we set earlier in main() */
        i2c_clock_t *i2c = (i2c_clock_t *)(w->data);

        /* write the time buffer to framebuffer first */
        ssd1306_framebuffer_clear(i2c->fbp);
        ssd1306_framebuffer_box_t bbox;
        ssd1306_framebuffer_draw_text(i2c->fbp, buf, 0, 32, 16, SSD1306_FONT_DEFAULT, 4, &bbox);

        /* update the OLED screen with the framebuffer */
        if (ssd1306_i2c_display_update(i2c->oled, i2c->fbp) < 0) {
            fprintf(stderr, "ERROR: failed to update I2C display, exiting...\n");
            ev_break(EV_A_ EVBREAK_ALL);
        }

        /* count down until we time out */
        if ((i2c->call_count--) <= 0) {
            ev_break(EV_A_ EVBREAK_ALL);
        }
    }
}

DEMONSTRATION

Here is a short video of the demo at https://youtu.be/T_ox1At1x-o.

C Library for Reading GPS data from a GlobalTop MTK3339

Thu, 16 Apr 2020 00:00:00 -0400

We purchased the Adafruit Ultimate GPS breakout board (Figure 1) several months ago, but finally got to the point of using it for something. This GPS breakout uses a GlobalTop MTK3339 GPS chip, comes with an SMA connector antenna, and also requires an SMA to uFL adapter (Figure 2) also available at Adafruit. You will also require an FTDI USB-to-TTL serial cable, which can be available at various vendors like Sparkfun, Adafruit, Amazon, DigiKey, etc.

To read the GPS data as fast as possible using the libev event API, we chose to write a C library from scratch as opposed to using a server like gpsd. We want our application to embed the reading of the GPS and display the GPS data to the OLED library using our libssd1306 library.

Figure 1. Adafruit Ultimate GPS Breakout Board © Adafruit Industries

Figure 2. Adafruit SMA to uFL Connector © Adafruit Industries

The code in this post is as of git tag 0.2 or commit fd14b8884510bc42c55127890d9bdd51bc1473a5 from Github.

DATASHEET LINKS

The datasheets for the GPS chip (version PA6H) on the breakout board (version 3) can be found at Adafruit’s website and we have mirrored it here.

The GPS chip also accepts custom commands that start with the string $PMTK and the details of the commands can be found at Adafruit and we have mirrored it here.

CONNECTING THE GPS BREAKOUT BOARD

Using the USB-to-TTL Cable

The easiest way to connect and test the GPS breakout board is by using the FTDI USB-to-TTL serial cable.

Connecting the cable has to be done using the wiring in Figure 3.

Figure 3. How to connect the FTDI USB-to-TTL Cable Connector to the Ultimate GPS Breakout board © Adafruit Industries

You will need some extra connecting wires to be able to connect the USB-to-TTL cable’s connectors to the GPS breakout board’s connecting pins.

Connecting via GPIO Pins on Raspberry Pi

If you want to directly connect the GPS breakout board to a Raspberry Pi or Beaglebone Black UART GPIO pins, you have to perform the wiring as in Figure 4.

Figure 4. How to connect the UART GPIO Pins on a Raspberry Pi to the Ultimate GPS Breakout board © Adafruit Industries

COMPILING THE LIBRARY

We have made it as simple as possible to compile the library.

## install pre-requisites
$ sudo apt-get -y install ragel libev-dev build-essential \
    autoconf automake autotools-dev libtool

## clone the library source code
$ git clone https://github.com/stealthylabs/libgps_mtk3339
$ git submodule init
$ git submodule update

## change to the source directory
$ cd libgps_mtk3339

## run the autotools
$ ./autogen.sh

## run configure in release mode
$ ./configure

## run make and make sure unit tests run
$ make && make check

## optionally run make install if you want to install the library
$ make install

READING THE DATA

This library’s main purpose is to be able to seamlessly, and with the least amount of effort, be able to read data from the MTK3339 GPS chip made by GlobalTop. Here for example, we are using the open source AdaFruit Ultimate GPS breakout board, but you could be using your own custom board with this chip and want to read the data faster than a Python script could.

That is why we have written this parser using one of the best parser generator tools, ragel, so that we can parse each individual NMEA sentence sent by the GPS in under 6-10 microseconds depending on the client computer.

The library is also re-entrant so that the user can use event libraries like libev or just a select() or epoll() or a blocking read() function call to read the data from the GPS chip when connected in any of the above two ways, shown in Figures 3 and 4. One such example we explain below.

Example with `libev`

We provide a usable example that prints location information on screen using libev. This example can be found in src/libev_uart.c file. In this section, we go over some important portions of the code to help the user understand how to use the library.

To run the example, you can do the following after compiling the code:

$ ./src/libev_uart_gps

This expects the device to be connected as /dev/ttyUSB0. You can also specify your own device path on the command line:

$ ./src/libev_uart_gps /dev/serial0

This example automatically exits after 10 seconds. However, sometimes the GPS chip may take more than 10 seconds to get a fix, so you can set the example to run without the timeout by setting the NO_TIMEOUT environment variable as shown below. You can then press Ctrl C to interrupt the running application.

$ NO_TIMEOUT=1 ./src/libev_uart_gps

Header Files

The user only needs to include the gpsdata.h header file which indirectly includes all the other dependency files such as:

gpsconfig.h: has the constants based on the build system
gpsutils.h: has some utility functions such as for opening the device and setting the defaults
gps_utlist.h: we provide a copy of the build version of utlist.h self-contained header/library from the utlist project. We use this to return a linked-list of parsed objects that the user can iterate through.

For this example, the user needs to also include ev.h to use libev.

#include <gpsdata.h>
/* ... other headers like errno.h, fcntl.h, stdio.h etc.... */
#ifdef HAVE_EV_H
    #include <ev.h>
#endif

Logging

The gpsutils.h file defines a set of macros for performing conditional logging at various levels. By default, the logging happens to stderr. The default log level is set to INFO and the user can change it using the GPSUTILS_LOGLEVEL_SET() macro as shown below.

// set the log level to DEBUG
GPSUTILS_LOGLEVEL_SET(DEBUG);

The user can also either reopen the stderr to a different log file using freopen(), or perform the following C-language macro-magic to set it to their favorite global FILE * variable, which they can set up later. NOTE: we do not do this in the src/libev_uart.c file, and this is for a special use case where the user cannot use freopen() on stderr.

/* use variable my_custom_log_ptr instead of stderr */
#define GPSUTILS_LOG_PTR my_custom_log_ptr
#include <gpsdata.h>

/* ... later in the code define the my_custom_log_ptr globally or locally to
every function before calling any GPSUTILS_LOG_* macro ... 
Here is a global pointer example
*/
FILE *my_custom_log_ptr = NULL;
/* ... main function ... */

int main(int argc, char **argv)
{
    my_custom_log_ptr = fopen("/path/to/log/file", "+w");
    /* ... more code ... */
    GPSUTILS_INFO("Starting log file...\n");
    return 0;
}

Opening the device

When using the USB-to-TTL cable on a Linux system, the device will show up as /dev/ttyUSB0 or in the device file format /dev/ttyUSB[0-9]. The src/libev_uart.c file assumes that the /dev/ttyUSB0 is the default, but also accepts a command-line argument to change that default to another device path.

When using the UART GPIO pins on a Raspberry Pi, the device path changes to /dev/serial or matches the /dev/serial[0-9] pattern.

To open the device, we provide a wrapper function that also sets the default chip baud rate to 9600 bps and the default NMEA sentences to GPRMC and GPGGA. This function is the gpsdevice_open() function and it returns the file descriptor after a successful open, or -1 on error. There is a corresponding gpsdevice_close() function that closes the open device. Below is a small snippet of code from the src/libev_uart.c file demonstrating the usage of these functions. We open the device in non-blocking mode so that we can read the data as fast as possible, but also handle other events when the data is not coming in.

int main (int argc, char **argv)
{
    /* ... */
    const char *dev = "/dev/ttyUSB0";
    int device_fd = gpsdevice_open(dev, true /* non-blocking */);
    if (device_fd < 0) {
        return -1;
    } else {
        /* use the device_fd here */
    }
    gpsdevice_close(device_fd);
    /* ... */
    return 0;
}

Creating the Parser

This library uses ragel, which is a streaming parser that uses state machines to parse data. It allows us to parse data read from the GPS chip, even if the data is incomplete in the buffer until the next buffer can be read. Not only that, it is also written in pure C which allows it to be really fast for our needs.

We encapsulate all the parser related code into an opaque object called gpsdata_parser_t and the user can create one using gpsdata_parser_create(). Each device must have its own gpsdata_parser_t object, as each file descriptor will be reading data which may be at a different state. In general, it is likely that you will be using only one GPS chip, but if you are using more, you need to have one parser object per GPS chip.

Once an array of bytes have been read from the GPS chip’s file descriptor, the function that parses it is gpsdata_parser_parse() which then returns a linked list of gpsdata_data_t objects which may have location information, antenna information, speed information, GPS chip firmware information and other possible messages.

The below code shows how to create the parser, and use the functions in blocking mode without libev:

/* create the parser object */
gpsdata_parser_t *parser = gpsdata_parser_create();
/* open device */
int device_fd = gpsdevice_open("/dev/ttyUSB0", false /* blocking */);
/* a buffer pointer to read data */
char buf[80];
ssize_t nb = 0;
gpsdata_data_t *listp = NULL;
/* blocking read */
while ((nb = read(device_fd, buf, sizeof(buf))) > 0) {
    size_t onum = 0;
    /* parse the data that was read and store outputs in listp
     *  onum holds the number of items added to listp
     */
    if (gpsdata_parser_parse(parser, buf, nb, &listp, &onum) < 0) {
        /* if the buffer had bad data in it, we reset the parser state
         * and allow the parser to continue working to parse the next set of
         *  messages.
         */
        gpsdata_parser_reset(parser);
    }
    printf("Parsed %zu NMEA messages in the buffer\n", onum);
    /** do something with the listp data like store in a database or
     * update a display on screen etc.
     */
}
/* close the device */
gpsdevice_close(device_fd);
/* free the listp  object */
gpsdata_list_free(listp);
/* free the parser object */
gpsdata_parser_free(parser);

Sending Messages to the GPS Device

We can also send several messages to the GPS device since it uses a UART interface for receiving data. The messages that can be sent are found in the PMTK command datasheet (also linked above).

We have taken most of the useful ones and wrapped them in their own functions, and also provide a low level message send function that allows the user to send their own custom message to the GPS device. All these functions begin with gpsdevice_ and use the file descriptor returned by gpsdevice_open() to send the messages to the GPS chip.

gpsdevice_set_baudrate(): Allows the user to set a custom baudrate for the GPS. The default value is set to be 9600 bps, and the other supported values are 1200, 2400, 4800, 9600, 19200, 38400, 57600 and 115200. As of this writing, we have only tested 9600 bps since that’s what the datasheet says we should use. This function gets called with the 9600 default value in the gpsdevice_open() call, but the user can change that by calling it again.
gpsdevice_set_restart(): Allows the user to perform different type of restarts as specified in the PMTK document linked above &em; the warm start, cold start and a full cold start or a factory reset.
gpsdevice_set_standby(): Sends a message to the GPS chip to be on standby. To exit standby mode the user can send any message to the GPS chip, such as an enable message or a firmware or antenna request or anything else.
gpsdevice_set_fix_interval(): Tells the GPS the fix interval in milliseconds that it should use. For a 9600 baud this should be 1000 milliseconds or 1 second. The minimum value is 100 and maximum value accepted is 10000 milliseconds.
gpsdevice_set_enabled(): By default the only NMEA messages enabled are GPGGA and GPRMC since they give us the location which is enough for most uses. The user may want to enable other NMEA sentences like GPVTG, GPGSA and GPGSV. To do that the user may want to use this function. As of this writing, GPGLL is disabled at all times as it is unnecessary. We have tested enabling GPGLL, GPGGA and GPRMC simultaneously and the value of the location is the same, hence have deemed GPGLL unnecessary.
gpsdevice_set_speed_threshold(): The navigation speed has a minimum accuracy threshold that can be set here. By default, it is set to 0.2 m/s. The valid values as per the data sheet are 0.2, 0.4, 0.6, 0.8, 1.0, 1.5 and 2.0 m/s. If the user wants to disable the threshold they can use 0. If the speed is slower than the threshold the location is considered constant or frozen.
gpsdevice_request_firmware_info(): The user can request the firmware version that the GPS chip is running. The data gets returned and parsed by the gpsdata_parser_parse() function and the firmware can be read in the gpsdata_data_t object using the fwinfo field, and the msgid will be GPSDEVICE_MSGID_PMTK.
gpsdevice_request_antenna_status(): The user can request antenna status of the chip. If the user is using the Adafruit GPS breakout board like us, we are using the external antenna, which will set the antenna_status field in the gpsdata_data_t object as GPSDATA_ANTENNA_ACTIVE. If the user is using the chip’s internal antenna, the antenna status will be GPSDATA_ANTENNA_INTERNAL.
gpsdevice_send_message(): This is the core message send function which is used by all the wrappers internally. The user can set their own PMTK message if any of our wrappers are insufficient for their use case.

Using the Device with `libev`

The sample application present in src/libev_uart.c can be used as a starting point for using libev and the libgps_mtk3339 library. Remember to open the device in non-blocking mode and to create one parser per opened device.

With this we come to the end of the introduction to the libgps_mtk3339 library. Try it out instead of using the gpsd daemon or the Adafruit Python libraries and let us know if you have any issues.

Updated Drawing Text on OLED Chip SSD1306 Using FreeType2

Tue, 31 Mar 2020 00:00:00 -0400

We are updating the previous post on drawing text, since we realized we needed to fix a major display bug in pixel locating the text. In addition to that we updated the API for drawing text to return a bounding box around the drawn text so that the developer can know the pixel coordinates of where the text was drawn in the framebuffer. We also updated the bit-dump API to optionally add color to the terminal output.

The code in this post is as of git tag 0.6 or commit 50e836f9299f61a3fe2901f794d2131ade7c23be from Github.

BITDUMP COLOR

The bitdump API now automatically colors the 0’s as blue and the 1’s as red in the default ssd1306_framebuffer_bitdump() function. If the user sets use_color to true in the ssd1306_framebuffer_bitdump_custom() function the colors are set to blue and red for 0 and 1, respectively. There is currently no plan on supporting other color combinations.

DRAWING TEXT

To draw a font on a framebuffer, we chose to use FreeType2 as it is open source, and supports a variety of fonts. It also lends itself well to drawing the font directly to our framebuffer memory image.

Just by following the FreeType2 tutorial we were able to implement the ssd1306_framebuffer_draw_text() and the ssd1306_framebuffer_draw_text_extra() functions.

We have abstracted out the FreeType2 usage, so that if in the future we choose to change the dependency on FreeType2, we can without exposing the APIs of the library to idiosyncrasies of FreeType2.

The simplest way to draw a string of text at (x,y) coordinates is to use the ssd1306_framebuffer_draw_text() function, which will start drawing the text at (x,y) for the given font and font size, as shown below.

If the user provides a pointer to an ssd1306_framebuffer_box_t object as the optional last argument, the function returns the bounding box for the drawn text in the framebuffer. This contains the pixel coordinates of the rectangle in which the text has been drawn, and informs the user of the region where the pixels are drawn.

#include <ssd1306_graphics.h>

/* ... some initialization code ... */

/* create the framebuffer for a OLED screen 128x32 */
ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(128, 32, NULL);

ssd1306_framebuffer_box_t bbox; // bounding box

// draw ABCDeF with the default font and font size 4 at (x,y) of (32, 32)
ssd1306_framebuffer_draw_text(fbp, "ABCDeF", 0, 32, 32, SSD1306_FONT_DEFAULT, 4, &bbox);

ssd1306_framebuffer_bitdump(fbp);

fprintf(stderr,
    "Bounding box coordinates top: %d left: %d right: %d bottom %d",
    bbox.top, bbox.left, bbox.right, bbox.bottom);

The framebuffer now looks like:

Figure 1. Bitdump of the colored framebuffer on the terminal

As you can see above the default font (BitStream Vera) gets rendered onto the framebuffer as expected, and in the same way gets displayed on screen on the OLED device as seen in the image below.

We also note that the top and left of the bounding box are the same as the (x,y) coordinates at which the drawing of the text was requested. The right and bottom values denote the maximum pixel coordinates where the drawing completed. If you want to know where to draw the next string, these values can be useful to locate the position of the string correctly.

Figure 2. Drawing aligned text on screen using Bitstream Vera font

Here is an example of drawing a large font size on the screen.

Figure 3. Drawing a large font size on screen using the Bitstream Vera font

SUPPORTED FONT FACES

By default, the libssd1306 library supports the following fonts, and also allows the user to load their own font file. The package requirements for the default fonts require the user to install fonts-freefont-ttf and ttf-bitstream-vera. If the user wants to have access to Microsoft®’s TrueType fonts, they can install ttf-mscorefonts-installer using the package manager and get access to Microsoft® specific fonts like Arial and Comic Sans.

We shall show you examples of using the custom fonts below. Using the ssd1306_fontface_t enum type allows the user to not have to know where the font file is located, since we already know that as part of the installation packages. So we currently hard-code these locations in and map them to an enum. If the user wants to load their own font file they can use the SSD1306_FONT_CUSTOM option and the ssd1306_framebuffer_draw_text_extra() function which accepts custom options for drawing the text, including the font file location.

The default font paths are provided in the ssd1306_graphics.h header file.

If the user wants to draw using the Microsoft® TrueType font Comic Sans, they can use the following code example:

#include <ssd1306_graphics.h>
/* ... some initialization ... */

/* create the framebuffer for a OLED screen 128x32 */
ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(128, 32, NULL);

// setup the options
ssd1306_graphics_options_t opts;
opts.type = SSD1306_OPT_FONT_FILE;
opts.value.font_file = "/usr/share/fonts/truetype/msttcorefonts/Comic_Sans_MS.ttf";
// call the draw_text_extra() function which accepts options
ssd1306_framebuffer_draw_text_extra(fbp. "ABCDeF", 0, 32, 32, SSD1306_FONT_CUSTOM, 4, &opts, 1);

The only difference between the ssd1306_framebuffer_draw_text() and ssd1306_framebuffer_draw_text_extra() functions is that the latter accepts custom options for font files, rotation of fonts and rotation of pixels.

ROTATING THE FONT

In some rare cases, we may want to draw a text at an angle such as for displaying logos, or just rotating a text on screen by say 30°. We can do that with the SSD1306_OPT_ROTATE_FONT option and provide the rotation angle in the rotation_degrees field. This uses the font transformation functions provided by FreeType2 internally, and is highly accurate.

Below is an example that uses both the custom font file option for Comic Sans and rotates it by 30°, as seen in the framebuffer output.

#include <ssd1306_graphics.h>
/* ... some initialization ... */

/* create the framebuffer for a OLED screen 128x32 */
ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(128, 32, NULL);

ssd1306_framebuffer_box_t bbox; // bounding box
// setup the options
ssd1306_graphics_options_t opts[2];
opts[0].type = SSD1306_OPT_FONT_FILE;
opts[0].value.font_file = "/usr/share/fonts/truetype/msttcorefonts/Comic_Sans_MS.ttf";
opts[1].type = SSD1306_OPT_ROTATE_FONT;
opts[1].value.rotation_degrees = 30;
// call the draw_text_extra() function which accepts options
ssd1306_framebuffer_draw_text_extra(fbp. "ABCDeF", 0, 32, 32, SSD1306_FONT_CUSTOM, 4, opts, 2, &bbox);
// dump the framebuffer to screen
ssd1306_framebuffer_bitdump(fbp);
fprintf(stderr,
    "Bounding box coordinates top: %d left: %d right: %d bottom %d",
    bbox.top, bbox.left, bbox.right, bbox.bottom);

Below is the screenshot of the terminal displaying the rotation of the font and the usage of the Microsoft® Comic Sans font. As you may notice, that the bounding box is different in this example as the font selected is different and rotating the font changes the size of the box.

Figure 4. Bitdump of the rotated Comic Sans font on the terminal

All the code snippets can be found in the examples/fb_graphics.c file.

ROTATING PIXELS

As shown in the previous post, we may want to rotate an image on the screen by using the pixel rotation function. We can absolutely use that feature for drawing text at different locations by rotating not just the font, but also the pixels.

Below is an example that uses both the custom font file option for Comic Sans and rotates it by 30°, and then rotates the drawing by 180° as seen in the framebuffer output.

Note that the SSD1306_OPT_ROTATE_PIXEL option only accepts multiples of 90° in the rotation_degrees field. Any other value will get ignored, and an error statement printed to the log.

#include <ssd1306_graphics.h>
/* ... some initialization ... */

/* create the framebuffer for a OLED screen 128x32 */
ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(128, 32, NULL);

// setup the options
ssd1306_graphics_options_t opts[1];
opts[0].type = SSD1306_OPT_ROTATE_PIXEL;
opts[0].value.rotation_degrees = 180;
// call the draw_text_extra() function which accepts options
ssd1306_framebuffer_draw_text_extra(fbp. "ABCDeF", 0, 0, 0, SSD1306_FONT_DEFAULT, 4, opts, 1);
// dump the framebuffer to screen
ssd1306_framebuffer_bitdump(fbp);

In Figure 5, you can see an example of the pixels rotated by 180° to flip the drawing of the text.

Below is the code for rotating both the font and the pixels by 30° each.

#include <ssd1306_graphics.h>
/* ... some initialization ... */

/* create the framebuffer for a OLED screen 128x32 */
ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(128, 32, NULL);

// setup the options
ssd1306_graphics_options_t opts[2];
opts[0].type = SSD1306_OPT_ROTATE_FONT;
opts[0].value.rotation_degrees = 18;
opts[1].type = SSD1306_OPT_ROTATE_PIXEL;
opts[1].value.rotation_degrees = 30;
// call the draw_text_extra() function which accepts options
ssd1306_framebuffer_draw_text_extra(fbp. "ABCDeF", 0, 0, 0, SSD1306_FONT_DEFAULT, 4, opts, 2);
// dump the framebuffer to screen
ssd1306_framebuffer_bitdump(fbp);

Figure 6. Bitdump of the rotated default font and rotated pixels on the terminal

Figure 7 is an example of using Comic Sans and rotating the font and pixels each by 30 degrees on the OLED screen.

Figure 7. Drawing Comic Sans rotated text on screen

Drawing Lines on OLED Chip SSD1306

Wed, 25 Mar 2020 00:00:00 -0400

In an earlier post we had discussed the framebuffer object of the C library for performing graphics on the OLED screen SSD1306 using a Raspberry Pi. We also discussed how to draw text using FreeType2.

In this post we show you how to draw straight lines on the OLED screen using our ssd1306_framebuffer_draw_line() function.

The code in this post is as of commit 597002e7e6792ff236f760c11d67ff6a6d719ab9 from Github.

There may be several algorithms to draw lines on a screen, but for our case we use the Bresenham’s line drawing algorithm as described in the great Michael Abrash’s Graphics Programming Black Book. The book explains in great detail how the algorithm works and how to draw to a VGA or EVGA screen using the x86 processor. We have appropriately adjusted the algorithm to work correctly for our OLED screen and also be more generic to work on both ARM and x86 chips, but most of the algorithm does not change from what is in the book’s chapter.

Our function here is ssd1306_framebuffer_draw_line() which takes 6 arguments: the framebuffer pointer, the (x₀, y₀) starting point coordinates, the (x₁, y₁) ending point coordinates and the pixel color for whether to draw a clear (black) or filled (blue) pixel for the line.

In the examples/draw_line.c we draw three different lines - a horizontal line at 0°, a vertical line at 90° and a diagonal line between two random points.

If we want to draw a horizontal line from (0,0) to (64,0) with a filled pixel, our function call will look like:

#include <ssd1306_graphics.h>

/* ... some initialization code ... */
/* create the framebuffer for a OLED screen 128x32 */
ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(128, 32, NULL);

// draw the line
ssd1306_framebuffer_draw_line(fbp, 0, 0, 64, 0, true);

// dump the framebuffer memory with no-spaces
ssd1306_framebuffer_bitdump_nospace(fbp);

The framebuffer dump looks like:

0000 ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||................................................................
0001 ................................................................................................................................
0002 ................................................................................................................................
0003 ................................................................................................................................
0004 ................................................................................................................................
0005 ................................................................................................................................
0006 ................................................................................................................................
0007 ................................................................................................................................
0008 ................................................................................................................................
0009 ................................................................................................................................
000A ................................................................................................................................
000B ................................................................................................................................
000C ................................................................................................................................
000D ................................................................................................................................
000E ................................................................................................................................
000F ................................................................................................................................
0010 ................................................................................................................................
0011 ................................................................................................................................
0012 ................................................................................................................................
0013 ................................................................................................................................
0014 ................................................................................................................................
0015 ................................................................................................................................
0016 ................................................................................................................................
0017 ................................................................................................................................
0018 ................................................................................................................................
0019 ................................................................................................................................
001A ................................................................................................................................
001B ................................................................................................................................
001C ................................................................................................................................
001D ................................................................................................................................
001E ................................................................................................................................
001F ................................................................................................................................

If we want to draw a vertical line from (64,0) to (64,32) with a filled pixel, our function call will look like:

#include <ssd1306_graphics.h>

/* ... some initialization code ... */
/* create the framebuffer for a OLED screen 128x32 */
ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(128, 32, NULL);

// draw the line
ssd1306_framebuffer_draw_line(fbp, 64, 0, 64, 32, true);

// dump the framebuffer memory with no-spaces
ssd1306_framebuffer_bitdump_nospace(fbp);

The framebuffer dump looks like:

0000 ................................................................|...............................................................
0001 ................................................................|...............................................................
0002 ................................................................|...............................................................
0003 ................................................................|...............................................................
0004 ................................................................|...............................................................
0005 ................................................................|...............................................................
0006 ................................................................|...............................................................
0007 ................................................................|...............................................................
0008 ................................................................|...............................................................
0009 ................................................................|...............................................................
000A ................................................................|...............................................................
000B ................................................................|...............................................................
000C ................................................................|...............................................................
000D ................................................................|...............................................................
000E ................................................................|...............................................................
000F ................................................................|...............................................................
0010 ................................................................|...............................................................
0011 ................................................................|...............................................................
0012 ................................................................|...............................................................
0013 ................................................................|...............................................................
0014 ................................................................|...............................................................
0015 ................................................................|...............................................................
0016 ................................................................|...............................................................
0017 ................................................................|...............................................................
0018 ................................................................|...............................................................
0019 ................................................................|...............................................................
001A ................................................................|...............................................................
001B ................................................................|...............................................................
001C ................................................................|...............................................................
001D ................................................................|...............................................................
001E ................................................................|...............................................................
001F ................................................................|...............................................................

A line that is not at 0° or 90° or a 1:1 diagonal will have to be approximately drawn using Bresenham’s line drawing algorithm as noted above. As part of the algorithm sometimes to make the line look neat, we have to color two pixels in each row as you can see in the framebuffer dump below to get the perfect look of the line.

#include <ssd1306_graphics.h>

/* ... some initialization code ... */
/* create the framebuffer for a OLED screen 128x32 */
ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(128, 32, NULL);

// draw the line
ssd1306_framebuffer_draw_line(fbp, 0, 0, 64, 32, true);

// dump the framebuffer memory with no-spaces
ssd1306_framebuffer_bitdump_nospace(fbp);

0000 |...............................................................................................................................
0001 .||.............................................................................................................................
0002 ...||...........................................................................................................................
0003 .....||.........................................................................................................................
0004 .......||.......................................................................................................................
0005 .........||.....................................................................................................................
0006 ...........||...................................................................................................................
0007 .............||.................................................................................................................
0008 ...............||...............................................................................................................
0009 .................||.............................................................................................................
000A ...................||...........................................................................................................
000B .....................||.........................................................................................................
000C .......................||.......................................................................................................
000D .........................||.....................................................................................................
000E ...........................||...................................................................................................
000F .............................||.................................................................................................
0010 ...............................||...............................................................................................
0011 .................................||.............................................................................................
0012 ...................................||...........................................................................................
0013 .....................................||.........................................................................................
0014 .......................................||.......................................................................................
0015 .........................................||.....................................................................................
0016 ...........................................||...................................................................................
0017 .............................................||.................................................................................
0018 ...............................................||...............................................................................
0019 .................................................||.............................................................................
001A ...................................................||...........................................................................
001B .....................................................||.........................................................................
001C .......................................................||.......................................................................
001D .........................................................||.....................................................................
001E ...........................................................||...................................................................
001F .............................................................||.................................................................

In the example file examples/i2c_128x32_graphics.c we have added a call to the line drawing function and below are some images from drawing the line on the screen.

Figure 1. Drawing a diagonal line

Figure 2. Drawing vertical and diagonal lines

Figure 3. Drawing horizontal, vertical and diagonal lines

Drawing Text on OLED Chip SSD1306 Using FreeType2

Sun, 22 Mar 2020 00:00:00 -0400

In the previous post we had discussed the framebuffer object of the C library for performing graphics on the OLED screen SSD1306 using a Raspberry Pi.

In this blog post, we demonstrate how we have used FreeType2 to draw text on the screen using fonts that can be installed using your Raspbian distro packages. FreeType2 provides an easy way to render any type of supported font on the screen, and we encapsulate all of that in a single function call ssd1306_framebuffer_draw_text().

UPDATE: This code is OBSOLETE as of git tag 0.6 or commit 50e836f9299f61a3fe2901f794d2131ade7c23be. Please refer to the latest blog post on this topic.

The code in this post is as of git tag 0.51 or commit 294ffccc1004b35028406fc4281cef894f473d2a from Github.

DRAWING TEXT

Just by following the FreeType2 tutorial we were able to implement the ssd1306_framebuffer_draw_text() and the ssd1306_framebuffer_draw_text_extra() functions.

We have abstracted out the FreeType2 usage, so that if in the future we choose to change the dependency on FreeType2, we can without exposing the APIs of the library to idiosyncrasies of FreeType2.

#include <ssd1306_graphics.h>

/* ... some initialization code ... */

/* create the framebuffer for a OLED screen 128x32 */
ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(128, 32, NULL);

// draw ABCDeF with the default font and font size 4 at (x,y) of (32, 32)
ssd1306_framebuffer_draw_text(fbp, "ABCDeF", 0, 32, 32, SSD1306_FONT_DEFAULT, 4);

ssd1306_framebuffer_bitdump(fbp);

The framebuffer now looks like:

0000 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0001 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0002 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0003 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0004 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0005 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0006 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0007 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0008 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0009 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
000A ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
000B ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
000C ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
000D ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
000E ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
000F ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0010 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0011 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0012 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0013 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0014 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0015 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0016 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0017 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0018 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0019 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001A ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001B ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001C ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001D ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001E ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001F ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0020 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0021 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0022 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0023 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0024 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0025 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0026 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0027 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0028 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0029 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002A ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002B ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002C ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002D ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002E ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002F ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0030 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0031 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0032 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0033 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0034 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0035 ..|||||. ...||||| |....... ||||||.| ||||.... ........ ...||||| ||||.... ........ ........ ........ ........ ........ ........ ........ ........ 
0036 ..|||||. ...||||| |||...|| ||||||.| ||||||.. ........ ...||||| ||||.... ........ ........ ........ ........ ........ ........ ........ ........ 
0037 ....|||. ....||.. .||...|| ...|||.. |...|||. ........ ....||.. ..||.... ........ ........ ........ ........ ........ ........ ........ ........ 
0038 ...||.|| ....||.. ..|..||. ....||.. |....||| ...||||| ....||.. |.||.... ........ ........ ........ ........ ........ ........ ........ ........ 
0039 ...||.|| ....||.. .||..||. ........ |.....|| ..|||.|| |...||.| |....... ........ ........ ........ ........ ........ ........ ........ ........ 
003A ...||.|| ....|||| |||..||. ........ |.....|| .||....| ||..|||| |....... ........ ........ ........ ........ ........ ........ ........ ........ 
003B ..|||||| |...||.. .|||.||. ........ |.....|| .||||||| ||..||.| |....... ........ ........ ........ ........ ........ ........ ........ ........ 
003C ..|||||| |...||.. ..||.||. ........ |.....|| .||||||| ||..||.. |....... ........ ........ ........ ........ ........ ........ ........ ........ 
003D .||..... ||..||.. ..||.||| ....||.. |....||. .|||.... ....||.. ........ ........ ........ ........ ........ ........ ........ ........ ........ 
003E |||||..| |||||||| ||||..|| ||||||.| |||||||. ..|||.|| ||.||||| ........ ........ ........ ........ ........ ........ ........ ........ ........ 
003F |||||..| |||||||| |||....| |||||..| ||||||.. ...||||| |..||||| |....... ........ ........ ........ ........ ........ ........ ........ ........ 

As you can see above the default font (BitStream Vera) gets rendered onto the framebuffer as expected, and in the same way gets displayed on screen on the OLED device as seen in the image below.

Figure 1. Drawing aligned text on screen using Bitstream Vera font

Here is an example of drawing a large font size on the screen.

Figure 2. Drawing a large font size on screen using the Bitstream Vera font

SUPPORTED FONT FACES

The default font paths are provided in the ssd1306_graphics.h header file.

If the user wants to draw using the Microsoft® TrueType font Comic Sans, they can use the following code example:

#include <ssd1306_graphics.h>
/* ... some initialization ... */

/* create the framebuffer for a OLED screen 128x32 */
ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(128, 32, NULL);

// setup the options
ssd1306_graphics_options_t opts;
opts.type = SSD1306_OPT_FONT_FILE;
opts.value.font_file = "/usr/share/fonts/truetype/msttcorefonts/Comic_Sans_MS.ttf";
// call the draw_text_extra() function which accepts options
ssd1306_framebuffer_draw_text_extra(fbp. "ABCDeF", 0, 32, 32, SSD1306_FONT_CUSTOM, 4, &opts, 1);

ROTATING THE FONT

Below is an example that uses both the custom font file option for Comic Sans and rotates it by 30°, as seen in the framebuffer output.

#include <ssd1306_graphics.h>
/* ... some initialization ... */

/* create the framebuffer for a OLED screen 128x32 */
ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(128, 32, NULL);

// setup the options
ssd1306_graphics_options_t opts[2];
opts[0].type = SSD1306_OPT_FONT_FILE;
opts[0].value.font_file = "/usr/share/fonts/truetype/msttcorefonts/Comic_Sans_MS.ttf";
opts[1].type = SSD1306_OPT_ROTATE_FONT;
opts[1].value.rotation_degrees = 30;
// call the draw_text_extra() function which accepts options
ssd1306_framebuffer_draw_text_extra(fbp. "ABCDeF", 0, 32, 32, SSD1306_FONT_CUSTOM, 4, opts, 2);
// dump the framebuffer to screen
ssd1306_framebuffer_bitdump(fbp);

0000 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0001 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0002 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0003 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0004 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0005 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0006 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0007 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0008 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0009 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
000A ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
000B ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
000C ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
000D ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
000E ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
000F ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0010 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0011 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0012 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0013 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0014 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0015 ........ ........ ........ ........ ........ ......|| |||..... ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0016 ........ ........ ........ ........ ........ ....|||| ||...... ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0017 ........ ........ ........ ........ ........ ...||||| |....... ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0018 ........ ........ ........ ........ ........ ..|||||. ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0019 ........ ........ ........ ........ ........ ..||||.. .|||.... ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001A ........ ........ ........ ........ ........ ...|||.| ||||.... ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001B ........ ........ ........ ........ ........ ...||||| ||||.... ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001C ........ ........ ........ ........ ........ ....|||| ||...... ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001D ........ ........ ........ ........ ........ ....|||| |....... ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001E ........ ........ ........ ........ ......|| ||...||| ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001F ........ ........ ........ ........ .....||| ||...||| |....... ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0020 ........ ........ ........ ........ .....||| ||....|| |....... ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0021 ........ ........ ........ ....|||| |....||| ||.....| ||...... ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0022 ........ ........ ........ |||||||| |||..||. ||.....| ||...... ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0023 ........ ........ ........ |||||||| ||||.||| ||...... ||...... ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0024 ........ ........ ....|||| ||||.... .||||||| |.|||||. ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0025 ........ ........ ...||||| .|||.... ..|||.|| ||||||.. ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0026 ........ ........ ..|||||| .||||... ...||.|| |||||... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0027 ........ ........ ..|||... ..|||... ...||... |||..... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0028 ........ ........ ..|||... ...|||.. ..|||... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0029 ........ ........ .|||.... ...|||.. .||||... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002A ........ ........ .|||.... ....|||| |||||... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002B ........ ||||||.. .|||.... ....|||| ||||.... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002C .......| |||||||. .|||.... .....||| |||..... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002D ......|| |||||||. .|||.... .....||| ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002E ......|| |...|||. ..|||... ||||.... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002F .......| ||..|||. ..||||.| |||..... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0030 |||....| ||.||||| |..||||| |||..... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0031 ||||.... |||||||| |..||||| ||...... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0032 ||||.... |||||||. |.....|| ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0033 |||||... .||||..| ||...... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0034 ||||||.. .|||..|| ||...... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0035 ||.|||.. ..|||||| |....... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0036 ||||||.. ..|||||| |....... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0037 ||||||.. ...||||. ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0038 |||||... ...|||.. ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0039 ||||...| ||...... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
003A |||..... ||...... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
003B |||..... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
003C |||..... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
003D |||..... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
003E |||..... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
003F ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 

All the code snippets can be found in the examples/fb_graphics.c file.

ROTATING PIXELS

Below is an example that uses both the custom font file option for Comic Sans and rotates it by 30°, and then rotates the drawing by 180° as seen in the framebuffer output.

Note that the SSD1306_OPT_ROTATE_PIXEL option only accepts multiples of 90° in the rotation_degrees field. Any other value will get ignored, and an error statement printed to the log.

#include <ssd1306_graphics.h>
/* ... some initialization ... */

/* create the framebuffer for a OLED screen 128x32 */
ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(128, 32, NULL);

// setup the options
ssd1306_graphics_options_t opts[2];
opts[0].type = SSD1306_OPT_ROTATE_FONT;
opts[0].value.rotation_degrees = 30;
opts[1].type = SSD1306_OPT_ROTATE_PIXEL;
opts[1].value.rotation_degrees = 30;
// call the draw_text_extra() function which accepts options
ssd1306_framebuffer_draw_text_extra(fbp. "ABCDeF", 0, 0, 0, SSD1306_FONT_DEFAULT, 4, opts, 2);
// dump the framebuffer to screen
ssd1306_framebuffer_bitdump(fbp);

If you scroll to the right of this buffer dump, you can see the flip of the rotated font string.

0000 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ......|| 
0001 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .....||| 
0002 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ....|||| 
0003 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .|....|| 
0004 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .......| |||...|| 
0005 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ....|||| 
0006 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ....|||. ...||||| 
0007 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ..||||.. ...||..| 
0008 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .|||.||. ...|||.| 
0009 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ |||..||. ....|||| 
000A ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .......| |.....|| .....||| 
000B ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .......| |...|||| |.....|| 
000C ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .|||||.. .||||||| |....... 
000D ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ |||||||. .||||..| |||..... 
000E ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .......| |....||| ..||.... |||..... 
000F ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ......|| |.||..|| ||...... 
0010 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ...|||.. .......| |..||||| ........ 
0011 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .||||... .......| |....... ........ 
0012 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ |||.||.. .......| |....... ........ 
0013 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .......| ||..|||. .......| |....... ........ 
0014 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .......| |....||. ..|...|| |....... ........ 
0015 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .......| |....||| ..|||||| ........ ........ 
0016 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ |||||..| |.....|| ..||||.. ........ ........ 
0017 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ......|| ||.|||.| |......| ||.|.... ........ ........ 
0018 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ......|| ...||||. ||....|| ||...... ........ ........ 
0019 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ..|||||. |||||||| |....... ........ ........ 
001A ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .|||.... .|||.||. ..|||||. ........ ........ ........ 
001B ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ||||.... .|..|||. ........ ........ ........ ........ 
001C ........ ........ ........ ........ ........ ........ ........ ........ ........ .......| ||||.... .|.|||.. ........ ........ ........ ........ 
001D ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ...||... .||||... ........ ........ ........ ........ 
001E ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ...||... ........ ........ ........ ........ ........ 
001F ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ||||||.. ........ ........ ........ ........ ........ 
0020 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .||||||. ........ ........ ........ ........ ........ 
0021 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .||..||| |....... ........ ........ ........ ........ 
0022 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .....||| |....... ........ ........ ........ ........ 
0023 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ |..||||. ........ ........ ........ ........ ........ 
0024 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ||||||.. ........ ........ ........ ........ ........ 
0025 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ||||.... ........ ........ ........ ........ ........ 
0026 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .|...... ........ ........ ........ ........ ........ 
0027 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0028 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0029 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002A ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002B ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002C ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002D ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002E ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002F ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0030 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0031 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0032 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0033 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0034 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0035 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0036 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0037 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0038 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0039 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
003A ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
003B ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
003C ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
003D ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
003E ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
003F ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 

Here is an example of using Comic Sans and rotating the text.

Figure 3. Drawing Comic Sans rotated text on screen

Framebuffer and Drawing Pixels on OLED Chip SSD1306

Sat, 21 Mar 2020 00:00:00 -0400

In the previous post we had introduced the C library for performing graphics on the OLED screen SSD1306 using a Raspberry Pi.

In this post we explain the framebuffer object and how to draw individual pixels on the screen.

The code in this post is as of git tag 0.51 or commit 294ffccc1004b35028406fc4281cef894f473d2a from Github.

UNDERSTANDING FRAMEBUFFER

The SSD1306 OLED screen has a display RAM that is of the same size as the screen pixels, with a one-to-one correspondence between pixel and a bit in the display RAM (GDRAM in the datasheet). To mimic the behavior of the RAM, we have the framebuffer object that has a buffer of the same size as the display RAM, and allows you, the developer, to draw to the framebuffer memory image, before writing that memory image directly to the display RAM of the OLED screen. This allows the programs to perform multiple drawing tasks in memory, which is faster, and then writing once via I²C to the display RAM, which is slower.

Having a framebuffer graphics object, independent of the actual SSD1306 command object, enables you to perform faster drawing by using multiple framebuffer objects. For instance, lets say you have drawn an image onto a single framebuffer object and then queued a write to the display RAM. During the time it takes to update the display RAM using I²C, you could be updating a second framebuffer object simultaneously or using multi-threading. This methodology of using more than one framebuffer has been used by game developers for several decades. This can enable fast re-drawing of the screen.

If you want to use the Raspberry Pi (or Beagleboard, etc.) with the SSD1306 OLED screen, and want to build a fun game with our library you can utilize the multiple framebuffer approach to make the game appear to display fast.

DEBUGGING FRAMEBUFFER

Sometimes, or all the time if you are me, you may want to look at what the framebuffer memory looks like, so that whatever you are drawing and expecting to see on the OLED screen, you can actually see on your computer terminal too.

To achieve that we have a function ssd1306_framebuffer_bitdump() which takes only one argument, the framebuffer pointer, and dumps the framebuffer memory to the screen in the same way it would display on the OLED screen.

#include <ssd1306_graphics.h>
/* ... some initialization code ... */
/* create the framebuffer for a OLED screen 128x32 */
ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(128, 32, NULL);
/* ... do something to the framebuffer ... */
// dump the framebuffer memory
ssd1306_framebuffer_bitdump(fbp);

Having the framebuffer object work without the need of the I²C device can be very useful for running memory leak tests using Valgrind, which we have been doing to make sure that our code is memory leak free, which it is. Valgrind works great on x86 devices but does not work reliably, as of this writing, on the Raspberry Pi. Eventually, we plan to use a USB-to-I²C device, like the TUMPA Lite which we possess, so we can test the full library directly from an x86 computer too.

DRAWING PIXELS

We have four pixel-level functions in our graphics library, three for drawing a pixel and one for knowing the pixel value. For the SSD1306 OLED screen, there are only two possible values for the pixel color: black (clear) or blue (colored). We handle that with a boolean flag.

`ssd1306_framebuffer_put_pixel()`

This function takes the (x,y) coordinates of where you want to draw the pixel on the framebuffer, the framebuffer pointer and a boolean flag for coloring or clearing the pixel. The (x,y) coordinates need to be within the width and height values of the OLED screen, which in our example below is 128x32.

The function returns 0 on success and -1 on error.

The below code snippet is present in the examples/i2c_128x32_graphics.c file.

#include <ssd1306_graphics.h>
/* ... some initialization code ... */

/* create the framebuffer for a OLED screen 128x32 */
ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(128, 32, NULL);

// for (x,y) (0, 0)
ssd1306_framebuffer_put_pixel(fbp, 0, 0, true);
// for (x,y) (127, 0)
ssd1306_framebuffer_put_pixel(fbp, fbp->width - 1, 0, true);
// for (x,y) (0, 31)
ssd1306_framebuffer_put_pixel(fbp, 0, fbp->height - 1, true);
// for (x,y) (127, 31)
ssd1306_framebuffer_put_pixel(fbp, fbp->width - 1, fbp->height - 1, true);
// for dumping the framebuffer to screen to view the changes
ssd1306_framebuffer_bitdump(fbp);

/* remove the framebuffer pointer */
ssd1306_framebuffer_destroy(fbp);

`ssd1306_framebuffer_get_pixel()`

This function returns the value of the color of the pixel, either 0 if clear (black) or 1 if colored (blue), or -1 if the arguments are invalid. This can be used by the developer in the event they want to analyze the display memory of the framebuffer. An example of where this is used is in the ssd1306_framebuffer_bitdump() function.

The usage is similar to the ssd1306_framebuffer_put_pixel() function, where the inputs are the framebuffer pointer, and the (x,y) coordinates. If the coordinates are not within the height and width of the OLED screen, or the framebuffer pointer is invalid the return value is -1.

// get the value of the color at (0,10)
int8_t color = ssd1306_framebuffer_get_pixel(fbp, 0, 10);

`ssd1306_framebuffer_invert_pixel()`

When you want to invert the color of a specific pixel location, they could do two function calls: one to ssd1306_framebuffer_get_pixel() to get the current pixel color and one to ssd1306_framebuffer_put_pixel() to change it. However, to speed up this in a single call by using the xor operation, we have the ssd1306_framebuffer_invert_pixel() function available to us.

If the color of the existing pixel at (x,y) is colored (blue) a call to this function will clear it, and if the existing pixel is clear (black) a call to this function will color it.

Below is a modified version of the above example, demonstrating coloring the pixel using the ssd1306_framebuffer_invert_pixel() function.

#include <ssd1306_graphics.h>
/* ... some initialization code ... */

/* create the framebuffer for a OLED screen 128x32 */
// the framebuffer is clear by default
ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(128, 32, NULL);

// for (x,y) (0, 0)
ssd1306_framebuffer_invert_pixel(fbp, 0, 0);
// for (x,y) (127, 0)
ssd1306_framebuffer_invert_pixel(fbp, fbp->width - 1, 0);
// for (x,y) (0, 31)
ssd1306_framebuffer_invert_pixel(fbp, 0, fbp->height - 1);
// for (x,y) (127, 31)
ssd1306_framebuffer_invert_pixel(fbp, fbp->width - 1, fbp->height - 1);
// for dumping the framebuffer to screen to view the changes
ssd1306_framebuffer_bitdump(fbp);

/* remove the framebuffer pointer */
ssd1306_framebuffer_destroy(fbp);

`ssd1306_framebuffer_put_pixel_rotation()`

There are cases that you may have when you are building display screens wher the drawings need to be rotated in position along the screen by mirror imaging the drawing using a rotation method. This can be useful for drawing mirror images of an existing diagram on one side of the screen, or for drawing rotating images.

To accomplish this task you could draw a pixel in a framebuffer and then re-draw the same image by keeping the same (x,y) coordinates, and instead rotating the drawn pixels by 90°, 180°, and 270° and back to 0°. This can be achieved by using the ssd1306_framebuffer_put_pixel_rotation() function.

It has the same signature as the ssd1306_framebuffer_put_pixel() function, with an extra argument of a rotation flag with values 1, 2 or 3 which represent the number of 90° rotations that need to be made. In fact, the ssd1306_framebuffer_put_pixel() is the same as this function, with the rotation flag set as 0.

// let's draw a diagonal line on one corner
for (size_t i = 0; i < 16; ++i) {
    ssd1306_framebuffer_put_pixel(fbp, i, i, true);
}
ssd1306_framebuffer_bitdump(fbp);

// let's mirror the same line across all 4 corners using rotation
for (size_t i = 0; i < 16; ++i) {
    ssd1306_framebuffer_put_pixel_rotation(fbp, i, i, true, 1 /* rotate by 90 degrees */);
}
for (size_t i = 0; i < 16; ++i) {
    ssd1306_framebuffer_put_pixel_rotation(fbp, i, i, true, 2 /* rotate by 180 degrees */);
}
for (size_t i = 0; i < 16; ++i) {
    ssd1306_framebuffer_put_pixel_rotation(fbp, i, i, true, 3 /* rotate by 270 degrees */);
}
ssd1306_framebuffer_bitdump(fbp);

Below is what the framebuffer dump looks like with the first line on the top-left corner, and the three mirror images of the line on the other corners.

0000 |....... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .......| 
0001 .|...... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ......|. 
0002 ..|..... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .....|.. 
0003 ...|.... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ....|... 
0004 ....|... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ...|.... 
0005 .....|.. ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ..|..... 
0006 ......|. ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .|...... 
0007 .......| ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ |....... 
0008 ........ |....... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .......| ........ 
0009 ........ .|...... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ......|. ........ 
000A ........ ..|..... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .....|.. ........ 
000B ........ ...|.... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ....|... ........ 
000C ........ ....|... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ...|.... ........ 
000D ........ .....|.. ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ..|..... ........ 
000E ........ ......|. ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .|...... ........ 
000F ........ .......| ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ |....... ........ 
0010 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0011 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0012 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0013 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0014 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0015 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0016 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0017 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0018 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0019 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001A ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001B ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001C ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001D ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001E ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
001F ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0020 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0021 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0022 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0023 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0024 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0025 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0026 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0027 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0028 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0029 ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002A ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002B ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002C ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002D ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002E ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
002F ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ 
0030 ........ .......| ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ |....... ........ 
0031 ........ ......|. ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .|...... ........ 
0032 ........ .....|.. ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ..|..... ........ 
0033 ........ ....|... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ...|.... ........ 
0034 ........ ...|.... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ....|... ........ 
0035 ........ ..|..... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .....|.. ........ 
0036 ........ .|...... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ......|. ........ 
0037 ........ |....... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .......| ........ 
0038 .......| ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ |....... 
0039 ......|. ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .|...... 
003A .....|.. ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ..|..... 
003B ....|... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ...|.... 
003C ...|.... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ....|... 
003D ..|..... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .....|.. 
003E .|...... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ......|. 
003F |....... ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ ........ .......| 

C Library for Display on OLED Chip SSD1306

Wed, 19 Feb 2020 00:00:00 -0500

We purchased a 128x32 pixel OLED screen model SSD1306 from DIYMall via Amazon to display live information on a Raspberry Pi, that we had been using for debugging a product. The requirement for a Raspberry Pi to have an HDMI screen to see live outputs on say a GPIO or SPI pin is too cumbersome, especially when you are not in your lab environment with a TV or HDMI compatible monitor lying around.

With this in mind we purchased the OLED screen that works using I2C pins on the Raspberry Pi. If your task is simple and one-off we recommend using CircuitPython or MicroPython with the Adafruit SSD1306 library. More help on this can be found at https://learn.adafruit.com/monochrome-oled-breakouts/python-usage-2.

However, we wanted to write our own library for writing to the SSD1306 OLED chip directly in C, as eventually this would be used in our internal product tools and help with longer battery life. We tested the Adafruit library and it used more CPU than expected.

INTRODUCTION

We are releasing this library on Github as open source with the MIT license. We want anyone who uses the SSD1306 on a Raspberry Pi, and who wants a library that uses low power to use this library. This is also a library for those developers who love coding in C, such as us.

The library is designed to be very easy to use. It separates out the graphics required to display information from the communication with the chip which is done using I2C. Eventually, we may add SPI to the communication options if needed.

The library allows the user to create one or more framebuffers and generate graphics for display on those framebuffers and then use the I2C functions to send the framebuffers to the screen for display.

Since we have a lot of Beaglebone Black boards lying around we will also be supporting those boards, however a blog post on that will be coming soon. We also plan to support multi-purpose debugging boards such as TUMPA Lite with this library, so that when you are reverse engineering a product using TUMPA Lite, or similar board, using a Linux machine you can display live data on that board using its I2C ports and the SSD1306 screen.

COMPILE

To compile the library we clone the repo from Github and run the following commands:

## install required pre-requisites
$ sudo apt-get -y install build-essential libfreetype6-dev  i2c-tools

## install optional libraries
$ sudo apt-get -y install libev-dev

## run our pre-configure scripts for your system
$ ./autogen.sh

## run the configure script with default options
$ ./configure

## run the configure script without libev
$ ./configure --without-libev

## if you want to install somewhere else other than /usr/local
$ ./configure --prefix=/path/to/local/install

## run make
$ make
$ make check

## install in /usr/local or your local path
$ make install

I2C TOOLS

In the above step we installed i2c-tools as a pre-requisite. That gives us i2cdetect which is a useful tool to determine the list of I2C devices attached to the system, such as a Raspberry Pi, and also determine their address.

Below is what our Raspberry Pi 3B+ showed with the OLED SSD1306 device connected via the I2C pins.

$ i2cdetect -l
i2c-1   i2c             bcm2835 I2C adapter                     I2C adapter

$ ls /dev/i2c-1
/dev/i2c-1

Above the I2C device is /dev/i2c-1, which is the first device in the list. This is the filename we will be using to access the device in our code example.

$ i2cdetect  -y 1
1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
         -- -- -- -- -- -- -- -- -- -- -- -- --
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
-- -- -- -- -- -- -- -- -- -- -- -- 3c -- -- --
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
-- -- -- -- -- -- -- --

The above command output shows us the address that the I2C device, our OLED screen, uses for every I/O request. The 1 in the command is for the first device in the list that was generated in the previous i2cdetect command shown earlier.

HEADER FILES

As of this post, there are two header files ssd1306_i2c.h and ssd1306_graphics.h that are important for the developer. The developer can include ssd1306_i2c.h to include both the files.

The ssd1306_graphics.h file has the functions for the developer to draw to a framebuffer in memory. The ssd1306_i2c.h has functions required by the developer to write to the OLED screen via the I2C bus.

EXAMPLE

We have provided examples in the examples directory. Let’s look at the test_ssd1306_i2c.c.

NOTE: this code is current as of commit a7e882980245561ca58621f684101ecaa2b56690 and may be updated in the future.

Let’s look at the main() function below.

#include <ssd1306_i2c.h>

int main ()
{
    fprintf(stderr, "DEBUG: Using library version: %s\n", ssd1306_i2c_version());
    const char *filename = "/dev/i2c-1";
    ssd1306_i2c_t *oled = ssd1306_i2c_open(filename, 0x3c, 128, 32, NULL);
    if (!oled) {
        return -1;
    }
    ssd1306_i2c_display_initialize(oled);
    sleep(3);
    ssd1306_framebuffer_t *fbp = ssd1306_framebuffer_create(oled->width, oled->height, oled->err);

    ssd1306_framebuffer_draw_bricks(fbp);
    ssd1306_framebuffer_hexdump(fbp);
    ssd1306_framebuffer_bitdump(fbp, 0, 0, true);
    ssd1306_i2c_display_update(oled, fbp);
    sleep(3);;
    ssd1306_i2c_run_cmd(oled, SSD1306_I2C_CMD_DISP_INVERTED, 0, 0);
    sleep(3);
    ssd1306_i2c_display_clear(oled);
    ssd1306_i2c_run_cmd(oled, SSD1306_I2C_CMD_DISP_NORMAL, 0, 0);
    ssd1306_framebuffer_clear(fbp);
    ssd1306_framebuffer_draw_pixel(fbp, 0, 0, false);
    ssd1306_framebuffer_draw_pixel(fbp, fbp->width - 1, 0, false);
    ssd1306_framebuffer_draw_pixel(fbp, 0, fbp->height - 1, false);
    ssd1306_framebuffer_draw_pixel(fbp, fbp->width - 1, fbp->height - 1, false);
    ssd1306_framebuffer_draw_pixel(fbp, 9, 10, false);
    ssd1306_framebuffer_bitdump(fbp, 0, 0, true);
    ssd1306_i2c_display_update(oled, fbp);
    sleep(3);
    ssd1306_framebuffer_clear(fbp);
    ssd1306_framebuffer_draw_pixel(fbp, 0, 0, true);
    ssd1306_framebuffer_draw_pixel(fbp, fbp->width - 1, 0, true);
    ssd1306_framebuffer_draw_pixel(fbp, 0, fbp->height - 1, true);
    ssd1306_framebuffer_draw_pixel(fbp, fbp->width - 1, fbp->height - 1, true);
    ssd1306_framebuffer_draw_pixel(fbp, 9, 10, true);
    ssd1306_framebuffer_bitdump(fbp, 0, 0, true);
    ssd1306_i2c_display_update(oled, fbp);
    sleep(3);
    ssd1306_i2c_run_cmd(oled, SSD1306_I2C_CMD_POWER_OFF, 0, 0);
    ssd1306_framebuffer_destroy(fbp);
    fbp = NULL;
    ssd1306_i2c_close(oled);
    oled = NULL;
    return 0;
}

We first open the device using ssd1306_i2c_open(). The device filename and the address are the same as that detected by the i2cdetect tool as shown in the section above.

The device address can be 0x3c or 0x3d and depending on i2cdetect -y 1 you must select the correct value. Based on the datasheet of the SSD1306, it is highly likely to be 0x3c. The height and width of the OLED screen are provided to the function since it initializes a copy of the memory needed to store the graphical display RAM (GDRAM) of the chip, so we could update the GDRAM all at once.

The OLED screen comes in 3 different sizes: 128x64, 128x32 and 96x16. In our example, we are using one that has the 128x32 size. This denotes the number of pixels available to the user on the OLED screen.

Next we initialize the display using the ssd1306_i2c_display_initialize() function. This function internally executes commands that turn on the display and make it ready for use.

We now create a framebuffer object and using some framebuffer functions found in ssd1306_graphics.h draw bricks onto the framebuffer object. Then we use the ssd1306_i2c_display_update() function and pass the framebuffer object to the display and make the screen display bricks.

Some extra helper functions like ssd1306_i2c_display_clear() are provided to clear the screen. The user can also debug the framebuffer object by dumping it to screen using the ssd1306_i2c_framebuffer_bitdump() function.

DEMONSTRATION

Here is a short video of the demo at https://youtu.be/PSZ2eYGcL0I.

TeaTime - An Experiment

Wed, 03 Jun 2015 00:00:00 -0400

Suppose you are an independent game developer. You are facing piracy and fake copies of your game, and you do not have the legal and economic power to handle this problem. You want to continue making games without getting discouraged by pirates, who most likely reside in other countries.

What do you do ? How do you prevent or reduce the incentive to pirate your game through reverse engineering ?

Maybe you could perform encryption of your game assets, like textures, shaders and images, to thwart the piracy and copy-cat efforts ? You could use standard encryption libraries like OpenSSL, but that still leaves the decrypted data open to access, in CPU memory, by anyone running a debugger on your software.

What if you could use OpenGL to do the encryption and leave the data in the framebuffer object and render it from there using OpenGL itself ? Then you would never have to even extract the data from GPU memory into CPU memory ! Debugging tools for OpenGL are not good enough, and reverse engineering tools for OpenGL are non-existent. Let’s try it!

Introducting `TeaTime`

We are going to demonstrate how to perform encryption and decryption of data on the GPU using OpenGL and OpenGL Shading Language (GLSL). To simplify the proof of concept, we will choose Tiny Encryption Algorithm (TEA) for the cryptography aspect. The advantage of TEA over other algorithms is twofold:

it is really light weight computationally, and
if you want to use it on mobile, it will not drain your battery as much as something like AES-256, which is compute intensive.

You could even use a simple XOR operation instead of TEA, but that’s too easy to break. We have called this proof-of-concept software TeaTime.

NOTE: This blog post:

is not for demonstrating the merits of TEA.

is not a tutorial on OpenGL.

is not a tutorial on cryptography and encryption algorithms.

only demonstrates a proof of concept.

Here is a simple method of implementing this idea:

Create a new framebuffer in addition to the default framebuffer.
Create two textures in the framebuffer.
Load your encrypted data into the first texture.
Decrypt the texture using the TEA shader code, written in GLSL, with the output written into the second texture.
Directly operate on the second texture and transfer it to the default framebuffer or do something else with it.

That’s it! All the operations are default OpenGL operations which you already use. You already are rendering to multiple textures and framebuffers, why not use that rendering concept to encrypt/decrypt data. That’s exactly what we have done with TeaTime, and we have abstracted it out into a high level API for you to use.

Description

The source code is available on Github and has been tested on Debian 7.0 Linux with AMD/ATI driver fglrx, and using the open source NVIDIA driver nouveau. You will need the GLUT, GLEW and OpenGL libraries installed to run this. The minimum required OpenGL version is 3.0. Since it uses pure OpenGL calls and is written in C, we see no reason why it will not work on iOS, Android, Windows and Mac OS X.

Our test example displays a solid teapot on the window, while performing encryption and decryption of sample data in the background.

If you look at the source code, the encryption part is placed in a function called teatime_demo(). The function is reproduced here, and the comments explain what is happening.

#define INPUT_SZ 64
#define TEA_ROUNDS 32

void teatime_demo()
{
    int rc = 0;
    teatime_t *tea = NULL;
    do {
        uint32_t ilen = INPUT_SZ;
        uint32_t input[INPUT_SZ];
        uint32_t olen = INPUT_SZ;
        uint32_t output[INPUT_SZ];
        uint32_t elen = INPUT_SZ;
        uint32_t expected[INPUT_SZ];
        /* the encryption key */
        uint32_t ikey[4] = { 0xDEADBEEF, 0xCAFEFACE,
                             0xFACEB00C, 0xF00D1337 };
        uint32_t rounds = TEA_ROUNDS;
        for (uint32_t i = 0; i < ilen; ++i)
            input[i] = (i + 1) * 5;
        for (uint32_t i = 0; i < olen; ++i)
            output[i] = 0;
        for (uint32_t i = 0; i < elen; ++i)
            expected[i] = 0;
        /* create the framebuffer here */
        tea = teatime_setup();
        if (!tea) {
            rc = -ENOMEM;
            break;
        }
        teatime_print_version(stdout);
        /* you need to set the viewport for the framebuffer */
        rc = teatime_set_viewport(tea, ilen);
        if (rc < 0)
            break;
        /* Perform encryption */
        /* Create the texture with the input data */
        rc = teatime_create_textures(tea, input, ilen);
        if (rc < 0)
            break;
        /* here you are creating the shader program for encryption */
        /* the teatime_encrypt_source() returns a null-terminated string
         * that has the source code for the TEA shader */
        rc = teatime_create_program(tea, teatime_encrypt_source());
        if (rc < 0)
            break;
        /* You are providing the number of rounds of TEA that you want to run
         * and the key with which you want to encrypt*/
        rc = teatime_run_program(tea, ikey, rounds);
        if (rc < 0)
           break;
        /* Since we want to verify the output, we are reading it back into CPU
         * memory. Ideally you will just reuse the texture by accessing the
         * tea->otexid variable for the texture. */ 
        rc = teatime_read_textures(tea, output, olen);
        if (rc < 0)
            break;
        /* Verify the output by doing CPU encryption and checking */
        for (uint32_t i = 0; i < olen && i < ilen; i += 2) {
            TEA_cpu_encrypt(&input[i], ikey, &expected[i], rounds);
            printf("%u. Encrypting Input = %08x Output = %08x Expected = %08x\n", i,
                    input[i], output[i], expected[i]);
            printf("%u. Encrypting Input = %08x Output = %08x Expected = %08x\n", i + 1,
                    input[i + 1], output[i + 1], expected[i + 1]);
        }
        for (uint32_t i = 0; i < elen; ++i)
            expected[i] = 0;
        for (uint32_t i = 0; i < olen && i < elen; i += 2) {
            TEA_cpu_decrypt(&output[i], ikey, &expected[i], rounds);
            printf("%u. Decrypting Input = %08x Output = %08x Expected = %08x\n", i, output[i],
                    expected[i], input[i]);
            printf("%u. Decrypting Input = %08x Output = %08x Expected = %08x\n", i + 1,
                    output[i + 1], expected[i + 1], input[i + 1]);
        }
        /* free up memory for now */
        teatime_delete_textures(tea);
        teatime_delete_program(tea);
        /* Perform decryption */
        for (uint32_t i = 0; i < elen; ++i)
            expected[i] = 0;
        /* the input for decryption is always the output of the encryption */
        rc = teatime_create_textures(tea, output, olen);
        if (rc < 0)
            break;
        /* here you are creating the shader program for decryption */
        /* the teatime_decrypt_source() returns a null-terminated string
         * that has the source code for the TEA shader */
        rc = teatime_create_program(tea, teatime_decrypt_source());
        if (rc < 0)
            break;
        rc = teatime_run_program(tea, ikey, rounds);
        if (rc < 0)
           break;
        rc = teatime_read_textures(tea, expected, elen);
        if (rc < 0)
            break;
        /* Verify the output by doing CPU encryption and checking */
        for (uint32_t i = 0; i < olen && i < elen; i++) {
            printf("%u. Decrypting Input = %08x Output = %08x Expected = %08x\n", i, output[i],
                    expected[i], input[i]);
        }
        teatime_delete_textures(tea);
        teatime_delete_program(tea);
    } while (0);
    teatime_cleanup(tea);
}

As you can see, we show the code for both encryption and decryption and compare it with the CPU implementations of TEA to verify the results. The TEA CPU implementations are available in the file teapot.c and the OpenGL implementation of all the teatime_* functions are available in the files teatime.h and teatime.c on Github.

The variable ikey is the encryption key in the above code. Here it is a constant, but in reality you may want to use something more dynamically generated, such as based on a user email address or phone number or device identifier. However, explaining key escrow and key management is out of the scope of this blog post. Nevertheless, here are some suggestions:

Use a unique key per asset you want to encrypt.

Try to use a set of unique keys per user of the product.

The keys should never be held in CPU memory.

Embed the key or set of keys in an encrypted asset. This will allow you to load the set of keys into texture memory and not in the CPU. Then you can decrypt the rest of the assets also on the GPU using methods like TeaTime, and directly display them on screen.

Use a verified key exchange system like Diffie-Hellman to exchange the key that will decrypt the set of unique keys onto the GPU.

Not all of the above may be feasible for your situation, but it is definitely doable. You as a developer can make that choice.

This code is fully reusable and the shader code in GLSL is a string that gets compiled at runtime by your OpenGL driver. This allows you, the developer, to actually use various encryption/decryption algorithms for different assets with the same API ! In other words, we have written the TEA algorithm for you, you can use Extended TEA (XTEA) or if you are up for a challenge, you could use AES-128 or AES-256 even.

The GPU is fully capable of running those operations as long as you have enough GPU memory available. You may also use multiple encryption algorithms for different assets, and if you’re running an online game service, you could send the shader code over the internet as well using HTTPS or other encrypted channels.

This is what the shader code for decryption looks like.

#version 130
#extension GL_EXT_gpu_shader4 : enable
uniform usampler2D idata;
uniform uvec4 ikey;
uniform uint rounds;
out uvec4 odata;
void main(void) {
    uvec4 x = texture(idata, gl_TexCoord[0].st);
    uint delta = 0x9e3779b9;
    uint sum = delta * rounds;
    for (uint i = 0; i < rounds; ++i) {
      x[1] -= (((x[0] << 4) + ikey[2]) ^ (x[0] + sum)) ^ ((x[0] >> 5) + ikey[3]);
      x[0] -= (((x[1] << 4) + ikey[0]) ^ (x[1] + sum)) ^ ((x[1] >> 5) + ikey[1]);
      x[3] -= (((x[2] << 4) + ikey[2]) ^ (x[2] + sum)) ^ ((x[2] >> 5) + ikey[3]);
      x[2] -= (((x[3] << 4) + ikey[0]) ^ (x[3] + sum)) ^ ((x[3] >> 5) + ikey[1]);
      sum -= delta;
   } 
   odata = x;
}

Demonstration

Here is a short video of the demo.

If you liked this, subscribe to our newsletter to receive our monthly research articles, or follow us on Twitter.

First Post!

Fri, 01 May 2015 00:00:00 -0400

Our interests in the field of reverse engineering, embedded hardware and cryptography will be the main feature of this blog. As a team of reverse engineers and developers, we encounter a variety of systems in use that are past manufacturing date or are not supported anymore. We help recover, repurpose or build modules to enhance such systems while maintaining their original purpose.

With this blog, we plan to showcase some of our past work and new work as we do it in some cases where open sourcing our efforts is in everyone’s benefit.

We hope developers will benefit from our blog.

Stealthy Labs Blog

How to setup ZoneMinder on Ubuntu 24.04 LTS

REQUIREMENTS

INSTALLATION OF UBUNTU

INSTALLING ZoneMinder

Install Apache and MariaDB

Setup Users in MariaDB

Install ZoneMinder

Configure ZoneMinder DB Password

Configure PHP Time Zone

Configure Apache2

Web Interface

Configuring Additional Drives

Using libev and libssd1306 to display a clock

USING WITH libev

UNDERSTANDING THE CODE

Initializing the OLED screen

Setting up the event loop

Defining the timer callback

DEMONSTRATION

C Library for Reading GPS data from a GlobalTop MTK3339

DATASHEET LINKS

CONNECTING THE GPS BREAKOUT BOARD

Using the USB-to-TTL Cable

Connecting via GPIO Pins on Raspberry Pi

COMPILING THE LIBRARY

READING THE DATA

Example with libev

Header Files

Logging

Opening the device

Creating the Parser

Sending Messages to the GPS Device

Using the Device with libev

Updated Drawing Text on OLED Chip SSD1306 Using FreeType2

BITDUMP COLOR

DRAWING TEXT

SUPPORTED FONT FACES

ROTATING THE FONT

ROTATING PIXELS

Drawing Lines on OLED Chip SSD1306

Drawing Text on OLED Chip SSD1306 Using FreeType2

DRAWING TEXT

SUPPORTED FONT FACES

ROTATING THE FONT

ROTATING PIXELS

Framebuffer and Drawing Pixels on OLED Chip SSD1306

UNDERSTANDING FRAMEBUFFER

DEBUGGING FRAMEBUFFER

DRAWING PIXELS

ssd1306_framebuffer_put_pixel()

ssd1306_framebuffer_get_pixel()

ssd1306_framebuffer_invert_pixel()

ssd1306_framebuffer_put_pixel_rotation()

C Library for Display on OLED Chip SSD1306

INTRODUCTION

COMPILE

I2C TOOLS

HEADER FILES

EXAMPLE

DEMONSTRATION

TeaTime - An Experiment

Introducting TeaTime

Description

Demonstration

First Post!

USING WITH `libev`

Example with `libev`

Using the Device with `libev`

`ssd1306_framebuffer_put_pixel()`

`ssd1306_framebuffer_get_pixel()`

`ssd1306_framebuffer_invert_pixel()`

`ssd1306_framebuffer_put_pixel_rotation()`

Introducting `TeaTime`