Документация ProtoCAN

Статус комплекта: Draft
Версия комплекта: 1.0
Дата редакции: 2026-08-29
Транспорт: Classic CAN 2.0B, Extended ID, DLC 0…8

Этот каталог разделяет нормативное описание протокола, загрузчик и реестр общего адресного пространства. Большой исходный документ Протокол CAN и ОАП.md сохранён как совместимое представление таблиц из Excel.

Документы

Приоритет источников

При расхождении данных действует следующий порядок:

1. PROTOCOL.md — структура ProtoCAN и реестр типов сообщений.
2. BOOTLOADER.md — загрузочный сервис 0x9…0xD.
3. XLSX — адреса и свойства регистров ОАП.
4. Сгенерированный HTML — только представление, не самостоятельный источник.

Сборка HTML

В PowerShell 7:

./build-html.ps1

Результат создаётся в build/protocol.html. Скрипт не изменяет исходные Markdown/XLSX и пригоден для запуска в CI.

ProtoCAN — базовый протокол

Статус: Stable с зарезервированным загрузочным расширением
Версия: 1.0
Порядок байтов payload: little-endian, если явно не указано иное

Назначение

ProtoCAN — прикладной протокол поверх classic CAN 2.0B. Используются только расширенные 29-битные идентификаторы (IDE=1) и payload длиной 0…8 байт.

Термины

Пара DeviceType/DeviceID задаёт до 8 × 16 = 128 уникальных адресов.

Расширенный CAN ID

28       27       26...24      23...20     19...16     15........0
Priority Route    DeviceType   DeviceID    MsgType     MsgBody
 1 бит    1 бит      3 бита      4 бита      4 бита      16 бит

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;

Route не является направлением физического трансивера. Ответ прибора сохраняет адрес DeviceType/DeviceID и устанавливает Route=1.

Реестр MsgType

Подробный формат 0x9…0xD находится в BOOTLOADER.md.

Разметки MsgBody

Общие правила обмена

• Многобайтовые значения в DATA передаются little-endian.
• Узел игнорирует адресованные кадры с чужим DeviceType/DeviceID.
• Прибор принимает команды ПМ с Route=0; ПМ принимает ответы с Route=1.
• Стандартные 11-битные CAN ID не являются кадрами ProtoCAN.
• RTR для загрузочного сервиса запрещён.
• Неописанные комбинации MsgType/MsgBody/DLC должны отвергаться.

Эталон упаковки ID

Priority   = 1
Route      = 0
DeviceType = 3
DeviceID   = 5
MsgType    = 0x9
MsgBody    = 0x0702

CAN ID = 0x13590702

Этот пример соответствует ENTER_BOOT, SessionID=7. Машинные варианты находятся в examples/test-vectors.json.

ProtoCAN Boot Protocol

Статус: Draft
Версия протокола: 1.0
Совместимость: classic CAN 2.0B, Extended ID, DLC 0…8
Реализация: templates/c/protocan-boot

Назначение

Сервис обновляет адресованный прибор по CAN и поддерживает два логических слота A/B. Активный слот не стирается: новый образ записывается в неактивный, проверяется и атомарно назначается кандидатом на запуск.

Карта сообщений

Все команды записи адресуются конкретному DeviceType/DeviceID и имеют Route=0. Ответы сохраняют адрес прибора и имеют Route=1.

Адресация образа

MsgBody кадра данных — номер 8-байтового блока:

offset = (uint32_t)BlockIndex * 8U;
address = SLOT_X_BASE + offset;

512 КиБ = 524 288 байт
524 288 / 8 = 65 536 блоков
BlockIndex = 0x0000…0xFFFF

0x80000 является первой позицией за границей слота. Последний кадр дополняется 0xFF, но CRC32 вычисляется только по ImageSize байтам.

Команды BOOT_CONTROL

BEGIN_IMAGE

DATA[0..3] ImageSize, uint32 little-endian
DATA[4..7] ImageCRC32, uint32 little-endian

BEGIN_COMPAT

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

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

State machine

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-обновление

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.

Общее адресное пространство

Статус: Stable, данные ведутся в XLSX
Порядок значений: 16-битные регистры, little-endian в CAN payload

Редактируемый источник реестра: Протокол CAN и ОАП.xlsx.

Просматриваемая большая таблица находится в Протокол CAN и ОАП.html и Протокол CAN и ОАП.md.

Назначение

ОАП связывает 16-битный адрес регистра с его типом, назначением, доступом и масштабом. В ProtoCAN используется MsgType=0x3, а MsgBody содержит адрес первого регистра.

Обязательные поля реестра

Правила ведения

• Адрес не переиспользуется с другим смыслом после выпуска стабильной версии.
• Многорегистровое значение занимает непрерывный диапазон.
• Порядок 16-битных слов для 32-битного значения фиксируется в строке типа.
• Резервные диапазоны явно отмечаются и не используются без изменения версии.
• Удалённый параметр помечается deprecated, а не исчезает молча.
• Изменение адреса, типа или масштаба отражается в CHANGELOG.md.

Экспорт

Для программной генерации каталог следует экспортировать из XLSX в CSV с UTF-8 и фиксированными английскими именами колонок. CSV должен проверяться на:

• уникальность адресов;
• пересечение многорегистровых значений;
• допустимые типы и права доступа;
• равенство шестнадцатеричного и десятичного адреса;
• попадание адреса в диапазон 0x0000…0xFFFF.

До появления автоматического экспортёра нормативным источником адресов остаётся XLSX, а HTML/Markdown считаются представлением.

История изменений ProtoCAN

Формат основан на Keep a Changelog. Версия относится к спецификации, а не к версии прошивки отдельного прибора.

[Unreleased]

Added

• Структурированный комплект документации docs/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 сохранены.