IoT Platform:Uso de las funciones básicas

Obtención de IoT as Bridge SDK

IoT Platform ofrece una demostración de IoT as Bridge SDK. Para obtener más información, visite alibabacloud-iot-bridge-core-demo.

Diagrama de flujo

La siguiente figura muestra el diagrama de flujo para conectar un dispositivo a IoT Platform mediante IoT as Bridge SDK.

Despliegue del entorno de desarrollo

Despliegue un entorno de desarrollo Java y agregue la siguiente dependencia a su proyecto Maven para importar IoT as Bridge SDK:

<dependency>
  <groupId>com.aliyun.openservices</groupId>
  <artifactId>iot-as-bridge-sdk-core</artifactId>
  <version>2.4.1</version>
</dependency>

Inicialización

Inicializar el SDK

Cree un objeto BridgeBootstrap y llame al método bootstrap(). Este método registra la devolución de llamada DownlinkChannelHandler en IoT as Bridge SDK para recibir mensajes descendentes desde IoT Platform.

Una vez inicializado IoT as Bridge SDK, este lee la información del puente y envía una solicitud de conexión a IoT Platform en nombre del puente.

Código de ejemplo:

BridgeBootstrap bridgeBootstrap = new BridgeBootstrap();
bridgeBootstrap.bootstrap(new DownlinkChannelHandler() {
    @Override
    public boolean pushToDevice(Session session, String topic, byte[] payload) {
        // Receive downstream messages from IoT Platform. 
        String content = new String(bytes);
        log.info("Get DownLink message, session:{}, {}, {}", session, topic, content);
        return true;
    }

    @Override
    public boolean broadcast(String topic, byte[] payload) {
        return false;
    }
});

Configurar un puente

• De forma predeterminada, un puente se configura mediante el archivo de configuración application.conf ubicado en el directorio src/main/resources/ del proyecto Java. El formato del archivo es HOCON, que es un superconjunto de JSON.

  IoT as Bridge SDK analiza sintácticamente el archivo de configuración basándose en los ajustes del archivo typesafe.config.

• Es posible registrar un puente dinámicamente o configurar directamente sus parámetros.

  Para obtener más información sobre cómo registrar un dispositivo dinámicamente, consulte la sección Dynamically register bridges del tema "Uso de las funciones avanzadas". La siguiente tabla describe los parámetros de un puente.

  Parámetro	Obligatorio	Descripción
  productKey	Sí	ProductKey del producto al que pertenece el puente.
  deviceName	Sí	DeviceName del puente.
  deviceSecret	Sí	DeviceSecret del puente.
  subDeviceConnectMode	No	Tipo de puente. Si este parámetro se establece en 3, se crea un puente de gran tamaño. Se pueden conectar hasta 500,000 dispositivos al puente. Si no se especifica este parámetro, se crea un puente de pequeño tamaño. Se pueden conectar hasta 1,500 dispositivos al puente. Los puentes de gran y pequeño tamaño utilizan políticas diferentes para desconectar dispositivos. Para obtener más información, consulte Disconnect a device from IoT Platform.
  http2Endpoint	Sí	Endpoint de la puerta de enlace HTTP/2. Este endpoint se utiliza para establecer una conexión persistente entre el puente e IoT Platform mediante el protocolo HTTP/2. Formato del endpoint: Instancias Enterprise Edition: https://${IotInstanceId}.http2.iothub.aliyuncs.com:443. Reemplace ${IotInstanceId} con el ID de la instancia que adquirió. Por ejemplo, si el ID de la instancia es iot-cn-g06kwb**, el endpoint es https://iot-cn-g06kwb**.http2.iothub.aliyuncs.com:443. Instancias públicas: El formato del endpoint para las instancias públicas de la nueva versión difiere del formato de las instancias públicas de la versión anterior. Las instancias públicas de la nueva versión utilizan el mismo formato de endpoint que las instancias Enterprise Edition. Instancias públicas de la versión anterior: https://${productKey}.iot-as-http2.${RegionId}.aliyuncs.com:443. Reemplace ${productKey} con el ProductKey del producto al que pertenece su puente. Reemplace ${RegionId} con el ID de la región donde reside su servicio de IoT Platform. Para obtener más información sobre los ID de región, consulte Regions and Zones. Por ejemplo, si el ProductKey de un puente es a1abcab** y la instancia pública reside en la región China (Shanghai), el endpoint es https://a1abcab**.iot-as-http2.cn-shanghai.aliyuncs.com:443. Para obtener más información sobre las instancias de IoT Platform, consulte Overview.
  authEndpoint	Sí	Endpoint del servicio de verificación de dispositivos. Formato del endpoint: Instancias Enterprise Edition: https://${IotInstanceId}.auth.iothub.aliyuncs.com/auth/bridge. Reemplace ${IotInstanceId} con el ID de la instancia que adquirió. Por ejemplo, si el ID de la instancia es iot-cn-g06kwb**, el endpoint es https://iot-cn-g06kwb**.auth.iothub.aliyuncs.com/auth/bridge. Instancias públicas: El formato del endpoint para las instancias públicas de la nueva versión difiere del formato de las instancias públicas de la versión anterior. Las instancias públicas de la nueva versión utilizan el mismo formato de endpoint que las instancias Enterprise Edition. Instancias públicas de la versión anterior: https://iot-auth.${RegionId}.aliyuncs.com/auth/bridge. Reemplace ${RegionId} con el ID de la región donde reside su servicio de IoT Platform. Para obtener más información sobre los ID de región, consulte Regions and Zones. Por ejemplo, si una instancia reside en la región China (Shanghai), el endpoint es https://iot-auth.cn-shanghai.aliyuncs.com/auth/bridge.

  El siguiente código de ejemplo muestra cómo configurar un puente de pequeño tamaño. En este ejemplo se utiliza una instancia Enterprise Edition.

  // The endpoints of services.
  http2Endpoint = "https://iot-2w****.http2.iothub.aliyuncs.com:443"
  authEndpoint = "https://iot-2w****.auth.iothub.aliyuncs.com/auth/bridge"
  
  // The parameters of the bridge.
  productKey = ${bridge-ProductKey-in-Iot-Plaform}
  deviceName = ${bridge-DeviceName-in-Iot-Plaform}
  deviceSecret = ${bridge-DeviceSecret-in-Iot-Plaform}

Verificar un dispositivo y conectarlo a IoT Platform

Conectar un dispositivo a IoT Platform

El siguiente código de ejemplo muestra cómo conectar un dispositivo a IoT Platform mediante IoT as Bridge SDK:

/**
 * Verify a device. 
 * @param newSession: the device session information that is returned in a downstream callback. 
 * @param originalIdentity: the original identifier of the device. 
 * @return
 */
public boolean doOnline(Session newSession, String originalIdentity);

Cuando un dispositivo se conecta a IoT Platform, envía una Session a la plataforma. Cuando IoT Platform envía un mensaje descendente, la Session se transmite al puente mediante una función de devolución de llamada. El puente determina el dispositivo destinatario del mensaje utilizando el campo originalIdentity de la Session.

La Session incluye el campo opcional channel, que contiene información sobre la conexión del dispositivo. Por ejemplo, si su servidor de puente está construido con Netty, puede usar el campo channel para almacenar el objeto de canal correspondiente a la conexión persistente del dispositivo. Si se envía un mensaje descendente, el puente puede obtener el objeto de canal desde la Session.

IoT as Bridge SDK no procesa los datos del campo channel. Puede utilizar este campo para almacenar cualquier información relacionada con el dispositivo.

Código de ejemplo:

UplinkChannelHandler uplinkHandler = new UplinkChannelHandler();
// Create a session. 
Object channel = new Object();
Session session = Session.newInstance(originalIdentity, channel);
// Connect a device to IoT Platform. 
boolean success = uplinkHandler.doOnline(session, originalIdentity);
if (success) {
    // If the device is connected to IoT Platform, the bridge accepts subsequent communication requests from the device. 
} else {
    // If the device fails to connect to IoT Platform, the bridge rejects subsequent communication requests, such as disconnection requests. 
}

Configurar asignaciones entre certificados de dispositivo e identificadores originales

De forma predeterminada, las asignaciones se configuran mediante el archivo de configuración devices.conf ubicado en el directorio src/main/resources/ del proyecto Java. El formato del archivo es HOCON, que es un superconjunto de JSON.

IoT as Bridge SDK analiza sintácticamente el archivo de configuración basándose en los ajustes del archivo typesafe.config.

Debe configurar los siguientes parámetros en el archivo:

${device-originalIdentity} {
  productKey : ${device-ProductKey-in-Iot-Plaform}
  deviceName : ${device-DeviceName-in-Iot-Platform}
  deviceSecret : ${device-DeviceSecret-in-Iot-Platform}
}

Envío de datos de un dispositivo a IoT Platform

El siguiente código de ejemplo muestra cómo enviar datos de un dispositivo a IoT Platform mediante IoT as Bridge SDK:

/**
 * Send a message from a device in synchronous mode. 
 * @param originalIdentity: the original identifier of the device. 
 * @param protocolMsg: the message to be sent, including the topic, payload, and quality of service (QoS) information. 
 * @param timeout: the timeout period. Unit: seconds. 
 * @return: indicates whether the message is sent within the timeout period. 
 */
boolean doPublish(String originalIdentity, ProtocolMessage protocolMsg, int timeout);
/**
 * Send a message from a device in asynchronous mode. 
 * @param originalIdentity: the original identifier of the device. 
 * @param protocolMsg: the message to be sent, including the topic, payload, and QoS information. 
 * @return: After this method is called, a CompletableFuture object is immediately returned and available for subsequent use. 
 */
CompletableFuture<ProtocolMessage> doPublishAsync(String originalIdentity, 
                                                  ProtocolMessage protocolMsg);

Código de ejemplo:

DeviceIdentity deviceIdentity = ConfigFactory.getDeviceConfigManager().getDeviceIdentity(originalIdentity);
ProtocolMessage protocolMessage = new ProtocolMessage();
protocolMessage.setPayload("Hello world".getBytes());
protocolMessage.setQos(0);
protocolMessage.setTopic(String.format("/%s/%s/update", deviceIdentity.getProductKey(), deviceIdentity.getDeviceName()));
// Send a message in synchronous mode. 
int timeoutSeconds = 3;
boolean success = upLinkHandler.doPublish(originalIdentity, protocolMessage, timeoutSeconds);
// Send a message in asynchronous mode. 
upLinkHandler.doPublishAsync(originalIdentity, protocolMessage);

Envío de datos de IoT Platform a un dispositivo

Al llamar al método bootstrap() para un puente, se registra la devolución de llamada DownlinkChannelHandler en IoT as Bridge SDK. Cuando IoT as Bridge SDK recibe un mensaje de IoT Platform, invoca el método pushToDevice() dentro de DownlinkChannelHandler.

Puede modificar el método pushToDevice() para permitir que el puente procese el mensaje descendente.

Código de ejemplo:

private static ExecutorService executorService  = new ThreadPoolExecutor(
    Runtime.getRuntime().availableProcessors(),
    Runtime.getRuntime().availableProcessors() * 2,
    60, TimeUnit.SECONDS,
    new LinkedBlockingQueue<>(1000),
    new ThreadFactoryBuilder().setDaemon(true).setNameFormat("bridge-downlink-handle-%d").build(),
    new ThreadPoolExecutor.AbortPolicy());
public static void main(String args[]) {
    // By default, the application.conf and devices.conf files are used. 
    BridgeBootstrap bridgeBootstrap = new BridgeBootstrap();
    bridgeBootstrap.bootstrap(new DownlinkChannelHandler() {
        @Override
        public boolean pushToDevice(Session session, String topic, byte[] payload) {
            // Receive downstream messages from IoT Platform. 
            executorService.submit(() -> handleDownLinkMessage(session, topic, payload));
            return true;
        }
        @Override
        public boolean broadcast(String s, byte[] bytes) {
            return false;
        }
    });
}
private static void handleDownLinkMessage(Session session, String topic, byte[] payload) {
    String content = new String(payload);
    log.info("Get DownLink message, session:{}, topic:{}, content:{}", session, topic, content);
    Object channel = session.getChannel();
    String originalIdentity = session.getOriginalIdentity();
}

Desconexión de un dispositivo de IoT Platform

Los siguientes puntos describen los escenarios en los que ocurre la desconexión de un dispositivo:

• Si un puente de pequeño tamaño se desconecta de IoT Platform, todos los dispositivos conectados a dicho puente se desconectan automáticamente de la plataforma.

• Si un puente de gran tamaño se desconecta de IoT Platform, los dispositivos conectados a él no se desconectan de la plataforma. Una vez que el puente se reconecta a IoT Platform, puede actualizar el estado de un dispositivo llamando al método doOffline.

  El estado de un dispositivo indica si está conectado al puente. El puente envía la información de estado de los dispositivos a IoT Platform. Si el puente no logra enviar esta información, el estado mostrado en la consola de IoT Platform permanecerá sin cambios.

  Por ejemplo, si un dispositivo está conectado a IoT Platform mediante un puente y su estado es en línea, pero el puente se desconecta de la plataforma, este no podrá enviar la actualización de estado. Como resultado, el dispositivo seguirá apareciendo como en línea.

• Tanto los puentes de pequeño como de gran tamaño pueden enviar una solicitud para desconectar un dispositivo de IoT Platform cuando están conectados.

  El siguiente código de ejemplo muestra cómo enviar una solicitud de desconexión:

  /**
   * Send a request to disconnect a device from IoT Platform. 
   * @param originalIdentity: the original identifier of the device. 
   * @return: indicates whether the disconnection request is sent. 
   */
  boolean doOffline(String originalIdentity);

  Código de ejemplo:

  upLinkHandler.doOffline(originalIdentity);

Cierre y restablecimiento de la conexión de un puente con IoT Platform

Un puente puede utilizar el objeto BridgeBootstrap y llamar a los métodos disconnectBridge y reconnectBridge para cerrar y restablecer su conexión con IoT Platform.

Código de ejemplo:

// Disconnect a bridge from IoT Platform.
bridgeBootstrap.disconnectBridge();
Thread.sleep(1000);
// Check whether the bridge is connected to IoT Platform.
boolean isConnected = bridgeBootstrap.isBridgeConnected();

// Re-establish a connection to IoT Platform.
bridgeBootstrap.reconnectBridge();
Thread.sleep(1000);
isConnected = bridgeBootstrap.isBridgeConnected();