Lorawan-stack: Пересмотрите стратегию документирования форм в консоли

Я сейчас прохожу через мастер устройства.

На первой странице давайте воспользуемся всплывающей подсказкой, чтобы ответить «что это» и «где мне это найти» для Activation Mode и LoRaWAN Version

Давайте возьмем описание из глоссария и небольшой фрагмент из описания продукта, подобного этому, с кружками или стрелками для версии LoRaWAN.

В основных настройках то же самое для AppEUI и DevEUI

В настройках сети: «что это?» Для частотных планов, а затем то же «как мне найти это» для региональных параметров с фрагментом информации о продукте.

Что касается настроек присоединения, я не уверен, что они означают, кроме AppKey, поэтому я добавлю их в глоссарий, и мы сможем делать «что это» и «где это найти» для материалов, поступающих с устройства mfr.

Я размещу описания встроенных полей в другом комментарии.

Для описаний, вместо встроенных, возможно, мы просто поставим вопросительный знак рядом с термином поля и отобразим эту информацию во всплывающей подсказке, например:

Я собираюсь обновить глоссарий именно этими определениями, чтобы мы могли извлечь эту информацию оттуда.

Режим активации:
Активация по беспроводной сети (OTAA) является предпочтительным и наиболее безопасным способом подключения устройства. Устройства выполняют процедуру присоединения к сети, во время которой назначается динамический DevAddr и с устройством согласовываются ключи безопасности.
Активация с помощью персонализации (ABP) требует жесткого кодирования DevAddr, а также ключей безопасности на устройстве. Эта стратегия может показаться более простой, поскольку вы пропускаете процедуру соединения, но у нее есть недостатки, связанные с безопасностью.
Многоадресная рассылка - это виртуальная группа устройств ABP, которая позволяет всем устройствам получать одни и те же нисходящие каналы. Группы многоадресной рассылки не поддерживают восходящие каналы.

Версия LoRaWAN: версия LoRaWAN - это спецификация LoRa Alliance LoRaWAN, которой соответствует ваше устройство, которая определяет, какие функции MAC оно поддерживает.

Идентификатор конечного устройства: уникальный, удобочитаемый идентификатор вашего устройства. Вы придумываете это, так что будьте изобретательны. Идентификаторы устройства не могут быть использованы повторно.

JoinEUI: Join EUI (ранее назывался Application EUI) - это 64-битный расширенный уникальный идентификатор, используемый для идентификации сервера присоединения во время активации. Это должно быть предоставлено производителем устройства для предварительно подготовленных устройств или владельцем сервера присоединения, который вы будете использовать.

DevEUI: 64-битный расширенный уникальный идентификатор вашего устройства. Это запрограммировано производителем и не должно изменяться. Он должен быть предоставлен вам производителем или напечатан на устройстве.

Частотный план: частотный план определяет скорости передачи данных и каналы, которые соответствуют региональным параметрам LoRaWAN для полосы или географической области. Устройства настраиваются для определенного частотного плана как часть активации и могут использовать любой частотный план в пределах поддерживаемого диапазона.

Версия региональных параметров: региональные параметры определяют частоту, время ожидания и другие параметры связи для разных географических областей. Версия региональных параметров - это версия спецификации LoRa Alliance, которую поддерживает ваше устройство. Это должно быть указано производителем устройства в техническом паспорте.

Поддерживает класс C: устройства класса C расширяют класс A, оставляя окна приема открытыми, если они не передают. Это обеспечивает связь с малой задержкой, но потребляет во много раз больше энергии, чем устройства класса A. Не все устройства поддерживают класс C, эта информация должна быть предоставлена ​​производителем устройства в таблице данных.

Установка блокировки / освобождения, поскольку нам нужно внести некоторые из этих изменений / улучшений вместе с выпуском мастера конечных устройств (# 2663).

Я свяжусь с вами как можно скорее.

Спасибо @benolayinka за эти описания.

Посмотрев на это еще раз, я думаю, что лучше использовать такую ​​стратегию документации:

• Используйте всплывающие подсказки глоссария, когда
  
  
  
  • полезно сообщить о незнакомых, сложных терминах более подробно (не ограничиваясь терминами, связанными с LoRaWAN)
  
  
  • полезно сообщить, где можно найти определенную информацию
  
  
• Используйте описания полей только тогда, когда
  
  
  
  • есть конкретная краткая информация, которая поможет пользователю при заполнении поля, например:
  
  
  • ограничения поля или информация о том, что считается допустимым вводом (например, The north-south position in degrees, where 0 is the equator )
  
  
  • быстрые уведомления о том, где можно найти необходимую информацию (например, The LoRaWAN version (MAC), as provided by the device manufacturer )
  
  
  • информация о том, что, вероятно, является желаемым вводом (например, Recommended for all gateways in order to respect spectrum regulations )
  
  
  • нет доступной записи в глоссарии, и можно (и необходимо) уточнить использование поля и / или значение в нескольких словах (в противном случае создайте запись в глоссарии)
  
  
  • он не повторяет информацию, которая уже может быть легко получена из имени поля и заполнителя, или из всплывающей подсказки глоссария (например, Gateway can be updated automatically , это ясно из самого заголовка поля)
  
  

Я добавлю это в наши рекомендации по дизайну вместе с PR, который представит всплывающие подсказки глоссария.

Следующим шагом будет соответствующее обновление глоссария и реализация # 2663. Ставим это на блокировку, пока они не будут готовы.

Режим активации:
Активация по беспроводной сети (OTAA) является предпочтительным и наиболее безопасным способом подключения устройства. Устройства выполняют процедуру присоединения к сети, во время которой назначается динамический DevAddr и с устройством согласовываются ключи безопасности.
Активация с помощью персонализации (ABP) требует жесткого кодирования DevAddr, а также ключей безопасности на устройстве. Эта стратегия может показаться более простой, поскольку вы пропускаете процедуру соединения, но у нее есть недостатки, связанные с безопасностью.
Многоадресная рассылка - это виртуальная группа устройств ABP, которая позволяет всем устройствам получать одни и те же нисходящие каналы. Группы многоадресной рассылки не поддерживают восходящие каналы.

Версия LoRaWAN: версия LoRaWAN - это спецификация LoRa Alliance LoRaWAN, которой соответствует ваше устройство, которая определяет, какие функции MAC оно поддерживает.

Идентификатор конечного устройства: уникальный, удобочитаемый идентификатор вашего устройства. Вы придумываете это, так что будьте изобретательны. Идентификаторы устройства не могут быть использованы повторно.

JoinEUI: Join EUI (ранее назывался Application EUI) - это 64-битный расширенный уникальный идентификатор, используемый для идентификации сервера присоединения во время активации. Это должно быть предоставлено производителем устройства для предварительно подготовленных устройств или владельцем сервера присоединения, который вы будете использовать.

DevEUI: 64-битный расширенный уникальный идентификатор вашего устройства. Это запрограммировано производителем и не должно изменяться. Он должен быть предоставлен вам производителем или напечатан на устройстве.

Частотный план: частотный план определяет скорости передачи данных и каналы, которые соответствуют региональным параметрам LoRaWAN для полосы или географической области. Устройства настраиваются для определенного частотного плана как часть активации и могут использовать любой частотный план в пределах поддерживаемого диапазона.

Версия региональных параметров: региональные параметры определяют частоту, время ожидания и другие параметры связи для разных географических областей. Версия региональных параметров - это версия спецификации LoRa Alliance, которую поддерживает ваше устройство. Это должно быть указано производителем устройства в техническом паспорте.

Поддерживает класс C: устройства класса C расширяют класс A, оставляя окна приема открытыми, если они не передают. Это обеспечивает связь с малой задержкой, но потребляет во много раз больше энергии, чем устройства класса A. Не все устройства поддерживают класс C, эта информация должна быть предоставлена ​​производителем устройства в таблице данных.

Глоссарий готов с этими терминами # 2741

Какой здесь статус?

Весь этот комплекс форм UX нуждается в некоторой консолидации в решаемые проблемы. Это все еще в моем списке, над которым нужно работать после текущих высокоприоритетных проблем.

Здорово! Удаление состояния обсуждения, чтобы сделать его более действенным. При необходимости вернитесь.

Можем ли мы сделать это действенным?

@kschiffer можем ли мы начать с низко висящих фруктов?

Заменено на № 3522, в котором есть конкретный и действенный план нового макета формы и стратегии документации.

Это также частично интегрирует работу @benolayinka в этот выпуск.