================================================================================
                ИНСТРУКЦИЯ ПО РАБОТЕ СО СКРИПТОМ LSU_1_UDP_rc3.py
          Массовое обновление ПО устройств Talentum LSU1A-PY по UDP
================================================================================

                           ОГЛАВЛЕНИЕ
1.  Назначение программы
2.  Системные требования
3.  Подготовка к работе
4.  Запуск и интерпретация вывода
5.  Технические особенности и ограничения
6.  Устранение типичных неисправностей
7.  Контакты

================================================================================
1. НАЗНАЧЕНИЕ ПРОГРАММЫ
================================================================================

Скрипт LSU_1_UDP_rc3.py предназначен для автоматического централизованного 
обновления встроенного программного обеспечения (прошивки) устройств Talentum 
(на базе микроконтроллеров CH32F207) в пределах локальной вычислительной сети.

Скрипт выполняет следующую последовательность действий:
- Обнаружение устройств, посылающих UDP-пакеты в сеть.
- Проверка текущей версии прошивки (CRC32) для исключения повторной записи.
- Активация режима Bootloader.
- Анализ состояния перемычек защиты записи (SA1).
- Разблокировка и стирание Flash-памяти.
- Запись нового образа прошивки страницами по 256 байт.
- Верификация записанных данных.
- Запуск основного приложения.

================================================================================
2. СИСТЕМНЫЕ ТРЕБОВАНИЯ
================================================================================

- Операционная система:   Windows 7/10/11, Linux (Debian/Ubuntu и производные).
- Интерпретатор:          Python версии 3.6 или выше.
- Сетевой интерфейс:      Ethernet или Wi-Fi.
- Сетевая топология:      Компьютер и обновляемые устройства ДОЛЖНЫ находиться 
                          в одном широковещательном домене (одна подсеть, 
                          один VLAN). Работа через NAT/роутер невозможна.
- Брандмауэр:             Порт 5008/UDP должен быть открыт на входящие и 
                          исходящие соединения.

================================================================================
3. ПОДГОТОВКА К РАБОТЕ
================================================================================

ШАГ 3.1. Получение файла прошивки
Необходимо получить бинарный файл приложения с расширением .bct.
ВАЖНО: Размер файла должен быть строго 122 880 байт (120 кБ).
ВАЖНО: Имя файла должно совпадать с контрольной суммой CRC32 его содержимого 
       (например, если CRC32 равен A1B2C3D4, имя файла должно быть A1B2C3D4.bct).
       Скрипт проводит проверку соответствия имени файла реальной CRC.

ШАГ 3.2. Размещение файлов
1. Создайте отдельную папку, например: C:\LSU_Update\.
2. Скопируйте в эту папку файл скрипта LSU_1_UDP_rc3.py.
3. Скопируйте в эту же папку файл прошивки *.bct.
4. Убедитесь, что в папке находится ТОЛЬКО ОДИН файл с расширением .bct.

ШАГ 3.3. Настройка оборудования
1. Подключите обновляемые устройства к локальной сети и подайте питание/перезагрузите.
2. Убедитесь, что на устройствах снята перемычка SA1 (если требуется снятие 
   защиты от записи Flash). Скрипт проверит состояние перемычки автоматически.
3. Устройства должны получить IP-адрес (по DHCP или статический).

================================================================================
4. ЗАПУСК И ИНТЕРПРЕТАЦИЯ ВЫВОДА
================================================================================

4.1. Команда запуска
Откройте терминал (Командную строку) в папке со скриптом и выполните:
>>> python LSU_1_UDP_rc3.py

4.2. Этапы работы скрипта в консоли

[Этап 1: Инициализация]
Найден файл: 1A2B3C4D.bct
Размер: 122880 байт
Ожидаемое количество страниц: 480 по 256 байт
CRC32 файла совпадает с именем: 0x1A2B3C4D
Сервер запущен на порту 5008
================================================================================
СЕРВЕР ОБНОВЛЕНИЯ ПО TALENTUM LSU1A-PY
================================================================================
Ожидание подключения устройств...
Для остановки сервера нажмите Ctrl+C
================================================================================
-> Скрипт готов к работе и слушает сеть.

[Этап 2: Обнаружение устройства]
УСТРОЙСТВО ОБНАРУЖЕНО:
  Публичный IP: 192.168.1.100
  MAC: 02:03:04:05:06:07
  CRC бутлоадера: 0x12345678
  Флаги состояния BL:
    • Программирование возможно: ДА (бит 0)
...
-> Если CRC устройства совпадает с CRC файла, вы увидите сообщение:
   "Устройство уже имеет актуальное ПО UP1. Обслуживание устройства ЗАВЕРШЕНО."
   и скрипт перейдет к ожиданию следующего устройства.

[Этап 3: Процесс прошивки (если CRC отличаются)]
Подготовка устройства...
Попытка 1/3...
Команда CMD_ACTIVATE_BL выполнена успешно
...
Прогресс: |====================----------------| 50.0% Страница 240/480 | Адр: 0x0801EF00
...
CRC сравнение:
  Файл: 0x1A2B3C4D
  Устройство: 0x1A2B3C4D
CRC совпадают! Программирование выполнено корректно!

[Этап 4: Итог]
================================================================================
ИТОГ ОБРАБОТКИ УСТРОЙСТВА: 192.168.1.100 (02:03:04:05:06:07)
================================================================================
Статус: УСПЕШНО ОБНОВЛЕНО
...
-> Скрипт возвращается в режим ожидания новых устройств.

================================================================================
5. ТЕХНИЧЕСКИЕ ОСОБЕННОСТИ И ОГРАНИЧЕНИЯ
================================================================================

1. ПОВТОРНОЕ ПОДКЛЮЧЕНИЕ:
   Скрипт ведет внутренний кэш обработанных устройств. Если пакет от устройства 
   с тем же MAC/IP приходит в течение 60 секунд после завершения обработки, 
   он игнорируется. Это защита от зацикливания.

2. BROADCAST:
   Устройства рассылают broadcast пакеты для установления соединения.

3. ПОРТ:
   Используется UDP порт 5008. Убедитесь, что он не занят другим приложением и
   не заблокирован брандмауэром!

4. ПЕРЕМЫЧКА SA1:
   Если бит 0 в конфигурации устройства равен 0 (перемычка установлена), скрипт 
   выведет предупреждение и пропустит этап записи Flash, но продолжит диалог 
   с устройством.

================================================================================
6. УСТРАНЕНИЕ ТИПИЧНЫХ НЕИСПРАВНОСТЕЙ
================================================================================

ПРОБЛЕМА: Скрипт запускается, но не видит ни одного устройства.
РЕШЕНИЕ:
- Проверьте, что устройства и ПК в одной подсети (например, оба подключены в 
  простой неуправляемый коммутатор).
- Отключите Брандмауэр Windows или добавьте правило для python.exe (Порт 5008 UDP).
- Проверьте, светятся ли индикаторы сетевой активности на устройстве и коммутаторе.

ПРОБЛЕМА: Ошибка "OP_BL_LOCK_PIN" или "OP_ERR_PASS" при активации.
РЕШЕНИЕ:
- Bootloader устройства заблокировал обновление, т.к. установлена перемычка SA1

ПРОБЛЕМА: Ошибка "CMD_WRITE_UP_FLASH не выполнена" на середине прогресс-бара.
РЕШЕНИЕ:
- Нестабильное соединение или помехи по Wi-Fi.

ПРОБЛЕМА: "Файлы .bct не найдены в текущей директории".
РЕШЕНИЕ:
- Положите файл *.bct в ту же папку, где лежит скрипт .py. Расширение должно быть 
строго .bct. Имя файла должно соответствовать CRC-32 файла.

================================================================================
7. КОНТАКТЫ
================================================================================

Версия скрипта: rc3
Статус: Release Candidate

================================================================================
                                КОНЕЦ ДОКУМЕНТА
================================================================================