Emotion keychain
A backpack keychain with a 128×64 OLED screen and a living face: it blinks, laughs, gets angry, falls asleep in the dark and reacts to taps, shaking, sound and light.
About the project
For anyone who wants a living keychain on a backpack or wants to build one. 139 emotions, ten personalities, a piezo voice and Bluetooth encounters between keychains. Code, board and case are open; the engine runs in the browser or on an ESP32 board with a screen.
Try it in a minute
- Open the simulator in the browser and poke the character
- Build the stand: any ESP32 board (C5, classic, C3 or S3) and an SSD1306 screen on four wires
- Flash the stand from the browser: files are preselected, just connect the board
Limitations
- The rev B keychain board is designed and passes DRC, but it has not been ordered or tested on real hardware.
- Battery life of 11, 15 and 18 days for the S, M and L cases is estimated from a board simulation, not measured.
- Bluetooth encounters on the ESP32 stand build and pass host tests, but have not been tested on real boards.
- There is no battery-backed clock: date-based holidays and easter eggs work once the date is set from a computer.
- The secret knock does not work on the rev B keychain yet; it works on the stand and in the simulator.
- Browser flashing works only in desktop Chrome or Edge.
Versions on : Firmware 0.1.0

README from the repository, in Russianemotion-keychain
Брелок с OLED-экраном и анимированными эмоциями
C++0pushed
English | Русский
Брелок на рюкзак с белым OLED-экраном, на котором живёт персонаж.
Он моргает, оглядывается, смеётся, злится, засыпает в темноте и реагирует на тапы, тряску, звук и свет.
Владельцу · Движок · Эмоции · Голос · Встречи · Железо · Плата · Корпус · Энергия · План
Important. Статус проекта
- Работает уже сейчас: движок лиц, симуляторы (на ПК и в браузере) и стенд на ESP32 — дешёвая отладочная плата с настоящим OLED-экраном.
- Разработана, но ещё не собрана: плата брелока rev B. Она проходит DRC и полную симуляцию прошивки, но не заказана и не проверена на живом железе.
- Автономность — оценка по симуляции платы, а не замер.
Что он умеет
- 139 эмоций. Радость, смех, грусть, злость, удивление, сон, головокружение, «слушает», «кушает» на зарядке — и мемные: орущий сойджак, Ленни,
¯\_(ツ)_/¯, FFFUUU,$_$, переворот стола. Весь каталог. - Каждая эмоция живая. Моргание, взгляд, подвижные зрачки и фирменный жест: дыхание, брови, прищур, наклон головы, «болтовня». Переходы плавные, смена формы глаз спрятана за морганием.
- Характер. Персонаж сам выбирает реакцию на ситуацию: тап, тряску, падение, хлопок, музыку, темноту, холод, зарядку, долгое одиночество. Варианты реакций чередуются, у раздражения есть лестница от «-_-» до переворота стола.
- Двух одинаковых не бывает. Характер и внешность выводятся из серийного номера чипа. Один брелок из ста — легендарный, с золотым кибер-глазом.
- Дружба брелоков. Встречи день за днём поднимают дружбу от NEW FRIEND до BFF. Старший брелок дарит младшему эмоцию, старые знакомые иногда шепчутся шифром.
- Растёт вместе с хозяином. На старте 44 эмоции, остальные открываются «имплантами» за дни вместе, касания, шаги и встречи — примерно за месяц. Сверху — серия дней вместе и 24 достижения с кубком: от FIRST FRIEND до MARATHON и 1337. На брелоке rev B открываются 23: KNOCK KNOCK за секретный стук там пока не получить.
- Сюрпризы и пасхалки. Иногда сам «взламывает» что-то, прячется, перезагружается, выдаёт ERROR 404: MOOD NOT FOUND, синий экран «:(» или визор-сканер. Празднует Новый год, Хэллоуин и твой день рождения. Знает день π, POEKHALI! 12 апреля, MAY THE 4TH, DONT PANIC, 1 апреля и пятницу 13-е. В 13:37 переходит в H4X0R MODE. Праздники и пасхалки по часам — когда дата и время заданы с компьютера: часов с батарейкой у брелока нет, и после выключения кнопкой их задают снова. На стенде ESP32 и в симуляторе в браузере отвечает на секретный стук «Shave and a haircut»; на брелоке rev B стук пока не срабатывает. На зарядке гоняет логотип, пока тот не попадёт точно в угол.
- Батарея — часть характера. Зарядка показывает наливающуюся батарею с процентом. Голодный благодарит, что покормили. При малом заряде сам переходит в экорежим, при пустой батарее желает спокойной ночи.
- Десять характеров: игрун, ворчун, соня, скромник, любопытный, пофигист, драма, глюк, хитрец, добряк. У каждого своё лицо в покое, свой ответ на касания, свои занятия, темп и голос. Характер выводится из серийного номера чипа.
- Голос. Пьезопищалка отвечает на касания короткими «словами» из нот, как R2-D2. У каждого характера своя нота и манера: игрун скачет, ворчун бурчит, соня сползает вниз, хитрец хихикает тройками. Сцены играют свою музыку — от рукопожатия модема при «взломе» до Happy Birthday. Ночью (по заданному времени) говорит только о важном, и тихо. Как он звучит.
- Секретный разговор. После дуэли два брелока переговариваются пищалками шифром: реплики по очереди, на экранах — знаки в пузырях, в конце мелькает «расшифровка» и ACCESS DENIED.
- Три темы. Классика. Киберпанк: загрузка OLERAST LINK, прицел, который щёлкает по делу, и сбои сигнала. Ретро: лицо крупными пикселями, как на старой карманной консоли.
- Экран не гаснет, пока его кто-то может видеть, и при этом экономит батарею. Кадр рисуется только при изменении лица, на экран уходят только изменённые участки, процессор спит между кадрами.
- Один код везде: прошивка своей платы на nRF52840, стенд на ESP32, симуляторы на ПК и страница в браузере.
Как это работает
flowchart LR
IMU["Акселерометр<br/>тап · тряска · падение · шаги"] --> B
MIC["Микрофон<br/>речь · музыка · хлопок"] --> B
LUX["Датчик света<br/>темно · ярко"] --> B
PWR["Батарея и USB<br/>заряд · зарядка"] --> B
CLK["Часы<br/>день · ночь"] --> B
B["Behavior<br/>настроение и реакции"] --> E["FaceEngine<br/>лицо · переходы · жесты"]
E -- "только изменённые окна" --> D["SSD1306<br/>128×64 по I2C"]
B --> V["Voice<br/>реплики · музыка сцен"]
V -- "частота ШИМ" --> Z["Пьезопищалка"]
Подробно — в описании движка.
Устройство
| Экран | белый OLED 0.96″, SSD1306, 128×64 |
| Мозг | nRF52840: модуль Raytac MDBT50Q на своей плате rev B |
| Датчики | акселерометр LIS3DH, PDM-микрофон, датчик света LTR-303ALS, кнопка |
| Голос и отдача | пьезопищалка, вибромотор |
| Питание | Li-Po с платой защиты: 402025, 502025 или 602025 (150–250 мА·ч); зарядка по USB-C током 100 мА, только при 10–42 °C по температуре кристалла nRF |
| Плата | 30×46 мм и ушко для кольца, 4 слоя, файлы для заказа на JLCPCB и PCBWay |
| Корпус | акриловый «бутерброд» под лазерную резку: 35×51 мм, толщина 18.8, 19.8 или 20.8 мм — три версии S, M, L под ячейки разной толщины |
| Автономность | обычный день — ≈11, 15 и 18 дней (S, M, L); 16 ч лица в сутки — ≈3–5 дней. Оценка по симуляции платы |
Компоненты, стек плат и закупки — в docs/hardware.md, расчёт тока — в docs/power.md. Как пользоваться брелоком — зарядка, кнопка, лица, встречи, хранение — в памятке владельцу.
Своя плата и корпус
![]() |
![]() |
| В сборе: экран за прозрачной крышкой | В разборе: слои акрила, модуль экрана и плата |
Плата rev B готова к заказу: DRC — 0 ошибок, 0 несоединённых и 0 предупреждений; панель для монтажа — в hardware/rev-b/out/panel.
- Генерация из одного описания. Схема, расстановка, разводка, Gerber, BOM и CPL строятся скриптами из
netlist.py, в KiCad руками ничего не правится. - Четыре слоя. L2 — сплошная земля. L3 — шины питания и медленные сигналы. Антенна у правого края, под ней меди нет.
- Трассировка в три прохода. Шины питания кладёт свой трассировщик, сигналы — Freerouting, остаток доводит собственный трассировщик по трём слоям.
- Монтаж. Мелочь с двух сторон ставит завод — JLCPCB или PCBWay, на панели из двух плат 76 × 72 мм. Руками — модуль экрана, ячейка и вибромотор, около 15 минут.
Корпус — слои акрила, стянутые четырьмя нейлоновыми винтами M2 × 25 (у всех версий). Экран и плата видны насквозь, торцы закрыты. Три версии, S, M и L, отличаются ячейкой (402025, 502025, 602025) и верхней рамкой вокруг неё (3, 4 или 5 мм), а с ними — гребёнкой экрана (у M и L длинная, от 15 мм) и длиной трубки микрофона. На ушках рамок лежит модуль экрана, покупных стоек нет. Сверху выходит ушко для кольца, снизу — вырез под USB-C, справа — толкатель кнопки на приливе рамки оборота, в дне — отверстие над пищалкой. Что купить для каждой версии — в README корпуса, файлы резки в SVG и DXF — в hardware/rev-b/case/out.
Для заказа платы ничего запускать не нужно: она разведена и проверена, файлы для завода лежат в hardware/rev-b/out (одна плата) и hardware/rev-b/out/panel (панель для монтажа) и загружаются как есть — по README платы. Генераторы нужны, только чтобы изменить плату или корпус:
cd hardware/rev-b/gen
python3 build.py fab # DRC и файлы для заказа → out/, out/panel/ (панель — через KiKit, см. README платы)
cd ../case && python3 case.py && python3 selftest.py && python3 viewer.py # корпус, проверка проверок, 3D-просмотр
build.py place --force и build.py route расставляют и разводят плату заново (для route нужны Java 21 и Freerouting). Без --force place разведённую плату не затрёт, а fab не выпустит файлы с платы без дорожек, с ошибками DRC или несоединёнными площадками. Вернуть плату и файлы из репозитория:
git checkout -- hardware/rev-b/keychain-rev-b.kicad_pcb hardware/rev-b/Keychain.pretty hardware/rev-b/out
viewer.py собирает case/out/keychain-3d.html: модель брелока с вращением и разбором по слоям. Открывается в браузере без сервера. Что нужно для скриптов (KiCad 7, cairosvg, facegen) — в README корпуса.
Быстрый старт
Нужны CMake 3.16+ и компилятор с C++20 (GCC 10+ или Clang 12+). SDL2 нужен только для оконного симулятора.
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/face_tests # тесты движка
./build/facegen list # все эмоции и клипы
./build/facegen anim lenny out/lenny.gif # эмоция в GIF
./build/facegen trans neutral laugh out/t.gif # переход между эмоциями
./build/facegen sheet out/all.gif --scale 2 # контактный лист всех эмоций
./build/facegen bench # кадры и нагрузка на шину по каждой эмоции
./build/facegen scene hack out/hack.gif # сцена-сюрприз в GIF (--theme cyber — киберпанк)
./build/facegen id 9 # какой персонаж получится из серийного номера
./build/facegen sound all out/voice.wav # голос брелока в WAV (--serial N — другой брелок)
./build/facesim # окно с лицом (если есть SDL2)
Симулятор в браузере
Готовая страница — olerast67.github.io/emotion-keychain. Собрать её самому:
sim/web/build.sh # нужны clang с целью wasm32 и wasm-ld (пакет lld)
Откройте sim/web/dist/index.html, сервер не нужен. На странице:
- тапы прямо по экрану;
- ситуации: тряска, падение, музыка, темнота, зарядка;
- голос через кнопку «Пищалка», встреча и дуэль с соседом, секретный разговор;
- выбор любой из 139 эмоций и жесты;
- ускорение времени;
- живые цифры: кадры в секунду и занятость шины.
На своей плате
Прошивка платы rev B — в firmware/README.md, откуда брать файлы — в «Где взять файлы».
- Готовые файлы — в
firmware/release/:keychain-revb-factory.hexдля программатора или завода,keychain-revb.uf2для диска KEYCHAIN,keychain-revb-dfu.zipдля adafruit-nrfutil. Версия и коммит — в README той же папки. Это файлы для прототипов: в них USB-номера Adafruit. Брелоки на продажу прошивают своей сборкой со своими номерами (раздел[sale]вfirmware/platformio.ini). - Своя сборка:
cd firmware && pio run -e keychain→firmware/.pio/build/keychain/firmware-factory.hex,firmware.uf2иfirmware.zip. Когда GitHub Actions снова запускается, те же файлы лежат в артефактах CI. - Старая прошивка не подходит. Сборки до коммита
098681eна этой плате не заряжают ячейку: в них нет CHG_EN на P0.24, а акселерометр ищется по адресу 0x18. Какая прошивка залита, видно по командеverв консоли (старая отвечает «Не знаю такую команду»); приветствие при включении до терминала обычно не доходит.
Один раз программатором по SWD записывается загрузчик или сразу заводской файл, плата при этом питается от USB-C. Дальше — файл .uf2 на диск KEYCHAIN или pio run -e keychain -t upload. Без прошивки ячейка не заряжается: заряд включает прошивка, и только при 10–42 °C по температуре кристалла nRF.
На живом экране
ESP32-C5, обычная ESP32, C3 или S3 и модуль SSD1306 на четырёх проводах. Прошивка ставится из браузера на странице прошивки брелока или через PlatformIO:
cd firmware && pio run -e esp32c5 -t upload && pio device monitor
Подключение, команды и что проверить на панели — в firmware/README.md.
Структура
engine/ движок лиц: C++20 без кучи, исключений и libm
include/face/ заголовки: параметры лица, каталог, движок, поведение
src/ отрисовка, анимация, 139 пресетов эмоций, поведение
tests/ тесты без внешних зависимостей
firmware/ прошивки: плата rev B (nRF52840) и стенд на ESP32
src/keychain/ плата rev B: датчики, радио, питание, консоль
bootloader/ загрузчик для первой прошивки по SWD
hardware/
rev-b/ своя плата: KiCad, Gerber, BOM, CPL, схема в PDF
gen/ генераторы: netlist.py, расстановка, разводка, файлы для заказа
case/ корпус из акрила: файлы резки и 3D-просмотр
sim/
cli/ facegen — GIF, контактные листы, бенчмарк, каталог
sdl/ facesim — оконный симулятор
web/ симулятор в браузере (движок в WebAssembly)
docs/ движок, эмоции, железо, энергия, план
tools/ вспомогательные скрипты
Дорожная карта
- Движок лиц: 139 эмоций, переходы, жесты, поведение
- Симуляторы: консольный, оконный, в браузере
- Прошивка стенда: ESP32-C5 / ESP32 / C3 / S3 + SSD1306 + сенсорная кнопка
- Свой характер у каждого брелока, рост и импланты, сцены-сюрпризы, праздники, киберпанк-тема
- Голос: реплики пищалкой, музыка сцен, секретный разговор после дуэли
- Достижения и серии, дружба брелоков, батарея в характере, ретро-тема, пасхалки
- Встречи брелоков и дуэли по Bluetooth в прошивке платы (протокол)
- Своя плата rev B — схема, разводка, файлы для JLCPCB и PCBWay, исправления по предрелизному аудиту
- Корпус-«бутерброд» из акрила в трёх версиях и 3D-просмотр
- Прошивка платы rev B: датчики, голос, вибро, встречи, сон, заряд по температуре, загрузчик UF2
- Симуляция платы целиком: настоящая прошивка на моделях микросхем, две платы и эфир
- Заказ, сборка и запуск rev B
- Замеры тока и тест разряда на живой плате
- Настоящие датчики: пороги тапов, шагов, звука и света по записям с рюкзака
- Механика: падение, рывок за ушко, брызги, неделя носки
- Rev C: полностью заводская сборка — экран на разъёме FPC, разъём JST под ячейку, SMD-вибромотор
Этапы с критериями готовности — в docs/plan.md.
Как добавить эмоцию
- Добавьте id в
FACE_EXPR_LISTвengine/include/face/expressions.h. - Опишите пресет на том же месте в
engine/src/expressions.cpp: глаза, брови, рот, значки, жест. - Проверьте:
./build/facegen anim <id> out/x.gifи./build/face_tests. - Пересоберите каталог:
./build/facegen catalog docs/emotions.md. CI проверяет, что он совпадает с кодом.
Идеи эмоций удобно заводить задачей по шаблону.
Лицензии
Проект полностью открыт. Можно собирать брелоки для себя и на продажу, менять код, плату и корпус и выпускать свои версии — по условиям лицензий ниже.
| Что | Лицензия | Файл |
|---|---|---|
Код: engine/, firmware/, sim/, tools/, CMake и скрипты |
Apache-2.0 | LICENSE, NOTICE |
Железо: hardware/ — KiCad, генераторы, Gerber, BOM, CPL, файлы корпуса |
CERN-OHL-W-2.0 | hardware/LICENSE, текст |
Документация и картинки: docs/, README, *.md, PNG и GIF |
CC-BY-4.0 | текст |
Какая лицензия у какого файла, расписано в REUSE.toml. В готовых файлах прошивки есть чужой открытый код со своими лицензиями (ядро Arduino для nRF52 — LGPL-2.1, SoftDevice S140 — лицензия Nordic и другие) — список в THIRD_PARTY_NOTICES.md.
Название, логотип, образ персонажа и бренд OLERAST лицензиями не покрываются: форк или своё устройство называйте иначе, а «совместим с…» и «на основе…» писать можно. Подробно — в TRADEMARKS.md.
Как это сделано
Проект сделал не специалист — не инженер-электронщик и не профессиональный программист — вместе с ИИ-ассистентом Claude от Anthropic. Движок, прошивка, генераторы платы, корпус и эта документация написаны в диалоге, а потом проверены тестами, симуляцией, DRC и многими кругами ревью. Поэтому статус выше такой осторожный: всё, что не проверено на живом железе, так и помечено. Сообщения об ошибках и исправления от тех, кто разбирается лучше, очень приветствуются.
Поддержать проект
Проект бесплатный и открытый: без рекламы, платных функций и аккаунтов. Донаты идут на тестовые платы, детали и время, чтобы довести rev B от «спроектировано» до «проверено на живом железе».
Звёздочка репозиторию, фото собранного стенда или сообщение об ошибке тоже очень помогают.

