Andrey/templates
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/master' into codex/setprotocol-v2-all

Browse Source
This commit is contained in:
Andrey
2026-09-01 20:31:23 +03:00
parent 076c51c083 2fd51a1d7e
commit 15d9613472
20 changed files with 28932 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
README.md
View File

@@ -18,6 +18,9 @@ templates/
Пошаговая раскладка нового проекта и выбор портов для STM32F103, STM32G431
и STM32G474 описаны в [`NEW_PROJECT.md`](NEW_PROJECT.md).
Нормативная документация SETCAN/ProtoCAN, реестр общего адресного пространства
и исходный Excel собраны в [`doc/setcan`](doc/setcan/README.md).
## Что лежит
### C
@@ -28,7 +31,7 @@ templates/
| [`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/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/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 |

25
c/can-sensor/README.md
View File

@@ -20,6 +20,7 @@
| Файл | Что делает | Зависимости |
|---|---|---|
| `can_sensor.h`, `can_sensor.c` | сборка и разбор SETTINGS, повторы передачи, счётчики обмена | `stdint.h` |
| `ports/stm32f1/` | опросный порт CAN1: GPIO, BTR, фильтр, mailbox/FIFO, тайм-аут ACK | CMSIS `stm32f10x.h` |
`ZZ` — номер сборки, `YY` — позиция. Нулевой ROM с DLC=8 очищает локацию.
@@ -47,6 +48,30 @@ CanSensor_Message message;
if (CanSensor_Poll(&link, &message)) { /* принят идентификатор */ }
```
## Порт STM32F1
Порт не использует STM32 HAL и не занимает прерывания. Скопируйте
`ports/stm32f1/can_sensor_stm32f1_config.f103.template.h` в приложение под
именем `can_sensor_stm32f1_config.h`, добавьте `ports/stm32f1` в include path и
соберите `can_sensor_stm32f1.c` вместе с ядром:
```c
CanSensorStm32F1_Port bxcan = {0};
CanSensor_Io io;
CanSensorStm32F1_Start(&bxcan, 500000U, 0x17F00000UL, 0x1FF00000UL, 0U);
io = CanSensorStm32F1_MakeIo(&bxcan);
CanSensor_Init(&link, &io, &config);
/* Из главного цикла: */
CanSensorStm32F1_Task(&bxcan, now_ms, 20U);
```
Фильтр порта принимает только Extended data-кадры. Маска задаётся приложением:
можно пропустить только SETTINGS либо оставить открытым `MsgType` для соседних
команд того же узла. `CanSensorStm32F1_Receive()` доступна отдельно, если перед
`CanSensor_HandleFrame()` приложению нужно разобрать такие команды самому.
## Проверено в проектах
`KONOR_ds18b20` — bxCAN на STM32F103C8T6. Естественная пара — [`ds18b20`](../ds18b20):

330
c/can-sensor/ports/stm32f1/can_sensor_stm32f1.c Normal file
View File

@@ -0,0 +1,330 @@
/**
* @file can_sensor_stm32f1.c
* @brief Опросный порт can-sensor на bxCAN STM32F1 без STM32 HAL.
*/
#include "can_sensor_stm32f1.h"
#include "can_sensor_stm32f1_config.h"
#if !defined(CAN_SENSOR_STM32F1_GPIO) \
|| !defined(CAN_SENSOR_STM32F1_GPIO_CLOCK) \
|| !defined(CAN_SENSOR_STM32F1_RX_PIN) \
|| !defined(CAN_SENSOR_STM32F1_TX_PIN)
#error "can_sensor_stm32f1_config.h должен задать GPIO, GPIO_CLOCK, RX_PIN и TX_PIN"
#endif
#define CAN_STM32F1_TQ_MAX 18U
#define CAN_STM32F1_TQ_MIN 8U
#define CAN_STM32F1_TIMEOUT_CYCLES 1000000U
#define CAN_STM32F1_TSR_ALL_EMPTY (CAN_TSR_TME0 | CAN_TSR_TME1 | CAN_TSR_TME2)
#define CAN_STM32F1_TSR_ALL_ABORT (CAN_TSR_ABRQ0 | CAN_TSR_ABRQ1 | CAN_TSR_ABRQ2)
#define CAN_STM32F1_TSR_ANY_TXOK (CAN_TSR_TXOK0 | CAN_TSR_TXOK1 | CAN_TSR_TXOK2)
#define CAN_STM32F1_TSR_DONE_FLAGS \
(CAN_TSR_RQCP0 | CAN_TSR_TXOK0 | CAN_TSR_ALST0 | CAN_TSR_TERR0 \
| CAN_TSR_RQCP1 | CAN_TSR_TXOK1 | CAN_TSR_ALST1 | CAN_TSR_TERR1 \
| CAN_TSR_RQCP2 | CAN_TSR_TXOK2 | CAN_TSR_ALST2 | CAN_TSR_TERR2)
static uint32_t can_stm32f1_pclk1(void)
{
static const uint8_t shift[8] = { 0U, 0U, 0U, 0U, 1U, 2U, 3U, 4U };
const uint32_t bits = (RCC->CFGR & RCC_CFGR_PPRE1) >> 8U;
return SystemCoreClock >> shift[bits & 0x7U];
}
static void can_stm32f1_configure_pin(GPIO_TypeDef *gpio, uint8_t pin,
uint32_t mode)
{
uint32_t config;
uint32_t shift;
if (pin < 8U) {
shift = (uint32_t)pin * 4U;
config = gpio->CRL;
config = (config & ~(0xFUL << shift)) | (mode << shift);
gpio->CRL = config;
} else {
shift = ((uint32_t)pin - 8U) * 4U;
config = gpio->CRH;
config = (config & ~(0xFUL << shift)) | (mode << shift);
gpio->CRH = config;
}
}
static void can_stm32f1_configure_pins(void)
{
RCC->APB2ENR |= CAN_SENSOR_STM32F1_GPIO_CLOCK | RCC_APB2ENR_AFIOEN;
/* RX: input pull-up; TX: alternate function push-pull, 50 MHz. */
can_stm32f1_configure_pin(CAN_SENSOR_STM32F1_GPIO,
CAN_SENSOR_STM32F1_RX_PIN, 0x8UL);
can_stm32f1_configure_pin(CAN_SENSOR_STM32F1_GPIO,
CAN_SENSOR_STM32F1_TX_PIN, 0xBUL);
CAN_SENSOR_STM32F1_GPIO->BSRR =
(uint32_t)(1UL << CAN_SENSOR_STM32F1_RX_PIN);
}
static uint8_t can_stm32f1_calc_timing(uint32_t bitrate, uint32_t *btr,
CanSensorStm32F1_Timing *timing)
{
const uint32_t pclk = can_stm32f1_pclk1();
uint32_t total;
uint32_t tq;
if ((bitrate == 0U) || (btr == 0) || (pclk == 0U)
|| ((pclk % bitrate) != 0U)) {
return 0U;
}
total = pclk / bitrate;
for (tq = CAN_STM32F1_TQ_MAX; tq >= CAN_STM32F1_TQ_MIN; tq--) {
const uint32_t prescaler = total / tq;
if (((total % tq) == 0U) && (prescaler >= 1U)
&& (prescaler <= 1024U)) {
const uint32_t ts2 = tq / 5U;
const uint32_t ts1 = tq - 1U - ts2;
*btr = ((ts2 - 1U) << 20U) | ((ts1 - 1U) << 16U)
| (prescaler - 1U);
if (timing != 0) {
timing->pclk_hz = pclk;
timing->prescaler = (uint16_t)prescaler;
timing->ts1 = (uint8_t)ts1;
timing->ts2 = (uint8_t)ts2;
timing->bitrate = pclk / (prescaler * tq);
timing->sample_point =
(uint8_t)(((1U + ts1) * 100U) / tq);
}
return 1U;
}
}
return 0U;
}
uint8_t CanSensorStm32F1_CalcTiming(uint32_t bitrate,
CanSensorStm32F1_Timing *timing)
{
uint32_t btr;
return can_stm32f1_calc_timing(bitrate, &btr, timing);
}
static void can_stm32f1_configure_filter(uint32_t id, uint32_t mask)
{
const uint32_t filter_id = ((id & mask) << 3U) | CAN_RI0R_IDE;
const uint32_t filter_mask =
(mask << 3U) | CAN_RI0R_IDE | CAN_RI0R_RTR;
CAN1->FMR |= CAN_FMR_FINIT;
CAN1->FA1R &= ~1UL;
CAN1->FS1R |= 1UL;
CAN1->FM1R &= ~1UL;
CAN1->sFilterRegister[0].FR1 = filter_id;
CAN1->sFilterRegister[0].FR2 = filter_mask;
CAN1->FFA1R &= ~1UL;
CAN1->FA1R |= 1UL;
CAN1->FMR &= ~CAN_FMR_FINIT;
}
static void can_stm32f1_load_mailbox(uint32_t mailbox,
const CanSensor_Frame *frame)
{
uint32_t identifier;
uint8_t index;
if (frame->extended != 0U) {
identifier = ((frame->id & 0x1FFFFFFFUL) << 3U) | CAN_TI0R_IDE;
} else {
identifier = (frame->id & 0x7FFUL) << 21U;
}
CAN1->sTxMailBox[mailbox].TDTR = (uint32_t)(frame->length & 0x0FU);
CAN1->sTxMailBox[mailbox].TDLR = 0U;
CAN1->sTxMailBox[mailbox].TDHR = 0U;
for (index = 0U; index < frame->length; index++) {
if (index < 4U) {
CAN1->sTxMailBox[mailbox].TDLR |=
(uint32_t)frame->data[index] << (index * 8U);
} else {
CAN1->sTxMailBox[mailbox].TDHR |=
(uint32_t)frame->data[index] << ((index - 4U) * 8U);
}
}
CAN1->sTxMailBox[mailbox].TIR = identifier | CAN_TI0R_TXRQ;
}
uint8_t CanSensorStm32F1_Start(CanSensorStm32F1_Port *port,
uint32_t bitrate, uint32_t filter_id,
uint32_t filter_mask, uint8_t loopback)
{
uint32_t btr;
uint32_t guard;
uint32_t mode_bits;
if ((port == 0) || (filter_id > 0x1FFFFFFFUL)
|| (filter_mask > 0x1FFFFFFFUL)
|| (can_stm32f1_calc_timing(bitrate, &btr, &port->timing) == 0U)) {
return 0U;
}
CanSensorStm32F1_Stop(port);
can_stm32f1_configure_pins();
RCC->APB1ENR |= RCC_APB1ENR_CAN1EN;
CAN1->MCR &= ~CAN_MCR_SLEEP;
CAN1->MCR |= CAN_MCR_INRQ;
for (guard = 0U; guard < CAN_STM32F1_TIMEOUT_CYCLES; guard++) {
if ((CAN1->MSR & CAN_MSR_INAK) != 0U) {
break;
}
}
if ((CAN1->MSR & CAN_MSR_INAK) == 0U) {
return 0U;
}
mode_bits = (loopback != 0U) ? (CAN_BTR_LBKM | CAN_BTR_SILM) : 0U;
CAN1->MCR = CAN_MCR_INRQ | CAN_MCR_ABOM | CAN_MCR_TXFP;
CAN1->BTR = btr | mode_bits;
can_stm32f1_configure_filter(filter_id, filter_mask);
CAN1->MCR &= ~CAN_MCR_INRQ;
for (guard = 0U; guard < CAN_STM32F1_TIMEOUT_CYCLES; guard++) {
if ((CAN1->MSR & CAN_MSR_INAK) == 0U) {
break;
}
}
if ((CAN1->MSR & CAN_MSR_INAK) != 0U) {
return 0U;
}
port->bitrate = bitrate;
port->loopback = (uint8_t)(loopback != 0U);
port->no_transceiver = 0U;
port->tx_waiting = 0U;
port->ready = 1U;
return 1U;
}
void CanSensorStm32F1_Stop(CanSensorStm32F1_Port *port)
{
if (port == 0) {
return;
}
RCC->APB1ENR |= RCC_APB1ENR_CAN1EN;
RCC->APB1RSTR |= RCC_APB1RSTR_CAN1RST;
RCC->APB1RSTR &= ~RCC_APB1RSTR_CAN1RST;
port->ready = 0U;
port->bitrate = 0U;
port->loopback = 0U;
port->no_transceiver = 0U;
port->tx_waiting = 0U;
}
uint8_t CanSensorStm32F1_Send(void *context, const CanSensor_Frame *frame)
{
CanSensorStm32F1_Port *port = (CanSensorStm32F1_Port *)context;
uint32_t mailbox;
if ((port == 0) || (frame == 0) || (port->ready == 0U)
|| (frame->length > CAN_SENSOR_MAX_DATA)) {
return 0U;
}
if ((CAN1->TSR & CAN_TSR_TME0) != 0U) {
mailbox = 0U;
} else if ((CAN1->TSR & CAN_TSR_TME1) != 0U) {
mailbox = 1U;
} else if ((CAN1->TSR & CAN_TSR_TME2) != 0U) {
mailbox = 2U;
} else {
return 0U;
}
can_stm32f1_load_mailbox(mailbox, frame);
return 1U;
}
uint8_t CanSensorStm32F1_Receive(void *context, CanSensor_Frame *frame)
{
CanSensorStm32F1_Port *port = (CanSensorStm32F1_Port *)context;
uint32_t identifier;
uint32_t low;
uint32_t high;
uint8_t index;
if ((port == 0) || (frame == 0) || (port->ready == 0U)
|| ((CAN1->RF0R & CAN_RF0R_FMP0) == 0U)) {
return 0U;
}
identifier = CAN1->sFIFOMailBox[0].RIR;
if ((identifier & CAN_RI0R_IDE) != 0U) {
frame->extended = 1U;
frame->id = (identifier >> 3U) & 0x1FFFFFFFUL;
} else {
frame->extended = 0U;
frame->id = (identifier >> 21U) & 0x7FFUL;
}
frame->length = (uint8_t)(CAN1->sFIFOMailBox[0].RDTR & 0x0FU);
if (frame->length > CAN_SENSOR_MAX_DATA) {
frame->length = CAN_SENSOR_MAX_DATA;
}
low = CAN1->sFIFOMailBox[0].RDLR;
high = CAN1->sFIFOMailBox[0].RDHR;
for (index = 0U; index < CAN_SENSOR_MAX_DATA; index++) {
if (index < 4U) {
frame->data[index] =
(uint8_t)((low >> (index * 8U)) & 0xFFU);
} else {
frame->data[index] =
(uint8_t)((high >> ((index - 4U) * 8U)) & 0xFFU);
}
}
CAN1->RF0R |= CAN_RF0R_RFOM0;
return 1U;
}
CanSensor_Io CanSensorStm32F1_MakeIo(CanSensorStm32F1_Port *port)
{
CanSensor_Io io;
io.send = CanSensorStm32F1_Send;
io.receive = CanSensorStm32F1_Receive;
io.context = port;
return io;
}
void CanSensorStm32F1_Task(CanSensorStm32F1_Port *port, uint32_t now_ms,
uint32_t timeout_ms)
{
uint32_t status;
if ((port == 0) || (port->ready == 0U)) {
return;
}
status = CAN1->TSR;
if ((status & CAN_STM32F1_TSR_ALL_EMPTY) == CAN_STM32F1_TSR_ALL_EMPTY) {
if ((status & CAN_STM32F1_TSR_ANY_TXOK) != 0U) {
port->no_transceiver = 0U;
}
CAN1->TSR = status & CAN_STM32F1_TSR_DONE_FLAGS;
port->tx_waiting = 0U;
return;
}
if ((timeout_ms == 0U) || (port->tx_waiting == 0U)) {
port->tx_waiting = (uint8_t)(timeout_ms != 0U);
port->tx_started_ms = now_ms;
return;
}
if ((now_ms - port->tx_started_ms) < timeout_ms) {
return;
}
CAN1->TSR = CAN_STM32F1_TSR_ALL_ABORT;
CAN1->TSR = CAN_STM32F1_TSR_DONE_FLAGS;
port->tx_waiting = 0U;
port->tx_timeouts++;
port->no_transceiver = 1U;
}
uint8_t CanSensorStm32F1_BusError(const CanSensorStm32F1_Port *port)
{
if ((port == 0) || (port->ready == 0U)) {
return 0U;
}
return (uint8_t)(((CAN1->ESR & (CAN_ESR_BOFF | CAN_ESR_EPVF)) != 0U)
? 1U : 0U);
}

77
c/can-sensor/ports/stm32f1/can_sensor_stm32f1.h Normal file
View File

@@ -0,0 +1,77 @@
/**
* @file can_sensor_stm32f1.h
* @brief Опросный порт can-sensor на bxCAN микроконтроллеров STM32F1.
*/
#ifndef CAN_SENSOR_STM32F1_H
#define CAN_SENSOR_STM32F1_H
#include <stdint.h>
#include "can_sensor.h"
/** Разрядность бита, записанная портом в регистр BTR. */
typedef struct {
uint32_t pclk_hz;
uint32_t bitrate;
uint16_t prescaler;
uint8_t ts1;
uint8_t ts2;
uint8_t sample_point;
} CanSensorStm32F1_Timing;
/** Состояние одного контроллера bxCAN. Поля доступны только для диагностики. */
typedef struct {
uint32_t bitrate;
uint32_t tx_timeouts;
uint32_t tx_started_ms;
CanSensorStm32F1_Timing timing;
uint8_t ready;
uint8_t loopback;
uint8_t no_transceiver;
uint8_t tx_waiting;
} CanSensorStm32F1_Port;
/**
* @brief Проверяет достижимость скорости и рассчитывает поля BTR.
* @param bitrate Требуемая скорость, бит/с.
* @param timing Приёмник результата либо 0.
* @return 1, если скорость получается из текущей частоты APB1 без ошибки.
*/
uint8_t CanSensorStm32F1_CalcTiming(uint32_t bitrate,
CanSensorStm32F1_Timing *timing);
/**
* @brief Запускает CAN1, настраивает выводы и один 32-битный фильтр FIFO 0.
*
* Фильтр сравнивает Extended ID по формуле `(id & filter_mask) ==
* (filter_id & filter_mask)` и отбрасывает Standard и Remote кадры.
*/
uint8_t CanSensorStm32F1_Start(CanSensorStm32F1_Port *port,
uint32_t bitrate, uint32_t filter_id,
uint32_t filter_mask, uint8_t loopback);
/** Останавливает CAN1 программным сбросом. */
void CanSensorStm32F1_Stop(CanSensorStm32F1_Port *port);
/** Помещает data-кадр в свободный mailbox. Совместима с CanSensor_Io.send. */
uint8_t CanSensorStm32F1_Send(void *context, const CanSensor_Frame *frame);
/** Забирает один data-кадр из FIFO 0. Совместима с CanSensor_Io.receive. */
uint8_t CanSensorStm32F1_Receive(void *context, CanSensor_Frame *frame);
/** Собирает таблицу callback-функций для CanSensor_Init(). */
CanSensor_Io CanSensorStm32F1_MakeIo(CanSensorStm32F1_Port *port);
/**
* @brief Обслуживает завершение и тайм-аут передачи без прерываний.
* @param now_ms Монотонное время приложения, мс.
* @param timeout_ms Предел ожидания ACK; 0 отключает принудительную отмену.
*/
void CanSensorStm32F1_Task(CanSensorStm32F1_Port *port, uint32_t now_ms,
uint32_t timeout_ms);
/** Возвращает 1 при bus-off или error-passive. */
uint8_t CanSensorStm32F1_BusError(const CanSensorStm32F1_Port *port);
#endif /* CAN_SENSOR_STM32F1_H */

19
c/can-sensor/ports/stm32f1/can_sensor_stm32f1_config.f103.template.h Normal file
View File

@@ -0,0 +1,19 @@
/**
* @file can_sensor_stm32f1_config.f103.template.h
* @brief Шаблон выводов CAN1 для STM32F103 без ремапа.
*
* Скопируйте файл в include-каталог приложения под именем
* can_sensor_stm32f1_config.h. Скорость и фильтр задаются при запуске порта.
*/
#ifndef CAN_SENSOR_STM32F1_CONFIG_H
#define CAN_SENSOR_STM32F1_CONFIG_H
#include "stm32f10x.h"
#define CAN_SENSOR_STM32F1_GPIO GPIOA
#define CAN_SENSOR_STM32F1_GPIO_CLOCK RCC_APB2ENR_IOPAEN
#define CAN_SENSOR_STM32F1_RX_PIN 11U
#define CAN_SENSOR_STM32F1_TX_PIN 12U
#endif /* CAN_SENSOR_STM32F1_CONFIG_H */

2
doc/index.html
View File

File diff suppressed because one or more lines are too long

30
doc/setcan/README.md Normal file
View File

@@ -0,0 +1,30 @@
# Документация SETCAN / ProtoCAN
Комплект перенесён из отдельного репозитория `SETCAN` (commit `ab60e58`) в
единый репозиторий `templates`. Здесь сохранены нормативные документы,
тестовые векторы, исходный реестр ОАП в Excel и автономная HTML-версия.
## Актуальное расположение кода
| Область | Модуль templates |
|---|---|
| Однокадровые SETTINGS и bxCAN STM32F1 | [`c/can-sensor`](../../c/can-sensor) |
| Единый SET protocol v2 | [`c/set-protocol`](../../c/set-protocol) |
| Транспорт ProtoCAN | [`c/protocan-transport`](../../c/protocan-transport) |
| CAN-загрузчик | [`c/protocan-boot`](../../c/protocan-boot) |
Файлы `Inc/protocan.h` и `Src/protocan.c`, упомянутые в историческом
[руководстве](index.html), больше не являются подключаемым исходным кодом.
В новых проектах используются нормализованные модули из таблицы выше.
## Документы
- [Интерактивное руководство](index.html)
- [Базовый протокол](protocan/PROTOCOL.md)
- [Загрузчик](protocan/BOOTLOADER.md)
- [Общее адресное пространство](protocan/OAP.md)
- [Редактируемый реестр ОАП](Протокол%20CAN%20и%20ОАП.xlsx)
- [Тестовые векторы](protocan/examples/test-vectors.json)
Для пересборки HTML запустите `doc/setcan/build-html.bat` из корня
репозитория `templates`.

13
doc/setcan/build-html.bat Normal file
View File

@@ -0,0 +1,13 @@
@echo off
setlocal
set "SCRIPT_DIR=%~dp0"
where pwsh.exe >nul 2>nul
if %ERRORLEVEL% EQU 0 (
pwsh.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File "%SCRIPT_DIR%build-html.ps1"
) else (
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File "%SCRIPT_DIR%build-html.ps1"
)
exit /b %ERRORLEVEL%

87
doc/setcan/build-html.ps1 Normal file
View File

@@ -0,0 +1,87 @@
[CmdletBinding()]
param()
$ErrorActionPreference = 'Stop'
$outputPath = Join-Path $PSScriptRoot 'index.html'
$sourceDirectory = Join-Path $PSScriptRoot 'protocan'
$documents = @(
'README.md',
'PROTOCOL.md',
'BOOTLOADER.md',
'OAP.md',
'CHANGELOG.md'
)
function Convert-LocalLinks {
param(
[string]$Html,
[string]$SourcePath
)
$sourceParent = Split-Path -Parent $SourcePath
$outputParent = Split-Path -Parent $outputPath
$pattern = '(?<attribute>href|src)="(?<target>(?![a-z]+:|/|#)[^"]+)"'
return [regex]::Replace($Html, $pattern, {
param($match)
$target = $match.Groups['target'].Value
$parts = $target -split '#', 2
$targetPath = [Uri]::UnescapeDataString($parts[0])
$absoluteTarget = [System.IO.Path]::GetFullPath((Join-Path $sourceParent $targetPath))
$relativeTarget = [System.IO.Path]::GetRelativePath($outputParent, $absoluteTarget).Replace('\', '/')
if ($parts.Count -eq 2) {
$relativeTarget += '#' + $parts[1]
}
return $match.Groups['attribute'].Value + '="' + $relativeTarget + '"'
})
}
$sections = foreach ($document in $documents) {
$path = Join-Path $sourceDirectory $document
$markdown = Get-Content -Raw -LiteralPath $path -Encoding UTF8
$html = (ConvertFrom-Markdown -InputObject $markdown).Html
$html = Convert-LocalLinks -Html $html -SourcePath $path
"<article class=`"card protocan-document`" data-source=`"$document`">$html</article>"
}
$vectorsPath = Join-Path $sourceDirectory 'examples\test-vectors.json'
$vectors = [System.Net.WebUtility]::HtmlEncode(
(Get-Content -Raw -LiteralPath $vectorsPath -Encoding UTF8)
)
$sections += @"
<article class="card protocan-document" data-source="examples/test-vectors.json">
<h1>Тестовые векторы</h1>
<p>Машинные эталоны из <code>examples/test-vectors.json</code>.</p>
<pre><code>$vectors</code></pre>
</article>
"@
$generatedBlock = @"
<!-- PROTOCAN:START -->
<section id="protocan-full" class="section">
<h2>Полная документация ProtoCAN</h2>
<p class="lead">Нормативные документы и тестовые векторы собраны в эту страницу из исходников <code>doc/setcan/protocan</code>.</p>
<div class="grid protocan-grid">
$($sections -join "`n")
</div>
</section>
<!-- PROTOCAN:END -->
"@
$page = Get-Content -Raw -LiteralPath $outputPath -Encoding UTF8
$pattern = '(?s)<!-- PROTOCAN:START -->.*?<!-- PROTOCAN:END -->'
if ($page -notmatch $pattern) {
throw 'Не найдены маркеры PROTOCAN:START/END в doc/setcan/index.html.'
}
$page = [regex]::Replace($page, $pattern, [System.Text.RegularExpressions.MatchEvaluator]{
param($match)
$generatedBlock
}, 1)
$page = $page.TrimEnd("`r", "`n") + [Environment]::NewLine
$utf8WithoutBom = [System.Text.UTF8Encoding]::new($false)
[System.IO.File]::WriteAllText($outputPath, $page, $utf8WithoutBom)
Write-Host "[DONE] Создан единый HTML: $outputPath"

1203
doc/setcan/index.html Normal file
View File

File diff suppressed because one or more lines are too long

183
doc/setcan/protocan/BOOTLOADER.md Normal file
View File

@@ -0,0 +1,183 @@
# ProtoCAN Boot Protocol
Статус: **Draft**<br>
Версия протокола: **1.0**<br>
Совместимость: **classic CAN 2.0B, Extended ID, DLC 0…8**<br>
Реализация: [`templates/c/protocan-boot`](../../../c/protocan-boot)
## Назначение
Сервис обновляет адресованный прибор по CAN и поддерживает два логических
слота A/B. Активный слот не стирается: новый образ записывается в неактивный,
проверяется и атомарно назначается кандидатом на запуск.
## Карта сообщений
| `MsgType` | Имя | `MsgBody` | Payload |
|---:|---|---|---|
| `0x9` | `BOOT_CONTROL` | `SessionID[15:8] \| Command[7:0]` | параметры команды |
| `0xA` | `BOOT_DATA_A` | `BlockIndex[15:0]` | 8 байт слота A |
| `0xB` | `BOOT_DATA_B` | `BlockIndex[15:0]` | 8 байт слота B |
| `0xC` | `BOOT_STATUS` | `SessionID[15:8] \| Command[7:0]` | статус и прогресс |
| `0xD` | `BOOT_DISCOVERY` | подтип ответа | идентификация |
Все команды записи адресуются конкретному `DeviceType/DeviceID` и имеют
`Route=0`. Ответы сохраняют адрес прибора и имеют `Route=1`.
## Адресация образа
`MsgBody` кадра данных — номер 8-байтового блока:
```c
offset = (uint32_t)BlockIndex * 8U;
address = SLOT_X_BASE + offset;
```
```text
512 КиБ = 524 288 байт
524 288 / 8 = 65 536 блоков
BlockIndex = 0x0000…0xFFFF
```
| `BlockIndex` | Смещение | Диапазон байтов |
|---:|---:|---:|
| `0x0000` | `0x00000` | `0x00000…0x00007` |
| `0x0001` | `0x00008` | `0x00008…0x0000F` |
| `0xFFFF` | `0x7FFF8` | `0x7FFF8…0x7FFFF` |
`0x80000` является первой позицией за границей слота. Последний кадр
дополняется `0xFF`, но CRC32 вычисляется только по `ImageSize` байтам.
## Команды `BOOT_CONTROL`
| Код | Команда | DLC | Payload | Допустимое состояние |
|---:|---|---:|---|---|
| `0x01` | `IDENTIFY` | 0 | отсутствует | любое |
| `0x02` | `ENTER_BOOT` | 0 | отсутствует | любое; `SessionID != 0` |
| `0x03` | `BEGIN_IMAGE` | 8 | размер и CRC32 | metadata |
| `0x04` | `BEGIN_COMPAT` | 8 | совместимость и версия | metadata |
| `0x05` | `ERASE` | 0 | отсутствует | ready-to-erase |
| `0x06` | `VERIFY` | 0 | отсутствует | образ получен |
| `0x07` | `COMMIT` | 0 | отсутствует | verified |
| `0x08` | `CONFIRM` | 0 | отсутствует | запущенное приложение |
| `0x09` | `REBOOT` | 0 | отсутствует | активная сессия |
| `0x0A` | `ABORT` | 0 | отсутствует | активная сессия |
| `0x0B` | `QUERY_PROGRESS` | 0 | отсутствует | активная сессия |
### `BEGIN_IMAGE`
```text
DATA[0..3] ImageSize, uint32 little-endian
DATA[4..7] ImageCRC32, uint32 little-endian
```
### `BEGIN_COMPAT`
```text
DATA[0..1] ProductType, uint16 little-endian
DATA[2] HardwareRevisionMin
DATA[3] HardwareRevisionMax
DATA[4..7] FirmwareVersion, uint32 little-endian
```
До `ERASE` прибор обязан получить обе части метаданных и проверить размер,
тип изделия, аппаратную ревизию, версию и политику anti-rollback.
## `BOOT_STATUS`
```text
MsgBody[15..8] SessionID
MsgBody[7..0] команда, на которую дан ответ
DATA[0] Status
DATA[1] TargetSlot: 0=A, 1=B, 0xFF=не выбран
DATA[2..3] NextBlock, uint16 little-endian
DATA[4..7] RunningCRC32, uint32 little-endian
```
| Код | Статус | Повтор допустим |
|---:|---|---|
| `0x00` | `OK` | — |
| `0x01` | `BUSY` | да, после задержки |
| `0x02` | `INVALID_COMMAND` | после исправления |
| `0x03` | `WRONG_DEVICE` | нет для этого образа |
| `0x04` | `WRONG_HARDWARE` | нет для этого образа |
| `0x05` | `INVALID_SIZE` | нет для этого образа |
| `0x06` | `CRC_ERROR` | новая передача |
| `0x07` | `FLASH_ERROR` | зависит от платформы |
| `0x08` | `SEQUENCE_ERROR` | да, с `NextBlock` |
| `0x09` | `SIGNATURE_ERROR` | нет |
| `0x0A` | `SESSION_ERROR` | открыть новую сессию |
| `0x0B` | `VOLTAGE_ERROR` | да после нормализации питания |
| `0x0C` | `INVALID_STATE` | выполнить правильный переход |
## State machine
```text
IDLE
└─ ENTER_BOOT ─> METADATA
├─ BEGIN_IMAGE
└─ BEGIN_COMPAT
│
v
READY_TO_ERASE
│ ERASE
v
RECEIVING
│ VERIFY
v
VERIFIED
│ COMMIT
v
PENDING + REBOOT
│ CONFIRM
v
CONFIRMED
```
Ошибка Flash, CRC, совместимости или подписи переводит сессию в `FAILED`.
Новая `ENTER_BOOT` создаёт чистую сессию. `ABORT` прекращает текущую передачу,
не активируя частично записанный слот.
## Надёжность и повторы
- Блоки передаются строго по возрастанию `BlockIndex`.
- Дубликат или пропуск возвращает `SEQUENCE_ERROR` и ожидаемый `NextBlock`.
- Базовый режим подтверждает каждый блок.
- Рабочий режим может подтверждать окно из 16 блоков.
- После потери связи `QUERY_PROGRESS` возвращает следующий ожидаемый блок,
пока состояние загрузчика сохранено.
- Для продолжения после перезагрузки порт должен сохранять session metadata
и восстановить её при инициализации; ядро версии 1.0 само это не делает.
## Безопасность и A/B-обновление
```text
active=A -> target=B -> verify -> pending=B
active=B -> target=A -> verify -> pending=A
```
CRC32 защищает только от случайного повреждения. Серийный загрузчик должен
дополнительно проверить подпись контейнера, границы вектора, совместимость и
anti-rollback. Bootloader не обновляется командами `BOOT_DATA_A/B`.
Boot metadata должна атомарно хранить:
- активный слот;
- pending-слот;
- подтверждение запуска;
- число неудачных попыток;
- версию и CRC32 образа.
Если приложение не выполняет `CONFIRM` за установленное число запусков,
загрузчик возвращается к предыдущему подтверждённому слоту.
## Эталонный сценарий
1. ПМ адресно отправляет `IDENTIFY`.
2. ПМ открывает ненулевой `SessionID` командой `ENTER_BOOT`.
3. ПМ отправляет `BEGIN_IMAGE` и `BEGIN_COMPAT`.
4. Прибор сообщает выбранный неактивный слот.
5. ПМ выполняет `ERASE` и передаёт `BOOT_DATA_A` либо `BOOT_DATA_B`.
6. ПМ выполняет `VERIFY`, затем `COMMIT` и `REBOOT`.
7. Новое приложение после самопроверки выполняет `CONFIRM`.

21
doc/setcan/protocan/CHANGELOG.md Normal file
View File

@@ -0,0 +1,21 @@
# История изменений ProtoCAN
Формат основан на Keep a Changelog. Версия относится к спецификации, а не к
версии прошивки отдельного прибора.
## [Unreleased]
### Added
- Структурированный комплект документации `doc/setcan/protocan`.
- Загрузочный сервис `MsgType=0x9…0xD`.
- Два логических слота по 512 КиБ, 65 536 блоков по 8 байт каждый.
- Машинные эталоны CAN ID в `examples/test-vectors.json`.
## [1.0] — 2026-08-29
### Added
- Зафиксирована 29-битная структура ProtoCAN ID.
- Зафиксирована адресация 8 типов по 16 экземпляров.
- Существующие сообщения `0x0…0x8`, `0xE`, `0xF` сохранены.

56
doc/setcan/protocan/OAP.md Normal file
View File

@@ -0,0 +1,56 @@
# Общее адресное пространство
Статус: **Stable, данные ведутся в XLSX**<br>
Порядок значений: **16-битные регистры, little-endian в CAN payload**
Редактируемый источник реестра:
[`Протокол CAN и ОАП.xlsx`](../Протокол%20CAN%20и%20ОАП.xlsx).
Просматриваемая большая таблица находится в
[`Протокол CAN и ОАП.html`](../Протокол%20CAN%20и%20ОАП.html) и
[`Протокол CAN и ОАП.md`](../Протокол%20CAN%20и%20ОАП.md).
## Назначение
ОАП связывает 16-битный адрес регистра с его типом, назначением, доступом и
масштабом. В ProtoCAN используется `MsgType=0x3`, а `MsgBody` содержит адрес
первого регистра.
## Обязательные поля реестра
| Поле | Требование |
|---|---|
| AddressHex | `0x0000…0xFFFF`, уникальное значение |
| AddressDec | десятичный эквивалент AddressHex |
| Group | функциональная группа |
| Name | однозначное имя параметра |
| Type | `u16`, `i16`, `u32`, `i32`, `float32`, bitmap или массив |
| Registers | число занятых 16-битных регистров |
| Access | `R`, `W` или `RW` |
| Unit | физическая единица либо `—` |
| Scale | множитель/делитель представления |
| Default | значение после сброса, если применимо |
| Description | семантика, диапазон и особые значения |
## Правила ведения
- Адрес не переиспользуется с другим смыслом после выпуска стабильной версии.
- Многорегистровое значение занимает непрерывный диапазон.
- Порядок 16-битных слов для 32-битного значения фиксируется в строке типа.
- Резервные диапазоны явно отмечаются и не используются без изменения версии.
- Удалённый параметр помечается deprecated, а не исчезает молча.
- Изменение адреса, типа или масштаба отражается в `CHANGELOG.md`.
## Экспорт
Для программной генерации каталог следует экспортировать из XLSX в CSV с
UTF-8 и фиксированными английскими именами колонок. CSV должен проверяться на:
- уникальность адресов;
- пересечение многорегистровых значений;
- допустимые типы и права доступа;
- равенство шестнадцатеричного и десятичного адреса;
- попадание адреса в диапазон `0x0000…0xFFFF`.
До появления автоматического экспортёра нормативным источником адресов
остаётся XLSX, а HTML/Markdown считаются представлением.

114
doc/setcan/protocan/PROTOCOL.md Normal file
View File

@@ -0,0 +1,114 @@
# ProtoCAN — базовый протокол
Статус: **Stable с зарезервированным загрузочным расширением**<br>
Версия: **1.0**<br>
Порядок байтов payload: **little-endian**, если явно не указано иное
## Назначение
ProtoCAN — прикладной протокол поверх classic CAN 2.0B. Используются только
расширенные 29-битные идентификаторы (`IDE=1`) и payload длиной 0…8 байт.
## Термины
| Термин | Значение |
|---|---|
| ПМ | управляющий модуль |
| прибор | адресуемый узел на шине |
| `DeviceType` | тип прибора, 0…7 |
| `DeviceID` | экземпляр прибора данного типа, 0…15 |
| `MsgType` | класс сообщения или сервис |
| `MsgBody` | 16-битное поле, формат которого зависит от `MsgType` |
Пара `DeviceType/DeviceID` задаёт до `8 × 16 = 128` уникальных адресов.
## Расширенный CAN ID
```text
28 27 26...24 23...20 19...16 15........0
Priority Route DeviceType DeviceID MsgType MsgBody
1 бит 1 бит 3 бита 4 бита 4 бита 16 бит
```
```c
can_id =
((uint32_t)priority << 28) |
((uint32_t)route << 27) |
((uint32_t)device_type << 24) |
((uint32_t)device_id << 20) |
((uint32_t)msg_type << 16) |
msg_body;
```
| Поле | Значения | Назначение |
|---|---|---|
| `Priority` | `0` critical, `1` standard | CAN-арбитраж |
| `Route` | `0` от ПМ, `1` от прибора | логическое направление |
| `DeviceType` | `0…7` | тип прибора |
| `DeviceID` | `0…15` | номер экземпляра |
| `MsgType` | `0…15` | тип сообщения |
| `MsgBody` | `0…65535` | команда, адрес или номер блока |
`Route` не является направлением физического трансивера. Ответ прибора
сохраняет адрес `DeviceType/DeviceID` и устанавливает `Route=1`.
## Реестр `MsgType`
| Код | Имя | Основное направление | DLC | Статус |
|---:|---|---|---:|---|
| `0x0` | `BROADCAST` | ПМ → все | зависит от команды | stable |
| `0x1` | `DISCRETE` | оба | 0…8 | stable |
| `0x2` | `ANALOG` | оба | 0…8 | stable |
| `0x3` | `GAS` | оба | 0/2/4/6/8 | stable |
| `0x4` | `MODBUS_COIL` | оба | 0…8 | stable |
| `0x5` | `MODBUS_DISCRETE` | оба | 0…8 | stable |
| `0x6` | `MODBUS_HOLDING` | оба | 0…8 | stable |
| `0x7` | `MODBUS_INPUT` | оба | 0…8 | stable |
| `0x8` | `ERROR` | прибор → ПМ | 0 | stable |
| `0x9` | `BOOT_CONTROL` | ПМ → прибор | 0/8 | draft |
| `0xA` | `BOOT_DATA_A` | ПМ → прибор | 8 | draft |
| `0xB` | `BOOT_DATA_B` | ПМ → прибор | 8 | draft |
| `0xC` | `BOOT_STATUS` | прибор → ПМ | 8 | draft |
| `0xD` | `BOOT_DISCOVERY` | прибор → ПМ | 8 | draft |
| `0xE` | `SETTINGS` | оба | 0/1/8 | stable |
| `0xF` | `PULSE` | прибор → сеть | 1 | stable |
Подробный формат `0x9…0xD` находится в [BOOTLOADER.md](BOOTLOADER.md).
## Разметки `MsgBody`
| `MsgType` | Биты `MsgBody` |
|---|---|
| broadcast | команда `[15:4]`, параметр `[3:0]` |
| discrete/analog | подтип `[15:12]`, значение/адрес `[11:0]` |
| Modbus | начальный адрес `[15:4]`, количество `[3:0]` |
| GAS | адрес первого 16-битного регистра `[15:0]` |
| error | дополнительная информация `[15:8]`, код `[7:0]` |
| settings | номер сборки `[15:8]`, позиция `[7:0]` |
| boot control/status | `SessionID[15:8]`, команда `[7:0]` |
| boot data | `BlockIndex[15:0]` |
## Общие правила обмена
- Многобайтовые значения в `DATA` передаются little-endian.
- Узел игнорирует адресованные кадры с чужим `DeviceType/DeviceID`.
- Прибор принимает команды ПМ с `Route=0`; ПМ принимает ответы с `Route=1`.
- Стандартные 11-битные CAN ID не являются кадрами ProtoCAN.
- RTR для загрузочного сервиса запрещён.
- Неописанные комбинации `MsgType/MsgBody/DLC` должны отвергаться.
## Эталон упаковки ID
```text
Priority = 1
Route = 0
DeviceType = 3
DeviceID = 5
MsgType = 0x9
MsgBody = 0x0702
CAN ID = 0x13590702
```
Этот пример соответствует `ENTER_BOOT`, `SessionID=7`. Машинные варианты
находятся в [examples/test-vectors.json](examples/test-vectors.json).

43
doc/setcan/protocan/README.md Normal file
View File

@@ -0,0 +1,43 @@
# Документация ProtoCAN
Статус комплекта: **Draft**<br>
Версия комплекта: **1.0**<br>
Дата редакции: **2026-08-29**<br>
Транспорт: **Classic CAN 2.0B, Extended ID, DLC 0…8**
Этот каталог разделяет нормативное описание протокола, загрузчик и реестр
общего адресного пространства. Большой исходный документ
[`Протокол CAN и ОАП.md`](../Протокол%20CAN%20и%20ОАП.md) сохранён как
совместимое представление таблиц из Excel.
## Документы
| Документ | Назначение | Статус источника |
|---|---|---|
| [PROTOCOL.md](PROTOCOL.md) | 29-битный CAN ID, адресация, реестр `MsgType`, порядок байтов | нормативный |
| [BOOTLOADER.md](BOOTLOADER.md) | обновление прошивки, кадры, состояния, ошибки и A/B-слоты | нормативный draft |
| [OAP.md](OAP.md) | правила ведения общего адресного пространства | нормативный индекс |
| [../Протокол CAN и ОАП.xlsx](../Протокол%20CAN%20и%20ОАП.xlsx) | редактируемый реестр ОАП | источник таблиц |
| [examples/test-vectors.json](examples/test-vectors.json) | машинные эталоны CAN ID и payload | нормативные примеры |
| [CHANGELOG.md](CHANGELOG.md) | история версий документа | нормативный |
## Приоритет источников
При расхождении данных действует следующий порядок:
1. `PROTOCOL.md` — структура ProtoCAN и реестр типов сообщений.
2. `BOOTLOADER.md` — загрузочный сервис `0x9…0xD`.
3. XLSX — адреса и свойства регистров ОАП.
4. Сгенерированный [`../index.html`](../index.html) — только представление, не самостоятельный источник.
## Сборка HTML
Из корня проекта:
```powershell
./doc/setcan/build-html.bat
```
Все документы и тестовые векторы включаются в единый файл
`doc/setcan/index.html`.
Скрипт не изменяет исходные Markdown/XLSX и пригоден для запуска в CI.

45
doc/setcan/protocan/examples/test-vectors.json Normal file
View File

@@ -0,0 +1,45 @@
{
"schema_version": 1,
"byte_order": "little-endian",
"frames": [
{
"name": "enter_boot_session_7",
"direction": "pm_to_device",
"priority": 1,
"route": 0,
"device_type": 3,
"device_id": 5,
"msg_type": 9,
"msg_body": 1794,
"can_id_hex": "0x13590702",
"dlc": 0,
"data_hex": ""
},
{
"name": "slot_b_block_1",
"direction": "pm_to_device",
"priority": 1,
"route": 0,
"device_type": 3,
"device_id": 5,
"msg_type": 11,
"msg_body": 1,
"can_id_hex": "0x135B0001",
"dlc": 8,
"data_hex": "1011121314151617"
},
{
"name": "enter_boot_ok",
"direction": "device_to_pm",
"priority": 1,
"route": 1,
"device_type": 3,
"device_id": 5,
"msg_type": 12,
"msg_body": 1794,
"can_id_hex": "0x1B5C0702",
"dlc": 8,
"data_hex": "00FF000000000000"
}
]
}

13404
doc/setcan/Протокол CAN и ОАП.html Normal file
View File

File diff suppressed because it is too large Load Diff

13276
doc/setcan/Протокол CAN и ОАП.md Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
doc/setcan/Протокол CAN и ОАП.xlsx Normal file
View File

Binary file not shown.

1
doc/setcan/ссылки на док.md Normal file
View File

@@ -0,0 +1 @@
https://disk.yandex.ru/i/TMyHlpYxIP75YQ