Introducción
Esta documentación proporciona una guía integral para integrar Node.js con la nuestraMQTT broker(CrystalMQ) o cualquier corredor de MQTT de su elección. Cubre tareas esenciales como establecer conexiones, suscribir temas, sin suscribirse, y intercambiando mensajes. Al seguir estos pasos, usted puede implementar eficazmenteMQTTcomunicación dentro Aplicaciones Node.js.
Pre-requisitos
Antes de empezar, asegúrese de que tiene lo siguiente:
- Descargar e instalar Node.js desde nodejs.org
- Crear un nuevo directorio para su proyecto e iniciar un nuevo proyecto Node.js utilizando "Npm init"
- npm para instalar la biblioteca MQTT.js, que es esencial para la comunicación MQTT en Node.js
npm Instalación mqtt --save
Conexión al Bróker MQTT
Esta sección tiene fragmentos de código de varias maneras de conectarse a MQTT Broker. Garantizar que MQTT Broker admite la conexión tipo que te gustaría usar. También, obtener los parámetros de conexión correspondientes del MQTT Broker (Address, Port, Nombre de usuario/Password, certificado CA)
MQTT Over TCP
Utilice el siguiente código para conectar al cliente sobre TCP. Define el Macro ADDRESS utilizando los parámetros de conexión de MQTT Broker.
Para MQTT 3.1.1 :
const broker Url =
mqtt://public-mqtt-broker.bevywise.com;
const conn_params = {client Id: "crystalmq_" +
Math.random().toString(36).substring(2, 12)};
const client = mqtt.connect(brokerUrl, conn_params);
Para MQTT 5 :
const mqtt = require('mqtt');
const broker Url = 'mqtt://public-mqt-broker.bevywise.com';
const conn_params = {
clientId: "crystalmq_" + Math.random().toString(36).substring(2,).
12),
protocolo Versión: 5 // Especificar MQTT 5 versión de protocolo
};
const client = mqtt.connect(brokerUrl, conn_params);
MQTT sobre TLS / SSL
Utilice el siguiente código para conectarse de forma segura a MQTT Broker sobre TLS. Define el Macro ADDRESS utilizando los parámetros de conexión de MQTT Broker.
// Define la dirección de corredor MQTT
const ADDRESS = 'mqtt://public-mqtt-broker.bevywise.com';
/ Opciones TLS
const tls_options = {
Rechazo No autorizado: verdadero, // Set to false if using self-signed
certificados
ca: [fs.readFileSync('/path/to/ca.crt')], // CA certificate(s)
cert: fs.readFileSync('/path/to/client.crt'), // Certificado cliente
clave: fs.readFileSync('/path/to/client.key'), //
};
// Opciones de conexión MQTT
const conn_params = {
clientId: "crystalmq_" + Math.random().toString(36).substring(2,).
12),
protocoloVersión: 4, // MQTT 3.1.1 versión del protocolo
protocolo Id: 'MQTT'
limpio: verdadero,
reconnectPeriod: 1000,
connectTimeout: 30 * 1000,
nombre de usuario: 'su nombre de usuario',
contraseña: 'su contraseña',
{
tema: 'trabajo-tópico',
payload: 'Connection Cerrada anormalmente ..',
1,
retener: falso,
}
de mantenimiento: 60,
resubscribe: verdadero,
Rechazo No autorizado: verdadero, // Opcionalmente, se establece en falso si se utiliza
certificados autofirmados
ca: [fs.readFileSync('/path/to/ca.crt')], // CA certificate(s)
cert: fs.readFileSync('/path/to/client.crt'), // Certificado cliente
clave: fs.readFileSync('/path/to/client.key'), //
};
// Conectarse con el corredor MQTT
const client = mqtt.connect(ADDRESS, conn_params);
Establecer parámetros TLS antes de llamar al MQTTClient_connect para conectar al cliente el MQTT Broker seguro sobre TLS.
Si el MQTT Broker es hospedado en un servidor de confianza y la verificación del servidor no es requerido, el siguiente código se puede utilizar para configurar Opciones TLS:
// Define la dirección de corredor MQTT
const ADDRESS = 'mqtt://public-mqtt-broker.bevywise.com';
/ Opciones TLS
const tls_options = {
Rechazo No autorizado: falso, // Set to false to skip server
Verificación
};
// Opciones de conexión MQTT
const conn_params = {
clientId: "crystalmq_" + Math.random().toString(36).substring(2,).
12),
protocoloVersión: 4, // MQTT 3.1.1 versión del protocolo
protocolo Id: 'MQTT'
limpio: verdadero,
reconnectPeriod: 1000,
connectTimeout: 30 * 1000,
nombre de usuario: 'su nombre de usuario',
contraseña: 'su contraseña',
{
tema: 'trabajo-tópico',
payload: 'Connection Cerrada anormalmente ..',
1,
retener: falso,
}
de mantenimiento: 60,
resubscribe: verdadero,
Rechazo No autorizado: falso, // Set to false to skip server
Verificación
};
// Conectarse con el corredor MQTT
const client = mqtt.connect(ADDRESS, { ...conn_params, ...tls_options
});
Si el MQTT Broker tiene el certificado de servidor emitido por un CA con confianza, entonces el servidor El certificado puede verificarse utilizando:
// Define la dirección de corredor MQTT
const ADDRESS = 'mqtt://public-mqtt-broker.bevywise.com';
/ Opciones TLS
const tls_options = {
ca: [fs.readFileSync('/path/to/ca.crt')], // Certificados de CA con confianza
};
// Opciones de conexión MQTT
const conn_params = {
clientId: "crystalmq_" + Math.random().toString(36).substring(2,).
12),
protocoloVersión: 4, // MQTT 3.1.1 versión del protocolo
protocolo Id: 'MQTT'
limpio: verdadero,
reconnectPeriod: 1000,
connectTimeout: 30 * 1000,
nombre de usuario: 'su nombre de usuario',
contraseña: 'su contraseña',
{
tema: 'trabajo-tópico',
payload: 'Connection Cerrada anormalmente ..',
1,
retener: falso,
}
de mantenimiento: 60,
resubscribe: verdadero,
Rechazo No autorizado: verdadero, // Establecer para verificar el servidor
certificado
ca: [fs.readFileSync('/path/to/ca.crt')], // Certificados de CA con confianza
};
// Conectarse con el corredor MQTT
const client = mqtt.connect(ADDRESS, { ...conn_params, ...tls_options
});
Si el MQTT Broker tiene un certificado de servidor auto-firmado, entonces el certificado de servidor puede verificarse utilizando el certificado de raíz obtenido del Bronker MQTT:
// Define la dirección de corredor MQTT
const ADDRESS = 'mqtt://public-mqtt-broker.bevywise.com';
// Certificado Root CA (autosigned certificate from MQTT broker)
const rootCA = fs.readFileSync('/path/to/root-ca.crt');
/ Opciones TLS
const tls_options = {
ca: [rootCA], // Certificado CA de raíz proporcionado por el corredor MQTT
};
// Opciones de conexión MQTT
const conn_params = {
clientId: "crystalmq_" + Math.random().toString(36).substring(2,).
12),
protocoloVersión: 4, // MQTT 3.1.1 versión del protocolo
protocolo Id: 'MQTT'
limpio: verdadero,
reconnectPeriod: 1000,
connectTimeout: 30 * 1000,
nombre de usuario: 'su nombre de usuario',
contraseña: 'su contraseña',
{
tema: 'trabajo-tópico',
payload: 'Connection Cerrada anormalmente ..',
1,
retener: falso,
}
de mantenimiento: 60,
resubscribe: verdadero,
Rechazo No autorizado: verdadero, // Establecer para verificar el servidor
certificado
ca: [rootCA], // Certificado CA de raíz proporcionado por el corredor MQTT
};
// Conectarse con el corredor MQTT
const client = mqtt.connect(ADDRESS, { ...conn_params, ...tls_options
});
MQTT sobre WebSocket
Define la dirección MQTT Broker como esta para conectar al cliente en WebSocket.
const broker Url = 'ws://public-mqt-broker.bevywise.com:103/mqtt';
const conn_params = {
cliente Id : "crystalmq_" + Math.random().toString(36).substring(2, 12),
nombre de usuario : "algo usuario",
contraseña : "una contraseña"
};
const client = mqtt.connect(brokerUrl, conn_params);
MQTT sobre Secure WebSocket
Utilice el siguiente código para conectar al cliente sobre Secure WebSocket. Establecer opciones TLS como se indica en la sección MQTT Más TLS. Define el Macro ADDRESS utilizando los parámetros de conexión de MQTT Broker.
const broker Url = 'ws://public-mqt-broker.bevywise.com:11443/mqtt';
const conn_params = {
cliente Id : "crystalmq_" + Math.random().toString(36).substring(2,).
12),
};
const client = mqtt.connect(brokerUrl, conn_params);
Configuración de MQTT Autenticación
Para conectarse a MQTT Broker que requiere MQTT Usuario y MQTT Contraseña para autenticación, añadir a nombre de usuario y contraseña a las opciones de conexión como esta:
const broker Url = 'mqtt://public-mqt-broker.bevywise.com;
const conn_params = {
cliente Id : "crystalmq_" + Math.random().toString(36).substring(2, 12),
nombre de usuario : "algo usuario",
contraseña : "una contraseña"
};
const client = mqtt.connect(brokerUrl, conn_params);
Características avanzadas
Configuración de la última voluntad
Configurar elÚltima Voluntad y Testamentofunción para especificar un mensaje que broker publicará si el cliente inesperadamente desconecta. Esto ayuda a informar a otros suscriptores del estado del cliente desconectado.
Utilice el siguiente código para establecer Last Will en las opciones de conexión:
const broker Url = 'mqtt://public-mqt-broker.bevywise.com;
const conn_params = {
cliente Id : "crystalmq_" + Math.random().toString(36).substring(2, 12),
{
tema: 'última voluntad',
¡Adiós, CrystalMQ! '
}
};
const client = mqtt.connect(brokerUrl, conn_params);
Ajuste Mantener Alive
MQTT mantiene conexiones cliente-broker con unmantener la calmamecanismo. Ajuste el intervalo de mantenimiento para controlar con qué frecuencia envía el cliente PINGREQ mensajes al corredor.
Modifique el código de abajo para satisfacer sus requisitos:
const conn_params = {
cliente Id : "crystalmq_" + Math.random().toString(36).substring(2, 12),
: 60,
}
};
Configuración de la Persistencia de Sesión
Datos de sesión de un cliente MQTT incluyen las Suscripciones hechas por el Cliente y cualquier dato que el Cliente recibiría con QoS confía0. El Cliente puede conseguir que el MQTT Broker almacene sus datos de sesión a través de las conexiones.
MQTT 3.1.1 Los clientes pueden establecer sesión limpia = 0 para solicitar el Broker MQTT para mantener su información de sesión almacenada a través de conexiones.
Para MQTT 3.1.1 :
const conn_params = {
cliente Id : "crystalmq_" + Math.random().toString(36).substring(2, 12),
limpio: verdadero,
}
};
MQTT 5 Los clientes pueden establecer Clean Start = 0 y Session Expiry Interval = 'N' para solicitar el MQTT Broker para mantener su información de sesión almacenada a través de conexiones durante 'N' segundos.
Para MQTT 5 :
// Opciones de conexión MQTT para MQTT 5
const conn_params = {
clientId: "crystalmq_" + Math.random().toString(36).substring(2, 12),
limpio: verdadero,
protocolo Versión: 5 // Especificar MQTT 5 versión de protocolo
};
Configuración Máxima Tamaño del paquete
MQTT5 Client puede solicitar el MQTT Broker para enviar sólo paquetes de datos menos que un específico tamaño por fijarlo así:
Para MQTT 5 :
const conn_params = {
cliente Id : "crystalmq_" + Math.random().toString(36).substring(2, 12),
protocoloVersión: 5,
propiedades: {}
máximoPaqueteTamaño: 1024, // Tamaño máximo del paquete
}
};
Publish
Envío de datos
Distribución eficiente de los datos a múltiples suscriptores por publicarlos a los designados temas con el siguiente fragmento de código:
Para MQTT 3.1.1 :
cliente.publish('testtopic', 'Hola, CrystalMQ!', (err) = confianza {}
si (err) {
consola.error('Failed to publish message:', err);
. ♫ ... {
consola.log('Message published');
}
});
Para MQTT 5 :
cliente.publish('testtopic', 'Hola, CrystalMQ!', {
qos: 1, // Calidad del nivel de servicio (0, 1, o 2)
retener: falso, // Retener bandera
propiedades: { // MQTT 5 propiedades
payloadFormatIndicator: 1,
mensajeExpiryIntervalo: 60, // Intervalo de caducidad del mensaje en segundos
TemaAlias: 1,
respuestaTema: 'responseTopic',
correlaciónData: Buffer.from('correlationData'),
usuario Propiedades: {}
'key': 'valor',
}
}
}, (err) = confianza {}
si (err) {
consola.error('Failed to publish message:', err);
. ♫ ... {
consola.log('Message published');
}
});
Configuración de mensajes retenidos
Permitir la bandera de retención al publicar un mensaje para asegurar que el corredor almacena la último mensaje para cada tema. Esto garantiza que los nuevos suscriptores reciban los más recientes mensaje al conectarse.
Para implementar esto, utilice el siguiente fragmento de código:
cliente.publish('testtopic', 'Hola, CrystalMQ!', { conservar: true },
(err) = título
{}
si (err) {
consola.error('Failed to publish message:', err);
. ♫ ... {
console.log('Message publicado con la bandera de retención fijada a la verdad');
}
});
Especificación de los niveles de QoS
MQTT proporciona tres niveles de calidad de servicio (QoS) para la entrega de mensajes:
- QoS 0 (Al menos una vez)
- QoS 1 (Al menos una vez)
- QoS 2 (Exactamente una vez)
Especifique el nivel QoS requerido cuando publique mensajes MQTT usando este código:
cliente.publish('testtopic', 'Hola, Crysql MQ!', { qos: 1 }); // 0 or 1 o 2
PUBLISH Propiedades
Las propiedades de publicación son atributos o ajustes asociados con MQTT mensajes que proporcionan contexto o instrucciones adicionales para manejar el mensaje por el corredor u otros clientes. Estas propiedades pueden incluir intervalo de expiración de mensaje, nivel QoS, tipo de contenido, tema de respuesta, etc. Permiten un control más preciso sobre cómo son los mensajes publicado y procesado, asegurando una entrega eficiente y fiable de mensajes en MQTT comunicación.
Intervalo de viaje
La propiedad 'intervalo de caducidad del mensaje' establece la duración de la vida del mensaje en segundos; si sin entrega dentro de este tiempo, el corredor lo descarta. MQTT5 admite esta función. MQTT5 Los clientes pueden configurar esto mientras publican datos.
Para MQTT 5 :
const topic = "testtopic";
const payload = "Hola, CrystalMQ!"
const payload_prop = {
1,
propiedades: {}
mensajeExpiryIntervalo: 60, // Intervalo de caducidad del mensaje en segundos
}
};
cliente.publish(topic, payload, payload_prop, (err) = {}
si (err) {
consola.error('Failed to publish message:', err);
. ♫ ... {
console.log('Message publicado con la bandera de retención fijada a la verdad');
}
});
Tema Alias
La propiedad 'Topic Alias' permite a los clientes utilizar un breve alias en lugar de un tema completo nombre, reducción del tamaño del paquete de mensajes y mejora la eficiencia de la red.
Para MQTT 5 :
const topic = "testtopic";
const payload = "Hola, CrystalMQ!"
const payload_prop = {
1,
propiedades: {}
TemaAlias: 1, // Establecer los Alias Tema para ser usados para este mensaje
}
};
cliente.publish(topic, payload, payload_prop, (err) = {}
si (err) {
consola.error('Failed to publish message:', err);
. ♫ ... {
console.log('Message publicado con la bandera de retención fijada a la verdad');
}
});
Propiedades asociadas con MQTT PUBLISH mejorar el manejo de mensajes, proporcionando contexto o instrucciones para corredores y clientes. Estas propiedades, incluida la expiración del mensaje intervalos y alias tópicos, optimizar la entrega de mensajes y ancho de banda de red.
Suscríbete
Suscribirse al filtro del tema
Para recibir datos publicados por otros clientes, este cliente tiene que suscribirse a un coincidente Tema Filtro como este:
cliente.subscribe('testtopic', (err) = {}
si (err) {
consola.error('Error de suscripción:', err);
. ♫ ... {
consola.log (`Subscribed`);
}
});
Este filtro de tema puede coincidir con un tema exacto o puede tener como # y +
Datos de recepción
Para recibir los datos enviados para las suscripciones, es necesario definir una función callback como esto:
cliente.on('connect', función () {}
consola.log('Connected to MQTT broker');
// Suscribirse a un tema
cliente.subscribe('testtopic', { qos: 1 }, función (err) {
si (err) {
consola.error('Failed to subscribe to topic:', err);
. ♫ ... {
consola.log('Suscrito al tema');
}
});
});
Suscripción de Temas
Para dejar de recibir actualizaciones de un tema, utilice el código proporcionado para darse de baja.
cliente.unsubscribe('testtopic', (err) = {
si (err) {
consola.log('unsubscribe error:', err)
Regreso
}
consola.log(`unsubscribed.`)
})
Desconectar al cliente
Asegurar una terminación adecuada de la conexión de su cliente con el corredor para evitar problemas y filtraciones de recursos en ambas partes, manteniendo así la estabilidad del sistema.
Utilice el siguiente código para desconectar al cliente del broker:
cliente.end();
Construcción de su lógica de negocio
Usted tiene la oportunidad de desarrollar y personalizar su propia lógica de negocio intrincada dentro este entorno, adaptándolo precisamente a sus necesidades y objetivos específicos.
Aplicación de las mejores prácticas
Identificación individual del cliente
Asignar un ID de cliente único a cada dispositivo con fines de identificación precisos. Para despliegues privados, asegurar que cada cliente reciba un ID distinto, mientras que en ambientes compartidos, incorpora una cadena aleatoria al cliente IDs para asegurar la singularidad.
Organización estructurada de datos
Planifique su estructura de datos cuidadosamente. Ya sea manejando texto plano, Formatos de datos JSON, o datos numéricos, asegúrese de que el diseño se adapte a su las necesidades específicas de la aplicación.
Manejo de error robusto
Implementar una gestión de errores sólida para manejar fallos de conexión MQTT, suscripción problemas y errores de publicación de mensajes eficazmente.
Verificación de credenciales
Guardar información confidencial como nombres de usuario, contraseñas y ID de cliente por no codificarlos duros en su código fuente. Use variables ambientales o seguras configuración archivos en su lugar.
Pruebas periódicas " Monitoreo
Prueba continuamente la comunicación de MQTT y monitorea métricas de clientes como conexión status, message throughput, and error rates to quickly identify and fix issues.
Optimización de la gestión de las sesiones
Elija entre sesiones limpias y persistentes ( " limpias: verdaderas " o " limpias: falsas " ) on su necesidad de retener suscripciones y mensajes queued a través de las conexiones cliente.
Reconnect on Disconnect
Agregar código para intentar la reconexión con el MQTT Broker cuando hay un inesperado desconexión. Esto asegurará que su cliente permanezca conectado y no pierda cualquiera datos.
Descargar Código
Descargar el código completo para el cliente que utiliza Node JS MQTT Client Library para conectarse con nuestro corredor de mensajería o cualquier corredor de su elección.
Para MQTT 3.1.1 :
const mqtt = require('mqtt');
// const fs = require('fs');
const broker Url = 'mqtt://public-mqt-broker.bevywise.com';
const conn_params = {
cliente Id : "crystalmq_" + Math.random().toString(36).substring(2, 12),
// guardián : 60, // mantener vivo en segundos
// host : "public-mqtt-broker.bevywise.com" // Host
// protocolo: 'mqts', // protocolo
// limpio: verdadero, // Sesión limpia
// nombre de usuario : "algo nombre de usuario", // mqtt
// contraseña : "alguna contraseña", // mqtt
// will: {
// tema: 'última voluntad', // Tema de Will
// carga útil: 'Adiós, CrystalMQ!' // mensaje
// }
// ca: [fs.readFileSync('/path/to/root.crt')],
};
const publishInterval = 2000;
const client = mqtt.connect(brokerUrl, conn_params);
const topic = 'testtopic'; // publicar tema
mensaje const = "Hola CrystalMQ !" // mensaje publicado
cliente.on('connect', () = {
consola.log('Connected to MQTT broker');
setInterval((() = título {}
client.publish(topic, message, (err) = {}
si (err) {
consola.error('Error editorial message:', err);
. ♫ ... {
consola.log('Message published:', message);
}
});
}, publicarInterval);
});
cliente.on('message', (topic, message) = {}
consola.log(`Recibido mensaje: ${message.toString()} sobre el tema:
- ¿Qué?
});
cliente.on('error', (err) = {}
consola.error('Error: ', err);
});
cliente.on('close', () = {}
consola.log('Disconnected from MQTT broker');
});
cliente.on('reconnect', () = {}
consola.log('Reconectarse a MQTT broker...');
});
client.on('offline', () = {
consola.error('MQTT cliente está fuera de línea);
});
Para MQTT 5
const mqtt = require('mqtt');
const broker Url = 'mqtt://public-mqt-broker.bevywise.com';
const conn_params = {
clientId: "crystalmq_" + Math.random().toString(36).substring(2, 12),
protocoloVersión: 5, // Especificar MQTT 5 versión de protocolo
limpio: verdadero, // Sesión limpia
// Uncomment y establecer estas opciones si es necesario
// Guarda: 60, // Sigue vivo en segundos
// nombre de usuario: "algo nombre de usuario", //
// contraseña: "algo de contraseña", //
// will: {
// tema: 'última voluntad', // Tema de Will
// payload: 'Adiós, CrystalMQ!', // Mensaje
// }
// ca: [fs.readFileSync('/path/to/root.crt')],
};
const publishInterval = 2000;
const client = mqtt.connect(brokerUrl, conn_params);
const topic = 'testtopic'; // Publish topic
mensaje const = "¡Hola CrystalMQ!"; // Mensaje publicado
cliente.on('connect', () = {
consola.log('Connected to MQTT broker');
setInterval((() = título {}
cliente.publish(topic, message, { qos: 1 }, (err) = {}
si (err) {
consola.error('Error editorial message:', err);
. ♫ ... {
consola.log('Message published:', message);
}
});
}, publicarInterval);
});
cliente.on('message', (topic, message, packet) = {}
consola.log(`Recibido mensaje: ${message.toString()} sobre el tema:
- ¿Qué?
// Handle MQTT 5 propiedades si es necesario
consola.log('Properties:', packet.properties);
});
cliente.on('error', (err) = {}
consola.error('Error: ', err);
});
cliente.on('close', () = {}
consola.log('Disconnected from MQTT broker');
});
cliente.on('reconnect', () = {}
consola.log('Reconectarse a MQTT broker...');
});
client.on('offline', () = {
consola.error('MQTT cliente está fuera de línea);
});
Crear un Bundle ejecutable
Pasos para crear un archivo ejecutable utilizando 'pkg `
1. Instalar " pkg " a nivel mundial
Abra su terminal o el comando prompt y ejecute el siguiente comando para instalar `pkg`:
npm instalar -g pkg
2. Prepare su aplicación Node.js
Asegúrese de que su `paquete.json` incluye una propiedad 'bin' que apunta a su script principal. Para ejemplo, si su script principal es `index.js`, su `paquete. Json debería mirar algo como esto:
{}
"nombre": "su nombre de aplicación",
"versión": "1.0.0",
"main": "index.js",
"bin": "index.js",
"scriptos": {}
"Iniciar": "Indice de nodos.js"
}
"dependencias": {}
"mqtt": "^4.2.8"
}
}
3. Crear ejecutables
Use `pkg` para crear ejecutables para diferentes sistemas operativos. Ejecute lo siguiente comandos en su terminal:
pkg . --targets node16-linux-x64,node16-win-x64
Este comando especifica los objetivos como Node.js versión 16 para Linux y Windows 64-bit arquitecturas. Ajuste la versión y la arquitectura según sea necesario.
4. Distribuir sus ejecutables
Después de ejecutar el comando 'pkg', encontrará los ejecutables en el directorio actual. Tú. puede distribuir estos archivos ejecutables a los usuarios. Serán nombrados basados en tu aplicación nombre y el sistema operativo objetivo, tales como `su-app-name-linux` y `su-app-name-win.exe`.
Conecta a tu cliente con nuestro estado de arteMQTT brokero cualquier agente de su elección. Esta potente combinación garantizará un rendimiento óptimo y fiabilidad para todas sus necesidades de mensajería, allanando el camino para una robusta y eficiente sistema integración.