docs: индекс библиотек и порядок подключения к проектам
Таблицы: что делает каждая библиотека, какие у неё зависимости и что требуется от платформы; где она уже работает; как подключать репозиторий сабмодулем или subtree. Отдельным разделом — что сюда не попало и почему: SETCAN/Src/protocan.c (59 вызовов HAL), драйверы 1921vk028 на plib028, вендорные Drivers. Там же сказано, что из них имеет смысл вытаскивать, чтобы следующий разбор не начинался с нуля.
This commit is contained in:
93
README.md
Normal file
93
README.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# 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) — что считается переносимой библиотекой,
|
||||
как оформлять порт, как называть коммиты.
|
||||
Reference in New Issue
Block a user