Update CCS12 peripheral firmware and documentation

Doc/mainpage.md

@@ -0,0 +1,70 @@
+# Balsam 167 Peripheral {#mainpage}
+
+Прошивка периферийного контроллера **Balsam 167** для цифрового сигнального
+контроллера Texas Instruments TMS320F28335. Контроллер измеряет токи,
+напряжения и температуры, анализирует аварийные состояния, управляет
+дискретными выходами и обменивается данными по CAN и двум каналам SCI/RS-485.
+
+@tableofcontents
+
+## Назначение
+
+Один исполняемый образ поддерживает несколько аппаратных ролей. Роль платы
+определяется входами режима при старте и хранится в `Desk`:
+
+| Значение | Роль | Основная задача |
+|---|---|---|
+| `dsk_COMM` | COMM | связь и термокалибровка |
+| `dsk_BKSD` | BKSD | дискретные сигналы |
+| `dsk_BKST` | BKST | температурные каналы |
+| `dsk_EPLT` | EPLT | пульт/индикация |
+| `dsk_SHKF` | SHKF | шкафной контроллер |
+| `dsk_LOAD` | LOAD | нагрузка и аналоговый выход |
+
+Конфигурация изделия выбирается макросом `BALSAM` в `package.h`. Для этого
+репозитория задано значение `167`.
+
+## Выполнение программы
+
+1. `main()` настраивает системную тактовую частоту, PIE, внешнюю память,
+   GPIO, CAN, SCI, EEPROM и измерительные каналы.
+2. `timer_Init()` выбирает обработчик Timer1: `cpu_timer1_isr_SENS()` для
+   измерительных плат или `cpu_timer1_isr_PULT()` для пульта.
+3. Быстрый контур АЦП выполняется в `adc_isr()`.
+4. Главный цикл передаёт телеметрию, обслуживает команды настройки,
+   дискретные входы и протокол BIOS/Modbus.
+
+## Карта модулей
+
+- @ref measurement — сбор АЦП, фильтрация, пересчёт физических величин и ошибки.
+- @ref communication — SCI/RS-485, разбор команд и Modbus-пакеты.
+- @ref can_bus — CAN eCAN-A и циклическая телеметрия.
+- @ref storage — SPI EEPROM, параметры и журнал во внешней памяти.
+- @ref hardware — GPIO, дискретные выходы, ЦАП и семисегментный канал.
+- @ref boot_protocol — команды чтения, записи и запуска ПО через BIOS-протокол.
+- @ref utilities — CRC, фильтр Баттерворта, задержки и служебные функции.
+
+## Общая память данных
+
+Массив `modbus` — центральная модель состояния. Макросы из `package.h`
+проецируют его участки на флаги ошибок, измерения, уставки, коэффициенты
+калибровки и команды. Измерительный контур обновляет модель, а CAN/RS-485
+публикуют или изменяют её. При изменении разметки следует одновременно
+проверять адреса протокола, `ANSWER_LEN` и таблицу данных изделия в `Doc`.
+
+## Сборка прошивки
+
+Инструкции для Code Composer Studio 12 находятся в
+[README_CCS12.md](README_CCS12.md). Старый проект CCS 3 использует
+`UKSSTMS320F28335.pjt`; проект CCS 12 расположен в каталоге
+`UKSSTMS320F28335`.
+
+## Сборка документации
+
+Запустите `Doc\\build.bat`. Обзор будет помещён в `Doc\\build\\index.html`,
+а при наличии Doxygen API-справочник появится в
+`Doc\\build\\api\\html\\index.html`.
+
+@warning Обработчики прерываний и функции, меняющие GPIO или регистры
+периферии, нельзя вызывать как обычные функции без понимания контекста PIE,
+частоты тактирования и выбранной роли платы.