BLE Cat Thermal Printer with MEMENTO

by Liz Clark

published February 23, 2024, last updated February 23, 2024

posted in Hacks Sensors/ Camera Arduino Compatibles Internet of Things - IOT/ Bluefruit / BLE

Save Download

Updated

Intermediate

Project guide

Overview

Picture it: Toys "R" Us, 1998. Sonic has yet to run on a Nintendo system and there is only one PlayStation. Your eye catches the new Game Boy Printer behind a security cage and you think about how cool it would be to print out your Pokémon stats to show off to your friends at recess.

Almost 30 years later and everything old is new again. You can use the MEMENTO camera board with an internet famous BLE cat thermal printer to instantly print photos with the classic "Gameboy" grayscale filter.

The ESP32-S3 on the MEMENTO connects to the cat printer over BLE with the CatGFX library. The MEMENTO runs a "Gameboy" filter on the incoming frames from the onboard camera module. When you press the shutter/boot button, the image is sent to the cat printer for printing.

You can choose to print your images with a Polaroid-style frame around the picture. You can press the select button to enable or disable the frame.

On startup, the MEMENTO display will let you know if there are any initial connection problems with the printer. You can also press the down button once the code is running to disconnect and reconnect to the printer.

Cat Printer

There are many versions of the BLE cat printer out there in the world. This project is aimed at the MX06 variant of the printer, which at the time of writing seems to be the most common type.

1 x BLE Cat Thermal Printer

BLE Cat Thermal Printer - MX06 variant

Buy Now

Parts

MEMENTO - Python Programmable DIY Camera - Bare Board

Make memories, or just a cool camera-based project, with Adafruit's MEMENTO Camera Board. It's a development board with everything you need to create...

guides with product

$34.95

In Stock

Add to Cart

Lithium Ion Polymer Battery 3.7v 420mAh with JST 2-PH connector and short cable

Lithium Ion Polymer Battery with Short Cable - 3.7V 420mAh

Lithium-ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light, and powerful. The output ranges from 4.2V when completely charged to 3.7V. This...

$6.95

In Stock

Add to Cart

Angled shot of coiled pink and purple USB cable with USB A and USB C connectors.

Pink and Purple Woven USB A to USB C Cable - 1 meter long

This cable is not only super-fashionable, with a woven pink and purple Blinka-like pattern, it's also made for USB C for our modernized breakout boards, Feathers, and...

$2.95

In Stock

Add to Cart

Text editor powered by tinymce.

Software

The Arduino code for the MEMENTO and cat printer is available as a pre-compiled .UF2 file that you can drag and drop onto your MEMENTO board.

Memento_Cat_Printer.uf2

Load the UF2

Click the link above to download the UF2 file.

Save it wherever is convenient for you.

Plug your board into your computer, using a known-good data-sync USB cable, directly, or via an adapter if needed.

Double-click the reset button (highlighted in red above), wait about a half a second and then tap reset again.

You will see a new disk drive appear called CAMERABOOT.

Drag the UF2 file to CAMERABOOT.

The code will begin running by initializing the MEMENTO and then connecting to the cat printer. After a successful connection, you'll see the camera frame show on the display with the gameboy filter.

Code

Download File

Copy Code

// SPDX-FileCopyrightText: 2024 Liz Clark for Adafruit Industries
//
// SPDX-License-Identifier: MIT

#include <Arduino.h>
#include "Adafruit_PyCamera.h"
#include <CatGFX.h>
// CatGFX library source is included in the project with modifications
// https://github.com/TheNitek/CatGFX

Adafruit_PyCamera pycamera;

bool frame = true;

String frame_info[] = {"NO", "YES"};

// Buffer which can hold 400 lines
byte buffer[48 * 400] = {0};

// Create a printer supporting those 400 lines
CatPrinter cat(400);

// hard reset
void(* resetFunc) (void) = 0;

// atkinson dithering algorithm parameters from CircuitPython
struct DitherAlgorithmInfo {
    int mx, my;
    int divisor;
    struct { int dx, dy, dl; } terms[4];
} atkinson = {
    1, 1, 8, // mx, my, divisor
    {
        {1, 0, 1}, {-1, 1, 1}, {0, 1, 1}, {1, 1, 1} // dx, dy, dl
    }
};

// this sends a full bitmap to the printer
void gameboy(uint16_t *source, int width, int height, bool createForPrinter) {
    uint16_t *bitmap = new uint16_t[width * height];
    int16_t *errorBuffer = new int16_t[(width + 2) * (height + 2)]();
    uint8_t *bitmapForPrinter = nullptr;
    if (createForPrinter) {
        bitmapForPrinter = new uint8_t[(width * height)]();
    }
    // dither the pixels
    // referenced from CP module
    for (int y = 0; y < height; y++) {
      for (int x = 0; x < width; x++) {
          int idx = (y + 1) * (width + 2) + (x + 1);
          uint16_t rgb = source[y * width + x];
          uint8_t r = (rgb & 0xF800) >> 8;
          uint8_t g = (rgb & 0x07E0) >> 3;
          uint8_t b = (rgb & 0x001F) << 3;
          uint8_t grayscale = (r * 30 + g * 59 + b * 11) / 100;
          grayscale += errorBuffer[idx] / atkinson.divisor;
          uint16_t outPixel = grayscale > 127 ? 0xFFFF : 0x0000; // White or Black for RGB bitmap
          bitmap[y * width + x] = outPixel;
          if (createForPrinter) {
              if (grayscale <= 127) {
                  bitmapForPrinter[(y * width + x) / 8] |= (1 << (7 - (x % 8)));
              }
          }
          int16_t error = grayscale - (outPixel ? 255 : 0);
          for (int i = 0; i < 4; i++) {
              int dx = atkinson.terms[i].dx, dy = atkinson.terms[i].dy;
              errorBuffer[idx + dy * (width + 2) + dx] += error * atkinson.terms[i].dl;
          }
      }
  }
    if (createForPrinter == true) {
        cat.fillScreen(1);
        cat.drawBitmap(72, 25, bitmapForPrinter, 240, 240, 0);
        if (frame == true) {
          cat.drawRect(50, 0, 285, 350, 0);
          cat.drawRect(71, 24, 242, 242, 0);
          cat.setTextSize(2);
          cat.setTextColor(0);
          cat.setCursor(72, 300);
          cat.print("shot on MEMENTO");
        }
        delay(500);
        Serial.println("Printing...");
        cat.printBuffer();
        delay(500);
        Serial.println("scrolling..");
        cat.feed(50);
        Serial.println("Done!");
    } 
    pycamera.drawRGBBitmap(0, 0, bitmap, width, height);
    pycamera.refresh();
    delete[] bitmap;
    delete[] errorBuffer;
    delete[] bitmapForPrinter;
}

void setup() {
  Serial.begin(115200);
  // while (!Serial) delay(10);
  Serial.println();
  if (!pycamera.begin()) {
    Serial.println("Failed to initialize pyCamera interface");
    while (1)
      yield();
  }
  Serial.println("pyCamera hardware initialized!");
  pycamera.fillScreen(pycamera.color565(0, 0, 0));
  pycamera.setCursor(10, 10);
  pycamera.setTextSize(2);
  pycamera.setTextColor(pycamera.color565(0, 0, 255));
  pycamera.print("CONNECTING..");
  Serial.print("Connecting to cat printer..");
  cat.begin(buffer, sizeof(buffer));
  Serial.print(".");
  cat.resetNameArray();
  Serial.print(".");
  cat.addNameArray((char *)"MX06");
  Serial.println(".");
  if (cat.connect()) {
    Serial.println("Connected!");
    }
    else {
    Serial.println("Could not find printer! Resetting..");
    pycamera.fillScreen(pycamera.color565(0, 0, 0));
    pycamera.setCursor(10, 10);
    pycamera.setTextSize(2);
    pycamera.setTextColor(pycamera.color565(255, 0, 0));
    pycamera.print("Could not\nfind printer!\nResetting..");
    delay(200);
    resetFunc();
  }
  Serial.println("going into loop");
}

void loop() {
  pycamera.readButtons();
  pycamera.captureFrame();
  pycamera.setNeopixel(0x00FF00);
  // blits gameboy filter to display but does not print
  gameboy((uint16_t *)pycamera.fb->getBuffer(), 240, 240, false);
  // pressing shutter prints the frame
  if (pycamera.justPressed(SHUTTER_BUTTON)) {
    pycamera.setNeopixel(0x0000FF);
    pycamera.setCursor(25, 25);
    pycamera.setTextSize(3);
    pycamera.setTextColor(pycamera.color565(255, 0, 255));
    pycamera.print("PRINTING..");
    gameboy((uint16_t *)pycamera.fb->getBuffer(), 240, 240, true);
    Serial.println("SHUTTER");
  }

  if (pycamera.justPressed(AWEXP_BUTTON_SEL)) {
    frame = not frame;
    pycamera.fillScreen(pycamera.color565(0, 0, 0));
    pycamera.setCursor(10, 10);
    pycamera.setTextSize(3);
    pycamera.setTextColor(pycamera.color565(255, 0, 0));
    pycamera.println("Print with \nframe?");
    pycamera.println(frame_info[frame]);
    delay(2000);
    Serial.println("SEL");
  }
  if (pycamera.justPressed(AWEXP_BUTTON_DOWN)){
    cat_reconnect();
    Serial.println("DOWN");
  }
}

void cat_reconnect() {
  Serial.println("Disconnecting..");
  pycamera.fillScreen(pycamera.color565(0, 0, 0));
  pycamera.setCursor(10, 10);
  pycamera.setTextSize(2);
  pycamera.setTextColor(pycamera.color565(0, 0, 255));
  pycamera.print("DISCONNECTING..");
  cat.disconnect();
  Serial.println("Disconnected.");
  delay(1000);
  pycamera.fillScreen(pycamera.color565(0, 0, 0));
  pycamera.setCursor(10, 10);
  pycamera.setTextSize(2);
  pycamera.setTextColor(pycamera.color565(0, 0, 255));
  pycamera.print("CONNECTING..");
  cat.resetNameArray();
  cat.addNameArray((char *)"MX06");
  if (cat.connect()) {
    Serial.println("Connected!");
    pycamera.fillScreen(pycamera.color565(0, 0, 0));
    pycamera.setCursor(10, 10);
    pycamera.setTextSize(2);
    pycamera.setTextColor(pycamera.color565(0, 0, 255));
    pycamera.print("CONNECTED!");
  }
    else {
    Serial.println("Could not find printer!");
    pycamera.fillScreen(pycamera.color565(0, 0, 0));
    pycamera.setCursor(10, 10);
    pycamera.setTextSize(2);
    pycamera.setTextColor(pycamera.color565(255, 0, 0));
    pycamera.print("Could not \nfind printer!\nResetting..");
    delay(200);
    resetFunc();
  }
  delay(500);
}

// SPDX-FileCopyrightText: 2024 Liz Clark for Adafruit Industries
//
// SPDX-License-Identifier: MIT

#include <Arduino.h>
#include "Adafruit_PyCamera.h"
#include <CatGFX.h>
// CatGFX library source is included in the project with modifications
// https://github.com/TheNitek/CatGFX

Adafruit_PyCamera pycamera;

bool frame = true;

String frame_info[] = {"NO", "YES"};

// Buffer which can hold 400 lines
byte buffer[48 * 400] = {0};

// Create a printer supporting those 400 lines
CatPrinter cat(400);

// hard reset
void(* resetFunc) (void) = 0;

// atkinson dithering algorithm parameters from CircuitPython
struct DitherAlgorithmInfo {
    int mx, my;
    int divisor;
    struct { int dx, dy, dl; } terms[4];
} atkinson = {
    1, 1, 8, // mx, my, divisor
    {
        {1, 0, 1}, {-1, 1, 1}, {0, 1, 1}, {1, 1, 1} // dx, dy, dl
    }
};

// this sends a full bitmap to the printer
void gameboy(uint16_t *source, int width, int height, bool createForPrinter) {
    uint16_t *bitmap = new uint16_t[width * height];
    int16_t *errorBuffer = new int16_t[(width + 2) * (height + 2)]();
    uint8_t *bitmapForPrinter = nullptr;
    if (createForPrinter) {
        bitmapForPrinter = new uint8_t[(width * height)]();
    }
    // dither the pixels
    // referenced from CP module
    for (int y = 0; y < height; y++) {
      for (int x = 0; x < width; x++) {
          int idx = (y + 1) * (width + 2) + (x + 1);
          uint16_t rgb = source[y * width + x];
          uint8_t r = (rgb & 0xF800) >> 8;
          uint8_t g = (rgb & 0x07E0) >> 3;
          uint8_t b = (rgb & 0x001F) << 3;
          uint8_t grayscale = (r * 30 + g * 59 + b * 11) / 100;
          grayscale += errorBuffer[idx] / atkinson.divisor;
          uint16_t outPixel = grayscale > 127 ? 0xFFFF : 0x0000; // White or Black for RGB bitmap
          bitmap[y * width + x] = outPixel;
          if (createForPrinter) {
              if (grayscale <= 127) {
                  bitmapForPrinter[(y * width + x) / 8] |= (1 << (7 - (x % 8)));
              }
          }
          int16_t error = grayscale - (outPixel ? 255 : 0);
          for (int i = 0; i < 4; i++) {
              int dx = atkinson.terms[i].dx, dy = atkinson.terms[i].dy;
              errorBuffer[idx + dy * (width + 2) + dx] += error * atkinson.terms[i].dl;
          }
      }
  }
    if (createForPrinter == true) {
        cat.fillScreen(1);
        cat.drawBitmap(72, 25, bitmapForPrinter, 240, 240, 0);
        if (frame == true) {
          cat.drawRect(50, 0, 285, 350, 0);
          cat.drawRect(71, 24, 242, 242, 0);
          cat.setTextSize(2);
          cat.setTextColor(0);
          cat.setCursor(72, 300);
          cat.print("shot on MEMENTO");
        }
        delay(500);
        Serial.println("Printing...");
        cat.printBuffer();
        delay(500);
        Serial.println("scrolling..");
        cat.feed(50);
        Serial.println("Done!");
    } 
    pycamera.drawRGBBitmap(0, 0, bitmap, width, height);
    pycamera.refresh();
    delete[] bitmap;
    delete[] errorBuffer;
    delete[] bitmapForPrinter;
}

void setup() {
  Serial.begin(115200);
  // while (!Serial) delay(10);
  Serial.println();
  if (!pycamera.begin()) {
    Serial.println("Failed to initialize pyCamera interface");
    while (1)
      yield();
  }
  Serial.println("pyCamera hardware initialized!");
  pycamera.fillScreen(pycamera.color565(0, 0, 0));
  pycamera.setCursor(10, 10);
  pycamera.setTextSize(2);
  pycamera.setTextColor(pycamera.color565(0, 0, 255));
  pycamera.print("CONNECTING..");
  Serial.print("Connecting to cat printer..");
  cat.begin(buffer, sizeof(buffer));
  Serial.print(".");
  cat.resetNameArray();
  Serial.print(".");
  cat.addNameArray((char *)"MX06");
  Serial.println(".");
  if (cat.connect()) {
    Serial.println("Connected!");
    }
    else {
    Serial.println("Could not find printer! Resetting..");
    pycamera.fillScreen(pycamera.color565(0, 0, 0));
    pycamera.setCursor(10, 10);
    pycamera.setTextSize(2);
    pycamera.setTextColor(pycamera.color565(255, 0, 0));
    pycamera.print("Could not\nfind printer!\nResetting..");
    delay(200);
    resetFunc();
  }
  Serial.println("going into loop");
}

void loop() {
  pycamera.readButtons();
  pycamera.captureFrame();
  pycamera.setNeopixel(0x00FF00);
  // blits gameboy filter to display but does not print
  gameboy((uint16_t *)pycamera.fb->getBuffer(), 240, 240, false);
  // pressing shutter prints the frame
  if (pycamera.justPressed(SHUTTER_BUTTON)) {
    pycamera.setNeopixel(0x0000FF);
    pycamera.setCursor(25, 25);
    pycamera.setTextSize(3);
    pycamera.setTextColor(pycamera.color565(255, 0, 255));
    pycamera.print("PRINTING..");
    gameboy((uint16_t *)pycamera.fb->getBuffer(), 240, 240, true);
    Serial.println("SHUTTER");
  }

  if (pycamera.justPressed(AWEXP_BUTTON_SEL)) {
    frame = not frame;
    pycamera.fillScreen(pycamera.color565(0, 0, 0));
    pycamera.setCursor(10, 10);
    pycamera.setTextSize(3);
    pycamera.setTextColor(pycamera.color565(255, 0, 0));
    pycamera.println("Print with \nframe?");
    pycamera.println(frame_info[frame]);
    delay(2000);
    Serial.println("SEL");
  }
  if (pycamera.justPressed(AWEXP_BUTTON_DOWN)){
    cat_reconnect();
    Serial.println("DOWN");
  }
}

void cat_reconnect() {
  Serial.println("Disconnecting..");
  pycamera.fillScreen(pycamera.color565(0, 0, 0));
  pycamera.setCursor(10, 10);
  pycamera.setTextSize(2);
  pycamera.setTextColor(pycamera.color565(0, 0, 255));
  pycamera.print("DISCONNECTING..");
  cat.disconnect();
  Serial.println("Disconnected.");
  delay(1000);
  pycamera.fillScreen(pycamera.color565(0, 0, 0));
  pycamera.setCursor(10, 10);
  pycamera.setTextSize(2);
  pycamera.setTextColor(pycamera.color565(0, 0, 255));
  pycamera.print("CONNECTING..");
  cat.resetNameArray();
  cat.addNameArray((char *)"MX06");
  if (cat.connect()) {
    Serial.println("Connected!");
    pycamera.fillScreen(pycamera.color565(0, 0, 0));
    pycamera.setCursor(10, 10);
    pycamera.setTextSize(2);
    pycamera.setTextColor(pycamera.color565(0, 0, 255));
    pycamera.print("CONNECTED!");
  }
    else {
    Serial.println("Could not find printer!");
    pycamera.fillScreen(pycamera.color565(0, 0, 0));
    pycamera.setCursor(10, 10);
    pycamera.setTextSize(2);
    pycamera.setTextColor(pycamera.color565(255, 0, 0));
    pycamera.print("Could not \nfind printer!\nResetting..");
    delay(200);
    resetFunc();
  }
  delay(500);
}

How the Code Works

The gameboy() function is pulled from the bitmaptools CircuitPython module. It uses the Atkinson dithering algorithm to create the iconic grayscale pixelated image. The function takes a bool argument called createForPrinter. If it is true, then a bitmap is prepared for printing and is sent to the printer. It also checks if a frame is included for printing. Otherwise, only the RGBBitmap is prepared for the display.

In the setup, the PyCamera library is initialized, followed by the CatGFX printer library. Once a connection is established over BLE with the printer, the loop begins. In the loop, the filtered camera preview is blitted to the screen. If you press the shutter button, then the filtered image is printed. You can press the select button on the MEMENTO to toggle the frame on or off for printing. You can also press the down button to reconnect to the printer if you lose connection.

Text editor powered by tinymce.

Connecting to the Cat Thermal Printer

First, turn on the cat printer. You'll see the blue LED blinking on the printer. Then, turn on the MEMENTO. You'll see "CONNECTING.." on the screen. After it connects, you'll see the Gameboy filter previewing the camera image. The blue LED will be solidly lit on the printer.

If the MEMENTO can't establish a connection with the printer, it will reset and try again. If you notice that the MEMENTO has reset a few times without connecting, try power cycling the cat printer.

Text editor powered by tinymce.

The Journey to Printing

I wanted to document some of the troubleshooting steps that I took to get the cat printer printing images from MEMENTO. It would have been lovely if everything had "just worked" but it took some sleuthing and experimentation.

First off I compiled the example in the CatGFX library for MEMENTO and tested to see if it could connect to the printer and successfully print at all. The example prints text and some circles.

After that success I brought in the PyCamera library and added in some button presses to initiate printing. This worked for printing text and shapes. Next was trying to get images printing.

Since thermal printers print in black and white, I initially tried converting the default framebuffer to a grayscale bitmap and sending that to the printer on a button press. This resulted in printing glitchy lines.

What I needed to do was capture a grayscale image from the start. Luckily Jeff Epler had implemented a "gboy" Gameboy-style filter in bitmaptools in CircuitPython. Since it was written in C, it was very straightforward to bring into Arduino. I added a simple refresh() function to the PyCamera library to allow the screen to update with the bitmap generated with the filter.

Now the moment of truth: would the bitmap print? And on the first try it was a success! I was so excited. But then, it was terrible. It would stop printing halfway thru an image. The printer would connect properly, it would receive the buffer to print, it would start printing but would stop before completing the task. The MEMENTO would think it was still printing and essentially be frozen, requiring a reset. The percentage that printed was different every time.

I tried a few different things to solve this. I experimented with the BLE connection settings, adjusted the buffer size, implemented hard resets after printing, tried a different thermal printer library with cat printer support, used drawPixel rather than drawBitmap but alas, the same behavior always occurred. It being a Friday, I collected my various scraps of half-printed thermal paper and I committed my progress with notes, making peace with the fact that this project probably wouldn't work.

On Monday it was suggested that I try adding in some delays to the CatGFX library, since there is nothing in the library to account for failed or delayed BLE packets. Adding in over the top 1 second delays between almost every command resulted in a successful, although comically slow, print. Cautiously optimistic, I worked to reduce the delays and dialed in a compromise between speed and reliability, getting the delays down to about 5 ms where needed. This modified version of the library is included in the code in the code repository and was used to compile the UF2.