Adafruit SSD1306: drive a 128x64 OLED from an Arduino

// OLED: text and shapes on a 128x64 SSD1306, over bit-banged I2C.
//
// Wiring, module to board:
//   SCL -> A5      SDA -> A4      VCC -> 5 V      GND -> GND
//
// Those are the Uno's I2C pins, but nothing here uses the TWI peripheral: the
// Mokxi ATmega328P model does not have one (docs/uno.md section 3), so
// mokxi_i2c.h pulls the two lines down and lets them go, and the module's own
// 4k7 pull-ups bring them back up. Any two pins would do.
//
// # The 1 KB
//
// A 128x64 monochrome frame is 1024 bytes, and the panel cannot be read back,
// so a driver that wants to change one pixel has to remember the other 1023.
// That is half of this part's SRAM. It is what a pixel display costs on an
// ATmega328P, and it is why the screen furniture below is drawn once into that
// buffer and only the ball, the counter and the bar are touched again.
//
// Each display() sends only the eight-column blocks of each page that actually
// changed. A moving ball is a few dozen bytes rather than a kilobyte, which is
// the difference between twenty-five frames a second and two: this board's
// software I2C manages about 32 kbit/s, so a full 1 KB refresh would take a
// third of a second.

#include "mokxi_i2c.h"
#include "mokxi_ssd1306.h"

const uint8_t SCL_PIN = A5;
const uint8_t SDA_PIN = A4;

// 400 kHz nominal. On this board the pin work dominates and it lands near
// 100 kHz, which is still twice what the 5 us standard-mode delays give.
SoftI2c bus(SCL_PIN, SDA_PIN, 400);
Ssd1306 oled(bus, SSD1306_ADDRESS);

// The arena the ball bounces in, and the ball.
const int16_t AX = 2;
const int16_t AY = 21;
const int16_t AW = 60;
const int16_t AH = 41;
const int16_t R = 4;

int16_t bx = AX + R + 6;
int16_t by = AY + R + 4;
int16_t bdx = 2;
int16_t bdy = 1;

uint16_t ticks = 0;

const int FRAME_MS = 40;

// Everything that never moves, drawn once into the buffer.
static void furniture() {
  oled.clear();
  oled.text(3, 2, "MOKXI", 2);
  oled.text(100, 8, "UNO", 1);
  oled.hLine(0, 18, 128);
  oled.rect(AX - 1, AY - 1, AW + 2, AH + 2);

  oled.rect(68, 22, 24, 16);
  oled.circle(110, 30, 7);
  oled.rect(106, 44, 20, 16);
}

void setup() {
  Serial.begin(115200);
  Serial.println("Mokxi Uno: SSD1306 over bit-banged I2C");
  bus.begin();
  if (!oled.begin()) {
    Serial.println("no OLED answered 0x3C; check SCL, SDA and power");
    return;
  }
  furniture();
  oled.display();
}

void loop() {
  oled.fillCircle(bx, by, R, false);

  bx = (int16_t)(bx + bdx);
  by = (int16_t)(by + bdy);
  if (bx - R <= AX) {
    bx = (int16_t)(AX + R);
    bdx = (int16_t)-bdx;
  } else if (bx + R >= AX + AW - 1) {
    bx = (int16_t)(AX + AW - 1 - R);
    bdx = (int16_t)-bdx;
  }
  if (by - R <= AY) {
    by = (int16_t)(AY + R);
    bdy = (int16_t)-bdy;
  } else if (by + R >= AY + AH - 1) {
    by = (int16_t)(AY + AH - 1 - R);
    bdy = (int16_t)-bdy;
  }
  oled.fillCircle(bx, by, R, true);

  // The counter and the bar move a good deal more picture than the ball does,
  // so they tick at a sixth of the frame rate and the lozenge at a third. The
  // driver only sends the eight-column blocks that changed, and a frame where
  // only the ball moved is a few dozen bytes on the bus instead of four hundred.
  ticks++;
  if (ticks % 6u == 0u) {
    oled.number(68, 44, (long)((ticks / 6u) % 1000u), 2, true, true);
    int16_t fill = (int16_t)(1 + ((ticks / 6u) % 16u));
    oled.fillRect(108, 46, 16, 12, false);
    oled.fillRect(108, 46, fill, 12, true);
  }
  if (ticks % 3u == 0u) {
    // The lozenge in the top box slides, so the shapes panel is not quite still.
    oled.fillRect(70, 24, 20, 12, false);
    oled.fillRect((int16_t)(70 + ((ticks / 3u) % 14u)), 24, 6, 12, true);
  }

  oled.display();
  delay(FRAME_MS);
}