Поделиться через

Использование команд в решении Azure IoT Central

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

Оператор может использовать пользовательский интерфейс IoT Central для вызова команды на устройстве. Команды управляют поведением устройства. Например, оператор может вызвать команду для перезагрузки устройства или сбора диагностических данных.

Устройство может:

  • Немедленное реагирование на команду.
  • Ответьте IoT Central при получении команды, а затем сообщите IoT Central, когда длительная команда будет завершена.

По умолчанию команды ожидают, что устройство подключено, и завершатся ошибкой, если к устройству невозможно подключиться. Если вы выберите опцию Очередь, если в автономном режиме в пользовательском интерфейсе шаблона устройства, команда может быть поставлена в очередь, пока устройство не подключится к сети. Эти автономные команды описаны в отдельном разделе далее в этой статье.

Дополнительные сведения о соглашениях о командах IoT Plug and Play см. в соглашениях IoT Plug and Play.

Дополнительные сведения о данных команд, обменяющихся устройством с IoT Central, см. в статье Телеметрия, свойства и полезные данные команд.

Чтобы узнать, как управлять командами с помощью REST API IoT Central, см. инструкции по управлению устройствами с помощью REST API IoT Central.

Сведения о реализации команд на устройстве без использования пакетов SDK для устройств см. в статье "Обмен данными с центром Интернета вещей" с помощью протокола MQTT.

Определение команд

Стандартные команды отправляются на устройство, чтобы указать устройству делать что-то. Команда может включать параметры с дополнительными сведениями. Например, команда для открытия клапана на устройстве может иметь параметр, указывающий, сколько нужно открыть клапан. Команды также могут получить возвращаемое значение, когда устройство завершит команду. Например, команда, которая просит устройство запустить диагностику, может получить отчет диагностики как возвращаемое значение.

Команды определяются как часть шаблона устройства. В следующем снимке экрана показано определение команды Get Max-Min в шаблоне устройства Thermostat. Эта команда имеет параметры запроса и ответа:

Снимок экрана: команда Get Max Min Report в шаблоне устройства Thermostat.

В следующей таблице показаны параметры конфигурации для возможности команды:

Поле Description
Отображаемое имя Значение команды, используемое на плитках панели мониторинга и формах устройств.
Имя Имя команды. IoT Central создает значение для этого поля из отображаемого имени, но при необходимости можно выбрать собственное значение. Это поле должно быть буквенно-цифровым. Код устройства использует это значение Name .
Тип возможностей Команда.
Очередь, если офлайн Следует ли сделать эту команду автономной командой.
Description Описание возможностей команд.
Комментарий Комментарии по поводу возможностей команды.
Просьба Полезные данные для команды устройства.
Ответ Полезная нагрузка ответа команды устройства.

Чтобы узнать о языке определения цифровых двойников (DTDL), который Azure IoT Central использует для определения команд в шаблоне устройства, см. раздел Команды в соглашениях IoT Plug and Play>.

Необязательные поля, такие как отображаемое имя и описание, позволяют добавлять дополнительные сведения в интерфейс и возможности.

Стандартные команды

Для обработки стандартной команды устройство отправляет значение ответа сразу после получения команды из IoT Central. Пакет SDK для устройств Интернета вещей Azure можно использовать для обработки стандартных команд, вызываемых приложением IoT Central.

Примеры реализации на нескольких языках см. в руководстве. Создание и подключение клиентского приложения к приложению Azure IoT Central.

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

Снимок экрана, показывающий, как просмотреть нагрузку команды для стандартной команды.

Замечание

Для стандартных команд существует время ожидания в 30 секунд. Если устройство не отвечает в течение 30 секунд, IoT Central предполагает, что команда не удалась. Этот период ожидания не настраивается.

Долго выполняющиеся команды

В длительной команде устройство не сразу завершает команду. Вместо этого устройство подтверждает получение команды, а затем подтверждает, что команда завершена. Такой подход позволяет устройству выполнять длительные операции, не сохраняя подключение к IoT Central открытым.

Замечание

Длительные команды не являются частью конвенций IoT Plug and Play. IoT Central имеет собственное соглашение о реализации выполнения длительных команд.

В этом разделе показано, как устройство может отложить отправку подтверждения о завершении команды.

В следующем фрагменте кода показано, как устройство может реализовать долго выполняющуюся команду:

Замечание

В этой статье используется Node.js для простоты.

client.onDeviceMethod('rundiagnostics', commandHandler);

// ...

const commandHandler = async (request, response) => {
  switch (request.methodName) {
  case 'rundiagnostics': {
    console.log('Starting long-running diagnostics run ' + request.payload);
    await sendCommandResponse(request, response, 202, 'Diagnostics run started');

    // Long-running operation here
    // ...

    const patch = {
      rundiagnostics: {
        value: 'Diagnostics run complete at ' + new Date().toLocaleString()
      }
    };

    deviceTwin.properties.reported.update(patch, function (err) {
      if (err) throw err;
      console.log('Properties have been reported for component');
    });
    break;
  }
  default:
    await sendCommandResponse(request, response, 404, 'unknown method');
    break;
  }
};

Вызов функции onDeviceMethod настраивает метод commandHandler. Этот обработчик команд:

  1. Проверяет имя команды.
  2. Вызывает sendCommandResponse, чтобы отправить ответ обратно в IoT Central. Этот ответ включает 202 код ответа для указания ожидающих результатов.
  3. Завершает длительную операцию.
  4. Использует сообщаемое свойство с тем же именем, что и команда, чтобы сообщить IoT Central о завершении команды.

На следующем снимках экрана показан пользовательский интерфейс IoT Central при получении обновления свойства, указывающего, что команда завершена:

Снимок экрана: долго выполняющаяся команда.

Оффлайн команды

В этом разделе показано, как устройство обрабатывает автономную команду. Если устройство подключено к сети, оно может обрабатывать автономную команду сразу после получения. Если устройство находится в автономном режиме, оно обрабатывает автономную команду при следующем подключении к IoT Central. Устройства не могут отправлять возвращаемое значение в ответ на автономную команду.

Замечание

Автономные команды не являются частью соглашений IoT Plug and Play. IoT Central имеет собственное соглашение о реализации команд для работы в автономном режиме.

Замечание

В этой статье используется Node.js для простоты.

На следующем снимке экрана показана автономная команда GenerateDiagnostics. Параметр запроса — это объект с свойством datetime с именем StartTime и целочисленным свойством перечисления с именем Bank:

Снимок экрана: пользовательский интерфейс для автономной команды.

В следующем фрагменте кода показано, как клиент может прослушивать автономные команды и отображать содержимое сообщения:

client.on('message', function (msg) {
  console.log('Body: ' + msg.data);
  console.log('Properties: ' + JSON.stringify(msg.properties));
  client.complete(msg, function (err) {
    if (err) {
      console.error('complete error: ' + err.toString());
    } else {
      console.log('complete sent');
    }
  });
});

Выходные данные из предыдущего фрагмента кода показывают структуру данных со значениями StartTime и Bank. Список свойств включает имя команды в элементе списка method-name.

Body: {"StartTime":"2021-01-06T06:00:00.000Z","Bank":2}
Properties: {"propertyList":[{"key":"iothub-ack","value":"none"},{"key":"method-name","value":"GenerateDiagnostics"}]}

Замечание

Время жизни по умолчанию для автономных команд — 24 часа, после чего истекает срок действия сообщения.

Команды на неназначенных устройствах

Вы можете вызывать команды на устройстве, которое не назначено шаблону устройства. Чтобы вызвать команду на неназначаемом устройстве, перейдите к устройству в разделе "Устройства ", выберите "Управление устройством " и " Команда". Введите имя метода, нагрузку и любые другие обязательные значения. На следующем снимке экрана показан пользовательский интерфейс, используемый для вызова команды:

Снимок экрана: пример вызова команды на неназначенных устройствах.

Дальнейшие шаги

Теперь, когда вы знаете, как использовать команды в вашем приложении Azure IoT Central, просмотрите данные телеметрии, свойства и полезные нагрузки команды , чтобы узнать больше о параметрах команд, и изучите создание и подключение клиентского приложения к приложению Azure IoT Central , чтобы увидеть полные примеры кода на разных языках.

  • Last updated on