Introducción

El puente HTTP es una característica de la plataforma Gear Studio, que permite realizar la integración de dispositivos utilizando la HTTP a través de MQTT. De esta forma, es posible migrar dispositivos que utilizan la interfaz HTTP para que utilicen MQTT, con pocos cambios.

Importante: el puente HTTP está diseñado principalmente para la migración de dispositivos desde HTTP hacia MQTT, pero para dispositivos nuevos, es conveniente utilizar el intercambio de datos flexible, que puede verse aquí. El intercambio de datos flexible permite representar los datos con mucha más flexibilidad, y generalmente de una forma más compacta.

Peticiones

Para enviar un request por el puente HTTP, deberá utilizarse la siguiente estructura de topics:

{client-secure-id}/HttpApi/DeviceIntegration

Donde cliente-secure-id es el usuario utilizado en la conexión. La estructura de topics incluye el id de usuario como primer elemento, dado que cada usuario tiene permiso únicamente para los topics que comiencen con ese ID.

Cada request deberá contener un mensaje json, cuya estructura depende del tipo de mensaje. Sin embargo, algunos campos son comunes a todos los tipos de mensaje:

accessToken: este campo indica el access token que debe utilizarse para autentificar y autorizar el request.
mqttMethod: este campo indica el tipo de petición. Por ejemplo, para reportar un valor de temperatura, se utiliza el valor "UpdateTemperatureSensorStatus".
mqttRID: este es un campo opcional que puede tomar un valor cualquiera, típicamente elegido al azar. En caso de que este campo sea informado, la plataforma generará automáticamente una respuesta al comando enviado, e incluirá el mismo mqttRID en esa respuesta, lo que permite que el cliente pueda vincular la respuesta con el request original. Opcionalmente, se puede especificar un subtopic de respuesta, concatenando una barra y un valor al inicio del mqttRID. Es decir, {subtopic}/{valor aleatorio} Por ejemplo usando el subtopic /device1 y el RID 1238j9. El mqttRID completo sería device1/1238j9

Peticiones simples y múltiples

Peticiones simples

Las peticiones simples permiten enviar un único dato por vez a la plataforma. Son utilizadas generalmente para reportar el estado de un único endpoint.

Ejemplo de petición simple:

{
	"accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"endpointID": 1,
	"temperatureCelsius": 25,
	"timestamp": "2021-02-23T14:55:03",
	"mqttMethod": "UpdateTemperatureSensorStatus",
	"mqttRID": "RXmp123"
}

Peticiones múltiples (arrays)

Las peticiones múltiples permiten enviar varios datos en un único mensaje MQTT. La sintaxis utilizada es la de un array JSON. Es decir, se deben usar corchetes al principio y al final, insertando adentro los datos, separados por comas. Las peticiones múltiples se utilizan normalmente para reportar el estado de múltiples endpoints en un único mensaje. También son útiles para que un dispositivo pueda enviar datos que se hayan almacenado durante un período son comunicación. En cualquier caso, los datos pueden incluir endpoints diferentes de un mismo dispositivo, o incluso endpoints de distintos dispositivos.

Ejemplo de petición múltiple:

[
	{
		"accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
		"endpointID": 1,
		"temperatureCelsius": 25,
		"timestamp": "2021-02-23T14:55:03",
		"mqttMethod": "UpdateTemperatureSensorStatus",
		"mqttRID": "RXmp123"
	},
	{
		"accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
		"endpointID": 2,
		"humidityPercentage": 30,
		"timestamp": "2021-02-23T15:55:03",
		"mqttMethod": "UpdateHumiditySensorStatus",
		"mqttRID": "xQzt395"
	}
]

Respuestas

En caso de que se informe un valor en el campo mqttRID, la plataforma creará un mensaje de respuesta en el topic

{client-secure-id}/HttpApi/DeviceIntegrationResponse

Si se concatena al inicio del mqttRID un subtopic, al topic de respuesta se le concatenará el subtopic:

{client-secure-id}/HttpApi/DeviceIntegrationResponse/{subtopic}

Esto permite conocer el estado final del request, y eventualmente obtener información de respuesta en caso de que el comando lo requiera.

El payload de las respuestas tiene típicamente el siguiente formato:

{
    "mqttRID":"RXmp123",
    "mqttStatus":200, 
    "mqttData":"{}" 
}

Nombre	Descripción	Tipo
mqttRID	Identificador único para cada petición	string
mqttStatus	Devuelve el código de estado del servidor (200, 500, 400, etc). Si la petición se ejecutó correctamente, será 200. En caso de error, puede traer cualquier código (400 o 500)	integer
mqttData	Es el cuerpo de la respuesta del servidor. Es un string con un JSON.	string

Integración por tipo de sensor

Sensores de temperatura

Sensores de humedad

Sensores de nivel de iluminación

Sensores de peso

Sensores de volumen

Sensores de presión

Sensores IAS (movimiento, ocupación, y sensores binarios)

Sensores de voltaje

Sensores de corriente

Sensores de potencia activa

Sensores de potencia reactiva

Sensores de potencia aparente

Sensores de coseno fi

Frecuencímetros

Sensores de consumo de energía

Sensores de flujo

Sensores genéricos

Sensores genéricos de flujo

Appliances y otros dispositivos on-off

Dimmers

Controladores de cortinas y cerramientos

Run-time meters (horómetros)

Rastreadores de ubicación

Sensores de concentración (ppm)

Sensores de concentración (masa/volumen)

Sensores de calidad de aire (AQI)

Sensores de flujo de personas

Contadores de personas

Comandos

Recibir comandos