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

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

  • Статья

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

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

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

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

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

Сведения о соглашениях о командах IoT Pug и Play см. в самонастраивающийся соглашениях Интернета вещей.

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

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

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

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

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

Команды определяются в составе шаблона устройства. На следующем снимке экрана показано определение команды Get Max-Min report в шаблоне устройства Термостат. Команда содержит параметры запроса и ответа:

Screenshot showing Get Max Min Report command in Thermostat device template.

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

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

Сведения о языке определения цифровых двойников (DTDL), который Azure IoT Central использует для определения команд в шаблоне устройства, см. в разделе "Команды самонастраивающийся Интернета > вещей".

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

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

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

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

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

Screenshot showing how to view command payload for a standard command.

Примечание.

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

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

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

Примечание.

Длительные команды не являются частью соглашений самонастраивающийся Интернета вещей. 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 при получении обновления свойства, указывающего на завершение команды:

Screenshot that shows long-running command finished.

Автономные команды

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

Примечание.

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

Примечание.

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

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

Screenshot that shows the UI for an offline command.

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

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 часа.

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

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

Screenshot that shows an example of calling a command on an unassigned device.

Следующие шаги

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