Stream deck on a Pro Micro
Six keys with their labels drawn on an SSD1306 OLED, a second page on the sixth key, and a Ctrl+Shift+F-key hotkey for each press through Keyboard.h. The whole build, a SparkFun Pro Micro and 7 more parts, runs here in your browser on the firmware below; open it in the editor to change the wiring or the code and run it again.
Teaching? Assign it to your class in one click.
Intermediate About 25 minutes to build and run. Runs in your browser. Free, and no account needed.
The parts retail for about $28. On Mokxi they're free.
What you'll learn
- Drawing text and boxes on an SSD1306 OLED
- Sending keystrokes with
Keyboard.h - Debouncing with a short lock time
- Using arrays to hold two pages of labels and hotkeys
- Redrawing the screen only when something changed
- Difficulty: Intermediate
- Time: About 25 minutes
- Board: SparkFun Pro Micro
- Parts: 9
How it works
Six arcade buttons on pins 4 to 9 each connect to ground, with the internal pull-up on. A 128x64 OLED on pins 2 and 3 shows a label above each key and lights the key you hold. Keys 1 to 5 send a hotkey. Key 6 flips between two pages of labels.
Each hotkey is Ctrl + Shift + one of the F-keys F13 to F22. Almost no program uses these, so streaming software can learn them without a clash.
In Mokxi, USB is a serial pipe, so each press shows up as a line in the Serial Monitor instead. The same sketch on a real Pro Micro would type the keys.
Parts list
9 parts, plus the jumper wires. They retail for about $28; on Mokxi they're free.
- 1 × SparkFun Pro MicroIn MIDI Controller Kit.
- 1 × Full-size breadboard
- 1 × OLED display, 128x64In Fight Stick Kit, Pocket Pet Kit, Slot Machine Kit.
- 6 × Arcade buttonIn Claw Machine Kit, Fight Stick Kit, Pinball Table Kit.
Wiring table
Every connection, pin by pin, read from the circuit itself. Each row joins the pin on the left to the pin on the right, by a jumper wire or a breadboard strip.
| Part and pin | Connects to |
|---|---|
| OLED display, 128x64 pin GND | SparkFun Pro Micro pin GND |
| Arcade button (1) pin 1 | SparkFun Pro Micro pin GND |
| Arcade button (2) pin 1 | SparkFun Pro Micro pin GND |
| Arcade button (3) pin 1 | SparkFun Pro Micro pin GND |
| Arcade button (4) pin 1 | SparkFun Pro Micro pin GND |
| Arcade button (5) pin 1 | SparkFun Pro Micro pin GND |
| Arcade button (6) pin 1 | SparkFun Pro Micro pin GND |
| OLED display, 128x64 pin SDA | SparkFun Pro Micro pin 2 |
| OLED display, 128x64 pin SCL | SparkFun Pro Micro pin 3 |
| Arcade button (1) pin 2 | SparkFun Pro Micro pin 4 |
| Arcade button (2) pin 2 | SparkFun Pro Micro pin 5 |
| Arcade button (3) pin 2 | SparkFun Pro Micro pin 6 |
| Arcade button (4) pin 2 | SparkFun Pro Micro pin 7 |
| Arcade button (5) pin 2 | SparkFun Pro Micro pin 8 |
| Arcade button (6) pin 2 | SparkFun Pro Micro pin 9 |
| OLED display, 128x64 pin VCC | SparkFun Pro Micro pin VCC |
The code
The firmware exactly as the editor opens it. Change a line there and press Run: it compiles in the browser.
// Stream deck on a Pro Micro: six keys, their labels on a 128x64 OLED, and a
// hotkey sent over USB for each press through Keyboard.h.
//
// The labels are the point. A plain macro pad makes you remember which key
// is which; here the screen shows a label over each key, the one you press
// lights up, and the sixth key flips to a second page of five more actions.
//
// Wiring.
//
// keys 4 5 6 7 8 9 (each to GND, pulled up inside the chip)
// OLED SSD1306 on I2C: SDA pin 2, SCL pin 3, VCC 5 V, GND
//
// In Mokxi: click the arcade buttons. The OLED shows the page and lights the
// key you hold, and the Serial Monitor shows the hotkey the board would type.
//
// Hotkeys. Each action is Ctrl + Shift + an F-key from F13 to F22. Almost no
// program uses F13 and up on its own, so streaming and recording software
// (OBS Studio's hotkey settings, for one) can take them without clashing with
// anything. Press the key in the program's hotkey box once and it learns it.
//
// Not simulated: the USB connection to a PC. Mokxi models this chip's USB as
// a serial pipe, so each press prints as a [Keyboard] line on the Serial
// Monitor. Flash the same sketch to a real Pro Micro and it types the keys.
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
#include <Keyboard.h>
// ---------------------------------------------------------------------------
// Make it yours
// ---------------------------------------------------------------------------
const uint8_t KEY_PINS[6] = {4, 5, 6, 7, 8, 9};
// Two pages of five actions; key 6 always turns the page. Labels are six
// characters at most so they fit a key's box.
const char *const LABELS[2][5] = {
{"SCENE1", "SCENE2", "MUTE", "CAM", "REC"},
{"BRB", "CLIP", "MARKER", "CHAT", "LIVE"},
};
const uint8_t HOTKEYS[2][5] = {
{KEY_F13, KEY_F14, KEY_F15, KEY_F16, KEY_F17},
{KEY_F18, KEY_F19, KEY_F20, KEY_F21, KEY_F22},
};
// Held with every hotkey. Change to just KEY_LEFT_CTRL, or add KEY_LEFT_ALT.
const uint8_t MODIFIERS[2] = {KEY_LEFT_CTRL, KEY_LEFT_SHIFT};
const unsigned long LOCK_MS = 20; // debounce: ignore a key this long after a change
// ---------------------------------------------------------------------------
Adafruit_SSD1306 display(128, 64, &Wire, -1);
uint8_t page = 0;
bool held[6];
unsigned long changedAt[6];
void drawKey(uint8_t k) {
int16_t x = (k % 3) * 43;
int16_t y = 16 + (k / 3) * 24;
bool lit = held[k];
display.fillRect(x, y, 42, 22, lit ? SSD1306_WHITE : SSD1306_BLACK);
display.drawRect(x, y, 42, 22, SSD1306_WHITE);
display.setTextColor(lit ? SSD1306_BLACK : SSD1306_WHITE);
display.setCursor(x + 3, y + 7);
display.print(k == 5 ? "PAGE>" : LABELS[page][k]);
}
void draw() {
display.clearDisplay();
display.setTextSize(1);
display.setTextColor(SSD1306_WHITE);
display.setCursor(0, 2);
display.print("STREAM DECK page ");
display.print(page + 1);
for (uint8_t k = 0; k < 6; k++) {
drawKey(k);
}
display.display();
}
void send(uint8_t k) {
for (uint8_t m = 0; m < 2; m++) Keyboard.press(MODIFIERS[m]);
Keyboard.press(HOTKEYS[page][k]);
Keyboard.releaseAll();
Serial.print("Key ");
Serial.print(k + 1);
Serial.print(": ");
Serial.println(LABELS[page][k]);
}
void setup() {
for (uint8_t k = 0; k < 6; k++) {
pinMode(KEY_PINS[k], INPUT_PULLUP);
}
Serial.begin(115200);
display.begin(SSD1306_SWITCHCAPVCC, 0x3C);
Wire.setClock(400000); // fast mode: the screen redraws sooner
Keyboard.begin();
draw();
Serial.println("Stream deck ready: page 1");
}
void loop() {
unsigned long now = millis();
bool redraw = false;
for (uint8_t k = 0; k < 6; k++) {
bool down = digitalRead(KEY_PINS[k]) == LOW;
if (down == held[k] || now - changedAt[k] < LOCK_MS) {
continue;
}
held[k] = down;
changedAt[k] = now;
redraw = true;
if (!down) {
continue;
}
if (k == 5) {
page = (uint8_t)(1 - page);
Serial.print("Page ");
Serial.println(page + 1);
} else {
send(k);
}
}
if (redraw) {
draw();
}
}
Code walkthrough
The key functions of the sketch, and what each one does.
drawKey sketch.ino
Draws one key's box. Keys sit in a grid of three across and two down. A held key is filled white with black text, and others are an outline with white text. Key 6 always reads PAGE>.
void drawKey(uint8_t k) {
int16_t x = (k % 3) * 43;
int16_t y = 16 + (k / 3) * 24;
bool lit = held[k];
display.fillRect(x, y, 42, 22, lit ? SSD1306_WHITE : SSD1306_BLACK);
display.drawRect(x, y, 42, 22, SSD1306_WHITE);
display.setTextColor(lit ? SSD1306_BLACK : SSD1306_WHITE);
display.setCursor(x + 3, y + 7);
display.print(k == 5 ? "PAGE>" : LABELS[page][k]);
}draw sketch.ino
Clears the screen, writes the title and page number, calls drawKey for all six keys, then sends the result to the display.
void draw() {
display.clearDisplay();
display.setTextSize(1);
display.setTextColor(SSD1306_WHITE);
display.setCursor(0, 2);
display.print("STREAM DECK page ");
display.print(page + 1);
for (uint8_t k = 0; k < 6; k++) {
drawKey(k);
}
display.display();
}send sketch.ino
Presses both modifiers, then the page's hotkey for that key, then releases everything, which types the shortcut. It also prints which key and label it was to the Serial Monitor.
void send(uint8_t k) {
for (uint8_t m = 0; m < 2; m++) Keyboard.press(MODIFIERS[m]);
Keyboard.press(HOTKEYS[page][k]);
Keyboard.releaseAll();
Serial.print("Key ");
Serial.print(k + 1);
Serial.print(": ");
Serial.println(LABELS[page][k]);
}loop sketch.ino
Checks all six keys. A change is ignored if it came within LOCK_MS of the last one. A new press on key 6 flips the page, and any other press calls send. The screen is redrawn only if a key changed.
void loop() {
unsigned long now = millis();
bool redraw = false;
for (uint8_t k = 0; k < 6; k++) {
bool down = digitalRead(KEY_PINS[k]) == LOW;
if (down == held[k] || now - changedAt[k] < LOCK_MS) {
continue;
}
held[k] = down;
changedAt[k] = now;
redraw = true;
if (!down) {
continue;
}
if (k == 5) {
page = (uint8_t)(1 - page);
Serial.print("Page ");
Serial.println(page + 1);
} else {
send(k);
}
}
if (redraw) {
draw();
}
}Troubleshooting
The usual mistakes with this circuit, and the fix for each.
- The OLED stays blank This project
On this board SDA goes to pin 2 and SCL goes to pin 3. The OLED needs VCC and GND, and its address is 0x3C. - A key does nothing This project
Each button needs one leg on its pin and the other leg on GND. - The hotkey is not the one your program expects This project
Change theHOTKEYSorMODIFIERSarrays. - The OLED stays blank. OLED display
Check SDA and SCL are not swapped, and power it with 3.3 V or 5 V as its board allows. Most use address 0x3C, some 0x3D. Call display.begin() with the matching address. - Text never shows up even though the code runs. OLED display
Drawing only writes to a buffer. Call display.display() after drawing to push it out. Also set a text color with setTextColor(WHITE) and clear the buffer between frames. - The button reads pressed all the time, or never changes, when wired to a pin. Arcade button
Use the COM and NO terminals of the microswitch. Wire COM to ground, NO to the pin, and use INPUT_PULLUP. NC is the opposite and reads pressed when released. - One press counts as several presses in your code. Arcade button
Microswitch contacts bounce for a few milliseconds. Ignore changes for 10 to 20 ms after the first one, or react only to the edge and wait before checking again. - The upload fails or the wrong board is selected. SparkFun Pro Micro
Pick SparkFun Pro Micro and match the 5 V 16 MHz or 3.3 V 8 MHz version printed on your board. A wrong choice can make the board hard to program.
Change it and keep it
Open it in the editor, change the circuit or the code, and keep your version in a free account.