konyahin

sttemp - пишем простой менеджер шаблонов

Sun, 25 Feb 2024 15:11:58 +0300

Как-то раз, мне захотелось собрать свои заготовки мейкфайлов, скелеты для скриптов и man страниц, тексты лицензий и прочую ерунду в одной директории и научиться удобно их использовать. Я не люблю привязанные к редактору схемы, так что мне нужен был максимально простой консольный менеджер шаблонов. Ну а люблю я костыли и велосипеды, поэтому такой менеджер я решил написать себе сам.

Первая версия была написана на C, использовала максимально простую реализацию и максимально уродский синтаксис для подстановки значений в шаблоны. Вот такой вот: {|variable|}.

Программа искала шаблон по имени в захардкоженной директории, построчно обрабатывала его и, если находила подстановку сначала искала переменную окружения с таким именем, а потом, в случае если она отсутствовала, спрашивала значение у пользователя на stderr.

Почему на stderr? Чтобы stdout можно было перенаправить в файл и всё равно увидеть, что прога чего-то от тебя хочет.

Так она и работал, причем вполне неплохо, чуть больше двух лет, если верить истории коммитов, пока я не решил переписать её на языке Shell. Я хотел упростить синтаксис подстановок, передать почти всю работу envsubst из состава GNU gettext utilities, и реализовать ещё несколько идей, которые позволили мне вокруг простой программы сделать такую же простую и маленькую экосистему использования.

Основная идея не поменялась. Всё так же есть директория с шаблонами, правда она переехала в $XDG_DATA_HOME/.local/share/sttemp, в знак уважения к free desktop, в них есть подстановки, но уже более привычного вида, в духе $VARIABLE и мы либо находим их в переменных окружения, либо спрашиваем у пользователя на stderr.

Shell и envsubst позволили мне сильно сократить размер программы, я удалил из репозитория 408 строк, вместе с .h и Makefile, и добавил 62, получив аналогичную программу. Она настолько проста, что не буду останавливаться на ней подробнее, приведу только одну функцию, которая будет иметь значение для дальнейшего повествования. А именно - ask. Всё что она делает, это принимает на вход имя подстановки из шаблона, запрашивает её значение у пользователя и возвращает текстом из себя.

ask () {
	echo "Enter $1:" >&2
	read -r value
	echo "$value"
}

Покончив с переписыванием, я двинулся к следующей идее. Я хотел иметь возможность использовать те же самые шаблоны, по точно такому сценарию, но уже в GUI приложениях. В редакторе, в браузере, где мне будет угодно. Так родился скрипт dsttemp.

Главной проблемой было то, как же мне спросить у пользователя, что он хочет подставить в шаблон. На помощь пришла утилита dmenu, от ребят из suckless. Утилита невероятно простая и настолько же невероятно полезная. Всё что она делает, это читает со стандартного ввода список вариантов, разделенных переносом строки, а потом позволяет пользователю, с помощью ввода какой-то части варианта, выбрать нужный, который и возвращает. Если вы когда-либо использовали fzf, то должны понять как оно работает. При этом, если пользователь вводит что-то не из набора изначальных вариантов, то возвращен будет этот самый ввод. В итоге, мы можем переписать нашу функцию ask как-то так:

ask () {
	echo $(dmenu -p "Enter $1" </dev/null)
}

Через -p мы задаем промпт для пользователя, а перенаправление /dev/null на вход нам нужно чтобы никаких вариантов пользователю не высвечивалось. Осталась одна проблема. Эта функция написана в одном файле - dsttemp, а вызывается в совсем другом, в sttemp.

Для решения этой проблемы я засунул код функции в переменную окружения STTEMP_ASK, а в sttemp добавил следующий код:

[ -n "${STTEMP_ASK:-}" ] && eval "$STTEMP_ASK"

Я уже говорил, что люблю костыли? В итоге, dsttemp принял следующий вид:

#!/usr/bin/env sh

set -eu

export STTEMP_ASK=$(
	cat <<'EOF'
ask () {
	echo $(dmenu -p "Enter $1" </dev/null)
}
EOF
)

TEMPL_NAME=$(sttemp -l | dmenu)
TEMPL_TEXT=$(sttemp "$TEMPL_NAME")

echo "$TEMPL_TEXT" | xclip -selection clipboard
xdotool key --clearmodifiers "Shift+Insert"

Сначала мы засовываем в переменную окружения код, которым хотим заменить оригинальную, консольную, функцию ask. Потом, тоже через dmenu предлагаем пользователю выбрать шаблон из списка, который возвращает sttemp -l. Дождавшись, когда пользователь заполнит все нужные переменные и к нам попадет итоговый текст, мы передаем его в иксовый буфер обмена, из которого вставляем его туда, где стоит курсор пользователя. В иксах несколько буферов обмена, возможно конкретный буфер и конкретную комбинацию клавиш нужно будет настроить исходя из того, каким окружением вы пользуетесь. У меня в dwm всё работает как часы.

Как видите, мы можем заскриптовать своё поведение в иксах с помощью консольных утилит, таких как xclip и xdotool. Это круто и это играет важную роль в следующем, и финальном на сегодня, скрипте.

Я читаю достаточно много статей в браузере и иногда мне хочется скопировать часть текста и отправить в свои заметки, чтобы потом над этим текстом отдельно подумать. В общем, хотелось что-то вроде Pocket, но попроще и чтобы он работал на меня, а не на Mozilla Corporation. И конечно же я не хочу ни писать, ни искать браузерное расширение. Я предпочитаю расширять Unix, а не браузер. Браузер и так расширился дальше некуда.

Для начала я набросал вот такой шаблон, назвав его webnote.

# $TITLE

$BODY

Source: $URL

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

С телом нет никаких проблем, просто считаем выделение в переменную.

export BODY=$(xclip -o)

С источником заметки история чуть более хитрая. Мы опять заскриптуем своё поведение в иксах, а именно нажатие Ctrl + l, для выделения содержимого address bar (у меня Chromium btw), а потом скопируем его и заключим в очередную переменную.

xdotool key --clearmodifiers "Ctrl+l"
xdotool key --clearmodifiers "Ctrl+c"
export URL=$(xclip -o -selection primary)
xdotool key --clearmodifiers "Escape"

Escape мы нажмем просто чтобы вернуться к тому состоянию, в котором пользователь начал выполнение скрипта. Теперь у нас есть всё, кроме заголовка, который пользователь заполнит сам. Осталось просто вызвать sttemp и сохранить его вывод туда, куда мы хотим.

FILE_NAME=$(date '+%Y-%m-%d-%H%M%S')
sttemp webnote >> "/home/anton/public_gopher/web/$FILE_NAME.md"

Вот собственно и всё. Полный исходный код доступен как на Github, так и на self host git. Зачем я вам всё это рассказал? Меня очаровывает тот факт, что даже простые программы, если объединять их с другими простыми программами, могут давать крутые эффекты, и даже наши действия в GUI можно и нужно скриптовать. А очаровывает ли это вас?

Портируем brogue на OpenBSD

Fri, 19 May 2023 21:31:16 +0300

В университетские годы, практически сразу после перехода на Linux, я от таких игр как Gothic 2, Morrowind и Fallout, перешел к новым развлечениям: многопользовательским текстовым MUDам и рогаликам. Так как друзей, готовых наслаждаться текстовыми битвами, у меня не нашлось, а я был слишком робок чтобы влиться в коллектив уже играющих людей, то мады пришлось забросить и остановиться на оффлайновых развлечениях.

Перепробовав несколько разных рогаликов я прикипел душой к самому красочному и простому из них - Brogue. Мне нравилось его изучать, разбираться как работают те или иные механики, нравилось исследовать этажи, ища новые свитки, оружие или хотя бы немного еды. Мне нравилось то, как игра своей случайностью создавала для меня уникальные игровые ситуации, из которых я так же уникально выбирался. Либо же уникально умирал.

Так и не пройдя её полностью, я, тем не менее, провел за игрой какое-то количество часов и она оставила в моей памяти несколько приятных воспоминаний. Недавно я снова вспомнил о ней и обнаружил, что в OpenBSD игру не завезли. Я нашел репозиторий с кодом и убедился, что с малыми правками она прекрасно собирается и работает на моей системе, просто никто не оформил порт. Так почему бы не сделать это самому?

Готовимся к работе

Все новые порты делаются для current версии OpenBSD. Обновитесь хотя бы до снапшота, чтобы ваша локальная система не сильно отличалась от той, в которую порт будут принимать.

Для работы над новым портом вам нужно дерево уже существующих. Обычно его кладут в /usr/ports. Чтобы не собирать порты под рутом и не класть их в домашнюю директорию - добавьте себя в группу wsrc.

doas user mod -G wsrc username

Теперь вам нужно определиться с тем, с какого зеркала вы будете забирать себе изменения в дереве. Выбор достаточно большой, ознакомьтесь со списком вот тут.

# замените на то, что выбрали выше
USER=anoncvs
HOST=mirror.osn.de

cd /usr
doas mkdir -m 775 ports
doas chown root:wsrc ports/

# запускаем именно из /usr
cvs -qd $USER@$HOST:/cvs checkout -P ports

Чтобы сэкономить время и трафик, можно вместо выкачивания всех портов через cvs предзагрузить текущий срез с какого-нибудь сервера. Тогда скрипт для выкачки будет выглядеть как-то так.

# замените на то, что выбрали выше
HOST=mirror.yandex.ru

cd /tmp
wget $HOST/pub/OpenBSD/snapshots/ports.tar.gz

cd /usr
doas tar xzf /tmp/ports.tar.gz
doas chown -R :wsrc ports/
doas chmod -R 775 ports/

У снапшотов нет .sig файла, так что придется обойтись без проверки подписи.

Чтобы cvs знал, откуда брать обновления, после скачивания портов выполните следующий скрипт, либо выставьте переменную окружения CVSROOT, либо используйте ключ командной строки -qd.

# замените на то, что выбрали выше
USER=anoncvs
HOST=mirror.osn.de

cd /usr/ports
echo "$USER@$HOST:/cvs" > CVS/Root

Чтобы не возвращаться к этой теме потом, сразу замечу, что порты надо держать в актуальном состоянии, периодически выкачивая себе новые изменения. Делается этот вот так.

cd /usr/ports
cvs -q up -Pd -A

Куда положить и как скачать

В /usr/ports много директорий, и большая часть из них - категории, содержащие порты. Так как мы портируем игру, то тут с категориями все просто, мы берем games и создаем директорию brogue внутри. Давайте скопируем в неё шаблон Makefile, который мы будем потихоньку заполнять.

mkdir -p /usr/ports/games/brogue
cp /usr/ports/infrastructure/templates/Makefile.template \
 /usr/ports/games/brogue/Makefile

Большая часть строк в Makefile закомментирована, мы заполним всё обязательное и будем раскомментировать интересующие нас строки в процессе работы над портом.

COMMENT =		roguelike game by Brian Walker with X11 support
CATEGORIES =	games

HOMEPAGE =	https://sites.google.com/site/broguegame/

MAINTAINER =	Anton Konyahin <me@konyahin.xyz>

Хоть DISTNAME и MASTER_SITES раскомментированы с самого начала, нам они не нужны, просто удалите эти строчки. Brogue живет на гитхабе и для него у нас есть очень удобный набор переменных, делающих ненужными эти две.

Обратите внимание на то, что после знака равно стоит знак табуляции. Это стандарт оформления, так что лучше его придерживаться.

Давайте укажем переменные, необходимые для скачивания исходников с github.

GH_ACCOUNT =	tmewett
GH_PROJECT =	BrogueCE
GH_TAGNAME =	v1.12

PKGNAME =	brogue-${GH_TAGNAME:S/v//}

Названия переменных говорят сами за себя, мы последовательно заполняем имя аккаунта, имя проекта и тег, которым помечен последний релиз. Если апстрим не использует теги для релизов, можно сослаться на конкретный коммит, заполнив переменную GH_COMMIT.

Здесь же мы указали имя пакета, добавив к названию игры версию из имени тега. Команда, использованная через двоеточие, заменяет (S - substitute) v на пустую строку, что в итоге даст нам просто 1.12.

Чтобы при сборке можно было проверить, что скачиваемый из интернета архив не подменили злоумышленники, в каждом порте хранится чексумма архива с исходниками. Давайте сохраним её и сразу же проверим.

make makesum
make checksum

Вы получите несколько предупреждений о том, что не всё заполнено в нашем Makefile, пока игнорируйте их. В конце вывода второй команды вы должны увидеть строку >> (SHA256) BrogueCE-1.12.tar.gz: OK, сигнализирующую о том, что с архивом (и подписью) всё в порядке.

После выполнения make makesum в директории с портом должен появиться файл distinfo, в нем хранится SHA256 подпись архива и его размер.

Теперь мы можем разархивировать архив командой make extract. Файлы будут сложены в /usr/ports/pobj/ИМЯ ПАКЕТА/ИМЯ АРХИВА/. Но искать его не нужно, просто сделайте make show=WRKSRC.

Следующим важным вопросом является вопрос лицензий. Для разработчиков важно, чтобы лицензия как на само ПО, так и на используемые им ресурсы, позволяла опакечивание и распространение в бинарном виде. Если лицензия этого сделать не позволяет, то пользователю придется самому собирать приложение из портов.

В случае с Brogue все достаточно просто: код распространяется под GNU Affero General Public License, а все игровые ресурсы - под Creative Commons Attribution-ShareAlike 4.0. Понять это можно ознакомившись с двумя LICENSE.txt файлами, один из которых лежит в корне проекта, а второй в /bin/assets. Эти лицензии позволяют опакечивание ПО, так что укажем это в нашем Makefile.

# Code: AGPLv3+
# Assets: CC BY-SA 4.0
PERMIT_PACKAGE =	Yes

Собираем и патчим

К счастью, Brogue для сборки использует обычный Makefile (хоть и содержащий GNU расширения). Собрать проект будет просто. Сразу укажем несколько зависимостей, проект не соберется без установленных пакетов sdl2 и sdl2-image.

USE_GMAKE =	Yes
# в рассылке посоветовали указать, так как тестов в проекте нет
NO_TEST =	Yes

# указываем, какую цель из Makefile будем собирать
ALL_TARGET =	bin/brogue

WANTLIB =	c m SDL2 SDL2_image
LIB_DEPENDS =	devel/sdl2 devel/sdl2-image

c это стандартная библиотека языка C, m - такая же математическая библиотека. В WANTLIB мы указываем библиотеки так, как указали бы их для линковки (-lm -lSDL2_image), а в LIB_DEPENDS пишем названия портов с категориями, необходимых для работы программы.

Теперь, прямо в директории порта, набираем make build. Игра собирается и мы даже можем её запустить, набрав в директории с исходниками ./brogue. Однако, при сборке мы видим некоторое количество варнингов, которые было бы неплохо исправить.

Первым делом избавимся от предупреждения о неизвестной опции компилятора. Для этого мы создадим копию Makefile с расширением .orig.port и поправим оригинал.

cd `make show=WRKSRC`
cp Makefile Makefile.orig.port

# убираем опцию из Makefile
vi Makefile

# возвращаемся директорию порта
cd -

make update-patches

Последняя команда автоматически создаст патч с правильным именем, поместит его в директорию patches и откроет на редактирование в выбранном вами $EDITOR. Не спешите закрывать файл, хорошим тоном считается указать в начале файла что и зачем вы редактировали. Например вот так.

 - drop unknown warning -Wformat-overflow=0

Index: Makefile
--- Makefile.orig
+++ Makefile
Дальше идет текст патча...

Схожим образом можно поправить и остальные предупреждения компилятора. Но не все они чинятся так легко. Например, Brogue использует небезопасные функции для работы со строками в сотне мест, исправить их все будет крайне трудозатратно и это добавит в порт огромную кучу патчей. Так как проект старый и представляет собой всего лишь игру - я решил их не трогать, но для чего-то более серьезного стоило бы приложить усилия к исправлению (только не патчами в порте, а сразу в апстриме.

Flavors и флаги сборки

Если внимательно посмотреть на Makefile brogue, можно увидеть несколько флагов сборки. Самым интересным из них будет DATADIR, позволяющий указать, в какой директории игра будет искать свои ассеты. По умолчанию это текущая директория, что неприемлемо для порта, ведь исполняемый файл должен лежать в /usr/local/bin/, а необходимые приложению ресурсы в /usr/local/share/<name>.

MAKE_FLAGS +=	DATADIR="${PREFIX}/share/brogue"

Второе, на что стоит обратить внимание, это возможность собрать brogue как в графическом, так и в консольном варианте (ещё есть web версия, но её мы оставим где лежит). Порты позволяют нам собирать несколько вариантов пакета с помощью механизма flavors, и даже несколько отдельных пакетов (например для утилиты, для GUI под нее и для документации) с помощью multi packages. В данном случае нам нужен именно flavors, который мы, аналогично пакетам со схожими вариантами, назовем no_x11.

FLAVORS =	no_x11
FLAVOR ?=

Чтобы поменять флаги сборки мы будем ориентироваться на переменную FLAVOR. Для сравнения её с no_x11 мы воспользуемся модификатором M, подробнее о котором, как и о упоминавшемся выше S, можно почитать в man make.

WANTLIB =	c m

.if ${FLAVOR:Mno_x11}
WANTLIB +=	curses
MAKE_FLAGS +=	TERMINAL=YES GRAPHICS=NO
.else
WANTLIB += SDL2 SDL2_image
LIB_DEPENDS +=	devel/sdl2 devel/sdl2-image
.endif

Обратите внимание, что мы поменяли WANTLIB, оставив там только библиотеки, общие для всех вариантов пакета, а LIB_DEPENDS перенесли внутрь условия, так как консольная версия не имеет дополнительных зависимостей.

В начало добавим отдельное описание для варианта без поддержки иксов.

COMMENT-no_x11 =	roguelike game by Brian Walker

Чтобы выполнять операции сборки и пакетирования не над основным пакетом, а над вариацией без иксов, нам нужно будет выставить переменную окружения. Например, вот так env FLAVOR=no_x11 make build. Обратите внимание, что флейвор собирается в отдельной директории и WRKSRC у неё будет другой.

Добавляем свои файлы в порт

Если собрать игру сейчас и немного в неё поиграть, вы заметите что она любит создавать самые разные файлы (сохранения, записи и т.п.) прямо в текущей рабочей директории. Нет никакой возможности указать нужную директорию при сборке, такое поведение зашито в код сразу в нескольких местах. Это крайне неудобно и поначалу я пытался пропатчить все эти места так, чтобы они использовали новый флаг сборки, введенный мною. Но большое количество патчей это сложное и хрупкое решение. К счастью, в рассылке мне подсказали более элегантный способ, спасибо Omar Polo за это и многие другие улучшения моего порта.

Мы переместим исполняемый файл игры в /usr/local/libexec, где лежат все дополнительные исполняемые файлы портов, а в /usr/local/bin мы положим небольшой скрипт, который определит директорию с сохранениями для текущего пользователя, сделает её текущей и уже там запустит игру.

Дополнительные файлы для порта должны лежать в директории files. Создадим там файл brogue со следующим содержимым.

#!/bin/sh

set -e

userdir="${XDG_DATA_HOME:-$HOME/.local/share}/Brogue"

mkdir -p "$userdir"
cd "$userdir"
exec ${TRUEPREFIX}/libexec/brogue "$@"

Установка и PLIST

У brogue нет нормального установочного скрипта в Makefile, так что нам придется взять эту обязанность на себя.

do-install:
	${INSTALL_PROGRAM} ${WRKBUILD}/bin/brogue ${PREFIX}/libexec/
	${SUBST_PROGRAM} ${FILESDIR}/brogue ${PREFIX}/bin/brogue
	${INSTALL_DATA_DIR} ${PREFIX}/share/brogue/assets
	${INSTALL_DATA} ${WRKDIST}/bin/assets/tiles.png \
		${PREFIX}/share/brogue/assets/tiles.png
	${INSTALL_DATA} ${WRKDIST}/bin/assets/tiles.bin \
		${PREFIX}/share/brogue/assets/tiles.bin
	${INSTALL_DATA} ${WRKDIST}/bin/assets/icon.png \
		${PREFIX}/share/brogue/assets/icon.png

Мы добавили новую цель, которая будет использоваться во время сборки пакета, для проведение “фейковой” установки. Наберите в директории порта make fake, а затем cd $(make show=WRKINST). Вы окажетесь в директории fake-amd64 (если вы на amd64, а не на Байкале, конечно), в которую был установлен ваш пакет. Можете убедиться, что файлы порта лежат именно там, где вы ожидаете, на следующем шаге именно фейковая установка послужит основой для описания того, что где и с какими правами должно лежать после установки на реальной системе. Больше про фейковую установку можно почитать тут.

Вернитесь в директорию порта и наберите make update-plist. Когда скрипт отработает, он сообщит вам что создал новый файл - pkg/PLIST.

bin/brogue
@bin libexec/brogue
share/brogue/
share/brogue/assets/
share/brogue/assets/icon.png
share/brogue/assets/tiles.bin
share/brogue/assets/tiles.png

В нашем случае он выглядит достаточно просто - это перечисление файлов и директорий, с одним только @bin напротив исполняемого файла. Но PLIST может больше, указывать права на файлы, группы пользователей и даже запускать какие-то программы при установке пакета. О формате и его возможностей написано здесь.

Дело осталось за малым - добавьте описание пакета в файл pkg/DESCR и проверьте, не забыли ли вы чего, запустив /usr/ports/infrastructure/bin/portcheck и make port-lib-depends-check. Если всё хорошо, то смело набирайте make package, пора поставить пакет в вашу систему и хорошо всё потестировать.

При установке пакета pkg_add проверяет его подпись, но наш пакет самособранный и подписи не имеет. К тому же, он находится не в репозитории с остальными пакетами, а в вашем разделе с портами. Решить обе проблемы легко.

export PKG_PATH=/usr/ports/packages/amd64/all/
doas pkg_add -D unsigned brogue

Если все работает хорошо и стабильно - пакет ставится и удаляется без проблем, сохранения работают и лишние файлы нигде не появляются, поздравляю - у вас есть ваш собственный пакет. Если вы хотите осчастливить им мир - обратитесь в рассылку ports@openbsd.org. Если на ваш порт не обращают внимания не расстраивайтесь, их поддержкой занимаются волонтеры и им может банально не хватать времени, чтобы уследить за всем. Я пинговал рассылку два раза, с промежутком в неделю между каждым пингом, прежде чем смог набрать два ok, требуемых для принятия нового пакета.

Последнее о чем хочется упомянуть - используйте make clean, если исправленная вами ошибка не уходит или происходит что-то странное. Эту команду можно использовать с аргументами, мне очень помогал make clean=package пока я разбирался со сборкой пакета. Ну а если ничего не помогает, делайте make clean=all.

Из полезных ресурсов можно упомянуть:

подробный и практически пошаговый гайд на офф. сайте
man для bsd.port.mk
и почтовую рассылку ports@openbsd.org.

Фильтрация почты в формате MailDir

Sun, 09 Apr 2023 20:24:25 +0300

Я использую почту в формате MailDir. Мне кажется удобным держать весь свой архив сообщений локально, в виде директории с файлами, мне удобно его бэкапить и переносить с одного компьютера на другой. У меня всегда был не очень большой поток сообщений, рабочая почта жила отдельно, в своем огороженном корпоративном мирке, так что я получал письма либо от рекрутеров (которые хотели меня купить), либо от сайтов (которые хотели мне что-то продать).

Но, со временем, я подписался на кое-какое количество почтовых рассылок. Писем стало больше и появилось настойчивое желание их хоть как-то разделять, раскладывая по разным ящикам.

Я слышал про notmuch, однако теги и их фильтрация мне показались излишним усложнением, хотелось просто разложить яйца по корзинам. Слышал я и про procmail, однако он работает как фильтр с входящими сообщениями и не очень ложится ни на мой архив сообщений, ни на мою привычку получать почту через isync. В итоге, в одном из чатов, мне посоветовали посмотреть на mblaze, набор утилит для работы с MailDir. Хоть там и не было того, что прямо бы решало мою проблему, но утилиты были вполне себе удобными и превращали написание скрипта для фильтрации почты в тривиальное задание.

Формируем ТЗ

Перед тем, как начинать писать код давайте определим пару моментов. Само собой, хранить список правил в тексте программы мы не будем. Класть их куда-то ещё, в несвязанные с почтой места тоже не очень хочется. Я не придумал ничего лучше, чем хранить их прямо в корне почтовой директории, в файле .filter. Так как правила у меня будут максимально простые, то и формат файла будет прост. Пишем почту, сообщения от которой (или с которой) должны под правило попадать, и директорию, в которую нам эти письма нужно будет переложить.

Начало моего .filter выглядит вот так:

ports@openbsd.org ports-obsd
misc@openbsd.org misc-obsd
announce@openbsd.org announce-obsd

dev@suckless.org dev-suckless

Блоки отделяются пустой строкой для визуального удобства, никакого влияния на работу скрипта это не оказывает.

Теперь можно подумать об аргументах нашей программы. Хочется чтобы по умолчанию она обрабатывала только новые письма, однако при добавлении правила я хочу иметь возможность прогнать фильтрацию и по старым сообщениям. Также хочется уметь просто распечатать правила фильтрации, не выполняя никаких действий, помимо этого. Ну и добавим возможность вывести небольшую справку, чтобы пользователь (я) мог ожидаемым способом напомнить себе, как же тут все работает.

Я люблю набрасывать черновик справки ещё до написания кода, иногда это подсвечивает какие-то непродуманные моменты и позволяет лучше оценить удобство использования программы. Для сегодняшнего скрипта у меня вышло что-то такое:

mfilter [-hcp] [maildir]
   -h show this help
   -c filter old mails (by default we look at new)
   -p print all rules without filtering
You should specify maildir with -c and -p options. You can use only one flag at time.

Пишем код: приготовления, флаги и проверки

Теперь, после решения основных архитектурных вопросов, можно и код писать.

set -eu

Shell скрипты вещь хрупкая, и подверженная ошибкам. Чтобы хоть немного снизить вероятность их появления (и вероятность загаживания моей почтовой директории), давай включим пару опций. Первая, e, говорит, что если хоть одна команда в скрипте завершится с ошибкой, то мы с ошибкой завершим весь скрипт, продолжать его выполнение будет бессмысленно и опасно в любом случае. Это не касается команд, для которых мы явно проверяем код выполнения. Вторая, u, приводит к тому, что использование не инициализированной переменной приводит к ошибке, а учитывая e - к остановке выполнения всего скрипта. У нас будет пара моментов, где мы используем возможно не инициализированные переменные, и там нам будет нужно явно указать, что мы о такой возможности знаем.

По ходу написания скрипта я понял, что выводить помочь мне нужно в двух местах, при указании флага и при запуске без аргументов. Чтобы избежать дублирования я вынес вывод помощи и выход из скрипта в отдельную функцию.

help () {
    cat <<EOF
$0 [-hcp] [maildir]
   -h show this help
   -c filter old mails (by default we look at new)
   -p print all rules without filtering
You should specify maildir with -c and -p options. You can use only one flag at time.
EOF
    exit 0
}

Для того чтобы можно было удобно хранить и править текст справки я воспользуюсь heredoc. Это конструкция, которая позволяет встраивать данные прямо в шелл скрипт. Всё, от EOF до EOF, считается обычным текстом, который мы перенаправляем на ввод cat.

Теперь займемся аргументами нашей программы. Первым делом давайте обработаем тот случай, когда скрипт вызывается вовсе без аргументов. Обратите внимание, так как мы указали флаг u, то обращение просто к $1 приведет к ошибке, в случае если пользователь не указал аргумент при запуске. Чтобы этого избежать мы явно указываем, что если переменная пуста, то мы её заменим на пустую строку. -z здесь проверяет, что переданная ему в качестве аргумента строка имеет нулевую длину. Я очень плохо помню такие ключи проверки на память, к счастью, их всегда можно напомнить себе, если набрать man test.

if [ -z "${1:-}" ]; then
    help
fi

Далее мы обрабатываем флаги, полученные на вход и, на их основе, выставляем значения наших внутренних переменных.

case "$1" in
    "-h" )
	help
	;;
    "-p" )
	# если пользователь не хочет ничего фильтровать, то мы запомним это
	PRINT_ONLY=yes
	MAIL_DIR=${2:-}
	;;
    "-c" )
	# чтобы обработать старые почтовые сообщения, мы меняем флаг
	# фильтрации для программы mlist (о ней позднее) и поддиректорию,
	# в которую мы будем перекладывать файлы
	MAIL_DIR=$2
	MLIST_FILTER=-C
	MAIL_DEST=cur
	;;
    * )
	# если в первом аргументе не было ничего знакомого - будем считать
	# что это путь к maildir и мы хотим обработать только новые сообщения
	MAIL_DIR=$1
	MLIST_FILTER=-N
	MAIL_DEST=new
	;;
esac

Теперь мы сделаем две последние проверки: что пользователь указал maildir и что в этом самом maildir лежит файл с правилами переноса почты.

if [ -z "$MAIL_DIR" ]; then
    echo "You should specify maildir path"
    exit 1
fi

FILTER_FILE="$MAIL_DIR/.filter"
if [ ! -e "$FILTER_FILE" ]; then
    echo "You should have .filter file in maildir"
    exit 1
fi

Пишем код: основная рабочая логика

Вся работа с почтовыми сообщениями будет сосредоточена в функции move. Для начала, обработаем самый простой случай - когда пользователь хочет только распечатку правил фильтрации.

if [ -n "${PRINT_ONLY:-}" ]; then
	printf "%s\t-> %s\n" "$1" "$2"
else

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

Далее мы, в простом конвейере, вызываем три утилиты из mblaze и первая из них - mlist.

mlist "$MLIST_FILTER" "$MAIL_DIR/INBOX"

Данная утилита выводит список сообщений из указанного почтового ящика. Первый аргумент здесь этот тот самый флаг фильтрации, который мы меняем входным параметром -c. В man по утилите можно посмотреть список всех вариантов выбора сообщений, они достаточно просты и ориентированы на флаги и местоположение почты, без анализа её содержимого.

Теперь, когда мы получили список новых (или старых, если указан -c) почтовых сообщений, мы передаем его утилите mpick. Она позволяет нам осуществить более глубокую фильтрацию, на основе содержимого сообщения. Лично меня интересовали только отправитель или получатель, но в man mpick можно увидеть много других возможных правил.

mpick -t "\"To\" =~~ \"$1\" ||
	\"Cc\" =~~ \"$1\" ||
	\"From\" =~~ \"$1\""

Осталось просто переложить сообщения из одной директории в другую. Однако, даже для такого простого действия, я воспользуюсь отдельной утилитой, а именно mrefile. Дело в том, что у сообщений в maildir есть идентификатор, уникальный в пределах ящика, и если перекладывать почту без учета этого момента (как я, поначалу, и делал), можно напороться на Maildir error: duplicate UID при попытке запустить isync.

mrefile -v "$MAIL_DIR/$2"

Ключ -v мы указываем чтобы утилита напечатала новый путь для каждого сообщения. Эти пути мы передадим финальной программе в нашем конвейере - mv.

mrefile кладет все почтовые сообщения в директорию cur, даже если изначально они лежали в new. Это логично, ведь new указывает на то, что почтовое сообщение только пришло и не было никем обработано, а как раз его обработкой мы с помощью refile и занимались. Но для меня это было не самым удобным поведением. Я использую mutt для работы с почтой и в нем новые сообщения, из папки new, подсвечиваются как в списке самих сообщений, так и в боковой панели, где есть список всех моих почтовых ящиков. Сообщения, которые ещё не открывались, но уже лежат в cur, в терминологии mutt, считаются не новыми, а “старыми”. Они помечаются флагом O. Я смог настроить подсветку старых сообщений внутри ящика, но подсветить ящик со старыми сообщениями в боковой панели мне не удалось. Поэтому я просто двину все обработанные сообщения обратно в new.

xargs -r -n1 -I {} mv {} "$MAIL_DIR/$2/$MAIL_DEST"

mv не читает аргументы из стандартного ввода, поэтому нам потребуется использовать xargs. -r используется чтобы ничего не делать, если ничего не поступило на вход, -n1 говорит брать аргументы по одному, а -I {} задает паттерн ({}), который будет заменен на поступающие на стандартный вход аргументы. По сути, мы для каждого сообщения, которое mrefile переложила в cur, выполним команду

mv mail_file "$MAIL_DIR/$2/$MAIL_DEST"

Чтобы в новые сообщения не попали старые, попавшие под фильтр из-за флага -c, мы используем $MAIL_DEST. При указанном флаге мы переместим файл из cur в cur, в самого себя. Это не вызовет ошибок, так что я решил не писать здесь условие и не усложнять скрипт зря.

Наша функция готова и все что нам остается, это скормить ей набор правил из .filter.

while read -r line || [ -n "$line" ]; do
    if [ -n "$line" ]; then
	# shellcheck disable=SC2086
	move $line
    fi
done < "$FILTER_FILE"

Из-за особенностей shell мы делаем здесь пару неочевидных вещей. Например мы указываем флаг -r для read. Он нужен чтобы отключить фичу, позволяющую разбивать строку на две, с использованием \. Если read встретит такую строку, он сжует и слеш, и идущий следом символ переноса строки. Обычно это не то, что ожидает автор скрипта. Несмотря на то, что в нашем конкретном случае, появление слеша в конце строки не очень вероятно, лучше приучать себя ставить -r везде, где поедание слеша не является ожидаемой фичей.

Вторым удивительным приемом является двойное условие при чтении файла. Мы не просто проверяем какой код вернул read, мы ещё и смотрим, не осталось ли чего в $line. Связано это с тем, что в Unix любой файл должен оканчиваться переводом строки. Однако, ничего не запрещает не поставить его при ручном редактировании файла правил. read считает последнюю строку в переменную line, но не найдя переноса строки сделает вид, что файл кончился. Двойная проверка позволит нам этого избежать.

Последняя примечательная особенность скрипта это отключение проверки от shellcheck. Я стараюсь всегда проверять свои скрипты этим линтером, он указывает на многие неочевидные вещи, которые могут привести к проблемам при исполнении. В этом случае он жалуется на то, что $line не заключен в двойные кавычки. Обычно это хороший совет, все остальные случай использования переменных в скрипте используют кавычки, но если мы укажем их здесь, то на вход move поступит только один аргумент, зато с пробелом. Я же хочу чтобы пара “почта ящик” побилась пробелом на два отдельных аргумента. По хорошему, в данном случае стоит использовать массив или функцию, смотрите примеры в вики shellcheck, но в данном случае я нахожу это излишним и запутывающим код.

Вот и весь скрипт. Он небольшой и вызывается мной после каждой синхронизации почты. Читать рассылки стало куда удобнее, а предназначенная именно мне почта остается лежать в INBOX. Возможно, в дальнейшем мои сценарии использования почты станут сложнее и тогда больше смысла будет в использовании чего-то вроде notmuch, но сейчас мне достаточно и этого. Если вам интересна тема фильтрации и обработки почты из maildir - посмотрите на mblaze, там ещё много интересных утилит.

Исходный код целиком можно посмотреть в моем git.

Поднимаем Git сервер на OpenBSD

Wed, 15 Feb 2023 19:38:25 +0300

Если вам хочется иметь запасное (или даже основное) хранилище для ваших программных проектов, и вы не очень доверяете Github и его собратьям, то ваша дорога лежит в сторону selfhosted git сервера. Давайте поднимем его, используя машину на OpenBSD, и сверху накрутим простой web ui, для просмотра репозиториев через браузер.

Тему базовой настройки сервера и сертификата я оставлю за скобками, скажу только что и httpd, и acme-client содержатся в базовой системе, работают просто прекрасно и обладают хорошей документацией.

Gitdaemon

Помимо базовой системы нам потребуются ещё два пакета, сам git и простой генератор статического сайта из git репозиториев - stagit. Я выбрал именно его потому что мне нравилось пользоваться решениями на его основе, например вот этим сайтом.

pkg_add git stagit

Git сервер будет работать из под своего собственного пользователя, так что давайте его заведем.

В OpenBSD принято добавлять к сервисным учеткам префикс _, то есть наш пользователь должен называться _git. Однако, по эстетическим причинам, я префикс не использую. Я, конечно же, не прав.

Не делайте так.

# -m приведет к созданию домашней директории для пользователя
user add -m git

Чтобы мы могли лить изменения со своего локального компьютера на сервер по ssh, давайте добавим на него наш публичный ключ.

cd /home/git
mkdir -p .ssh && chmod 700 .ssh
touch .ssh/authorized_keys && chmod 600 .ssh/authorized_keys

cat > .ssh/authorized_keys << "END"
no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-ed25519 *** you@example.com
END

chown -R git:git .ssh

Перед ключом мы указали ряд настроек, которые ограничивают возможности ssh соединения с этим ключом. Чтобы добавить ещё безопасности, стоит урезать возможности нашего служебного пользователя. Для этого мы поменяем ему shell на git-shell, позволяющий выполнять только операции над git репозиториями.

chsh -s /usr/local/bin/git-shell git

Всё что нам осталось, это создать директорию для хранения наших репозиториев и натравить на неё gitdaemon.

mkdir -p /git/
chown -R git:git /git

rcctl enable gitdaemon
rcctl set gitdaemon flags --export-all --base-path="/git"
rcctl set gitdaemon user git
rcctl start gitdaemon

rcctl это системная утилита, которая используется для конфигурирования и настройки сервисов и демонов в OpenBSD. В данном случае мы указываем с какими аргументами командной строки сервис должен запускаться и под каким пользователем работать.

Если вы хотите увидеть, с какими аргументами демон будет работать прямо сейчас, наберите rcctl get gitdaemon.

Для добавления нового репозитория я использую небольшой скрипт, который приведу полностью.

#!/usr/bin/env sh

set -e

REPO=$1

if [ -z $REPO ]
then
    echo "You should specify repository name"
    exit 1
fi

mkdir -p /git/$REPO
cd /git/$REPO
git init --bare

echo "Owner name" > owner
echo "git://git.example.com/$REPO" > url
${EDITOR:-vi} description

chown -R git:git /git/$REPO

В качестве аргумента скрипт принимает название репозитория, которое будет так же использоваться в качестве названия директории для него. Помимо директории мы заполняем владельца и общедоступный url для скачивания на просмотр. Для заполнения описания мы открываем текстовый редактор. Все эти вещи будут использоваться stagit для генерации сайта.

На этом моменте стоит попробовать создать новый репозиторий и закачать в него какие-либо изменения, чтобы убедиться что всё работает правильно. Для скачивания репозитория по ssh воспользуйтесь адресом вида ssh://git@example.com:/git/repo-name.

Stagit

Теперь, когда git daemon исправно работает, самое время прикрутить хоть какой-то интерфейс, чтобы любопытствующие могли покопаться в ваших проектах не скачивая их себе.

Для начала давайте отредактируем /etc/httpd.conf и добавим туда новый сервер для нашей веб морды.

server "git.example.com" {
    listen on * tls port 443
    root "/htdocs/git"
    tls {
        certificate "/etc/ssl/example.com.fullchain.pem"
        key "/etc/ssl/private/example.com.key"
    }

    location "./well-known/acme-challenge/*" {
        root "/acme"
        request strip 2
    }

    location "*/style.css" {
        request rewrite "/style.css"
    }

    location "*/logo.png" {
        request rewrite "/logo.png"
    }

    location "*/favicon.png" {
        request rewrite "/favicon.png"
    }
}

Я исхожу из того, что вы используете https на своем сайте, если это не так - конфиг станет ещё проще.

Последние три блока нужны исключительно по той причине, что stagit генерирует относительные ссылки на логотип, стили и favicon сайта. Чтобы не подкладывать их в каждый репозиторий, я просто делаю редирект с любого урла, оканчивающегося запросом одного из этих файлов, на корень, где они, собственно и лежат.

Данный конфиг будет раздавать пользователям статику из директории /var/www/htdocs/git, которую нам надо создать и передать во владение пользователю git, так как контент в ней будет генерироваться из него (но об этом чуть позже).

mkdir -p /var/www/htdocs/git
chown -R git:git /var/www/htdocs/git

Чтобы проверить что мы правильно написали конфиг, стоит воспользоваться командой httpd -n, которая заставляет сервер распарсить и проверить конфиги, но ничего не запускать. Если всё ок, то давайте перезапустим httpd.

rcctl restart httpd

Делать генерацию сайта руками после каждого обновления репозиториев – занятие недостойное человека, поэтому давайте поручим его компьютеру.

Для этого нам нужно создать скрипт, выполняющийся каждый раз после того, как сервер получил какие-либо изменения. Нам нужно создать файл по адресу /usr/local/share/git-core/templates/hooks/post-receive и записать туда приведенный ниже скрипт.

#!/usr/bin/env sh

set -e

# удаляем индекс, если он уже есть
rm -rf /var/www/htdocs/git/index.html

# обходим все имеющиеся у нас репозитории
cd /git/
for repo in */ ; do
    mkdir -p /var/www/htdocs/git/$repo
    cd /var/www/htdocs/git/$repo
    stagit /git/$repo
done

# создаем новый индекс файл
cd /var/www/htdocs/git/
stagit-index /git/* >> index.html

Не забудьте сделать этот хук исполняемым.

chmod +x /usr/local/share/git-core/templates/hooks/post-receive

Теперь всё должно работать. Попробуйте запушить что-нибудь в свой репозиторий и зайти на главную страницу веб интерфейса.

Интерфейс очень простой и полностью статичный, речь не идет ни о каких пулл-реквестах или поиске по коду, но если вам это и не нужно, то stagit должен вам понравиться.

Внешний вид можно настроить с помощью css файла. Погружаться в эту тему я не буду, если хотите, можете посмотреть на мой собственный css файл.

О сайте

Sat, 01 Oct 2022 17:51:16 +0300

Этот сайт сделан с использованием следующих технологий и сервисов:

Помодоро-таймер на Attiny45

Mon, 01 Jan 0001 00:00:00 +0000

Коробка с ардуино и кучкой электронных компонентов стояла у меня в шкафу уже несколько лет. Я купил её в районе 2017-го года, побаловался с Arduino IDE, потом с программатором, приехавших ко мне с aliexpress, помигал диодами и успокоился. Интерес иссяк, придумать проект, который вдохновил бы меня на действия, мне так и не удалось. Я пережил несколько переездов, сменил город, переехал ещё раз, каждый раз с упорством таская за собой оранжевую коробку, с надписью Amperka на боку, и, наконец-то, спустя пять лет, понял что таскал её не зря. Что мне снова хочется что-то делать. И у меня даже была идея - помидоро таймер.

Мой список требований к прибору выглядел так:

включать рабочий режим по нажатию кнопки (красный диод)
через 25 минут сообщать о том, что работа кончилась
переключаться в режим отдыха (зеленый диод)
через пять минут сообщать, что отдых тоже пора сворачивать
засыпать.

Примеряем компоненты на площадке

Bill of materials

Вот так выглядела получившаяся в KiCad схема

Так как проект достаточно простой, то и компонентов для него было нужно не так много. Большая их часть встречается в любом базовом наборе для начинающего, докупать пришлось только гнездо для батарейки. Я использовал:

два диода, красный и зеленый, они будут показывать, что идет работа/отдых
кнопка без фиксации, единственный инструмент ввода нашего устройства
пьезо-динамик, нужен чтобы издавать звуки извещая о смене режима
батарейный отсек под 3V батарейку (у меня это CR2032)
attiny45, самый простой микроконтроллер, который был у меня дома
конденсатор на 100 нФ, блокировочный по питанию, чтобы ток был стабильнее и его не затрагивали переключения режимов
два резистора на 10 кОм, использовались как подтягивающие для кнопки и ножки сброса
два резистора на 220 Ом, чтобы ограничить ток, идущий через диоды
две макетные платы, к которым я всё это припаял
ну и немного проводов, чтобы всё припаянное соединить.

Пройдемся по коду

В main.c файле у нас содержится общий код проекта, осуществляющий оркестрацию работы устройства. Например, там хранится текущий режим работы, в виде enum и переменной для его хранения:

enum status_e
{
    ON,
    WORK,
    REST
};

// int8_t чтобы сэкономить пару спичек на хранении значения
int8_t status = ON;

Для перехода из статуса в статус написано три функции, выполняющие всю нужную работу. Так как они более-менее однотипные, то я покажу только одну.

void
status_to_rest()
{
    status = REST;
    // подаем 1 на ножку с зеленым диодом, и 0 на ножку с красным
    PORTB &= ~(1 << LED_RED);
    PORTB |= (1 << LED_GREEN);
    // играем мелодию (об этом ниже)
    play_melody(&rest_melody);
    // вызываем переключение в другой статус через REST_MIN минут (опять же, подробности ниже)
    set_timer_callback(REST_MIN, &status_to_on);
}

PORTB это специальный регистр, отвечающий за ножки, относящиеся к порту B. Так как Attiny45 это простой микроконтроллер и ножек у него мало, то все они относятся к порту B. Задавая значение того или иного бита в этом регистре, мы можем подавать или убирать напряжение с ножек микроконтроллера.

Сама конструкция может выглядеть загадочно, но там работает обычная битовая логика. (1 << LED_GREEN) дает нам число вида 00001000, с единичкой на том месте, которое соответствует пину, связанному с зеленым диодом. Соответственно выражение PORTB |= (1 << LED_GREEN) устанавливает в единичку этот же самый бит (так как мы выполняем побитовое ИЛИ), а PORTB &= ~(1 << LED_GREEN) наоборот, зануляет его (так как мы выполняем побитовое И с инвертированным значением, таким в котором на нужном месте, и только на нем, стоит нолик).

В самой функции main мы сначала настраиваем контроллер под наши нужды:

// указываем что обе эти ножки работают на вывод
DDRB |= (1 << LED_GREEN);
DDRB |= (1 << LED_RED);

// указываем какой именно режим сна нам нужен и разрешаем его использование
set_sleep_mode(SLEEP_MODE_PWR_DOWN);
sleep_enable();
// включаем обработку прерываний
sei();

// настраиваем наши прерывания, инициализируем код связанный с музыкой и таймером
init_interrupt(switch_status);
init_music();
init_timer();

DDRB это ещё один специальный регистр. Он также относится к порту B, но регулирует не состояние, а режим работы ножки. Ножка может работать как выход, то есть мы можем сами подавать на неё ток или убирать его, а может как вход. В последнем случае мы хотим проверять есть ли напряжение на ножке и, если есть, то сколько. Эти две ножки должны управлять диодами, так что мы включаем для них режим вывода.

Теперь, когда все настроено, мы устраиваем маленький стартовый концерт:

// зажигаем все диоды
PORTB |= (1 << LED_GREEN);
PORTB |= (1 << LED_RED);
// играем стартовую мелодию
play_melody(&start_melody);
// по её окончании все диоды гасим
PORTB &= ~(1 << LED_GREEN);
PORTB &= ~(1 << LED_RED);

Всё что нам осталось, это зациклить работу нашей программы, заодно проверяя, не пора ли увести микроконтроллер в режим сна:

while (true) {
    if (sleep)
    {
        sleep = false;
        sleep_cpu();
    }
}

Что будет, если нажать на кнопку

Чтобы упростить код нашей программы, мы не будем проверять нажата ли кнопка на каждом цикле. Микроконтроллер может сам сообщать нам, если её состояние меняется. Происходит это с помощью механизма прерываний. Чуть выше мы использовали функцию init_interrupt, чтобы повесить на нажатие кнопки смену режим работы устройства. Давайте посмотрим на её код.

void
init_interrupt(void (*on_press) (void))
{
    // сохраняем коллбэк функцию, чтобы вызвать её позже
    callback = on_press;

    // ножку, к которой привязана кнопка, переключаем в режим ввода
    DDRB &= ~(1 << PB2);
    // включаем внешние прерывания
    GIMSK |= (1 << INT0);
}

Режим работы микроконтроллера можно настраивать меняя состояние тех или иных регистров. Мы уже работали с ножками, меняя DDRB и PORTB, теперь же мы воспользуемся новым регистром - GIMSK. В документации на Attiny45 он гордо именуется General Interrupt Mask Register и выставляя на нем INT0 в единичку мы включаем внешние прерывания. Теперь изменение напряжения на ножке PB2 будет приводить к срабатыванию прерывания, которое остановит нормальное выполнение программы и передаст управление сециальному куску кода. Вот этому:

ISR (INT0_vect)
{
    if (PINB & (1 << PB2))
        return;
    _delay_ms(30);
    if (PINB & (1 << PB2))
        return;
    (*callback)();
}

ISR это специальный макрос, который позволяет нам определять функции для обработки прерываний. В скобках после него указывается название прерывания, в данном случае INT0_vect. Далее мы два раза, с перерывом в 30мс, проверяем состояние кнопки. Делается это чтобы избежать ложных срабатываний при дребезге контактов. Между контактами кнопки могут проскакивать отдельные электрические сигналы, особенно если мы начинаем её нажимать или отпускать, приближая контакты друг к другу. Два замера через 30мс дают нам большую уверенность, в том, что прерывание сработало на полноценное нажатие кнопки. После этого мы вызываем коллбэк функцию, которая меняет режим работы устройства и проигрывает какую-нибудь мелодию.

Издаем звуки

Чтобы проиграть мелодию мы будем использоваь пьезодинамик. Внутри него находится специальный кристал, который меняет свой размер при изменении приложенного к нему напряжения. Если менять напряжение достаточно часто, то кристалл будет своим движением производить звук. Не особо музыкальный, но для привлечения внимания к прибору нам хватит и такого.

Звук это волна, но так как наш микроконтроллер работает по цифровым, а не по аналоговым принципам, то просто так подать волну на пьезодинамик мы не можем. Мы будем имитировать её с помощью PWM, широтно-импульсной модуляции. Суть её состоит в том, что вместо того, чтобы подавать на выход 0.5 мы будем 50% времени держать на выходе 1 и 50% времени 0. Если делать это достаточно быстро, то для внешнего наблюдателя это будет выглядеть как работа в половину мощности.

void
init_music(void)
{
    // ножка с пьезодинамиком работает на выход и, по началу, сигнал на неё мы не даем
    DDRB |= (1 << SOUND);
    PORTB &= ~(1 << SOUND);

    TCCR0A |= (1 << WGM01);
    TCCR0A |= (1 << COM0A0);
}

TCCR0A это ещё один регистр нашего микроконтроллера, отвечающий за настройки его внутреннего таймера. Устанавливая в единичку бит WGM01 мы говорим, что работать он должен в режиме CTC (Clear Timer on Compare Match). При каждом срабатывании таймера его значение будет увеличиваться на единицу и сравниваться со значением, лежащим в регистре OCR0A. Когда они окажутся равны, то состояние ножки с динамиком переключится, а когда значение переполнится и отсчет начнется с 0, то состояние ножки поменяется ещё раз. Таким образом мы можем управлять тем, какой процент времени на ножку подается напряжение. Это значение называется Duty Cycle или коэффициент заполнения.

Мелодия для проигрывания у нас хранится в простенькой структуре, содержащей число нот и сами эти ноты.

typedef struct melody_s {
    uint8_t length;
    uint8_t tones[];
} melody_t;

Ноты для наших мелодий зашиты в код программы, вместе с временем в мс, в продолжении которого будет звучать каждая нота.

#define TONE_A 42
#define TONE_AS 39
#define TONE_B 37
#define TONE_C 71
#define TONE_CS 67
#define TONE_D 63
#define TONE_DS 59
#define TONE_E 56
#define TONE_F 53
#define TONE_FS 50
#define TONE_G 47
#define TONE_GS 44

#define DELAY 250

Значения для нот высчитывались исходя из частоты микроконтроллера, но статью с формулами для расчета я потерял. Так что просто поверьте в эти значения. Сами мелодии объявлены в main.c, вот пример одной из них:

melody_t start_melody = {
    .length = 5,
    .tones = {
        TONE_A,
        TONE_D,
        TONE_G,
        TONE_E,
        TONE_B
    }
};

Логика функции, которая играет музыку, крайне проста:

void
play_melody(const melody_t *melody)
{
    // запускаем таймер, выставляя ему частоту срабатывания
    TCCR0B |= (1 << CS01);

    for (int8_t i = 0; i < melody->length; i++)
    {
        // выставляем duty cycle, равный значению текущей ноты
        OCR0A = melody->tones[i];
        // пока мы здесь ждем 250мс, нота продолжает звучать
        _delay_ms(DELAY);
    }

    // выключаем таймер
    TCCR0B &= ~(1 << CS01);
}

Вот и всё, что нужно, чтобы издавать звуки. Осталось только определить, когда именно их надо издавать.

Ещё один таймер

Отсчитывать время работы (или отдыха) у нас будет другой таймер. Настроен он таким образом, чтобы срабатывать приблизительно раз в секунду и, при каждом своем срабатывании, вызывать прерывание.

void
init_timer(void)
{
    // отключаем прерывания, чтобы они не помешали нам полностью настроить таймер
    cli();
    // на каждом шаге таймер будет сранивать свое значени вот с этим, как было с `OCR0A` у таймера звука
    OCR1A = 244;
    // указываем что этот таймер тоже работает в режиме CTC
    TIMSK |= (1 << OCIE1A);
    // выставляем ещё несколько бит для настройки таймера
    // CTC1 запускает таймер
    // CS13 CS12 CS10 - настраиваем то, с какой периодичностью, 
    // относительного частоты процессора, он будет срабатывать,
    // в данном случае это CK/4096
    TCCR1 |= (1 << CTC1) | (1 << CS13) | (1 << CS12) | (1 << CS10);
    // снова включаем прерывания
    sei();
}

Если мы умножим 4096 на 244, то получим 999424. Так как наш микроконтроллер должен работать с частотой 1000000 операций в секунду, то мы можем ожидать, что таймер будет вызывать прерывание где-то раз в эту самую секунду. Но Attiny не очень точны в плане частоты. У микроконтроллеров из разных партий частота может немного отличаться, к тому же на неё может влиять температура и поданое напряжение. Чтобы приблизить ожидаемое время срабатывания к реальному, я прогонял тесты и выяснил, что за одну минуту таймер срабатывает в среднем 57 раз. Это значение записано у меня в SEC и если вы решите использовать мой код со своим микроконтроллером, то скорее всего вам нужно будет его поменять. Для устройств, которые требуют более точного измерения времени, стоит воспользоваться внешними часами реального времени, например DS1307.

static uint8_t minutes = 0;
static uint8_t seconds = 0;
static void (*callback) (void) = NULL;

ISR (TIMER1_COMPA_vect)
{
    if (seconds > 0)
    {
        --seconds;
        return;
    }
    else
    {
        // тот самый SEC равный 57, а не 60
        seconds = SEC;
        --minutes;
    }
    if (minutes == 0 && callback != NULL)
        callback();
}

Код прерывания ещё проще. Отсчитываем секунды и минуты, заданные кодом смены режим работы, и, когда дошли до нуля, дергаем указанный при старте коллбэк.

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

Вот такой вот получился проект. С исходным кодом целиком можно познакомиться здесь. Несмотря на его простоту, в процессе я успел познакомиться с многими функциями Attiny, такими как таймеры, прерывания и режимы сна. Ну а главное, я получил нечто физическое, как результат своей работы. И это очень приятное чувство.