templates/NEW_PROJECT.md

Новый проект на переносимых библиотеках

Этот репозиторий содержит два разных типа кода:

1. c/<library>/include и c/<library>/src — переносимое ядро;
2. c/<library>/ports/<family> — небольшой аппаратный порт конкретного семейства микроконтроллеров.

Привязка выводов, частоты шин и выбранной периферии принадлежит плате и всегда остаётся в проекте в app_config.h либо в узком конфигурационном заголовке библиотеки, например onewire_config.h.

Рекомендуемая структура прошивки

my-device/
  app/                    логика изделия
    include/
    src/
  board/                  одна конкретная плата
    app_config.h          выводы, частоты, адреса, возможности платы
  port/                   связь библиотек с SDK выбранного МК
    display_port.c
    keypad_port.c
    eeprom_port.c
    can_port.c
  vendor/                 CMSIS, startup, linker script или Cube-generated код
  lib/templates/          git submodule этого репозитория

Не следует помещать stm32xxxx.h, HAL_*, регистры, IRQ handlers и номера выводов в app/ или в ядро библиотеки. Тогда при переходе на другой МК заменяются только board/, port/, startup и linker script.

Выбор готового порта DS18B20

Целевой МК	Файл порта	Шаблон конфигурации
STM32F103	c/ds18b20/ports/stm32f1/onewire_stm32f1.c	onewire_config.f103.template.h
STM32G431	c/ds18b20/ports/stm32g4/onewire_stm32g4.c	onewire_config.g431.template.h
STM32G474	c/ds18b20/ports/stm32g4/onewire_stm32g4.c	onewire_config.g474.template.h

В сборку добавляются ровно три файла:

c/ds18b20/src/onewire.c
c/ds18b20/src/ds18b20.c
c/ds18b20/ports/<family>/onewire_<family>.c

Пути включения:

c/ds18b20/include
board

Нужный шаблон копируется в board/onewire_config.h; после этого в нём меняются только порт, номер вывода и бит тактирования GPIO.

G431 и G474 намеренно используют один исходник порта: GPIO, RCC и DWT для этой задачи совместимы. Раздельными остаются конфигурация платы, startup, linker script и выбранный CMSIS device define.

Выбор готового порта parallel NAND

Целевой МК	Реализация шины	Каталог порта
TMS320F2812	XINTF Zone 6	c/parallel-nand/ports/tms320f2812
STM32F103RCT6	GPIO bit-bang, поскольку FSMC недоступен в LQFP64	c/parallel-nand/ports/stm32f103rc
STM32F103ZET6	FSMC NAND Bank 3	c/parallel-nand/ports/stm32f103ze
STM32F407VET6	FSMC NAND Bank 2	c/parallel-nand/ports/stm32f407ve
STM32G474CEU6	GPIO bit-bang для UFQFPN48	c/parallel-nand/ports/stm32g474ce

Ядро поддерживает профили Micron MT29F1G08ABADA и Hynix HY27UF084G2M. В сборку добавляются src/parallel_nand.c, при необходимости src/parallel_nand_gas.c или src/parallel_nand_pcan_gas.c, и ровно один аппаратный порт. Конкретная распиновка, требуемые модули HAL и пример инициализации приведены в README выбранного порта.

Для PROGRAM/ERASE линия WP# должна управляться портом. Готовые порты STM32F103RC, STM32F103ZE и STM32G474CE объявляют поддержку записи. Базовые схемы TMS320F2812 и STM32F407VE фиксируют WP# аппаратно и безопасно возвращают PNAND_ERROR_WRITE_PROTECTED, пока плата и порт не доработаны.

Рабочий пример полноценного G474-порта находится в соседнем проекте candleLight_fw: src/device/device_g4.c отвечает за clock/GPIO, src/can/m_can.c — за FDCAN, а include/config.h — за привязку платы STM32G474VET6. Эти файлы остаются в прошивке, поскольку зависят от STM32 HAL, USB gs_usb и конкретной разводки адаптера; переносимая логика протоколов остаётся в templates.

Какие части KONOR уже общие

Возможность	Переносимое ядро	Что остаётся в port/ проекта
DS18B20/1-Wire	c/ds18b20	готовый порт выбранного семейства и вывод
дисплей ST7789	c/st7789	SPI, DC, CS, RESET, подсветка и задержка
кнопки	c/keypad	настройка GPIO и чтение уровней
меню	c/menu	только привязка painter к дисплею
индикация состояний	c/led-indicator	готовый STM32 HAL-порт или callbacks GPIO и выбранного таймера
EEPROM FT24C256	c/eeprom-ft24c256	I2C write/write-read и задержка
CAN SETTINGS	c/can-sensor	bxCAN для F103 либо FDCAN для G431/G474

Порт дисплея, EEPROM и CAN нельзя честно сделать только по названию МК: нужно знать экземпляр периферии, альтернативную функцию и выводы конкретной платы. Поэтому библиотеки принимают таблицы обратных вызовов, а короткие адаптеры лежат в проекте рядом с app_config.h.

Порядок создания проекта

1. Создать проект в CubeMX/Keil либо добавить CMSIS, startup и linker script.
2. Подключить templates сабмодулем.
3. Добавить только ядра нужных библиотек.
4. Выбрать готовый 1-Wire порт по таблице выше.
5. Создать board/app_config.h с выводами и частотами.
6. Реализовать короткие адаптеры SPI/GPIO/I2C/CAN в port/.
7. Сначала прогнать host-тесты библиотек, затем проверить аппаратные порты логическим анализатором или осциллографом.

Так новый проект не является копией старого: он использует общие ядра одной версии, а аппаратные отличия видны в одном небольшом каталоге port/.