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

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

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

Документы

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

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

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

Сборка HTML

Из корня проекта:

./doc/setcan/build-html.bat

Все документы и тестовые векторы включаются в единый файл doc/setcan/index.html. Скрипт не изменяет исходные Markdown/XLSX и пригоден для запуска в CI.

GAS: регистры 0x3 и слоты 0x4

Адресация GAS: 0x3 — отдельные 16-битные регистры 0…65535, запись 1…4 слов. 0x4 — слот с Word0-маской и тремя значениями; PERIPH сохраняет 200 слов в 67 слотах 0xMM00…0xMM42. Формат определяется MsgType, без настройки профиля.

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

Статус: Stable с зарезервированным загрузочным расширением
Версия: 2.1: GAS 0x3 и масочный GAS SLOT 0x4
Порядок байтов 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

Контракт обоих GAS: OAP.md. Тип 0x3 адресует отдельные слова; тип 0x4 имеет маску битов 1…3 в Word0 и три значения. Для PERIPH 0x4 используются 67 слотов 0xMM00…0xMM42, последний содержит два значения. Старый Coil 0x4 заменён; формат определяется MsgType.

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

Профиль синхронизации часов и сообщения платы о завершении инициализации: GLOBAL_TIME.md. Он сохраняет штатный BROADCAST RTCSETUP и определяет общий пакет готовности поверх DISCRETE/FLAGS.

• Многобайтовые значения в 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.

Общее адресное пространство: GAS и GAS SLOT

Дата редакции: 2026-10-23. Номер типа однозначно определяет единицу адресации:

В обоих случаях запрос чтения — extended data frame с DLC=0, Route=0. Ответ имеет Route=1, тот же узел и адрес. Прикладного ACK записи нет; успех применения уставки проверяется прикладным ответом или последующим чтением. RTR, error frame, стандартный 11-битный ID и нечётные длины не исполняются.

GAS 0x3: отдельные регистры

MsgBody=RegisterAddress[15:0]. Адреса 0…65535 (0x0000…0xFFFF) обозначают 65 536 отдельных 16-битных регистров, логически 128 КиБ на узел. Это адреса протокола, а не указатели RAM MCU; provider подключает только существующие регионы.

Payload содержит значения с адресов addr, addr+1, addr+2, addr+3 в порядке little-endian. Количество равно DLC/2, допускаются DLC 2, 4, 6, 8. Для изменения одной уставки по адресу 0x0001 на 0x1234 передаются MsgBody=0x0001, DLC=2, Data=34 12; соседние слова не изменяются. Чтение возвращает до четырёх существующих последовательных регистров, останавливаясь на первом недоступном адресе или границе 0xFFFF. Запись, пересекающая 0xFFFF, отвергается до изменения данных.

Регионы карты, права и значения проверяет pcan_gas; callback остаётся ответственностью приложения. Блочная запись может остановиться на первом отказе provider: атомарность нескольких регистров не обещается. Связанные u32/float32 и команды требуют согласованной прикладной операции. Основной контракт: c/set-protocol/docs/legacy/GAS.md. GAS 167/v1, GAS Logger, GAS_WATCH2, NAND и Altera Logic сохраняют регистровые адреса. Номер mode задаёт адрес узла; его нельзя автоматически прибавлять к адресу регистра.

GAS SLOT 0x4: маска в Word0

MsgBody=SlotAddress[15:0]. Восемь октетов имеют фиксированное расположение:

Биты маски 1, 2, 3 соответствуют Word1, Word2, Word3. Бит 0 и биты 4…15 зарезервированы и должны быть нулевыми. Маска непустая; все допустимые маски: 0x0002, 0x0004, 0x0006, 0x0008, 0x000A, 0x000C, 0x000E. При записи отмеченные значения применяются, неотмеченные позиции игнорируются и сохраняют текущие значения устройства. Нули не являются специальными маркерами. При чтении маска ответа отмечает достоверные/доступные значения.

Например, изменить только Word2 на 0x1234: Data=04 00 00 00 34 12 00 00. Word1 и Word3 сохраняются. Полная запись трёх значений использует маску 0x000E. Передаются всегда восемь октетов, кроме пустого запроса чтения. Сжатия или сегментации нет. Provider проверяет все выбранные права и значения до первого изменения, затем применяет выбранные слова под общей блокировкой. Невыбранные readonly-поля не записываются. Ядро не выполняет опасное чтение-изменение-запись слота на стороне клиента.

Полное пространство 0x4 содержит 65 536 слотов × 3 значения = 196 608 слов = 384 КиБ. Word0 — метаданные кадра, не четвёртый хранимый регистр. Координата значения — (SlotAddress, WordIndex), где WordIndex=1…3. Любой узел поддерживается общими pcan_gas_slot_id() и pcan_gas_slot_handle_address(); адрес слота не ограничен страницами PERIPH. Тип 0x4 MODBUS_COIL заменён этим сервисом. Modbus 0x5/0x6/0x7 сохраняет номера. Старое оборудование с Coil 0x4 требует согласованного обновления; автоопределения формата нет.

PERIPH: проекция 200 слов на слоты 0x4

mode=0…31; DeviceType=1+mode/16, DeviceID=mode mod 16. SlotAddress=(mode<<8)|LocalSlot. Маски не занимают места в карте значений. На mode сохранены 200 слов, поэтому используются 67 слотов LocalSlot=0x00…0x42: 66 полных слотов и два значения последнего. В последнем разрешена только маска из битов 1/2 (0x0002, 0x0004, 0x0006); Word3 не существует. LocalSlot=0x43…0xFF — резерв. Узел и старший октет слота должны совпадать.

Смещение технологического слова: n=3*LocalSlot+(WordIndex-1). Обратное преобразование: LocalSlot=n/3, WordIndex=1+n mod 3. Соседние native-сервисы могут оказаться в одном слоте, поэтому provider проверяет доступ и наличие каждой отмеченной позиции отдельно.

Назначения mode из periph_28335

Источники: 28335_periph/Source/Internal/Include/package.h, peripher.c:get_Mode(), cntrl_adr.c. Код платы Desk не участвует в вычислении адреса.

Соответствия native-сервисам PERIPH

pcan_gas_slot_native() принимает WordIndex=1…3; WordIndex=0 является маской и не переводится в регистр. Наличие сервиса, права и блокировку проверяет приложение. GAS 0x3 сохраняет собственные адреса подключённых регионов; эта проекция относится только к 0x4. Архив УМП, окна 120/124 слова и физическая EEPROM сохраняют native-контракты.

Реализация и реестр

• GAS 0x3: pcan_gas.h/.c, существующие ABI и клиенты.
• GAS SLOT 0x4: pcan_gas_slot.h/.c; тонкие Python GasSlots и Android/JNI GasSlots.
• Формат определяется MsgType, параметр gas_profile не используется.
• C28x хранит wire-октеты в uint_least8_t; DLC измеряется октетами линии.
• Перенос в другую единицу адресации или fallback после отказа запрещены.

XLSX «Интерфейс протокола» содержит оба типа; «Общее адресное пространство» — проекцию 0x4 и native-адреса её значений; «ОАП legacy» сохраняет исходный словный реестр 0x3. Уникальный ключ реестра включает узел, MsgType, адрес и для 0x4 WordIndex. Права, тип, единица, масштаб и порядок слов u32/float32 задаются явно. Эталоны: examples/gas-slot-vectors.json; регистровые проверки — test_gas_register.c.

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

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

[Unreleased]

Changed — 2026-10-23

• GAS 0x3 возвращён к адресации отдельных 16-битных регистров 0…65535, DLC 0/2/4/6/8.
• Слотный GAS перенесён на 0x4 вместо MODBUS_COIL; Word0 содержит маску битов 1…3, Word1…Word3 — значения.
• PERIPH сохраняет 200 значений на mode в 67 слотах; последний содержит два значения.
• Формат выбирается номером MsgType; Python/JNI, STM32, Modbus routing, тесты, XLSX и HTML согласованы.

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 сохранены.

Тестовые векторы

Машинные эталоны из examples/test-vectors.json.

{
  "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"
    }
  ]
}