106 lines
7.8 KiB
Markdown
106 lines
7.8 KiB
Markdown
# templates
|
||
|
||
Общий репозиторий переносимых библиотек. Одно место, откуда прошивки и
|
||
инструменты забирают код, который не привязан к плате и повторяется из
|
||
проекта в проект.
|
||
|
||
Правило отбора одно: **ядро не знает о платформе**. Ни HAL, ни ОС, ни
|
||
динамической памяти, ни глобального состояния — всё аппаратное живёт в порте,
|
||
который приносит с собой проект. Библиотеки не зависят друг от друга и
|
||
подключаются поодиночке.
|
||
|
||
```
|
||
templates/
|
||
c/ библиотеки на C99: заголовок, реализация, README, где есть — порт и тесты
|
||
python/ модули на чистом Python 3.9+, только stdlib
|
||
```
|
||
|
||
Пошаговая раскладка нового проекта и выбор портов для STM32F103, STM32G431
|
||
и STM32G474 описаны в [`NEW_PROJECT.md`](NEW_PROJECT.md).
|
||
|
||
## Что лежит
|
||
|
||
### 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 — **порты STM32F103, STM32G431 и STM32G474 в комплекте** |
|
||
| [`c/set-protocol`](c/set-protocol) | единое ядро SETProtocol: SET v2, совместимые ProtoCAN/GUI v1, GAS, телеметрия, firmware flow и стабильный host ABI | C99 | COM/SLCAN/SocketCAN/USB/Ethernet или callbacks — **Windows, Android и STM32F4-порты в комплекте** |
|
||
| [`c/protocan-boot`](c/protocan-boot) | адресная прошивка по ProtoCAN: A/B-слоты, сессия, CRC32, verify и rollback-контракт | C99 | CAN TX, erase/write Flash, boot metadata, проверка образа и reboot |
|
||
| [`c/rs485-boot`](c/rs485-boot) | прошивка по RS-485 в формате SETGUI v1: потоковый parser, CRC32 и resume | C99 | UART TX/RX, DE, Flash — **порты STM32F103 и STM32G474VET в комплекте** |
|
||
| [`c/rtc-service`](c/rtc-service) | RTC с резервированным backup-томом | `stdint.h` | доступ к RTC и backup-памяти — **порт K1921VK028 в комплекте** |
|
||
| [`c/firmware-info`](c/firmware-info) | SemVer, build stamp и git build ID работающего образа | C99 | config-порты STM32F1/F4/G4 и К1921ВК028; упаковка для Modbus/SETGUI |
|
||
|
||
### Python
|
||
|
||
| Модуль | Что делает | Зависимости |
|
||
|---|---|---|
|
||
| [`python/protocan`](python/protocan) | разбор ProtoCAN, транспортный кадр моста, кадр SETGUI, кодеки каталога | stdlib, Python 3.9+ |
|
||
|
||
Кодировщики `c/set-protocol` и `python/protocan` дают побайтово
|
||
одинаковый результат — это зафиксировано эталонами в тестах на C.
|
||
|
||
Интерактивная документация общего ядра: [`doc/setprotocol.html`](doc/setprotocol.html).
|
||
В ней отдельно описаны граница ядра, ABI, память, три wire format и состояние
|
||
портов Windows, Android, Linux и MCU.
|
||
|
||
## Как подключить к проекту
|
||
|
||
**Сабмодуль** — когда нужна одна конкретная версия и обновление по команде:
|
||
|
||
```
|
||
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, firmware-info |
|
||
| `OpticalTester` | st7789, keypad, menu, eeprom-ft24c256 |
|
||
| `CAN_to_RS485` | set-protocol legacy transport, python/protocan |
|
||
| `candleLight_fw` | эталон разделения общей логики и G431/G474 FDCAN-порта; общий ProtoCAN Boot переносится по контракту `protocan-boot` |
|
||
| `SETGUI` | python/protocan |
|
||
| `SETGUI`, Android GUI и новые устройства SET | set-protocol |
|
||
| `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) — что считается переносимой библиотекой,
|
||
как оформлять порт, как называть коммиты.
|