Andrey
f17c124f0e
Обнови спецификацию GAS 0x3/0x4, реестр устройств и описание загрузочных сервисов одновременно в Markdown, HTML и XLSX. Свяжи новые аппаратные порты, глобальное время и сборку C2000/ПЛИС с корневыми инструкциями, чтобы проекты подключались по одному актуальному контракту.
143 lines
13 KiB
Markdown
143 lines
13 KiB
Markdown
# templates
|
||
|
||
Общий репозиторий переносимых библиотек. Одно место, откуда прошивки и
|
||
инструменты забирают код, который не привязан к плате и повторяется из
|
||
проекта в проект.
|
||
|
||
Правило отбора одно: **ядро не знает о платформе**. Ни HAL, ни ОС, ни
|
||
динамической памяти, ни глобального состояния — всё аппаратное живёт в порте,
|
||
который приносит с собой проект. Библиотеки не зависят друг от друга и
|
||
подключаются поодиночке.
|
||
|
||
```
|
||
templates/
|
||
c/ библиотеки на C99: заголовок, реализация, README, где есть — порт и тесты
|
||
python/ модули на чистом Python 3.9+, только stdlib
|
||
tools/ общие инструменты сборки и выпуска прошивок
|
||
```
|
||
|
||
Пошаговая раскладка нового проекта и выбор портов для STM32F103, STM32G431
|
||
и STM32G474 описаны в [`NEW_PROJECT.md`](NEW_PROJECT.md).
|
||
|
||
Нормативная документация SETCAN/ProtoCAN, реестр общего адресного пространства
|
||
и исходный Excel собраны в [`doc/setcan`](doc/setcan/README.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/led-indicator`](c/led-indicator) | неблокирующие режимы LED: работа, активность, предупреждение и ошибка | C99 | логическая запись канала, время выбранного таймера — **STM32F1/F4/G4 HAL-порт в комплекте** |
|
||
| [`c/eeprom-ft24c256`](c/eeprom-ft24c256) | EEPROM 24Cxx по I²C с нарезкой записи по страницам | `stdint.h` | две I²C-транзакции, задержка |
|
||
| [`c/can-sensor`](c/can-sensor) | однокадровые SETCAN SETTINGS для 64-битных ROM | ядро: `stdint.h`; порт F1: CMSIS | callbacks либо готовый bxCAN STM32F1 |
|
||
| [`c/ds18b20`](c/ds18b20) | термометры DS18B20 поверх программной 1-Wire | `stdint.h` | Init, DelayUs, Reset, WriteBit, ReadBit — **порты STM32F103, STM32G431 и STM32G474 в комплекте** |
|
||
| [`c/ds18b20-ds2480`](c/ds18b20-ds2480) | DS18B20 через DS2480B: поиск ROM, температура, EEPROM, паразитное питание | C99 | UART 9600 8N1, сброс моста, задержка |
|
||
| [`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 и TMS320F2812-порты в комплекте** |
|
||
| [`c/set-protocol/ports/stm32f407-devboard-v1`](c/set-protocol/ports/stm32f407-devboard-v1) | доступ SETGUI к Modbus-регистрам F407 через CAN485 DevBoard_V1 | `pcan_modbus_server`, STM32 HAL CAN | bxCAN FIFO0 и callbacks карты регистров |
|
||
| [`c/set-protocol/ports/stm32-bxcan`](c/set-protocol/ports/stm32-bxcan) | порт прикладного ProtoCAN для STM32, бывший SETCAN; сохранён API `PROTOCAN_*` | STM32 HAL CAN/RTC/TIM + общее ядро `pcan_id` | classic bxCAN; настройки платы предоставляет прошивка |
|
||
| [`c/set-protocol/ports/tms320f2812`](c/set-protocol/ports/tms320f2812) | SETProtocol v2 firmware service по segmented classic CAN | `set_protocol`, `set_can`, `set_firmware` | CAN TX, Flash erase/write/read, optional signature policy и reboot |
|
||
| [`c/protocan-boot`](c/protocan-boot) | адресная прошивка по ProtoCAN: A/B-слоты, сессия, CRC32, verify и rollback-контракт | C99 | **STM32F103C8/F407VE/G474VE и TMS320F2812/F28335-порты в комплекте**; проекты STM32 подключены через templates, есть boot main и вход из приложения |
|
||
| [`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/global-time`](c/global-time) | программные часы 1 мс, ProtoCAN RTCSETUP, готовность платы и атомарная метка логгера | C99 | IRQ lock, CAN TX, такт 1 мс — **порт TMS320F28335 eCAN-A / CPU Timer2 в комплекте** |
|
||
| [`c/firmware-info`](c/firmware-info) | SemVer, build stamp и git build ID работающего образа | C99 | config-порты STM32F1/F4/G4 и К1921ВК028; упаковка для Modbus/SETGUI |
|
||
| [`c/parallel-nand`](c/parallel-nand) | parallel NAND x8: raw read/program/erase, профили Micron MT29F1G08 и Hynix HY27UF084G2M, bad-block marker и банковое окно GAS для SETGUI | C99, опционально `set-protocol/pcan_gas` | **порты TMS320F2812, STM32F103RC/ZE, STM32F407VE и STM32G474CEU6; запись требует управляемого WP#** |
|
||
|
||
### Python
|
||
|
||
Экспериментальный [`c/gas-logger`](c/gas-logger/README.md): непрерывная запись
|
||
в два банка RAM, снимки через GAS/Modbus/ProtoCAN, JSON-карта имён и адресов,
|
||
проектный порт ПМ35 и MCU-порты C28x / STM32. Клиент в `set_devices.gas_logger`.
|
||
|
||
| Модуль | Что делает | Зависимости |
|
||
|---|---|---|
|
||
| [`python/setprotocol/firmware_database.py`](python/setprotocol/firmware_database.py) | база прошивок: HTTPS-каталог, скачивание с SHA-256 и кэшем, публикация в Gitea без SETGUI; [подключение и CLI](tools/firmware-publish/DATABASE.md) | stdlib, Python 3.10+ |
|
||
| [`python/setprotocol/firmware_publish.py`](python/setprotocol/firmware_publish.py) | общие метаданные публикации, SHA-256, release tag и обновление каталога прошивок; [подключение](tools/firmware-publish/PORTING.md) | stdlib; сетевой адаптер в SETGUI |
|
||
| [`python/setprotocol/firmware_catalog.py`](python/setprotocol/firmware_catalog.py) | модель и parser каталога `firmware.releases` | stdlib |
|
||
| [`python/protocan`](python/protocan) | разбор ProtoCAN, транспортный кадр моста, кадр SETGUI, кодеки каталога | stdlib, Python 3.9+ |
|
||
| [`python/protocan/trends.py`](python/protocan/trends.py) | общие настройки графиков, ограниченная история, ctypes-декодер GAS/raw CAN | stdlib, опционально SETProtocol DLL/SO |
|
||
|
||
### Инструменты
|
||
|
||
| Инструмент | Что делает |
|
||
|---|---|
|
||
| [`tools/firmware-build/fpga`](tools/firmware-build/fpga/README.md) | общий итератор версии и HDL-паспорт для Xilinx ISE, Vivado и Altera/Intel Quartus; контроль `.bit`/`.sof`, manifest, SHA-256 и архив |
|
||
| [`tools/firmware-publish`](tools/firmware-publish) | единый BAT и конфигурации для проверки и публикации `.hex` Keil / `.bin` CCS 12 в каталоге SETGUI |
|
||
|
||
Общие тренды для Android GUI и SETGUI: [формат JSON, C99-ядро и адаптеры](c/set-protocol/docs/GUI_TRENDS.md).
|
||
Общие масштабирование и маркеры: [C99, JNI и Python/Qt](c/set-protocol/docs/GUI_PLOT.md).
|
||
|
||
Кодировщики `c/set-protocol` и `python/protocan` дают побайтово
|
||
одинаковый результат — это зафиксировано эталонами в тестах на C.
|
||
|
||
Интерактивная документация общего ядра: [`doc/setprotocol.html`](doc/setprotocol.html).
|
||
В ней отдельно описаны граница ядра, ABI, память, три wire format и состояние
|
||
портов Windows, Android, Linux и MCU.
|
||
|
||
Обзор всего репозитория, включая слияние при подключении через submodule:
|
||
[`doc/index.html`](doc/index.html). Справочник Doxygen собирается командой
|
||
`powershell -ExecutionPolicy Bypass -File doc/build-doxygen.ps1` в
|
||
`.codex-build/doxygen/html/index.html`.
|
||
|
||
## Как подключить к проекту
|
||
|
||
**Сабмодуль** — когда нужна одна конкретная версия и обновление по команде:
|
||
|
||
```
|
||
git submodule add https://git.rd12.ru/Andrey/templates.git lib/templates
|
||
git submodule update --init --recursive
|
||
```
|
||
|
||
Как обновлять зафиксированную ревизию, переносить изменения из проекта и
|
||
разрешать конфликт gitlink при слиянии веток, подробно описано в разделе
|
||
[`Слияние и обновление templates как Git submodule`](NEW_PROJECT.md#слияние-и-обновление-templates-как-git-submodule).
|
||
|
||
Дальше в сборку добавляются только нужные каталоги:
|
||
|
||
```
|
||
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 |
|
||
| `CANdle_stm32` (candleLight) | G431/G474 FDCAN board-support; CAN/UART-загрузчик G474 и вход из приложения подключены к `protocan-boot/ports/stm32g474` через templates |
|
||
| `SETGUI` | python/protocan |
|
||
| `SETGUI`, Android GUI и новые устройства SET | set-protocol |
|
||
| `k1921vk028` | rtc-service |
|
||
|
||
## Что сюда не попало и почему
|
||
|
||
| Код | Почему не переносится | Что можно вытащить |
|
||
|---|---|---|
|
||
| `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) — что считается переносимой библиотекой,
|
||
как оформлять порт, как называть коммиты.
|