IoT Platform:Device shadow data stream

Temas de la sombra de dispositivo

IoT Platform predefine dos temas por dispositivo para gestionar el flujo de datos de la sombra de dispositivo.

• /shadow/update/${YourProductKey}/${YourDeviceName}

  Los dispositivos y las aplicaciones publican mensajes en este tema. Cuando IoT Platform recibe un mensaje en este tema, actualiza la sombra de dispositivo con el estado contenido en el mensaje.

• /shadow/get/${YourProductKey}/${YourDeviceName}

  La sombra de dispositivo publica actualizaciones de estado en este tema. Un dispositivo se suscribe a este tema para recibir los mensajes más recientes.

Ejemplos de uso

A continuación se utilizan ejemplos con un foco para ilustrar cómo interactúan un dispositivo, su sombra de dispositivo y una aplicación. Los ejemplos cubren los cuatro escenarios de flujo de datos: reporte de estado, cambio de estado del dispositivo desde una aplicación, recuperación del contenido de la sombra al reconectarse y eliminación de propiedades de la sombra.

En estos ejemplos, ProductKey/@parmname es a1PbRCF**** y DeviceName/@parmname es lightbulb. El dispositivo publica y se suscribe a ambos temas de la sombra de dispositivo con una Calidad de Servicio (QoS) de 1.

Un dispositivo reporta su estado

Cuando un dispositivo se conecta, reporta su estado actual a la sombra de dispositivo. Las aplicaciones pueden leer el estado del dispositivo desde la sombra en cualquier momento.

La siguiente figura muestra el flujo de datos.

1. El foco se conecta y publica su estado actual en el tema /shadow/update/a1PbRCF****/lightbulb.

   El formato del mensaje JSON es:

   {
       "method": "update", 
       "state": {
           "reported": {
               "color": "red"
           }
       }, 
       "version": 1
   }

   Tabla 1. Descripción de parámetros

   Parámetro	Descripción
   method/@parmname	Tipo de operación. Al realizar una actualización, method/@parmname es obligatorio. Establézcalo en update/@option.
   state/@parmname	Datos de estado enviados a la sombra de dispositivo. reported/@parmname es obligatorio. El valor se escribe en la sección reported/@parmname del documento de la sombra.
   version/@parmname	Versión de la solicitud. La sombra de dispositivo acepta la actualización solo si la nueva versión es mayor que la versión actual. Si version/@parmname se establece en -1, se borran todos los datos de la sombra y la versión se restablece a 0.

2. La sombra de dispositivo actualiza su documento con el estado reportado.

   {
       "state": {
           "reported": {
               "color": "red"
           }
       }, 
       "metadata": {
           "reported": {
               "color": {
                   "timestamp": 1469564492
               }
           }
       }, 
       "timestamp": 1469564492, 
       "version": 1
   }

3. Después de actualizar el documento de la sombra, esta envía un resultado al tema /shadow/get/a1PbRCF****/lightbulb. Suscríbase a este tema antes de publicar en el tema de actualización para asegurar que se reciba el resultado.

   • Si la actualización se realiza correctamente:

     {
         "method": "reply", 
         "payload": {
             "status": "success", 
             "version": 1
         }, 
         "timestamp": 1469564576
     }

   • Si la actualización falla:

     {
         "method": "reply", 
         "payload": {
             "status": "error", 
             "content": {
                 "errorcode": "${errorcode}", 
                 "errormessage": "${errormessage}"
             }
         }, 
         "timestamp": 1469564576
     }

     Tabla 2. Códigos de error

     errorCode	errorMessage
     400	Formato JSON no válido.
     401	A los datos de la sombra les falta el campo method/@parmname.
     402	A los datos de la sombra les falta el campo state/@parmname.
     403	El valor del campo version/@parmname no es un número.
     404	A los datos de la sombra les falta el campo reported/@parmname.
     405	El campo reported/@parmname está vacío.
     406	El valor de method/@parmname no es válido.
     407	El contenido de la sombra está vacío.
     408	El número de propiedades en el campo reported/@parmname excede 128.
     409	Conflicto de versión.
     500	Error de procesamiento en el servidor.

Una aplicación cambia el estado del dispositivo

Una aplicación llama a la API UpdateDeviceShadow para escribir un estado deseado en la sombra de dispositivo. La sombra envía el estado deseado al dispositivo, el cual aplica el cambio y reporta su estado actualizado.

La siguiente figura muestra el flujo de datos.

1. Una aplicación llama a la API UpdateDeviceShadow para establecer la propiedad color/@parmname en green/@option.

   El valor del parámetro ShadowMessage/@parmname es:

   {
       "method": "update", 
       "state": {
           "desired": {
               "color": "green"
           }
       }, 
       "version": 2
   }

2. La sombra de dispositivo recibe la actualización y escribe el estado deseado en su documento:

   {
       "state": {
           "reported": {
               "color": "red"
           }, 
           "desired": {
               "color": "green"
           }
       }, 
       "metadata": {
           "reported": {
               "color": {
                   "timestamp": 1469564492
               }
           }, 
           "desired": {
               "color": {
                   "timestamp": 1469564576
               }
           }
       }, 
       "timestamp": 1469564576, 
       "version": 2
   }

3. La sombra de dispositivo publica el documento actualizado en el tema /shadow/get/a1PbRCF****/lightbulb con method establecido en control, lo que indica al dispositivo que aplique el cambio deseado.

   {
       "method": "control", 
       "payload": {
           "state": {
               "reported": {
                   "color": "red"
               }, 
               "desired": {
                   "color": "green"
               }
           }, 
           "metadata": {
               "reported": {
                   "color": {
                       "timestamp": 1469564492
                   }
               }, 
               "desired": {
                   "color": {
                       "timestamp": 1469564576
                   }
               }
           }
       }, 
       "version": 2, 
       "timestamp": 1469564576
   }

4. Si el foco está en línea y se ha suscrito al tema /shadow/get/a1PbRCF****/lightbulb, recibe el mensaje inmediatamente.

   El dispositivo lee el campo desired/@parmname y cambia el color del foco a verde.

   Después de actualizar su estado, el foco reporta el estado más reciente a IoT Platform.

   {
       "method": "update", 
       "state": {
           "reported": {
               "color": "green"
           }
       }, 
       "version": 3
   }

   Nota

   Si se utiliza una marca de tiempo para determinar que el comando ha caducado, puede elegir no realizar la actualización.

5. La sombra de dispositivo envía una respuesta al dispositivo en el tema /shadow/get/a1PbRCF****/lightbulb. Para conocer el formato de la respuesta, consulte Step 3 in "A device reports its status".

6. Una vez que el estado se reporta correctamente, el dispositivo y la sombra de dispositivo limpian el estado deseado.

   • El dispositivo publica un mensaje en el tema /shadow/update/a1PbRCF****/lightbulb para borrar el campo desired/@parmname:

     {
         "method": "update", 
         "state": {
             "desired": "null"
         }, 
         "version": 4
     }

   • La sombra de dispositivo actualiza su documento. El campo desired se borra y el documento de la sombra refleja el estado final:

     {
         "state": {
             "reported": {
                 "color": "green"
             }
         }, 
         "metadata": {
             "reported": {
                 "color": {
                     "timestamp": 1469564577
                 }
             }, 
             "desired": {
                 "timestamp": 1469564576
             }
         }, 
         "version": 4
     }

Un dispositivo obtiene el contenido de la sombra

Si un dispositivo está desconectado cuando una aplicación envía un comando, puede recuperar el contenido de la sombra después de reconectarse.

La siguiente figura muestra el flujo de datos.

1. Después de reconectarse, el foco publica una solicitud get en el tema /shadow/update/a1PbRCF****/lightbulb para recuperar el contenido más reciente de la sombra.

   {
       "method": "get"
   }

2. La sombra de dispositivo responde publicando el contenido más reciente en el tema /shadow/get/a1PbRCF****/lightbulb. Suscríbase a este tema antes de enviar la solicitud get para asegurar que se reciba la respuesta.

   {
       "method": "reply", 
       "payload": {
           "status": "success", 
           "state": {
               "reported": {
                   "color": "red"
               }, 
               "desired": {
                   "color": "green"
               }
           }, 
           "metadata": {
               "reported": {
                   "color": {
                       "timestamp": 1469564492
                   }
               }, 
               "desired": {
                   "color": {
                       "timestamp": 1469564492
                   }
               }
           }
       }, 
       "version": 2, 
       "timestamp": 1469564576
   }

Un dispositivo elimina propiedades de la sombra

Si el dispositivo ya tiene el estado más reciente, puede eliminar propiedades específicas de la sombra de dispositivo.

La siguiente figura muestra el flujo de datos.

Para eliminar propiedades de la sombra, publique en el tema /shadow/update/a1PbRCF****/lightbulb con method/@parmname establecido en delete/@option y el valor de la propiedad objetivo establecido en null/@option.

• Elimine propiedades específicas de la sombra.

  {
      "method": "delete", 
      "state": {
          "reported": {
              "color": "null", 
              "temperature": "null"
          }
      }, 
      "version": 1
  }

• Elimine todas las propiedades de la sombra.

  {
      "method": "delete", 
      "state": {
          "reported": "null"
      }, 
      "version": 1
  }