DITHR//CAM

Firmware that turns an ESP32-CAM into an offline camera with effects: a viewfinder on a 128×128 OLED, styles from anime to Game Boy, photos on microSD.

prototypeopen source

About the project

For people who have an ESP32-CAM lying around: the firmware turns it into an offline camera with styles, a viewfinder on a small OLED and photos on a memory card.

Try it in a minute

  1. Look at the styles and the wiring in the README
  2. Download the firmware from the releases

Limitations

  • There are no photos from the camera itself yet: the examples in the README were made on a synthetic scene.
  • You need an ESP32-CAM with 4 MB or more PSRAM, a 1.5 inch OLED on an SH1107, a button and a microSD card.

Report a bug

Восемь стилей на одной сцене: LOOP, PULSE, NEON, SHARD, Y2K, HOLO, TOPO, GHOST
Восемь стилей на одной сцене: LOOP, PULSE, NEON, SHARD, Y2K, HOLO, TOPO, GHOST. Picture from the README.

README from the repository, in Russiandithr-cam

Офлайн-камера с эффектами на ESP32-CAM: 13 стилей, видоискатель на OLED SH1107, снимки на microSD

C0pushed

Прошивка, которая превращает ESP32-CAM в офлайн-камеру с эффектами. Видоискатель работает на однобитном OLED 128x128, у камеры одна кнопка, снимки пишутся на microSD. В прошивке 13 стилей и 35 вариантов. Интернет и телефон камере не нужны.

Восемь стилей на одной сцене: LOOP, PULSE, NEON, SHARD, Y2K, HOLO, TOPO, GHOST

На каждый снимок на карту ложатся два файла: исходный JPEG с сенсора 1600x1200 и обработанный кадр 800x600. Тяжёлые проходы эффектов считаются на двух ядрах ESP32. Код эффектов собирается и на ПК, и стиль можно проверить на своих фото до прошивки.

Экран камеры

Видоискатель на OLED: заставка, смена стилей, снимок

Анимацию собрал симулятор host/oled_sim.c из того же кода интерфейса и эффектов, что работает в прошивке. В видоискателе сам двигается рисунок в трёх стилях. LOOP вращает спираль, HOLO покачивает объём, а TIDE показывает щелевую развёртку из последних 24 кадров.

Стили

Примеры в этом разделе сделаны из синтетической сцены tools/gen_scene.py: в ней закат, горы, озеро и идущий человек. Снимков с самой камеры пока нет. На ПК каждый пример прошёл тот же путь, что на камере: JPEG 1600x1200, декодер прошивки, эффект.

Исходная сцена
исходная сцена

NEON

Кадр в стиле аниме. Фильтр Кувахары на половинном разрешении сглаживает текстуру в ровные мазки, контур строится по разности гауссиан (XDoG), на каждый оттенок приходится три тона. Варианты: VAPOR (пастельная палитра, искры) и MANGA (чёрно-белый растр под 45° и один красный акцент).

Y2K

Кадр закручивается воронкой вокруг самого яркого места, светлое выжигается белым свечением, к краям расходятся каналы R и B. Поверх ложится интерфейс, привязанный к кадру: кольцо-прицел на ярком объекте, волна по линии горизонта, окно ошибки в духе Windows 98, орбиты и крупное слово. Компоновка у каждого снимка своя. Варианты отличаются палитрой: ICE, CHROME, SUNSET, TOXIC.

MELT

Сортировка пикселей. Маска строится по размытой яркости, внутри каждого отрезка пиксели сортируются по яркости. Варианты: DRIP (кадр стекает вниз), RISE (поднимается), WIND (сдвигается вбок), MOLTEN (огненная карта цвета).

GHOST

Камера снимает три кадра подряд с интервалом. RGB: каналы R, G и B берутся из разных моментов, и всё, что двигалось, расслаивается на цветные копии. ECHO: неподвижное гаснет, движение оставляет голубой и пурпурный след. XRAY: контуры трёх моментов светятся на чёрном фоне, неподвижные складываются в белый.

MOSH

CRPT: прошивка портит отдельные биты сжатых данных и таблицы квантования в копии JPEG и вписывает испорченное декодирование в несколько полос кадра. BLOCK: макроблоки 16x16 тянутся по векторам движения, цвет схлопывается в блоки.

DMG

Снимок в духе Game Boy Camera. Кадр 128x112 вписан в экран 160x144 с рамкой, контуры подчёркиваются формулой камеры P + (4P - N - S - E - W) * a, дизеринг идёт матрицей 4x4 с тремя порогами на клетку. Пиксель увеличен в 5 раз, файл PNG 800x720 на 2 бита. Палитры: DMG, POCKET, SGB (Super Game Boy 1-A) и PRINT (термобумага Game Boy Printer).

INK

ENGRV: гравюра волнистыми линиями, толщина линии зависит от тона, в тенях добавляется второй слой. RISO: ризограф в две краски, розовую и синюю, каждый слой дизерится синим шумом, синий слой сдвинут при печати. Оба варианта пишутся в PNG без потерь.

TIDE

Камера снимает 24 кадра подряд, и каждый пиксель снимка берётся из своего момента по карте времени. SLIT: время бежит поперёк кадра полосами. RADIAL: кольцами от центра. LIQUID: волнами. Неподвижное остаётся как было, движущееся растягивается и гнётся по форме карты. На этих примерах двигается только человек на берегу.

PULSE

Кадр из горизонтальных линий, каждую приподнимает яркость под ней. Линии рисуются от дальних к ближним, и каждая следующая закрашивает фон под собой. SCOPE: зелёный луч осциллографа на сетке. CHROMA: линии в цветах снимка.

SHARD

Кадр разбит на ячейки Вороного. Центров больше там, где больше деталей. GLASS: у каждого осколка свой сдвиг картинки и блик, грани светлые. MOSAIC: витраж с ровным цветом и тёмным швом. PRISM: у каждого осколка каналы R и B разведены в свою сторону.

HOLO

Яркость становится высотой, сетка точек кадра поднимается рельефом, наклоняется и поворачивается, затем рисуется с перспективой на чёрном. CLOUD: облако точек в цветах снимка. WIRE: каркасная сетка. SCAN: светящиеся строки скана.

LOOP

Эффект Дросте: кадр уходит сам в себя. Каждая точка переводится в комплексный логарифм, умножается на число, которое закручивает плоскость, и возвращается экспонентой. Один оборот вокруг центра соответствует переходу на уровень глубже. SPIRAL: один уровень на оборот. VORTEX: два.

TOPO

Снимок как топографическая карта. Яркость сглаживается и считается высотой, на границах уровней рисуются горизонтали, каждая пятая толще. Рельеф подсвечен сбоку, низины тонированы зелёным, вершины светлые, поверх сетка и подписи высот.

Ещё два режима работают без своей обработки. MIX снимает каждый кадр в случайном стиле и варианте, RAW сохраняет только исходник.

Что нужно

Деталь Какая Зачем
ESP32-CAM AI-Thinker или совместимая (Estardyn и другие клоны), ESP32 с PSRAM от 4 МБ, камера OV2640 или OV3660 камера, процессор, слот microSD
Программатор ESP32-CAM-MB, плата с micro-USB, на которую ставится ESP32-CAM прошивка и питание
Экран OLED 1.5" 128x128 на SH1107, версия на 4 пина I2C (SDA, SCL, GND, VCC) видоискатель
Кнопка тактовая кнопка или сенсорный модуль TTP223 на 3 контакта снимок, смена стиля и варианта
Вторая кнопка тактовая кнопка, по желанию выбор варианта стиля
microSD карта в FAT32, удобнее всего до 32 ГБ снимки
Питание повербанк и кабель micro-USB работа без компьютера
Провода 6 проводов (с TTP223 семь), паяльник подключение

Отдельный кардридер на 6 пинов не нужен. Карта стоит в слоте на самой ESP32-CAM: в 1-битном режиме ей хватает трёх линий, а кардридеру понадобились бы четыре свободных пина, которых на плате нет.

Подключение

Откуда Куда на ESP32-CAM Цвет на схеме Что это
Экран VCC 3V3 красный питание экрана 3,3 В
Экран GND GND в ряду с 5V серый общий провод
Экран SDA IO13 синий данные I2C
Экран SCL U0T (GPIO1) жёлтый тактовая линия I2C
TTP223 VCC 3V3, вместе с VCC экрана красный питание сенсора
TTP223 GND GND, вместе с GND экрана серый общий провод
TTP223 I/O IO12 зелёный выход сенсора: касание даёт 1
Карта microSD слот на ESP32-CAM линии IO14, IO15, IO2 заняты картой
Повербанк micro-USB на ESP32-CAM-MB питание 5 В

Порядок выводов у модулей TTP223 бывает разным, сверяйтесь с подписями на плате модуля. На 3V3 и GND приходят по два провода: их удобно спаять вместе или завести через короткую перемычку.

Вместо TTP223 подойдёт обычная тактовая кнопка: одна нога на IO12, другая на GND. Вид кнопки прошивка определяет сама при старте.

Порядок штырей ESP32-CAM, если держать плату антенной вверх, как на схеме и в редакторе схем olerast.com. Подписи напечатаны на обратной стороне платы, сверяйтесь с ними.

Левый ряд Правый ряд
IO4 вспышка GND
IO2 карта U0T экран SCL
IO14 карта U0R
IO15 карта VCC
IO13 экран SDA GND
IO12 TTP223 I/O IO0 занят камерой
GND экран и TTP223 IO16 занят PSRAM
5V 3V3 экран и TTP223

Снизу штыри закрывает ESP32-CAM-MB. Провода удобнее припаять сверху, к точкам пайки штырей.

Почему такие пины

Камера, карта и PSRAM занимают большую часть выводов ESP32-CAM. В 1-битном режиме карты свободными остаются IO4, IO12 и IO13. К IO4 подключена вспышка, и экран с кнопкой я развёл по IO12, IO13 и линии TX порта.

SCL экрана нельзя вешать на IO12. При включении ESP32 читает этот вывод и по нему выбирает напряжение flash-памяти. Подтягивающий резистор модуля экрана держит линию в единице, ESP32 выбирает 1,8 В, и плата не загружается. Кнопка на землю может дать на IO12 только ноль, а ноль при загрузке разрешён.

Сенсорный модуль TTP223 работает с IO12 так же безопасно: в покое его выход держит 0. Касаться сенсора в момент включения нельзя, с единицей на IO12 плата не загрузится. Тип кнопки прошивка определяет при старте. Она включает на IO12 подтяжку вверх и читает уровень: механическая кнопка в покое даёт 1, выход TTP223 держит 0. Если определение ошибается, тип задаётся вручную в board.h (BTN_KIND).

SCL стоит на U0T (GPIO1), это вывод TX порта. Пока экран не включён, прошивка пишет в порт журнал запуска. После включения экрана журнал в порт не идёт. Прошивка через USB при этом работает, потому что во время загрузки ESP32 линией управляет загрузчик.

Вторая кнопка на U0R (GPIO3) работает только без ESP32-CAM-MB, потому что на программаторе этот вывод держит микросхема CH340. Для такой сборки 5 В подаются на штырь 5V, а в firmware/main/board.h нужно прописать #define BTN_MODE_PIN 3.

Землю лучше брать со штыря рядом с 5V. На некоторых клонах вывод GND рядом с IO0 подписан, но ни к чему не подключён.

Прошивка через браузер

  1. Скачайте dithr-cam-esp32cam.bin со страницы Releases.
  2. Поставьте ESP32-CAM на ESP32-CAM-MB, подключите кабелем к компьютеру и выньте microSD. Вывод IO2 общий у карты и у режима загрузки, и с картой плата может не войти в прошивку.
  3. Откройте olerast.com/flash в Chrome или Edge, нажмите «Подключить», выберите порт CH340.
  4. Выберите скачанный файл и нажмите «Прошить».

Файл содержит загрузчик, таблицу разделов и программу. Прошивальщик находит таблицу разделов на адресе 0x8000, определяет файл как полный образ и пишет его с адреса 0x0. Адрес вручную вводить не нужно.

Через esptool тот же файл пишется командой:

python -m esptool --chip esp32 --port COM5 write-flash 0x0 dithr-cam-esp32cam.bin

Управление

Вся камера управляется одной кнопкой.

Действие Что происходит
Короткое нажатие Снимок. Экран мигает, сзади загорается красный светодиод, идёт шкала RENDER, затем на экране результат и время снимка
Удержание Следующий стиль. Пока кнопка зажата, стили листаются каждые 0,65 с, переход показан сбоем картинки
Короткие нажатия в течение 1,8 с после смены стиля Перебор вариантов стиля и RANDOM. Внизу экрана в это время написано TAP: и вариант, под ним полоска оставшегося времени

Когда полоска исчезла, короткое нажатие снова делает снимок. В обычной съёмке затвор срабатывает сразу, ожидания двойного нажатия нет. Если вариант не выбран, на каждый снимок он выбирается случайно, внизу экрана при этом написано RANDOM. Выбранный стиль и номер снимка сохраняются после выключения.

Вторая кнопка коротким нажатием перебирает варианты, удержанием листает стили назад. Все её действия доступны и с одной кнопки. Подключить её можно только на U0R и только без ESP32-CAM-MB, в обычной сборке я её не ставлю.

В TIDE камера снимает серию из 24 кадров подряд. Камеру в это время лучше держать неподвижно: всё, что сдвинется в кадре, растянется по карте времени.

Карта памяти

Карта должна быть в FAT32. В ESP-IDF поддержка exFAT отключена в исходниках FatFs (FF_FS_EXFAT 0), и карту в exFAT прошивка не смонтирует: на экране будет NO SD. Карты до 32 ГБ обычно уже размечены в FAT32. Карты от 64 ГБ приходят в exFAT, а Windows в окне форматирования для них FAT32 не предлагает, поэтому проще взять карту до 32 ГБ. Размер кластера при форматировании лучше поставить 32 КБ.

Чтобы забрать снимки, выключите камеру, выньте карту из слота на ESP32-CAM и вставьте её в компьютер или телефон через картридер. По USB-кабелю снимки не скачиваются: на ESP32-CAM-MB стоит переходник на последовательный порт CH340, и компьютер видит плату как COM-порт.

Снимки лежат в папке DITHR:

Файл Что внутри
0042_raw.jpg исходный JPEG с сенсора, 1600x1200 (у TIDE 800x600, первый кадр серии)
0042_NEON-VAPOR.jpg обработанный кадр 800x600, JPEG 4:4:4, качество 92
0042_DMG-POCKET.png DMG: PNG 800x720, 2 бита на пиксель
0042_INK-RISO.png INK: PNG 800x600, 1 или 2 бита на пиксель

Первый запуск

Что видно Что поменять в firmware/main/board.h
Картинка на экране перевёрнута или повёрнута OLED_ROTATE 0, 90, 180 или 270
Картинка съехала вбок, у края мусор OLED_COL_OFFSET 96 или 32
Кадр камеры вверх ногами или зеркальный CAM_VFLIP или CAM_HMIRROR в 1
Видоискатель обновляется рывками OLED_I2C_HZ 800000; по спецификации SH1107 400 кГц, многие модули работают быстрее
Мигает красный светодиод, экран тёмный экран не найден на I2C: проверьте SDA, SCL и питание 3V3
На экране NO SD карта не вставлена или не в FAT32; видоискатель работает, снимки не сохраняются

После правки board.h прошивку нужно собрать заново, см. следующий раздел.

Сборка из исходников

Нужен ESP-IDF 6.1. Компоненты espressif/esp32-camera 2.1.8 и espressif/esp_new_jpeg 1.0.2 менеджер компонентов скачивает при первой сборке. Декодер JPEGDEC 1.8.5 лежит в репозитории.

cd firmware
idf.py set-target esp32
idf.py build
idf.py -p COM5 flash
idf.py merge-bin -o dithr-cam-esp32cam.bin

На Windows с ESP-IDF в C:\Espressif эти команды запускает .\idf.ps1 из папки firmware, например .\idf.ps1 build. Последняя команда собирает полный образ для прошивальщика.

Журнал (idf.py -p COM5 monitor) показывает запуск карты и камеры и свободную память, затем обрывается на строке starting OLED.

Как устроена прошивка

Видоискатель работает на ядре 1. Камера отдаёт JPEG 320x240, декодер JPEGDEC считает только яркость и сразу уменьшает кадр вдвое, затем кадр масштабируется до 128x96, проходит упрощённый эффект стиля и дизеринг. Отправка кадра на экран по I2C идёт на ядре 0, пока ядро 1 готовит следующий.

Для снимка камера переключается на 1600x1200 без перезапуска драйвера: буферы кадров выделены при старте под размер 1600x1200. Кадры старого размера прошивка отбрасывает по заголовку JPEG. Исходник пишется на карту как есть, затем декодируется в 800x600 RGB. Эффект делит тяжёлые проходы между двумя ядрами. Результат кодирует esp_new_jpeg в JPEG 4:4:4, чтобы цвет не расплывался на контрастных границах, либо пишется в PNG.

GHOST хранит первый кадр целиком, а от второго и третьего по одному каналу. TIDE переключает камеру на 800x600 ради частоты кадров. Перед серией прошивка строит карту времени и кладёт каждый из 24 кадров только в свои пиксели, поэтому серию не нужно держать в памяти целиком.

Контроллер SD не читает данные из PSRAM по DMA. Запись на карту идёт кусками по 16 КБ через буфер во внутренней памяти.

firmware/
  main/                камера, экран, карта, кнопки, интерфейс, снимок
  components/fx/       эффекты на C99 без зависимостей от ESP-IDF
  components/jpegdec/  JPEGDEC 1.8.5 (bitbank2, Apache-2.0)
host/
  darkroom.c           снимок на ПК тем же путём, что в камере
  run.py               сборка darkroom и прогон стилей
  oled_sim.c           симулятор экрана камеры
tools/
  make_docs.py         картинки для этой страницы
  gen_scene.py         синтетическая сцена
  gen_wiring.py        схема подключения
  gen_bluenoise.py     таблица синего шума 64x64
  gen_font.py          пиксельный шрифт интерфейса

Эффекты на ПК

pip install ziglang pillow numpy
python host/run.py                          # все стили на тестовых фото
python host/run.py --style NEON photo.jpg   # все варианты стиля на своём фото
python tools/make_docs.py                   # картинки для README

Результаты появляются в host/out/. run.py собирает darkroom компилятором Zig в 32-битном режиме, как на ESP32: в 64-битной сборке под Windows JPEGDEC портит картинку. Список тестовых фото в run.py указывает на обои Windows, их можно заменить своими путями.

Состояние проекта

Прошивка собирается без ошибок, все стили проверены на ПК через darkroom и симулятор экрана. На плате ESP32-D0WD-V3 (ревизия 3.1, PSRAM 8 МБ, датчик OV3660) я проверил по журналу запуска, что камера находится и после выделения всех буферов остаётся 439 784 байта PSRAM. Работу экрана, скорость эффектов на ESP32 и вид снимков с датчика я ещё не проверял. После каждого снимка экран показывает, сколько секунд он занял. Если соберёте камеру, пришлите в Issues стиль, это время, плату и снимок.

Код написал Claude от Anthropic по моим задачам, я выбирал стили и проверял результат по снимкам с ПК.

Лицензия

Код проекта распространяется по лицензии MIT, см. LICENSE. JPEGDEC в firmware/components/jpegdec распространяется по Apache-2.0, его лицензия лежит рядом с кодом. Компоненты Espressif скачиваются при сборке, у каждого своя лицензия.