Part 8: SSD1306 Title Animation

Turn a still framebuffer into stars that assemble into WITH / RASPBERRY PI, hold the title, then scatter. This standalone C++17 sample separates drawing, frame pacing and I2C output; it does not start a background screensaver.

Sample code on GitHub

Sample and README · C++ source · CMake build instructions

The CMake target is oled_title. The downloadable standalone file matches the repository's main.cpp; no external font or course-specific C++ header is required.

Before you start

Complete your first SSD1306 display. For actual output, that still image must already be visibly correct on your documented 3.3 V-compatible, four-pin, 128×64 SSD1306 I2C module with an internal charge pump. This is not an SH1106, SPI or 128×32 example. Use the previous lesson's power, pin-numbering and I2C-permission checks; do not rewire a powered board.

Run the commands on the Pi, or build the preview on a Linux computer. You need basic C++17, Git, CMake 3.28+, Make and Python 3 for the tests. The rendering and software tests need no display, root access or additional libraries.

Outcome: explain how a frame changes over time, preview the held title without opening I2C, then deliberately run a finite animation that sends Display Off before normal exit.

The original effect and this recreation

Original Raspberry Pi 4B footage from October 2026. The sample below recreates the effect; this is not a recording of the new executable.

The original temporary animation source was not retained. This new implementation follows its stars → forming title → held title idea, with a compact built-in font and deterministic particles. It is not a recovered original program, a pixel-exact reproduction, or a claim that the footage measures this sample's speed.

1. Build in a fresh practice directory

First inspect your installed tools:

c++ --version
cmake --version
python3 --version
git --version

If a requirement is missing, prepare the development environment first. Do not build with sudo.

The following commands create a new temporary directory and download the examples:

title_practice=$(mktemp -d /tmp/pi-oled-title.XXXXXX)
git clone https://github.com/ohyaan/with-raspberry-pi-examples.git "$title_practice/examples"
cd "$title_practice/examples/cpp-hardware-programming"
cmake --preset native-debug
cmake --build --preset native-debug --parallel 2
ctest --preset native-debug --output-on-failure

The category currently has 42 software checks, including nine animation checks. They cover deterministic previews, argument limits and a link-time fake I2C bus. No test opens a real GPIO, PWM or I2C device. A simulated Display Off check is not evidence of visible pixels or working wiring.

Keep this terminal in the category directory. /tmp is temporary storage; keep your own changed source somewhere durable if needed.

2. Render without opening the bus

./build/native/debug/oled_title /unverified-device 0x3c

Expected output:

Dry run: WITH / RASPBERRY PI, 128x64, 128 frames, target 16 fps, 1024 framebuffer bytes.
checksum=2626571566
No I2C device opened.

/unverified-device is deliberately not a real device. Here 0x3c is an argument-format example, not discovery of your module's address. Both the dry run and the preview avoid opening the bus.

Export the held-title frame into the new practice directory:

./build/native/debug/oled_title /unverified-device 0x3c --preview 64 > "$title_practice/title.pbm"

Open title.pbm in a PBM-capable image viewer, or copy it to your client computer. This is a 128×64 binary PBM P4 file. Black PBM pixels represent lit OLED pixels; the software preview below inverts those colours for a display-like view.

The source uses the same page-oriented framebuffer as the previous lesson:

byte index = x + (y / 8) * 128
bit mask   = 1 << (y % 8)

The PBM exporter converts those vertical page bits into horizontal, most-significant-bit-first rows. Dumping the 1024 framebuffer bytes straight into a PBM would not produce this image.

3. Understand the 128-frame scene

title_pixels() draws two lines into a temporary framebuffer, then collects the lit coordinates as particle destinations. Each particle gets a reproducible starting position from an integer hash of its index. No wall clock or random seed changes the rendering.

Frame within the cycle	Scene
0–15	Moving stars
16–47	Particles move toward their title positions
48–95	Title stays readable; stars move outside its rows
96–111	Particles move away from the title
112–127	Stars only

The next frame starts the same scene again if you request more than 128 frames. The normal run sends just one cycle. The target 16 frames/second makes that an intended eight-second sequence, not proof that every bus and OS can deliver it in eight seconds.

The interpolation uses integer smoothstep: for t from 0 to 32, t*t*(96-2*t) goes from 0 to 32*32*32. Applying that fraction to a particle's start-to-target offset slows its approach near the final position. pixel() clips coordinates to the 128×64 buffer.

4. Run one cycle on the verified OLED

Use the actual bus and 7-bit address established in the previous lesson. The example below assumes /dev/i2c-1 and 0x3c; 0x3d is also accepted when that is your verified address. An I2C acknowledgement alone does not identify a controller.

Close other programs that write to the same OLED. If fuser is installed, fuser /dev/i2c-1 is a read-only check for visible bus users, not a guarantee that every possible writer has been identified. Do not kill an unfamiliar process or use I2C_SLAVE_FORCE.

Only after the still-frame, module, permission and ownership checks, enable output:

./build/native/debug/oled_title /dev/i2c-1 0x3c --show

For a completed 128-frame run:

frames_sent=128 target_fps=16 stopped=complete
Display Off command sent; no background process remains.
I2C writes are not pixel readback or an achieved-FPS measurement.

The display should show the scene and then turn off. Look at the physical panel: successful writes do not prove the pixels are correct. This sample resets orientation, addressing and contrast for its own output; it does not preserve a previous program's panel state.

Press Ctrl+C to request an earlier stop. The handler sets a flag; the normal loop sends Display Off and closes I2C. A signal exit returns status 130. The number of frames sent before the signal varies.

For a deliberately shorter run:

./build/native/debug/oled_title /dev/i2c-1 0x3c --show --frames 64 --fps 16

That stops during the held title; it is not a full cycle. --frames accepts 1–600, --fps accepts 1–30, and requested duration must be no longer than 30 seconds. A steady-clock deadline is checked between frames too. It cannot preempt a kernel I2C call that is already blocked.

To send Display Off again deliberately:

./build/native/debug/oled_title /dev/i2c-1 0x3c --off

Normal completion sends Display Off; exceptions try it as best-effort cleanup. A disconnected bus, power loss or SIGKILL can prevent cleanup. Do not leave a static, bright title running as a permanent installation and assume moving stars prevent OLED wear.

5. Separate drawing, transfer and pacing

• Drawing: render() returns exactly 1024 bytes, without opening I2C or sleeping. That makes previews and fixture comparisons repeatable.
• Transfer: Bus::initialize() configures the panel once. show() resets its column/page window for each frame and sends chunks with the 0x40 data control byte. Short writes stop the run rather than silently accepting a partial frame.
• Pacing: steady_clock and short sleeps avoid a busy loop. If a transfer is slow, the next frame is scheduled from the current time instead of sending a burst of overdue frames.
• Shutdown: the foreground loop owns the bus. There is no systemd service, reboot requirement, bus-speed edit or permanent background animation.

The sample requests low contrast (0x30) but does not measure brightness, power consumption or OLED lifetime. Full-frame transfers are not synchronized to panel scanout and are not claimed to be tear-free.

Full standalone C++ source

Complete file: app/oled-title/main.cpp. Download the same file.

/*
 * MIT License
 * Copyright (c) 2025-2026 ohyaan
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 *
 * I2C initialization/transfer adapted from ohyaan/ssd1306 and oled_hello.
 * Animation and compact title glyphs are defined here, not an external font.
 * Recreates the site's title effect; not the recovered original demo source.
 */
#include <algorithm>
#include <array>
#include <cerrno>
#include <charconv>
#include <chrono>
#include <csignal>
#include <cstdint>
#include <cstring>
#include <fcntl.h>
#include <iostream>
#include <linux/i2c-dev.h>
#include <stdexcept>
#include <string>
#include <string_view>
#include <sys/ioctl.h>
#include <thread>
#include <unistd.h>
#include <vector>

constexpr int width = 128;
constexpr int height = 64;
constexpr unsigned cycle_frames = 128;
using Frame = std::array<std::uint8_t, width * height / 8>;
struct Point {
    int x;
    int y;
};

volatile std::sig_atomic_t interrupted = 0;
extern "C" void stop_animation(int) {
    interrupted = 1;
}

void pixel(Frame& frame, int x, int y) {
    if (x >= 0 && x < width && y >= 0 && y < height) {
        frame[static_cast<std::size_t>(x + y / 8 * width)] |=
            static_cast<std::uint8_t>(1u << (y % 8));
    }
}

bool lit(const Frame& frame, int x, int y) {
    return (frame[static_cast<std::size_t>(x + y / 8 * width)] &
            (1u << (y % 8))) != 0;
}

std::array<unsigned, 7> glyph(char c) {
    // Four-bit rows (five for W), most significant bit on the left.
    switch (c) {
    case 'W':
        return {17, 17, 17, 21, 21, 21, 10};
    case 'I':
        return {15, 6, 6, 6, 6, 6, 15};
    case 'T':
        return {15, 6, 6, 6, 6, 6, 6};
    case 'H':
        return {9, 9, 9, 15, 9, 9, 9};
    case 'R':
        return {14, 9, 9, 14, 10, 9, 9};
    case 'A':
        return {6, 9, 9, 15, 9, 9, 9};
    case 'S':
        return {7, 8, 8, 6, 1, 1, 14};
    case 'P':
        return {14, 9, 9, 14, 8, 8, 8};
    case 'B':
        return {14, 9, 9, 14, 9, 9, 14};
    case 'E':
        return {15, 8, 8, 14, 8, 8, 15};
    case 'Y':
        return {9, 9, 9, 6, 6, 6, 6};
    case ' ':
        return {};
    default:
        throw std::runtime_error("Only WITH RASPBERRY PI glyphs are defined.");
    }
}

std::vector<Point> title_pixels() {
    Frame title{};
    const std::array<std::string_view, 2> lines{"WITH", "RASPBERRY PI"};
    for (std::size_t line = 0; line < lines.size(); ++line) {
        const auto text = lines[line];
        int text_width = -2;
        for (char c : text) {
            text_width += (c == 'W' ? 5 : 4) * 2 + 2;
        }
        int x = (width - text_width) / 2;
        const int y = line == 0 ? 12 : 34;
        for (char c : text) {
            const auto rows = glyph(c);
            for (int row = 0; row < 7; ++row) {
                for (int column = 0; column < (c == 'W' ? 5 : 4); ++column) {
                    if (rows[static_cast<std::size_t>(row)] &
                        ((c == 'W' ? 16u : 8u) >> column)) {
                        for (int dy = 0; dy < 2; ++dy) {
                            for (int dx = 0; dx < 2; ++dx) {
                                pixel(title, x + column * 2 + dx,
                                      y + row * 2 + dy);
                            }
                        }
                    }
                }
            }
            x += (c == 'W' ? 5 : 4) * 2 + 2;
        }
    }
    std::vector<Point> result;
    for (int y = 0; y < height; ++y) {
        for (int x = 0; x < width; ++x) {
            if (lit(title, x, y)) {
                result.push_back({x, y});
            }
        }
    }
    return result;
}

std::uint32_t mix(std::uint32_t value) {
    value ^= value >> 16;
    value *= 0x7feb352du;
    value ^= value >> 15;
    value *= 0x846ca68bu;
    return value ^ (value >> 16);
}

Frame render(unsigned number, const std::vector<Point>& targets) {
    Frame frame{};
    const unsigned phase = number % cycle_frames;
    for (unsigned star = 0; star < 24; ++star) {
        const auto seed = mix(star + 19);
        const int x = static_cast<int>(
            (seed % width + phase * (1 + star % 3) / 4) % width);
        const int y =
            static_cast<int>(((seed >> 8) % height + phase / 8) % height);
        // Keep the two held title lines readable; stars are background only.
        if (phase >= 48 && phase < 96 && y >= 10 && y <= 49) {
            continue;
        }
        if ((phase / 4 + star) % 4 != 0) {
            pixel(frame, x, y);
        }
    }
    if (phase < 16 || phase >= 112) {
        return frame;
    }
    const unsigned t =
        phase < 48 ? phase - 16 : (phase < 96 ? 32 : (112 - phase) * 2);
    const int eased = static_cast<int>(t * t * (96 - 2 * t));
    constexpr int denominator = 32 * 32 * 32;
    for (std::size_t i = 0; i < targets.size(); ++i) {
        const auto seed = mix(static_cast<std::uint32_t>(i) + 937);
        const int start_x = static_cast<int>(seed % width);
        const int start_y = static_cast<int>((seed >> 8) % height);
        const auto target = targets[i];
        pixel(frame, start_x + (target.x - start_x) * eased / denominator,
              start_y + (target.y - start_y) * eased / denominator);
    }
    return frame;
}

void preview(const Frame& frame) {
    // PBM P4 uses row-major, most-significant-bit-first pixels, unlike SSD1306.
    std::cout << "P4\n128 64\n";
    for (int y = 0; y < height; ++y) {
        for (int x = 0; x < width; x += 8) {
            std::uint8_t byte = 0;
            for (int bit = 0; bit < 8; ++bit) {
                if (lit(frame, x + bit, y)) {
                    byte |= static_cast<std::uint8_t>(0x80u >> bit);
                }
            }
            std::cout.put(static_cast<char>(byte));
        }
    }
    if (!std::cout) {
        throw std::runtime_error("Write preview failed.");
    }
}

class Bus {
  public:
    Bus(const char* device, unsigned address) {
        fd_ = open(device, O_RDWR | O_CLOEXEC);
        if (fd_ < 0) {
            throw std::runtime_error(std::string("Open I2C: ") +
                                     std::strerror(errno));
        }
        if (ioctl(fd_, I2C_SLAVE, address) < 0) {
            const std::string error = std::strerror(errno);
            close(fd_);
            throw std::runtime_error("Select I2C address: " + error);
        }
    }
    ~Bus() {
        // Best-effort cleanup during an exception. A disconnected bus can fail.
        if (touched_) {
            try {
                command(0xae);
            } catch (...) {
            }
        }
        close(fd_);
    }
    Bus(const Bus&) = delete;
    Bus& operator=(const Bus&) = delete;

    void command(std::uint8_t value) {
        touched_ = true;
        const std::array<std::uint8_t, 2> bytes{0x00, value};
        transfer(bytes.data(), bytes.size());
    }
    void initialize() {
        constexpr std::uint8_t commands[] = {
            0xae, 0xd5, 0x80, 0xa8, 0x3f, 0xd3, 0x00, 0x40, 0x8d,
            0x14, 0x20, 0x00, 0xa1, 0xc8, 0xda, 0x12, 0x81, 0x30,
            0xd9, 0xf1, 0xdb, 0x40, 0xa4, 0xa6, 0x2e};
        for (auto value : commands) {
            command(value);
        }
    }
    void show(const Frame& frame) {
        // Reset the full addressing window for each 1024-byte frame.
        for (auto value : {0x21, 0x00, 0x7f, 0x22, 0x00, 0x07}) {
            command(static_cast<std::uint8_t>(value));
        }
        for (std::size_t offset = 0; offset < frame.size();) {
            std::array<std::uint8_t, 32> chunk{};
            chunk[0] = 0x40;
            const auto count = std::min<std::size_t>(31, frame.size() - offset);
            std::copy_n(frame.data() + offset, count, chunk.data() + 1);
            transfer(chunk.data(), count + 1);
            offset += count;
        }
    }
    void off() {
        command(0xae);
        touched_ = false;
    }

  private:
    int fd_ = -1;
    bool touched_ = false;
    void transfer(const std::uint8_t* bytes, std::size_t count) {
        const auto written = write(fd_, bytes, count);
        if (written < 0) {
            throw std::runtime_error(std::string("I2C write: ") +
                                     std::strerror(errno));
        }
        if (written != static_cast<ssize_t>(count)) {
            throw std::runtime_error(
                "Short I2C write; stop and check the connection.");
        }
    }
};

unsigned number(std::string_view value, unsigned minimum, unsigned maximum) {
    unsigned result = 0;
    const auto parsed =
        std::from_chars(value.data(), value.data() + value.size(), result);
    if (parsed.ec != std::errc{} || parsed.ptr != value.data() + value.size() ||
        result < minimum || result > maximum) {
        throw std::runtime_error(
            "Numeric argument outside its permitted range.");
    }
    return result;
}

int main(int argc, char* argv[]) {
    try {
        if (argc < 3) {
            throw std::runtime_error(
                "Usage: oled_title DEVICE 0x3c|0x3d [--show|--off|--preview "
                "FRAME] [--frames N] [--fps N]");
        }
        const std::string_view address_text(argv[2]);
        if (address_text != "0x3c" && address_text != "0x3d") {
            throw std::runtime_error(
                "Use the verified 7-bit address 0x3c or 0x3d.");
        }
        const unsigned address = address_text == "0x3c" ? 0x3c : 0x3d;
        std::string_view mode = "dry-run";
        unsigned frames = cycle_frames;
        unsigned fps = 16;
        unsigned preview_frame = 64;
        bool frames_set = false;
        bool fps_set = false;
        for (int i = 3; i < argc; ++i) {
            const std::string_view flag(argv[i]);
            if (flag == "--show" || flag == "--off" || flag == "--preview") {
                if (mode != "dry-run") {
                    throw std::runtime_error("Choose only one output mode.");
                }
                mode = flag;
                if (flag == "--preview") {
                    if (++i >= argc) {
                        throw std::runtime_error("Missing preview frame.");
                    }
                    preview_frame = number(argv[i], 0, cycle_frames - 1);
                }
            } else if (flag == "--frames" || flag == "--fps") {
                if (++i >= argc) {
                    throw std::runtime_error("Missing numeric argument.");
                }
                bool& specified = flag == "--frames" ? frames_set : fps_set;
                if (specified) {
                    throw std::runtime_error("Repeated numeric option.");
                }
                specified = true;
                if (flag == "--frames") {
                    frames = number(argv[i], 1, 600);
                } else {
                    fps = number(argv[i], 1, 30);
                }
            } else {
                throw std::runtime_error("Unknown option.");
            }
        }
        if ((mode == "--off" || mode == "--preview") &&
            (frames_set || fps_set)) {
            throw std::runtime_error(
                "Frame count and rate are for animation or dry run only.");
        }
        if (mode != "--off" && mode != "--preview" && frames > fps * 30) {
            throw std::runtime_error(
                "Requested animation must be no longer than 30 seconds.");
        }
        const auto targets = title_pixels();
        if (mode == "--preview") {
            preview(render(preview_frame, targets));
            return 0;
        }
        if (mode == "dry-run") {
            std::uint32_t checksum = 2166136261u;
            for (unsigned f = 0; f < frames; ++f) {
                for (auto byte : render(f, targets)) {
                    checksum = (checksum ^ byte) * 16777619u;
                }
            }
            std::cout << "Dry run: WITH / RASPBERRY PI, 128x64, " << frames
                      << " frames, target " << fps << " fps, " << Frame{}.size()
                      << " framebuffer bytes.\nchecksum=" << checksum
                      << "\nNo I2C device opened.\n";
            return 0;
        }
        Bus bus(argv[1], address);
        if (mode == "--off") {
            bus.off();
            std::cout << "Display Off command sent.\n";
            return 0;
        }
        std::signal(SIGINT, stop_animation);
        std::signal(SIGTERM, stop_animation);
        using Clock = std::chrono::steady_clock;
        const auto period = std::chrono::microseconds(1000000 / fps);
        auto next = Clock::now();
        const auto deadline = next + std::chrono::seconds(30);
        bus.initialize();
        unsigned sent = 0;
        for (; sent < frames && !interrupted && Clock::now() < deadline;
             ++sent) {
            bus.show(render(sent, targets));
            if (sent == 0) {
                bus.command(0xaf);
            }
            next = std::max(next + period, Clock::now());
            // Short sleeps make Ctrl+C responsive without doing I2C in a
            // handler.
            while (!interrupted && Clock::now() < next) {
                std::this_thread::sleep_until(std::min(
                    next, Clock::now() + std::chrono::milliseconds(10)));
            }
        }
        bus.off();
        std::cout
            << "frames_sent=" << sent << " target_fps=" << fps << " stopped="
            << (interrupted ? "signal"
                            : (sent == frames ? "complete" : "deadline"))
            << "\nDisplay Off command sent; no background process remains.\n"
               "I2C writes are not pixel readback or an achieved-FPS "
               "measurement.\n";
        return interrupted ? 130 : (sent == frames ? 0 : 1);
    } catch (const std::exception& error) {
        std::cerr << error.what() << '\n';
        return 1;
    }
}

An alternative direct build from the same checkout is:

c++ -std=c++17 -Wall -Wextra -Wpedantic -Werror -pthread \
  app/oled-title/main.cpp -o "$title_practice/oled_title"
"$title_practice/oled_title" /unverified-device 0x3c

This compiles only the standalone program; it does not replace the CTest suite.

Troubleshooting and verification scope

Result	Next check
Open I2C error	Device path, enabled interface and the login's permissions; do not make root the default workaround
Address-selection or write error	Correct bus, module, address and competing driver/writer; power down before checking wiring
Writes succeed but the display is blank or distorted	First reproduce the previous lesson's still image; verify the actual controller and dimensions
Fewer frames or slower motion	Inspect the transfer path and requested pacing; do not treat target_fps as a measurement or change bus speed blindly
Panel stays lit after interruption	Use the explicit --off command if I2C works; forced termination and electrical faults cannot guarantee cleanup

On 25 October 2026, the host (GCC 15.2) and Pi 4B (AArch64, GCC 14.2, CMake 3.31.6, Debian 13-based Raspberry Pi OS, kernel 6.18.50+rpt-rpi-v8) passed all 42 software checks in Debug and Release. The Pi sent all 128 frames to the already connected /dev/i2c-1, address 0x3c, then sent Display Off. A separate SIGINT run also exited after sending Display Off. No package, bus-speed or service configuration was changed.

Those are software/transfer results, not a new camera recording, pixel readback, achieved-frame-rate or power measurement. The video above remains the earlier physical demonstration. The fake-bus tests additionally cover payload packing, I/O errors, short writes and address-selection failure without touching hardware.

Practice before the next lesson

Without --show, export frames 0, 32, 64 and 112. Explain why only frame 64 contains the held title. Then plan a 64-frame run at 16 fps: how much of the eight-second scene would it request?

Hint and expected result

Frames 0 and 112 are stars-only phases; frame 32 is assembling. Frame 64 is inside 48–95, the held-title range. Sixty-four frames at a target of 16 fps request four seconds, ending partway through the held title. File rendering does not prove a physical refresh rate.

Check your understanding and continue

Why should render() avoid I2C and sleeps? Why is 0x40 not the device address? What can prevent Display Off even with a signal handler? Why is the original video not a benchmark of this new program?

Return to C++ Hardware Programming, revisit the first still display, or learn how to send application data in the Network course. A live temperature/network status display is a further integration project, not a feature of this title sample.

References: Linux I2C device interface, SSD1306 datasheet, and the original MIT-licensed driver.