FlipperOS

Кастомная прошивка для Flipper Zero на базе Unleashed (релиз unlshd-093). Внутри всё, что есть в Unleashed, плюс собственное приложение Flipper OS Toolkit прямо в главном меню.

English summary. Custom Flipper Zero firmware based on Unleashed. Adds a Flipper OS Toolkit app to the main menu, a branded desktop animation, and Patrol, a guard-tour log with HMAC-protected records that can be verified offline. Firmware packages are built and released by GitHub Actions. Docs below are in Russian.

Что добавлено поверх Unleashed:

• Пункт «Flipper OS» в главном меню с анимированной иконкой-чипом.
• Flipper OS Toolkit v1.3 входит в прошивку (apps/Tools/flipper_os.fap).
• Анимация FlipperOS на рабочем столе: заставка с логотипом добавлена в набор анимаций дельфина (см. firmware/patches).
• Брендинг: прошивка называется FlipperOS, файлы сборки — flipperos-<версия>.
• CI: GitHub Actions собирает пакет обновления на каждый пуш. Релиз публикуется, когда в main появляется новый docs/releases/<тег>.md (например v1.4.md, из него же берётся описание), а также для тега v* или при ручном запуске workflow Build FlipperOS firmware с параметром release_tag.

Patrol — журнал обходов с защитой от подделки

Отдельное приложение patrol/, тоже встроенное в прошивку (Apps → Tools → Patrol): Flipper становится считывателем для обходов охраны и регламентных осмотров. Охранник прикладывает Flipper к NFC-, RFID- или iButton-меткам маршрута, каждая запись журнала подписана HMAC-SHA-256 по цепочке, ключ зашифрован анклавом устройства, а руководитель проверяет журнал офлайн-страницей companion/patrol-report.html. Анализ рынка и варианты монетизации — в docs/PATROL_BUSINESS.md.

Flipper OS Toolkit

Модуль	Что делает	Управление
Stopwatch	Секундомер с сотыми долями и историей до 50 кругов: время круга, отсечка, лучший круг помечен *	OK — старт/стоп, ← — круг (идёт) / сброс (стоит), ↑/↓ — листать круги
Timer	Обратный отсчёт до 99:59 с прогресс-баром и сигналом (звук, вибро, LED). Идёт и звонит, даже если открыт другой модуль, — экран таймера всплывает сам. Сигнал звучит 30 с	←/→ — минуты/секунды, ↑/↓ — значение, удержание OK — пресеты 1…60 мин, OK — старт/пауза, ← — сброс, любая кнопка глушит сигнал
Pomodoro	Техника «помидора»: фокус / короткий перерыв / длинный перерыв после 4 сессий, длительности настраиваются, счётчик завершённых сессий. Работает в фоне, как таймер	Настройка: ↑/↓ — пункт, ←/→ — минуты, OK — старт. Во время сессии: OK — пауза, ← — сброс, → — пропустить этап
Flashlight	Белый светодиод: постоянно, стробоскоп или маяк; 4 уровня яркости; подсветка экрана не гаснет	OK — вкл/выкл, ↑/↓ — яркость, ←/→ — режим
Dice Roller	От 1 до 4 костей d4…d100 с анимацией и вибро	↑/↓ — грани, ←/→ — количество, OK — бросок
Coin & 8-Ball	Монетка (орёл/решка), «Да/Нет» со счётом результатов и Magic 8-Ball с 20 классическими ответами	←/→ — режим, OK — бросок/вопрос
Password Gen	Генератор паролей и PIN-кодов на аппаратном ГСЧ: 4…32 символа, 4 набора символов (гарантированно есть символ каждого класса), оценка энтропии в битах	↑/↓ — длина, ←/→ — набор символов, OK — новый пароль
Morse Beacon	Сообщение азбукой Морзе через LED, LED+вибро или LED+звук. Есть свой текст с экранной клавиатуры (буквы и цифры, _ — пробел)	←/→ — сообщение, ↑ — способ вывода (LED/вибро/звук), ↓ — повтор, OK — старт/стоп, удержание OK на «своём тексте» — редактировать
Snake	«Змейка» 32×14 с ускорением. Два режима: сквозные края или стены, у каждого свой рекорд	Стрелки — поворот, OK — старт/пауза, ↑/↓ между играми — режим
Reaction Test	Тест реакции: после случайной паузы экран и LED вспыхивают, нужно нажать любую кнопку. Время в мс, среднее за 5 попыток, рекорд. Фальстарт засчитывается	OK — начать, любая кнопка — реакция
Tally Counter	Счётчик с шагом 1…100	OK — плюс, ← — минус, удержание ← — сброс, ↑/↓ — шаг
System Info	Имя, заряд, напряжение, ток и температура АКБ, свободная память, аптайм, дата и время	—
Settings	Сброс сохранённых данных Toolkit: рекорды и статистика, счётчик или всё сразу. Действует сразу, перезапуск не нужен	↑/↓ — пункт, OK — подтвердить (дважды), ← — отменить подтверждение
About	Версия Toolkit, происхождение прошивки, ветка/коммит и дата сборки, модель и имя устройства	—

Рекорды, статистика «помидоров», значение счётчика и настройки всех модулей (кости, Морзе и свой текст, фонарик, таймер, генератор паролей) сохраняются на SD-карте в apps_data/flipper_os/settings.dat. Сами пароли нигде не сохраняются. При обновлении с 1.0–1.2 старые данные переносятся автоматически. Внизу меню — Settings (сброс сохранённых данных Toolkit) и About (версия Toolkit, ветка/коммит и происхождение прошивки, дата сборки).

Приложение совместимо и с официальной прошивкой: там оно ставится как обычный .fap в Apps → Tools.

Что даёт Unleashed

Всё это в прошивке FlipperOS работает «из коробки» — это код и функции самого Unleashed, подключённого субмодулем (см. «Как перенесены функции Unleashed» ниже):

• SubGHz — расширенный список поддерживаемых протоколов ворот/шлагбаумов/сигнализаций сверх официальной прошивки, приём и передача без региональных ограничений (в Unleashed они сняты всегда), расширение частотного диапазона за пределы спецификации CC1101 (по умолчанию выключено, включается в файле dangerous_settings на SD, см. ниже), сохранение и повтор сырых сигналов, режим анализа частоты (Frequency Analyzer), поддержка внешних модулей (SubGHz Rx/Tx-модули на CC1101).
• 125 кГц RFID (LF-RFID) — чтение, запись и эмуляция EM4100 и совместимых карт с добавочными настройками из Unleashed; брутфорс — приложением RFID Fuzzer из пака приложений (см. ниже).
• NFC — чтение/эмуляция/запись Mifare Classic/Ultralight/DESFire, восстановление ключей Mifare Classic (mfkey), больше NFC-словарей ключей, чем в официальной прошивке.
• iButton — чтение, запись и эмуляция Dallas/Cyfral/Metakom ключей.
• Infrared — универсальный пульт с расширенной базой ИК-кодов бытовой техники и учебный/анализирующий режим сигнала.
• BadUSB — раскладки клавиатур сверх стандартного набора, доп. режимы скрипта.
• GPIO — управление пинами, USB-UART bridge, 1-Wire.
• U2F — аппаратный ключ двухфакторной аутентификации.
• Bluetooth/BLE — расширенные настройки сопряжения и профиля клавиатуры/мыши по BLE (наследие Unleashed).
• Расширенный диапазон частот Sub-GHz — региональных ограничений на передачу в Unleashed нет; кроме того, диапазон можно расширить до 281–361, 378–481 и 749–962 МГц: в файле /ext/subghz/assets/dangerous_settings замените yes_i_want_to_destroy_my_flipper: false на true. В нашей сборке это, как и в Unleashed, выключено по умолчанию — включать сознательно и на свою ответственность: передача вне сертифицированных диапазонов может быть незаконна в вашей стране и потенциально перегреть/повредить радиомодуль.
• Расширенный набор тем и анимаций дельфина, доп. игры и Apps → Tools из самого Unleashed (Clock, Snake и т.д. — не путать с одноимёнными модулями нашего Toolkit, это отдельные, штатные для Unleashed приложения).

Мы не переписывали код этих функций — они входят как есть, вместе с исходниками Unleashed. Подробности ниже.

Установка прошивки

1. Скачайте пакет обновления из Releases (или из артефактов workflow Build FlipperOS firmware во вкладке Actions). Их два, как у Unleashed:

   • flipper-z-f7-update-flipperos-<версия>.tgz — прошивка + базовый пак приложений (то же, что в обычном релизе Unleashed);
   • flipper-z-f7-update-flipperos-<версия>e.tgz — то же + Extra-пак (все известные рабочие приложения сообщества, около 360 штук).

2. В qFlipper нажмите Install from file и выберите этот .tgz.

   Без компьютера: распакуйте архив в update/ на SD-карте и на Flipper откройте update/f7-update-flipperos-*/update.fuf через Archive → Run in App.

Вернуться на официальную прошивку или Unleashed можно тем же способом.

Сборка

Прошивка (нужны Linux или macOS, git, curl и Python 3; на macOS — GNU sha256sum из coreutils в PATH, системный /sbin/sha256sum не понимает --status; тулчейн fbt скачает сам):

git clone https://github.com/codebywater/flipper-os
cd flipper-os
firmware/build.sh                  # → firmware/unleashed/dist/f7-C/*.tgz
firmware/build.sh flash_usb_full   # собрать и сразу прошить по USB
FLIPPEROS_PACK=extra firmware/build.sh   # с Extra-паком приложений

FLIPPEROS_PACK выбирает приложения сообщества на SD-карте: base (по умолчанию), extra или none (только прошивка и наши приложения).

Только приложение, под любую прошивку, через ufbt:

pip install --upgrade ufbt
cd flipper_os
ufbt            # → dist/flipper_os.fap
ufbt launch     # собрать, загрузить и запустить по USB

Тесты

Тесты приложения Patrol запускаются на компьютере, без Flipper и без сборки прошивки. Нужны компилятор C, Python 3 и Node.js:

tests/run_patrol_tests.sh

Скрипт сверяет SHA-256/HMAC из кода на C с эталоном Python и проверяет, что офлайн-отчёт companion/patrol-report.html принимает журналы, подписанные приложением. Те же тесты запускаются в GitHub Actions на каждый пуш.

Как перенесены функции Unleashed

Функции Unleashed выше не переписывались и не портировались вручную — весь Unleashed подключён как git-субмодуль firmware/unleashed (закреплён на релизе unlshd-093) и собирается целиком, штатным fbt. Мы не трогаем список приложений Unleashed — только добавляем в него один свой пункт:

# firmware/overlay/fbt_options_local.py
FIRMWARE_APPS["default"].append("flipper_os")   # append, а не замена списка

Поэтому все приложения из штатного набора Unleashed (main_apps, system_apps, settings_apps) остаются в прошивке без изменений — включая dangerous_settings и прочее, описанное выше. Подробный список того, что именно добавлено поверх Unleashed, — в первом разделе этого README.

Приложения сообщества (Sub-GHz bruteforce, анализатор спектра, ESP32 / NRF24 / GPS, игры и т. д.) в исходники Unleashed не входят: его релизы получают их отдельным шагом, копируя готовые паки из xMasterX/all-the-plugins на SD-карту вместе с обновлением. Сборка только из исходников даёт «clean»-вариант без них — именно так выглядел наш релиз v1.3. firmware/build.sh теперь делает тот же шаг: скачивает закреплённый релиз паков (версия и SHA-256 — в начале скрипта), кладёт их в пакет обновления, а CI проверяет (firmware/tools/check_package.py), что все файлы паков действительно оказались в итоговом .tgz. При обновлении Unleashed меняйте закреплённый релиз паков вместе с ним.

Как устроен репозиторий

flipper_os/                 приложение Flipper OS Toolkit
├── application.fam         манифест (MENUEXTERNAL: пункт главного меню)
├── flipper_os.c            точка входа, ViewDispatcher, меню
├── settings.c/.h           сохранение состояния на SD
└── modules/                по одному View на модуль
firmware/
├── unleashed/              git-субмодуль Unleashed, закреплён на unlshd-093
├── overlay/                файлы, копируемые поверх Unleashed
│   ├── fbt_options_local.py            имя прошивки и состав меню
│   ├── assets/icons/MainMenu/FlipperOS_14/   иконка главного меню
│   └── assets/dolphin/external/L1_FlipperOS_128x64/   анимация рабочего стола
├── patches/                *.patch к исходникам Unleashed (см. README там)
│   └── 0001-flipperos-desktop-animation.patch   анимация в манифесте дельфина
├── tools/make_animation.py генератор кадров анимации (нужен Pillow)
├── tools/check_package.py  проверка, что в .tgz есть паки приложений
└── build.sh                сброс → патчи → паки приложений → overlay → приложения → ./fbt
patrol/                     приложение Patrol (журнал обходов)
companion/patrol-report.html  офлайн-проверка журналов Patrol
tests/run_patrol_tests.sh   тесты HMAC и проверки журналов
docs/PATROL_BUSINESS.md     анализ рынка и монетизация

Unleashed не копируется в репозиторий целиком, а подключён субмодулем. Поэтому переход на новую версию сводится к смене коммита субмодуля (команды ниже) и закреплённого релиза паков в firmware/build.sh (PLUGINS_URL, PLUGINS_BASE_SHA256, PLUGINS_EXTRA_SHA256):

cd firmware/unleashed && git fetch --depth 1 origin tag unlshd-XXX && git checkout unlshd-XXX
cd ../.. && git add firmware/unleashed && git commit -m "Bump Unleashed to unlshd-XXX"

Unleashed распространяется под лицензией GPL-3.0, поэтому собранная прошивка FlipperOS подпадает под ту же лицензию.