diff --git a/FW/readme.md b/FW/readme.md
new file mode 100644
index 0000000..d8d2d17
--- /dev/null
+++ b/FW/readme.md
@@ -0,0 +1,48 @@
+# ZX Spectrum Cartridge Controller — программисту
+
+## Общая информация
+
+Модуль `zx_cartridge` управляет четырьмя микросхемами ПЗУ типа AM29F040 (512 КБ каждая), что даёт **2 МБ** памяти.  
+Память организована в виде **256 страниц по 8 КБ**. Страницы нумеруются от 0 до 255.
+
+В адресном пространстве ZX Spectrum под картридж отведена область **0x0000…0x3FFF** (16 КБ, первые 16 КБ памяти).  
+Эта область разделена на два 8‑КБ окна:
+
+- **Нижнее окно** `0x0000…0x1FFF` (A13 = 0) — всегда **страница 0**.  
+  Здесь должен располагаться код BIOS картриджа.
+
+- **Верхнее окно** `0x2000…0x3FFF` (A13 = 1) — страница, номер которой задаётся программно через регистр `bank`.
+
+## Регистры управления
+
+Доступ к регистрам осуществляется через порты ввода‑вывода.  
+
+### Порт `bank` (адрес **0xDF7F**)
+
+- **Запись** (`OUT (0xDF7F), A`) — устанавливает номер страницы для верхнего окна.  
+- **Чтение** (`IN A, (0xDF7F)`) — возвращает текущее значение регистра.
+
+Формат байта `bank`:
+
+| Биты 7–6 | Биты 5–0            |
+|----------|---------------------|
+| Выбор микросхемы (0–3) | Номер страницы внутри микросхемы (0–63) |
+
+Таким образом, полный номер страницы = `(chip << 6) | page`.  
+После сброса регистр равен 0 (микросхема 0, страница 0).
+
+### Порт `control` (адрес **0xBF7F**)
+
+- **Запись** (`OUT (0xBF7F), A`) — запись в управляющий регистр.  
+- **Чтение** (`IN A, (0xBF7F)`) — чтение текущего значения.
+
+Формат байта `control`:
+
+| Биты 7   | Биты 6–0            |
+|----------|---------------------|
+| Отключение картриджа | Можно использовать по своему усмотрению |
+
+- **Бит 7 = 0** — картридж включён (обычный режим).  
+- **Бит 7 = 1** — картридж отключён. Выходы ПЗУ переводятся в высокоимпедансное состояние, внутреннее ПЗУ Spectrum работает штатно.
+
+После сброса бит 7 = 0 (картридж включён).
diff --git a/README.md b/README.md
index 918594a..868d0bc 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,41 @@
-# zx_cartridge
\ No newline at end of file
+# ZX Cartridge
+
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Проект картриджа для компьютера **Дельта 128К**. Устройство реализовано на четырех 29040 и CPLD, подключается к слоту расширения компьютера. Репозиторий содержит полный набор как исходных файлов, так и файлы для производства.
+Также есть схема в pdf. Есть две версии прошивки - для оригинальных картриджей и расширенный вариант.
+
+На текущий момент (23.02.2026) собран макет.
+
+## Функциональность
+
+В процессе тестирования.
+
+---
+
+## Аппаратная часть (HW)
+
+Печатная плата разработана в **Altium Designer** (файл `fix.PrjPCB`).  
+Структура папки `HW`:
+- `fix.PrjPCB` – проект.
+- `src/` – исходные файлы схемы (`main.SchDoc`) и платы (`pcb.PcbDoc`).
+- `altium_libs/` – библиотеки компонентов (субмодуль).  
+  Библиотеки содержат посадочные места, условные обозначения и 3D-модели (папка `3dmodels` со STEP-файлами).  
+  Репозиторий использует **git submodule** для подключения библиотек – это упрощает синхронизацию с обновлениями.
+
+Изображения готового прототипа и модели платы можно найти в папке [`media`](#media).
+
+---
+
+## Программируемая часть (FW)
+
+Прошивка для ПЛИС написана на Verilog и предназначена для синтеза в среде **Quartus** (файлы проекта `zx_cartridge.qpf`, `zx_cartridge.qsf`).  
+Основной модуль – `zx_cartridge` (файл `src/zx_cartridge.v`).
+
+## Медиа
+
+В папке [`media`](media) находятся фотографии платы в процессе разработки прототипа.
+
+![Image](./media/pcb_top.png)
+![Image](./media/proto_top.png)
+![Image](./media/proto_bot.png)
\ No newline at end of file
diff --git a/media/pcb_top.png b/media/pcb_top.png
new file mode 100644
index 0000000..bc8e55d
Binary files /dev/null and b/media/pcb_top.png differ
diff --git a/media/proto_bot.png b/media/proto_bot.png
new file mode 100644
index 0000000..00cfa5d
Binary files /dev/null and b/media/proto_bot.png differ
diff --git a/media/proto_top.png b/media/proto_top.png
new file mode 100644
index 0000000..c2268fa
Binary files /dev/null and b/media/proto_top.png differ