# templates

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

Правило отбора одно: **ядро не знает о платформе**. Ни HAL, ни ОС, ни
динамической памяти, ни глобального состояния — всё аппаратное живёт в порте,
который приносит с собой проект. Библиотеки не зависят друг от друга и
подключаются поодиночке.

```
templates/
  c/        библиотеки на C99: заголовок, реализация, README, где есть — порт и тесты
  python/   модули на чистом Python 3.9+, только stdlib
```

## Что лежит

### C

| Библиотека | Что делает | Зависимости | Что нужно от платформы |
|---|---|---|---|
| [`c/st7789`](c/st7789) | TFT ST7789V по SPI, RGB565, текст без кадрового буфера | `stdint.h` | SPI-запись, линия DC, задержка |
| [`c/keypad`](c/keypad) | шесть кнопок: антидребезг, автоповтор, удержание, очередь событий | `stdint.h` | чтение уровня кнопки, время в мс |
| [`c/menu`](c/menu) | экранное меню: стек экранов, курсор, прокрутка, тема | `stdint.h` | заливка прямоугольника, вывод строки |
| [`c/eeprom-ft24c256`](c/eeprom-ft24c256) | EEPROM 24Cxx по I²C с нарезкой записи по страницам | `stdint.h` | две I²C-транзакции, задержка |
| [`c/can-sensor`](c/can-sensor) | передача 64-битных ROM датчиков парой CAN-кадров | `stdint.h` | отправка и приём CAN-кадра |
| [`c/ds18b20`](c/ds18b20) | термометры DS18B20 поверх программной 1-Wire | `stdint.h` | Init, DelayUs, Reset, WriteBit, ReadBit — **порт STM32F1 в комплекте** |
| [`c/protocan-transport`](c/protocan-transport) | транспорт ProtoCAN: кадр, канал, CRC, общее адресное пространство, каталог GUI | `stdint.h` | запись в поток и запрос свободного места — **порт STM32F4 в комплекте** |
| [`c/rtc-service`](c/rtc-service) | RTC с резервированным backup-томом | `stdint.h` | доступ к RTC и backup-памяти — **порт K1921VK028 в комплекте** |

### Python

| Модуль | Что делает | Зависимости |
|---|---|---|
| [`python/protocan`](python/protocan) | разбор ProtoCAN, транспортный кадр моста, кадр SETGUI, кодеки каталога | stdlib, Python 3.9+ |

Кодировщики `c/protocan-transport` и `python/protocan` дают побайтово
одинаковый результат — это зафиксировано эталонами в тестах на C.

## Как подключить к проекту

**Сабмодуль** — когда нужна одна конкретная версия и обновление по команде:

```
git submodule add https://git.rd12.ru/Andrey/templates.git lib/templates
git submodule update --init --recursive
```

Дальше в сборку добавляются только нужные каталоги:

```
lib/templates/c/st7789/st7789.c
lib/templates/c/menu/menu.c
```

**Subtree** — когда правки чаще идут из проекта в библиотеку:

```
git subtree add  --prefix lib/templates https://git.rd12.ru/Andrey/templates.git master --squash
git subtree pull --prefix lib/templates https://git.rd12.ru/Andrey/templates.git master --squash
```

Копировать файлы руками не нужно: копия расходится с оригиналом за пару
недель, и потом непонятно, какая версия правильная.

## Где эти библиотеки уже работают

| Проект | Что берёт |
|---|---|
| `KONOR_ds18b20` | st7789, keypad, menu, eeprom-ft24c256, can-sensor, ds18b20 |
| `OpticalTester` | st7789, keypad, menu, eeprom-ft24c256 |
| `CAN_to_RS485` | protocan-transport, python/protocan |
| `SETGUI` | python/protocan |
| `k1921vk028` | rtc-service |

## Что сюда не попало и почему

| Код | Почему не переносится | Что можно вытащить |
|---|---|---|
| `SETCAN/Src/protocan.c` | 59 вызовов `HAL_*`, привязка к `CAN_HandleTypeDef`, `RTC_HandleTypeDef`, `NVIC_SystemReset()` | разбиение длинных посылок на кадры и проверка даты — чистая логика, нужны два интерфейса: «отправить кадр» и «часы». Раскладка идентификатора уже вынесена в `pcan_id` |
| `1921vk028/drivers/user/src/one_wire_user.c` | аппаратный 1-Wire `OWI_*` из `plib028`, мигание светодиодом прямо внутри опроса датчика | логика DS18B20 уже есть в `c/ds18b20` — переносится порт, а не алгоритм |
| `1921vk028/drivers/GPIO`, `uart`, `optical`, `Interrupt` | целиком на регистрах `plib028` | переносить стоит не код, а приём: таблица описаний портов вместо `#define`, разбросанных по файлу |
| `Drivers/` внутри прошивок | вендорный HAL и CMSIS | ничего, приходит со своим SDK |

Строчку в этой таблице стоит завести, когда очередной драйвер решили не
переносить: следующий человек не будет разбираться заново.

## Правила

[CONTRIBUTING.md](CONTRIBUTING.md) — что считается переносимой библиотекой,
как оформлять порт, как называть коммиты.