El Protocolo CloudBox es un conjunto de comandos y respuestas diseñados para controlar, configurar y supervisar el sistema de cronometraje de CloudBox. Estos comandos le permiten gestionar sesiones de cronometraje, configurar los ajustes del sistema, comprobar los estados del sistema y realizar diversas funciones de red. A continuación, se ofrece una explicación detallada de todos los comandos, incluidas sus posibles respuestas y códigos de error.
Formato de comando del protocolo
Al enviar comandos a CloudBox a través de un socket TCP, los comandos siempre deben enviarse como texto sin formato en un formato específico. La estructura general del comando sigue estas reglas:
- Nombre del comando: La primera parte del comando es el nombre de la acción que desea realizar (por ejemplo,
CHANGESYSTEMIPADDRESS). - Argumentos: Cualquier argumento requerido u opcional debe pasarse en orden, separado por puntos y coma (`;`).
- Terminación: cada comando debe terminar con los caracteres
\r(retorno de carro y salto de línea) para indicar el final del comando.
Ejemplo de formato de comando
Por ejemplo, al enviar el comando CHANGESYSTEMIPADDRESS con los argumentos necesarios para la dirección IP, el puerto y la subred, el formato sería:
CHANGESYSTEMIPADDRESS;192.168.1.100;8080;/24\r\nEn este ejemplo:
CHANGESYSTEMIPADDRESS: El nombre del comando.192.168.1.100: La nueva dirección IP que se asignará al sistema.8080: El nuevo puerto que se asignará./24: La máscara de subred.\r: Marca el final del comando.
Formato de respuesta del protocolo
En el protocolo CloudBox, las respuestas a los comandos siempre se estructuran en un formato JSON, siguiendo un patrón consistente. Cada respuesta contiene dos claves principales:
- comando: Esta clave especifica el comando que se envió a la CloudBox. Confirma qué acción o consulta se solicitó.
- resultado: Esta clave contiene el resultado o los datos reales devueltos por el sistema en función del comando ejecutado.
A continuación, se muestra un ejemplo de una respuesta típica para el comando GETSYSTEMTIME:
{
"command": "GETSYSTEMTIME",
"result": {
"dateTimeSync": "NTP",
"timezone": "Europe/Madrid (CEST, +0200)",
"timestamp": "2024-09-17;18:44:11.649"
}
}Comandos y respuestas clave
1. INICIO
Inicia la sesión de cronometraje.
Respuestas:
START_MODE: El sistema ya está en modo de temporización.READERNOTOK: El lector RFID no está presente o no funciona correctamente.DEVICE_INTEGRITY_FAILED: La comprobación de la integridad del dispositivo ha fallado.INVALIDREADERMODEL: El modelo de lector configurado no es válido.ERRREADER: Error general del lector.OK: La sesión de temporización se ha iniciado correctamente.
2. DETENER
Detiene la sesión de cronometraje actual.
Respuestas:
READERNOTOK: El lector RFID no está presente o no funciona correctamente.INVALIDREADERMODEL: El modelo de lector configurado no es válido.ERRREADER: Error general del lector.OK: La sesión se ha detenido correctamente.
3. OBTENER ESTADO DEL SISTEMA
Devuelve el estado actual del sistema, incluido el nivel de la batería, el estado de la conexión a la red 4G, el estado del GPS y más.
Ejemplo de respuesta:
{
"batteryVolts": "25.33",
"batteryPercentage": "88.27",
"cpuTemperature": "53.75",
"hasPower": false,
"hasInternet": true,
"startMode": false,
"sessionPassingCount": 0,
"lastPassingTimestamp": null,
"operator4G": null,
"signal4G": null,
"networkService4G": null,
"status4G": {"status": "CME_ERROR", "message": "SIM not inserted"},
"statusGps": {"status": "SEARCHING", "message": "No GPS data found. Searching..."},
"statusIoT": {"status": true, "message": "Connected to IoT server"},
"backupDownloadLink": "http://192.168.0.3:2999/download",
"sessionToken": null,
"cloudPassingCount": 0,
"deviceIntegrity": "Device integrity check passed",
"readerStatus": "RFID Reader not found",
"updateInfo": null,
"currentBackendVersion": "1.0.4",
"currentFrontVersion": "1.0.4"
}4. OBTENERCONFIGURACIÓNDELSISTEMA
Obtiene la configuración actual del sistema, incluidos los ajustes de red, la configuración del lector y los parámetros del sistema.
Ejemplo de respuesta:
{
"bounceTime": 1,
"buzzerPassings": false,
"readerModel": "R420",
"readerHost": "10.0.0.2",
"readerPort": "5084",
"tcpHost": "192.168.0.3",
"tcpSubnet": "/8",
"tcpPort": "8080",
"apName": "CLBX_192_168_0_3",
"wifiSsid": "MOVISTAR_91DA",
"disableStartButton": false,
"dateTimeSync": "NTP",
"timezone": "America/Argentina/Buenos_Aires",
"simPin": "4509",
"modemImei": "862636053313696",
"deviceSerialNumber": "CLBX10001"
}5. SETSYSTEMTIME;marca de tiempo
Establece la hora del sistema. El formato es YYYY-MM-DD HH:mm:ss.
Respuestas:
BAD_FORMAT: El formato de fecha u hora es incorrecto.START_MODE: El sistema está en modo de temporización y el comando no se puede ejecutar.NTPACTIVE: La sincronización NTP está activa y los cambios manuales de hora están deshabilitados.CMDERROR: Error general de comando.OK: La hora del sistema se ha configurado correctamente.
6. GETSYSTEMTIME
Devuelve la hora actual del sistema, la zona horaria y la configuración de sincronización.
Ejemplo de respuesta:
{
"dateTimeSync": "NTP",
"timezone": "Europe/Madrid (CEST, +0200)",
"timestamp": "2024-09-17;18:44:11.649"
}7. SETDATETIMESYNC;syncMode
Establece el modo de sincronización de fecha y hora. Las opciones disponibles son: "DISABLED", "GPS", "NTP".
Respuestas:
START_MODE: El sistema está en modo de temporización y el comando no se puede ejecutar.SYNCNOTAVAILABLE: El modo de sincronización seleccionado no está disponible.OK: El modo de sincronización se ha configurado correctamente.
8. CAMBIAR LA DIRECCIÓN IP DEL SISTEMA;ip;puerto;subred
Cambia la dirección IP, el puerto y la máscara de subred del sistema.
Respuestas:
START_MODE: El sistema está en modo de temporización y el comando no se puede ejecutar.INVALIDNETWORKCONFIGURATION: La configuración de red proporcionada no es válida.INVALIDNETWORKSUBNET: La máscara de subred no es válida.RESERVEDIPADDRESS: La dirección IP está reservada.STDERROR: Error general de aplicación.OK: Éxito. El sistema se reiniciará para aplicar la nueva configuración.
9. SETBUZZERPASSINGS;valor
Habilita o deshabilita el zumbador para las detecciones de paso (verdadero/falso).
Respuesta:
OK: La configuración del zumbador se ha actualizado correctamente.
10. SETBOUNCETIME;segundos
Establece el tiempo de rebote entre las lecturas de RFID. Si los segundos son null o <= 0, el valor predeterminado es de 5 segundos.
Respuesta:
OK: El tiempo de rebote se ha configurado correctamente.
11. APAGADO
Apaga el sistema después de 10-15 segundos.
Respuestas:
START_MODE: El sistema está en modo de temporización y el comando no se puede ejecutar.OK: El sistema se apagará.
12. LISTAR ARCHIVOS DE COPIA DE SEGURIDAD
Devuelve una lista de los archivos de copia de seguridad disponibles. Ejemplo: ["20240712-135902.txt"]
Respuestas:
ERROR: No se pudieron recuperar los archivos de copia de seguridad.OK: Se ha recuperado correctamente la lista de archivos.
13. ELIMINAR ARCHIVOS DE COPIA DE SEGURIDAD
Elimina todos los archivos de copia de seguridad del sistema.
Respuestas:
START_MODE: El sistema está en modo de temporización y el comando no se puede ejecutar.ERROR: No se pudieron eliminar los archivos.OK: Los archivos de copia de seguridad se han eliminado correctamente.
14. REBOBINAR;timestamp de inicio;timestamp de finalización
Rebobina los datos de paso entre las marcas de tiempo de inicio y finalización especificadas (YYYY-MM-DD HH:mm:ss) y los transmite a los clientes TCP conectados.
Respuesta:
OK: Se están transmitiendo los datos.
15. OBTENERINFORMACIÓNDEGPS
Devuelve la información del GPS, incluyendo la latitud, la longitud, la altitud y la hora de la última sincronización.
Ejemplo de respuesta:
{
"latitudeDecimal": 41.28425,
"longitudeDecimal": 1.98251,
"googleMapsLink": "https://www.google.com/maps/place/41.28425,1.98251",
"gpsTimezone": "Europe/Madrid",
"altitude": 38.7,
"speed": 0,
"lastSync": "2024-07-24 20:27:02"
}