Mouth

Mouth

• Introduction
• Showing icons
• Digits
• Scrolling text
• Brightness
• Clearing the display
• Going lower: the Matrix module

Introduction

Mouth is the expressive face of the 8x8 MAX7219 LED matrix. It is a facade over the Matrix module -- every call inlines straight through, so the friendly name costs nothing.

Mouth::show(Icon::Heart);

The word mouth comes from the Otto ecosystem: OttoDIYLib calls the display putMouth, and every Otto tutorial calls it Otto's mouth. When you want the hardware-truth name instead, use Matrix.

Showing icons

Mouth::show(Icon::Happy);
Mouth::show(Icon::Sad);
Mouth::show(Icon::Surprised);

The icon stays on the display until you show something else or clear it -- it is a state, not an animation.

There are 21 named icons; see the Icon, Sound and Gesture Reference for the complete list. The most used ones:

Icon	Looks like
Icon::Heart	A heart
Icon::Happy	An open smile
Icon::Smile	A closed smile
Icon::Sad	A frown
Icon::Angry	Angry mouth
Icon::Surprised	A big open mouth
Icon::Confused	A wavy mouth
Icon::Ok	A check mark
Icon::X	A cross
Icon::Question	A question mark
Icon::Line	A neutral straight mouth

A typical reaction pattern:

void loop() {
  Mouth::show(Eyes::closerThanCm(15) ? Icon::Surprised : Icon::Happy);
}

Digits

Mouth::showDigit(7);

Accepts 0 through 9; anything larger is ignored. Useful for countdowns and for displaying a sensor value one digit at a time:

for (uint8_t i = 3; i >= 1; i--) {
  Mouth::showDigit(i);
  delay(1000);
}
Mouth::show(Icon::Happy);

Scrolling text

Mouth::scrollText("HELLO");
Mouth::scrollText("SLOWLY", 120);   // milliseconds per step, default 50

Scrolling blocks until the whole message has passed by, so a long string keeps Otto busy. Higher values scroll slower.

Note Keep messages short. Text lives in RAM on an ATmega328, and eight pixels of height leave little room for lowercase detail -- uppercase reads best.

Brightness

Mouth::setBrightness(0);    // dimmest
Mouth::setBrightness(15);   // brightest

Levels above 15 are clamped. The starting value comes from config.matrix.brightness, which defaults to 4 -- comfortable indoors and easy on a battery. Raise it for daylight, lower it for photographs and video.

Clearing the display

Mouth::clear();

Turns every LED off. The matrix keeps whatever was last drawn even across a reset of your sketch logic, so clearing is worth doing before a phase where the face should be blank.

Going lower: the Matrix module

Mouth covers the everyday cases. The Matrix module underneath adds pixel-level control:

Matrix::drawPixel(3, 4, true);     // one LED on
Matrix::drawMouthId(17);           // raw OttoDIYLib mouth index, 0..30
Matrix::drawPattern(0b0000000000110010010000100000000000);  // raw pattern

drawMouthId() reaches the handful of built-in shapes that have no Icon name yet. drawPattern() takes a raw pattern in the driver's 6x5 grid encoding -- the same format the Otto DIY phone app sends over Bluetooth.

Custom 8x8 icons and multi-frame animations are on the Roadmap.