Приложение nRF Util [1] это пакет Python и утилита командной строки, которая поддерживает процедуру обновления Device Firmware Update (DFU) [2] и криптографический функционал для цифровой подписи и проверки кода firmware.
Приложение nRF Util и его библиотека обеспечивает следующие функции:
• Генерация пакета обновления DFU (DFU package). • Генерация криптографических ключей, их обслуживание и хранение. • Генерация настроек загрузчика (bootloader settings). • Поддержка процедуры DFU с передачей образа firmware по следующим протоколам: - Bluetooth® Low Energy (BLE) - Serial over UART - Serial over USB - Thread unicast - Thread multicast - Zigbee - ANT™.
Примечание: расшифровку незнакомых терминов и аббревиатур см. в Словарике [13].
Существует два разных пакета обновления DFU:
Legacy – использует простую структуру, не поддерживает функции безопасности. Modern – использует буферы протокола Google [12] для сериализации, и может использовать криптографическую сигнатуру образа firmware.
Переход на новый формат DFU-пакета Modern произошел в nRF5 SDK v12.0.0 (до этого использовался формат Legacy). В зависимости от версии SDK, которую Вы используете, выбелите совместимую версию релиза nRF Util:
• Версия 0.5.x генерирует legacy-пакеты firmware, совместимые с nRF5 SDK v11.0.0 или более старой версии. • Версия 1.5.0 генерирует современные modern-пакеты firmware, совместимые с nRF5 SDK v12.0.0 и более новой версии. • Версия 2.2.0 или более новая требует генерации страницы настроек загрузчика, которая совместима с nRF52840. • Версия 4.0.0 и более новая генерирует modern-пакеты firmware, совместимые с nRF5 SDK v15.1.0 и более новой версии. • Версия 5.0.0 и более новая генерирует modern-пакеты firmware, совместимые с nRF5 SDK v15.3.0 и более новой версии.
Примечание: чтобы создать образы firmware, совместимые с версиями от nRF SDK 12.0 до nRF SDK 15.0, используйте команду --no-backup при генерации настроек DFU.
Более подробно про DFU см. статьи [2, 3, 4] и примеры из SDK.
Система получения помощи по командам nRF Util чувствительна к контексту, т. е. можно получить подсказку по конкретной команде. Для получения подсказки по командной строки добавьте опцию --help к любой команде nRF Util, отобразится подсказка по соответствующей команде. Может быть также получена подсказка не только по команде, но и по конкретному протоколу.
Например, команда nrfutil dfu ble --help выведет подсказку по процедуре обновления (Device Firmware Update, DFU) по протоколу Bluetooth LE (BLE):
nrfutil dfu ble --help
Чтобы узнать опции, доступные для протокола Zigbee, введите следующую команду:
nrfutil zigbee --help
Общая подсказка по использованию будет отображена, если просто ввести nrfutil --help.
[Генерация пакетов DFU]
Команда pkg генерирует пакет, используемый для DFU. Пакет содержит образ нового firmware, init-пакет и файл манифеста, который показывает формат пакета. Эта команда также может использоваться для отображения содержимого пакета.
Запуск команды nrfutil pkg приведет к генерации zip-файла пакета, который Вы можете использовать позже вместе с мобильным приложением или другой утилитой для обновления firmware устройства на основе nRF5 MCU. Подсказку по доступным опциям команды pkg можно получить командой nrfutil pkg generate --help.
Следующая команда создаст пакет app_dfu_package.zip из файла приложения app.hex с версией приложения 4, которая требует версии аппаратуры 51 и SoftDevice S130 v2.0.0 (0x80), и также подписанного приватным ключом, сохраненным в файле key.pem:
Ведите следующую команду, чтобы отобразить содержимое созданного пакета:
nrfutil pkg display app_dfu_package.zip
Опция --hw-version должна соответствовать используемому nRF5 MCU.
Опция --sd-req должна соответствовать firmware ID (идентификатору) кода SoftDevice, который присутствует в целевом MCU. Список идентификаторов SoftDevice firmware ID (для опции --sd-req) будет показан командой nrfutil pkg generate --help.
Примечание: хотя стеки Thread и Zigbee не используют SoftDevice, опция --sd-req все равно нужна для обеспечения совместимости. Во время процесса DFU любое значение, предоставленное для этой опции, будет игнорироваться.
При генерации пакета доступны не любые комбинации загрузчика, SoftDevice и приложения. Для дополнительной информации по поддерживаемым комбинациям Bootloader, SoftDevice и Application см. статью [5].
[Выполнение процесса обновления]
Команда dfu передает пакет Device Firmware Update (DFU) в устройство на основе nRF5 MCU. Для передачи доступно несколько вариантов транспорта DFU. Для отображения списка поддерживаемых транспортов введите команду:
nrfutil dfu --help
Необходимо гарантировать, чтобы выбранный транспорт соответствовал загрузчику DFU, который установлен в целевом MCU.
Используйте nRF5 Development Kit (DK, отладочная плата с nRF5x MCU) в качестве connectivity-устройства (т. е. устройства, через которое происходит передача firmware) для процедуры обновления DFU по воздуху по протоколу Bluetooth LE. Для обновления выполните следующие шаги:
1. Подключите nRF5 DK к своему компьютеру.
Примечание: в опции -ic нужно указать, какого семейства чип в DK nRF51 - или nRF52.
2. Запустите команду nrfjprog --eraseall, чтобы стереть содержимое памяти чипа в DK.
3. Запустите команду nrfutil dfu ble, чтобы выполнить полное DFU по протоколу Bluetooth LE. Используйте опцию -f для программирования DK необходимым connectivity software. Эта опция перезапишет содержимое памяти DK MCU.
Введите команду nrfutil dfu ble --help, чтобы посмотреть доступные опции.
Например, для выполнения процедуры DFU пакета app_dfu_package.zip по протоколу Bluetooth LE на устройстве nRF52, подключенного через COM3, где MyDevice это доступное по радио устройство (remote Bluetooth LE device), которое должно быть обновлено, введите следующую команду:
Для выполнения DFU через ANT в качестве connectivity-устройства (т. е. устройства, через которое происходит передача firmware) используется ANT™ USB dongle (например ANT USB-m). Для обновления выполните следующие шаги:
1. Подключите ANT USB dongle к компьютеру.
2. Запустите nrfutil dfu ant для выполнения полного DFU через ANT.
Доступные опции можно посмотреть командой:
nrfutil dfu ant --help
Например, введите следующую команду, чтобы выполнить процедуру DFU файлом пакета app_dfu_package.zip:
Используйте nRF5 Development Kit (DK, отладочная плата с nRF5x MCU) в качестве connectivity-устройства (т. е. устройства, через которое происходит передача firmware) для процедуры обновления DFU через Thread.
Для DFU over Thread утилита nRF Util поддерживает как режим unicast, так и режим multicast. В режиме unicast каждый клиент DFU индивидуально запрашивает от nRF Util последовательные блоки firmware. В режиме multicast утилита nRF Util последовательно посылает блоки firmware в multicast-сообщениях, и клиенты, которым нужно новое firmware, принимают и обрабатывают эти сообщения.
Режим по умолчанию unicast. Чтобы выбрать режим multicast, вызовите nRF Util с multicast-адресом в качестве адреса назначения.
Для обновления выполните следующие шаги:
1. Подключите nRF5 DK к своему компьютеру. Плата DK работает как Thread network co-processor (NCP), чтобы выполнить процедуру DFU на целевом MCU.
2. Запустите команду nrfjprog --eraseall чтобы стереть содержимое памяти DK MCU.
3. Выполните команду nrfutil dfu thread, чтобы выполнить полное DFU через Thread. Используйте опцию -f для программирования DK необходимым connectivity software. Эта опция перезапишет содержимое памяти DK MCU.
Введите команду nrfutil dfu thread --help, чтобы посмотреть доступные опции.
Например, введите следующую команду для инициирования процедуры unicast DFU для файла пакета app_dfu_package.zip через Thread на канале channel 11 вместе с идентификатором PAN ID 0xABCD, используя nRF52840 NCP, подключенный через COM3:
Любое доступное по радио Thread-устройство может затем запросить обновление firmware.
Введите следующую команду, чтобы выполнить процедуру multicast DFU для пакета app_dfu_package.zip через Thread на канале 11 вместе с идентификатором PAN ID 0xABCD на multicast-адрес FF03::1, используя nRF52840 NCP, подключенный через COM3:
Используйте nRF5 Development Kit (DK, отладочная плата с nRF5x MCU) в качестве connectivity-устройства (т. е. устройства, через которое происходит передача firmware) для процедуры обновления DFU через Zigbee.
Сначала запустите следующую команду, чтобы сгенерировать специальный Zigbee-образ из своего приложения:
Процедура DFU over Zigbee выполняется путем загрузки образа обновления в OTA Server, работающий на DK MCU. Для обновления выполните следующие шаги:
1. Подключите nRF5 DK к своему компьютеру. Плата DK работает как Zigbee OTA Server, который распространяет образ Zigbee в радиосети.
2. Выполните команду nrfutil dfu zigbee, чтобы запустить Zigbee OTA Server, который будет распространять новое firmware в сети.
Введите команду nrfutil dfu zigbee --help, чтобы посмотреть доступные опции.
Процесс DFU over Zigbee немедленно завершится после загрузки образа, но OTA Server останется активным до сброса DK.
Например, введите следующую команду, чтобы запустить Zigbee OTA Server, который распространяет файл CAFE-1234-good_image.zigbee на канале 20, используя nRF52840 DK с серийным номером 683604699:
Обновление внешних приложений. Пакеты для обновления внешних приложений могут быть сгенерированы утилитой nRF Util путем установки опции –external-app.
nRF Util поддерживает обновление Device Firmware Update (DFU) через последовательное соединение UART.
Для обновления выполните следующие шаги:
1. Подключите DFU target к своему компьютеру.
У большинства китов разработчика (Development Kit, DK) от Nordic Semiconductor есть на борту MCU интерфейса, который работает как виртуальный COM-порт, прозрачно отображающий UART в интерфейс USB CDC ACM, доступный на компьютере (дополнительную информацию см. [6]). Если MCU интерфейса недоступен, используйте другие варианты последовательного подключения DFU target к своему компьютеру, например через адаптер USB - TTL UART.
2. Запустите команду nrfutil dfu serial, чтобы выполнить полное обновление DFU через последовательное соединение UART.
Введите команду nrfutil dfu serial --help, чтобы посмотреть доступные опции.
Следующий пример команды выполнит процедуру обновления файлом пакета app_dfu_package.zip через COM3 на скорости 115200 бит в секунду:
nrfutil dfu serial -pkg app_dfu_package.zip -p COM3 -b 115200
nRF Util поддерживает обновление Device Firmware Update (DFU) через соединение USB CDC ACM (виртуальный COM-порт). Соединение DFU over a serial USB поддерживается только на тех MCU, у которых есть ножки USB (например, nRF52840).
Примечание: не путайте интерфейсный MCU с целевым MCU, который программируется через DFU. Порт USB интерфейсного MCU (см. [6]) это совсем не то, что здесь имеется в виду. Интерфейсный MCU не подключается к ножкам USB программируемого через DFU чипа MCU. Если вы хотите использовать интерфейсный MCU, то должны выполнить DFU через последовательное соединение UART (см. предыдущую врезку).
Для обновления выполните следующие шаги:
1. Подключите DFU target к своему компьютеру. Если Ваш DFU target это nRF52840 Development Kit (DK), то используйте его порт USB, помеченный шелкографией nRF USB.
2. Запустите nrfutil dfu usb-serial, чтобы выполнить полную процедуру DFU через соединение USB CDC ACM.
Введите команду nrfutil dfu usb-serial --help, чтобы посмотреть доступные опции.
Например, следующая команда выполнит DFU файлом пакета app_dfu_package.zip через COM3 на скорости 115200 бит в секунду:
Команда keys может использоваться для генерации и просмотра криптографических ключей. Эти ключи требуются для подписи и проверки пакета DFU, дополнительную информацию см. в [7].
• Выполните команду nrfutil keys generate для генерации приватного приватного ключа (ключа подписи), и сохранение его в файл формата PEM.
• Выполните команду nrfutil keys display, чтобы показать приватный (подписывающий) или публичный (проверяющий) ключ из PEM-файла.
Вы можете просмотреть список доступных опций, если запустите команду:
nrfutil keys display --help
Например, введите следующую команду, чтобы сгенерировать private-ключ и сохранить его в файл private.pem:
nrfutil keys generate private.pem
Введите следующую команду, чтобы отобразить public-ключ в формате кода из этого файла ключа:
Используйте команду settings, чтобы сгенерировать и отобразить страницу настроек загрузчика (bootloader settings page).
DFU bootloader требует наличие страницы настроек, которая содержит информацию о текущем процессе DFU. Кроме того, страница настроек загрузчика может содержать информацию об установленном приложении и версии firmware.
• Выполните команду nrfutil settings generate, чтобы сгенерировать bootloader settings page, и сохранить её в HEX-файл.
Список доступных опций можно посмотреть командой:
nrfutil settings generate --help
• Выполните команду nrfutil settings display, чтобы отобразить содержимое страницы настроек загрузчика, которая представлена в HEX-файле. Чтобы прочитать страницу настроек загрузчика из запрограммированного MCU, используйте утилиту nrfjprog, чтобы создать дамп памяти FLASH (здесь HEX_file это имя дампа страницы в формате Intel HEX):
nrfjprog --readcode HEX_file
После генерации страницы настроек загрузчика Вы можете использовать mergehex и nrfjprog, чтобы запрограммировать её в память FLASH MCU. Для дополнительной информации по использованию утилит командной строки см. [8].
Например, введите следующую команду, чтобы сгенерировать bootloader settings page для MCU nRF52840 с установленным приложением app.hex, версией приложения 3, версией загрузчика 2, и версией настроек загрузчика 1 (для SDK v13.0.0), и сохранить эти сгенерированные настройки в файл settings.hex:
Введите следующую команду, чтобы отобразить содержимое сгенерированного HEX-файла:
nrfutil settings display settings.hex
Для каждого MCU семейств nRF должна быть соответствующая опция --family:
Таблица 1. Настройка --family.
Семейство nRF5x
Чипы MCU
NRF51
nRF51xxx
NRF52
nRF52832, nRF52833
NRF52QFAB
nRF52832-QFAB, nRF52820
NRF52810
nRF52810, nRF52811, nRF52805
NRF52840
nRF52840
Опция --bl-settings-version зависит от версии SDK:
Таблица 2. Версии SDK и BL.
Версия SDK
Настройка версии загрузчика (BL)
12.0
1
15.3.0
2
Поддерживаемые версии настроек DFU bootloader для выбранного Вами SDK перечислены в файле nrf_dfu_types.h библиотеки загрузчика. Хотя загрузчики, скомпилированные из nRF5 SDK 15.3.0 или более новой версии, могут использовать только версию 2, они могут быть сконфигурированы для поддержки страницы настроек версии 1. Когда загружается новый загрузчик с версией 1 настроек, перед загрузкой код загрузчика транслирует страницу настроек в версию 2. Если используется версия 2 настроек, то проверка загрузки для SoftDevice и приложения может быть сгенерирована со страницей загрузки с использованием команд --sd-boot-validation и --app-boot-validation.
[Генерация HEX-файлов для Zigbee]
Используйте команду zigbee production_config, чтобы генерировать HEX-файлы с производственной конфигурацией (production configuration) для устройств Zigbee. Эти HEX-файлы могут использоваться для установки блока FLASH-памяти production configuration в стеке Zigbee при работе с nRF5 SDK для Thread и Zigbee (см. [9]).
• Создайте входной файл yaml, который содержит список требуемых значений, используемых для генерации HEX-файла production configuration.
Введите следующую команду для примера ввода yaml и других доступных опций:
nrfutil zigbee production_config --help
• Выполните команду nrfutil zigbee production_config с предоставлением имен входного и выходного файлов, чтобы сгенерировать двоичный файл в формате Intel HEX.
Например, введите следующую команду, чтобы сгенерировать файл output.hex для production configuration из файла input.yaml:
Команда version может использоваться для вывода версии утилиты. Разные версии nRF Util поддерживают разные форматы init-пакета, который является частью пакета DFU. Используйте ту версию nRF Util, которая соответствует загрузчику DFU, запрограммированному в Ваш MCU.
Введите следующую команду, чтобы отобразить версию nRF Util:
nrfutil version
[Пользовательский init-пакет]
init-пакет это пакет, который посылается перед реальной отправкой образов firmware процесса обновления Device Firmware Update (DFU). В init-пакете содержатся метаданные, описывающие DFU, такие как размер и тип образа, информация версии и требования к совместимости.
Для кастомизации инструментария необходимо клонировать репозиторий GitHub утилиты nRF Util [10] (см. описание установки из исходного кода [11]). Если Вы используете формат пакета по умолчанию, как описано в примере защищенного загрузчика BLE DFU [4], то не нужно модифицировать nRF Util. Если Вам нужно определить свой собственный формат для init-пакета, то кроме модификации nRF Util необходимо также изменить реализацию загрузчика DFU, чтобы он использовал этот новый формат.
Формат init-пакета определен в буферах протокола (Protocol buffers), файл .proto. Этот файл может быть скомпилирован в разные форматы для гарантии, что используется тот же формат init-пакета, как в Вашей реализации загрузчика DFU и nRF Util.
Примечание: определение init-пакета требует версии proto2 для языка protocol buffers. Не подключайте syntax = "proto3"; в своем файле protocol buffer, потому что это приведет к интерпретации файла как версии языка proto3.
Выполните следующие шаги для кастомизации init-пакета:
1. Измените файл protocol buffer, чтобы он подошел для Ваших требований.
В репозитории nRF Util [10] этот файл находится в nordicsemi/dfu/dfu-cc.proto. В примере защищенного загрузчика BLE DFU [4] из nRF5 SDK этот файл находится в examples/dfu/bootloader_secure/dfu-cc.proto. Проверьте, что оба файла имеют одинаковое содержимое.
2. Загрузите и установите компилятор протокола [12] от Google.
3. Адаптируйте nRF Util для использования нового формата init-пакета:
(a) Скомпилируйте файл protocol buffer, чтобы сгенерировать соответствующий файл на языке Python. В папке, которая содержит Ваш файл dfu-cc.proto, введите следующую команду (здесь dest_folder это пустая папка, куда компилятор протокола будет записывать свой вывод):
protoc --python_out=dest_folder dfu-cc.proto
(b) Скопируйте или переместите созданный файл dest_folder/dfu_cc_pb2.py в каталог nordicsemi/dfu/, с перезаписью существующего файла.
(c) Если Вы добавили новую информацию в init-пакет, то необходимо обновить nRF Util. Адаптируйте nRF Util, чтобы она поддерживала новые опции командной строки для новых полей, и добавьте в init-пакет информацию, предоставляемую этими опциями. Чтобы адаптировать nRF Util, Вы должны отредактировать исходные файлы на языке Python. Содержимое init-пакета определено в файлах nordicsemi/dfu/init_packet_pb.py и nordicsemi/dfu/package.py. Опции командной строки определены в nordicsemi/__main__.py.
Если Вы установили nRF Util в локальные пакеты Python и папку script, или создали самостоятельно запускаемый файл (см. [11]), то должны повторить эту процедуру после редактирования исходных файлов.
4. Адаптируйте свою реализацию DFU bootloader, чтобы он использовал новый формат init-пакета:
(a) Убедитесь, что файл dfu-cc.proto находится в папке обработке запроса (по умолчанию это папка examples/dfu/dfu_req_handling/, которая находится в SDK), и это тот же самый файл, который использовался для адаптации nRF Util.
(b) В папке реализации DFU bootloader введите следующую команду, эта команда создаст файл dfu-cc.pb:
protoc -odfu-cc.pb dfu-cc.proto
(c) Если Вы не работаете в папке examples/dfu/dfu_req_handling/, сделайте копию файла dfu-cc.options из этой папки в папку со своей реализацией.
(d) Запустите скрипт nanopb_generator.py (находится в папке external/nano-pb/generator/), чтобы сгенерировать требуемые файлы dfu-cc.pb.c и dfu-cc.pb.h. Если Вы работаете в examples/dfu/dfu_req_handling/, то введите следующую команду:
