# seeed-clicker — система «кликер + USB-донгл» на ESP-NOW

Проект KiCad 8 (файлы открываются в KiCad 8 / 9 / 10) с двумя платами:

| Плата | Лист схемы | Назначение |
|---|---|---|
| **CLICKER** | `clicker.kicad_sch` | Носимый передатчик: ловит нажатия/движения, шлёт кадры по ESP-NOW |
| **DONGLE** | `dongle.kicad_sch` | USB-приёмник для ПК: ловит ESP-NOW, эмулирует HID-клавиатуру/мышь |

Обе платы лежат в одном проекте: корневая схема — `seeed-clicker.kicad_sch`
(иерархия из двух листов), раскладка — `seeed-clicker.kicad_pcb`
(два контура: CLICKER 0×0…56×88 мм, DONGLE 66×0…92×54 мм).
Связь между платами — **только радиоканал 2.4 ГГц (ESP-NOW)**, никаких
проводных линий между платами нет.

## Структура проекта

```
seeed-clicker/
├── seeed-clicker.kicad_pro      — проект
├── seeed-clicker.kicad_sch      — корневой лист (2 иерархических листа)
├── clicker.kicad_sch            — схема кликера
├── dongle.kicad_sch             — схема донгла
├── seeed-clicker.kicad_pcb      — обе платы в одном файле (расстановка, без трассировки)
├── fp-lib-table / sym-lib-table — таблицы библиотек (${KIPRJMOD}/libs/…)
├── libs/
│   ├── seeed-clicker.kicad_sym  — символы проекта (генерируются)
│   ├── seeed-clicker.pretty/    — футпринты проекта (генерируются)
│   └── vendor/                  — скачанные первоисточники (референс, в проект не подключаются)
└── tools/
    ├── gen.py                   — единственный источник истины: генерирует всё
    └── validate.py              — валидация (см. «Проверка»)
```

> Все `.kicad_sch`, `.kicad_pcb`, `.kicad_sym`, `.kicad_mod` создаются
> генератором. **Править их руками нельзя** — правки затрутся при следующем
> запуске `tools/gen.py`. Все изменения вносятся в `gen.py`.

## Схема и пинмап

### CLICKER (XIAO ESP32C3 = U1, RP2040-Zero = U2)

| XIAO | GPIO | Назначение | Пин модуля |
|---|---|---|---|
| D0 | GPIO2 | `VBAT_SENSE` — делитель 200к/200к с BAT+ | R5/R6 |
| D1 | GPIO3 | `JOY_X` (VRX, ADC1) | J4.3 |
| D2 | GPIO4 | `JOY_Y` (VRY, ADC1) | J4.4 |
| D3 | GPIO5 | `RTC_CLK` | J3.3 |
| D4 | GPIO6 | `SDA` (I2C, подтяжка R1 4.7к) | J1.4, J2.4 |
| D5 | GPIO7 | `SCL` (I2C, подтяжка R2 4.7к) | J1.3, J2.3 |
| **D6** | **GPIO21 (U0TXD)** | **`UART_TX` → GP1 (RX) RP2040** | U2.11 |
| **D7** | **GPIO20 (U0RXD)** | **`UART_RX` ← GP0 (TX) RP2040** | U2.10 |
| D8 | GPIO10 | `JOY_SW` + подтяжка R3 10к | J4.5 |
| D9 | GPIO9 | `RTC_DAT` + подтяжка R4 10к (**strapping BOOT**) | J3.4 |
| D10 | GPIO8 | `RTC_RST` | J3.5 |
| VBAT | — | аккумулятор (площадки BAT+/BAT−) | J5.1 |
| 5V | — | не используется (NC) | — |

Периферия (кроме аккумулятора) питается **строго от +3V3**.

Разъёмы кликера (порядок пинов строго по ТЗ):

* **J1 OLED SSD1306 0.96"** — `1 GND, 2 VDD, 3 SCK, 4 SDA`
* **J2 MPU-9250** — `1 VCC, 2 GND, 3 SCL, 4 SDA, 5 EDA, 6 ECL, 7 ADO, 8 INT, 9 NCS, 10 FSYNC`
* **J3 DS1302 RTC** — `1 VCC, 2 GND, 3 CLK, 4 DAT, 5 RST` (**3-проводной интерфейс, не I2C!**)
* **J4 KY-023** — `1 GND, 2 VCC(+3V3), 3 VRX, 4 VRY, 5 SW`
* **J5 аккумулятор** — JST-PH 2.0: `1 BAT+, 2 BAT−`
* **JP1** — перемычка 0R (0603) между шиной +3V3 и 3V3-выводом RP2040

### DONGLE (XIAO ESP32C3 = U3, RP2040-Zero = U4)

| Сигнал | XIAO | RP2040-Zero |
|---|---|---|
| `UART_TX` | D6 (GPIO21, TX) | GP1 (RX), пин 11 |
| `UART_RX` | D7 (GPIO20, RX) | GP0 (TX), пин 10 |
| `+5V` | 5V (пин 14) | 5V (пин 1, общий VBUS USB-C RP2040) |
| GND | GND (пин 13) | GND (пин 2) |

* RP2040-Zero — **USB HID** к ПК (клавиатура/мышь), XIAO — **ESP-NOW** приёмник.
* **3V3 контроллеров не объединяются** (у каждого свой стабилизатор).
* USB-C XIAO на донгле — только прошивка/отладка; в рабочем режиме донгл
  питается через USB-C RP2040 (VBUS → шина +5V → 5V XIAO).
* Остальные GPIO обоих контроллеров помечены NC.

## Отклонение от ТЗ (важно)

**UART кликера перенесён с D0/D1 (по ТЗ) на D6/D7.**

Обоснование: на XIAO ESP32C3 только **D0/D1/D2 — надёжный ADC1**
(GPIO2/GPIO3/GPIO4). D3 — это GPIO5 = **ADC2**, который перестаёт быть
доступным, когда работает WiFi/ESP-NOW. Джойстик требует два устойчивых
аналоговых входа, поэтому:

* VRX/VRY → **D1/D2** (ADC1);
* батарея `VBAT_SENSE` → **D0** (единственный оставшийся надёжный ADC1);
* UART → **D6/D7** (GPIO21/GPIO20 — аппаратный U0TXD/U0RXD, свободны).

На обеих платах UART идёт **крест-накрест**: `TX→RX`, `RX←TX`.

## Питание и прошивка — что надо знать

1. **Кликер**: LiPo → площадки BAT+/BAT− XIAO → встроенный зарядник → шина +3V3.
   VBATSense: делитель R5/R6 = 200к/200к с BAT+ на D0 (схема с wiki Seeed),
   номиналы большие — ток утечки ~9 мкА.
2. **JP1 (0R)** — питание RP2040-Zero кликера от шины +3V3.
   **Перед прошивкой RP2040 через его собственный USB-C выпаять/вскрыть JP1**,
   иначе 3V3 двух плат работают навстречу друг другу.
3. **D9 = GPIO9 = strapping BOOT** — на линии `RTC_DAT` обязана стоять
   подтяжка R4 10к к +3V3 (иначе чип может уйти не в тот режим загрузки).
   GPIO9 же является кнопкой BOOT на самой плате XIAO.
4. Пин 2 модуля KY-023 подписан «+5V», но **питаем его от +3V3** —
   логика ESP32-C3 не 5V-толерантна.
5. DS1302 — **не I2C**: отдельные CLK/DAT/RST (D3/D9/D10), общение
   3-проводным протоколом.
6. Донгл: VBUS (USB-C RP2040) → +5V → 5V XIAO; GND объединены жёстко.

## BOM (основные компоненты)

| Поз. | Элемент | Кол-во (обе платы) | Примечание |
|---|---|---|---|
| U1, U3 | Seeed XIAO ESP32C3 | 2 | ESP-NOW |
| U2, U4 | Waveshare RP2040-Zero | 2 | кликер: сопроцессор; донгл: USB HID |
| J1 | OLED SSD1306 0.96" 128×64, 1×04 | 1 | I2C |
| J2 | Модуль MPU-9250, 1×10 | 1 | I2C |
| J3 | Модуль DS1302, 1×05 | 1 | 3-проводной интерфейс |
| J4 | Джойстик KY-023, 1×05 | 1 | аналог + кнопка |
| J5 | JST-PH 2.0 1×02 (S2B-PH-K-S) | 1 | аккумулятор |
| R1, R2 | 4.7к 0603 | 2 | подтяжки I2C к +3V3 |
| R3, R4 | 10к 0603 | 2 | подтяжки JOY_SW и RTC_DAT |
| R5, R6 | 200к 0603 | 2 | делитель VBAT_SENSE |
| JP1 | 0R 0603 | 1 | питание RP2040 кликера |
| C1, C3 | 100нФ 0603 | 2 | по конденсатору на плату |
| C2, C4 | 10мкФ 0603 | 2 | по конденсатору на плату |

## Формат и библиотеки

* Формат KiCad **8** (`version 20231120` для схем/символов, `20240108` для PCB),
  открывается в KiCad 8, 9 и 10.
* Синтаксис сверялся с демками ветки `8.0` с GitLab-репозитория KiCad
  (`demos/complex_hierarchy`, `demos/ampli_ht`, `demos/complex_hierarchy` PCB).
* Все символы и футпринты — **из проектных библиотек** (`libs/seeed-clicker.*`),
  проект самодостаточен: `fp-lib-table`/`sym-lib-table` указывают на
  `${KIPRJMOD}/libs/…`.

### Геометрия посадочных мест (сверено с первоисточниками)

* **XIAO** — из официальной библиотеки Seeed
  (`New_XIAO_Series_Footprints/XIAO-ESP32-C3-DIP`): THT drill 0.889 мм,
  pad 1.524, **межрядное расстояние 15.24 мм (0.6")**, шаг 2.54,
  площадки VBAT/GND выведены сквозными отверстиями.
  Футпринт VectorSpaceHQ (16.025 мм) отклонён как неверный.
* **RP2040-Zero** — геометрия `dj505/RP2040-Zero-KiCAD` (23 пада: 9+9+5,
  межрядное 15.24), сверена с `CountParadox`.
* `libs/vendor/` содержит скачанные оригиналы (VectorSpaceHQ XIAO,
  dj505 RP2040-Zero) как референс — в таблицы библиотек они не включены.

Лицензии первоисточников — см. репозитории авторов (Seeed Studio XIAO
Series Symbols/Footprints, dj505/RP2040-Zero-KiCAD); они используются
только как геометрическая справка при написании собственных футпринтов.

## Генерация и проверка

```bash
python3 tools/gen.py        # пересобрать весь проект (детерминированно, uuid5)
python3 tools/validate.py   # валидация
```

`gen.py` при генерации сам проверяет: дубли референсов, сети минимум из 2 пинов,
все пины подключены или помечены NC.

`validate.py` дополнительно проверяет:

* баланс скобок и разбор s-выражений всех файлов;
* чтение схем объектной моделью **kicad-skip**;
* геометрию: метки и точки подключения пинов лежат на проводниках,
  нет наложения символов и примечаний;
* библиотеки: каждый `lib_id` и футпринт существует;
* PCB ↔ схема: каждая пара (референс, пин) имеет одну и ту же сеть;
* расстановку: нет наложений корпусов (по F.CrtYd), всё внутри контуров плат.

Последний прогон: **все проверки пройдены** (20 футпринтов, 18 рабочих сетей,
68 подключённых падов, 105 NC).

## Дальний план (следующий этап)

1. Трассировка CLICKER (56×88) и DONGLE (26×54), зоны GND.
2. Проверка DRC/ERC в KiCad (на сервере нет `kicad-cli` — открыть локально).
3. Прошивки: кликер (ESP-NOW + опрос периферии), RP2040 кликера (UART),
   XIAO донгла (ESP-NOW → UART), RP2040 донгла (UART → USB HID).