IoT Platform:Utiliser les fonctionnalités de base

Obtenir le SDK IoT as Bridge

IoT Platform fournit une démonstration du SDK IoT as Bridge. Pour plus d'informations, consultez le dépôt alibabacloud-iot-bridge-core-demo.

Organigramme

La figure suivante illustre le processus de connexion d'un appareil à IoT Platform à l'aide du SDK IoT as Bridge.

Déployer un environnement de développement

Déployez un environnement de développement Java et ajoutez la dépendance suivante à votre projet Maven pour importer le SDK IoT as Bridge :

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

Initialisation

Initialiser le SDK

Créez un objet BridgeBootstrap et appelez la méthode bootstrap(). Cette méthode enregistre le callback DownlinkChannelHandler auprès du SDK IoT as Bridge pour recevoir les messages descendants provenant d'IoT Platform.

Une fois le SDK IoT as Bridge initialisé, il lit les informations relatives au pont et envoie une demande de connexion à IoT Platform pour le pont.

Exemple de code :

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;
    }
});

Configurer un pont

• Par défaut, la configuration du pont s'effectue via le fichier application.conf situé dans le répertoire src/main/resources/ du projet Java. Le format du fichier est HOCON, un sur-ensemble de JSON.

  Le SDK IoT as Bridge analyse ce fichier de configuration selon les paramètres du fichier typesafe.config.

• Vous pouvez enregistrer un pont dynamiquement ou configurer directement ses paramètres.

  Pour plus d'informations sur l'enregistrement dynamique d'un appareil, consultez la section Enregistrer des ponts de manière dynamique de la rubrique « Utiliser les fonctionnalités avancées ». Le tableau ci-dessous décrit les paramètres d'un pont.

  Paramètre	Obligatoire	Description
  productKey	Oui	Clé ProductKey du produit auquel appartient le pont.
  deviceName	Oui	Nom DeviceName du pont.
  deviceSecret	Oui	Secret DeviceSecret du pont.
  subDeviceConnectMode	Non	Type de pont. Si ce paramètre est défini sur 3, un pont de grande taille est créé. Jusqu'à 500 000 appareils peuvent être connectés au pont. Si ce paramètre n'est pas spécifié, un pont de petite taille est créé. Jusqu'à 1 500 appareils peuvent être connectés au pont. Les ponts de grande et de petite taille appliquent des politiques différentes pour la déconnexion des appareils. Pour plus d'informations, consultez Déconnecter un appareil d'IoT Platform.
  http2Endpoint	Oui	Endpoint de la passerelle HTTP/2. Cet endpoint sert à établir une connexion persistante entre le pont et IoT Platform via le protocole HTTP/2. Format de l'endpoint : Instances Enterprise Edition : https://${IotInstanceId}.http2.iothub.aliyuncs.com:443. Remplacez ${IotInstanceId} par l'ID de l'instance achetée. Par exemple, si l'ID de l'instance est iot-cn-g06kwb**, l'endpoint est https://iot-cn-g06kwb**.http2.iothub.aliyuncs.com:443. Instances publiques : le format de l'endpoint diffère entre les instances publiques de la nouvelle version et celles de la version précédente. Les instances publiques de la nouvelle version utilisent le même format d'endpoint que les instances Enterprise Edition. Instances publiques de la version précédente : https://${productKey}.iot-as-http2.${RegionId}.aliyuncs.com:443. Remplacez ${productKey} par la clé ProductKey du produit auquel appartient votre pont. Remplacez ${RegionId} par l'ID de la région où réside votre service IoT Platform. Pour plus d'informations sur les ID de région, consultez Régions et zones. Par exemple, si la clé ProductKey d'un pont est a1abcab** et que l'instance publique se trouve dans la région Chine (Shanghai), l'endpoint est https://a1abcab**.iot-as-http2.cn-shanghai.aliyuncs.com:443. Pour plus d'informations sur les instances IoT Platform, consultez Présentation.
  authEndpoint	Oui	Endpoint du service de vérification des appareils. Format de l'endpoint : Instances Enterprise Edition : https://${IotInstanceId}.auth.iothub.aliyuncs.com/auth/bridge. Remplacez ${IotInstanceId} par l'ID de l'instance achetée. Par exemple, si l'ID de l'instance est iot-cn-g06kwb**, l'endpoint est https://iot-cn-g06kwb**.auth.iothub.aliyuncs.com/auth/bridge. Instances publiques : le format de l'endpoint diffère entre les instances publiques de la nouvelle version et celles de la version précédente. Les instances publiques de la nouvelle version utilisent le même format d'endpoint que les instances Enterprise Edition. Instances publiques de la version précédente : https://iot-auth.${RegionId}.aliyuncs.com/auth/bridge. Remplacez ${RegionId} par l'ID de la région où réside votre service IoT Platform. Pour plus d'informations sur les ID de région, consultez Régions et zones. Par exemple, si une instance se trouve dans la région Chine (Shanghai), l'endpoint est https://iot-auth.cn-shanghai.aliyuncs.com/auth/bridge.

  L'exemple de code suivant montre comment configurer un pont de petite taille. Dans cet exemple, une instance Enterprise Edition est utilisée.

  // 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}

Vérifier un appareil et le connecter à IoT Platform

Connecter un appareil à IoT Platform

L'exemple de code suivant montre comment connecter un appareil à IoT Platform à l'aide du SDK IoT as Bridge :

/**
 * 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);

Lorsqu'un appareil se connecte à IoT Platform, il envoie un objet Session à la plateforme. Lorsqu'IoT Platform envoie un message descendant, l'objet Session est transmis au pont via une fonction de callback. Le pont identifie l'appareil destinataire du message grâce au champ originalIdentity présent dans l'objet Session.

L'objet Session inclut le champ facultatif channel, qui contient les informations de connexion de l'appareil. Par exemple, si votre serveur de pont est construit sur Netty, vous pouvez utiliser le champ channel pour stocker l'objet channel correspondant à la connexion persistante de l'appareil. Lors de l'envoi d'un message descendant, le pont peut récupérer l'objet channel depuis l'objet Session.

Le SDK IoT as Bridge ne traite pas les données du champ channel. Vous pouvez utiliser ce champ pour stocker toute information relative à l'appareil.

Exemple de code :

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. 
}

Configurer les mappages entre les certificats d'appareil et les identifiants d'appareil d'origine

Par défaut, les mappages sont configurés via le fichier devices.conf situé dans le répertoire src/main/resources/ du projet Java. Le format du fichier est HOCON, un sur-ensemble de JSON.

Le SDK IoT as Bridge analyse ce fichier de configuration selon les paramètres du fichier typesafe.config.

Vous devez configurer les paramètres suivants dans le fichier :

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

Envoyer des données d'un appareil vers IoT Platform

L'exemple de code suivant montre comment envoyer des données d'un appareil vers IoT Platform à l'aide du SDK IoT as Bridge :

/**
 * 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);

Exemple de code :

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);

Pousser des données d'IoT Platform vers un appareil

Lorsque vous appelez la méthode bootstrap() pour un pont, le callback DownlinkChannelHandler est enregistré auprès du SDK IoT as Bridge. Lorsque le SDK reçoit un message d'IoT Platform, il appelle la méthode pushToDevice() de DownlinkChannelHandler.

Modifiez la méthode pushToDevice() pour permettre au pont de traiter le message descendant.

Exemple de code :

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();
}

Déconnecter un appareil d'IoT Platform

Les scénarios de déconnexion des appareils sont les suivants :

• Si un pont de petite taille est déconnecté d'IoT Platform, tous les appareils connectés à ce pont sont automatiquement déconnectés de la plateforme.

• Si un pont de grande taille est déconnecté d'IoT Platform, les appareils connectés à ce pont restent connectés à la plateforme. Après la reconnexion du pont à IoT Platform, vous pouvez mettre à jour le statut d'un appareil en appelant la méthode doOffline.

  Le statut d'un appareil indique s'il est connecté au pont. Le pont soumet les informations de statut des appareils à IoT Platform. Si le pont ne peut pas transmettre ces informations, le statut affiché dans la console IoT Platform reste inchangé.

  Par exemple, un appareil est connecté à IoT Platform via un pont et son statut est « en ligne ». Si le pont est déconnecté d'IoT Platform, il ne peut plus soumettre les informations de statut de l'appareil. Par conséquent, le statut de l'appareil reste « en ligne ».

• Si des ponts de petite et de grande taille sont connectés à IoT Platform, ils peuvent envoyer une demande de déconnexion d'un appareil de la plateforme.

  L'exemple de code suivant montre comment envoyer une demande de déconnexion :

  /**
   * 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);

  Exemple de code :

  upLinkHandler.doOffline(originalIdentity);

Fermer un pont et rétablir la connexion à IoT Platform

Un pont peut utiliser l'objet BridgeBootstrap et appeler les méthodes disconnectBridge et reconnectBridge pour fermer et rétablir la connexion à IoT Platform.

Exemple de code :

// 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();