Wialon para desarrolladores Manual de usuario Documentación de API events check_updates

check_updates

Para obtener actualizaciones de eventos de todos los elementos agregados a la sesión, utilice el método events/check_updates. Los elementos pueden ser unidades o recursos.

Antes de llamar a este método, agregue los elementos a la sesión y establezca los detectores que se deben monitorear con events/update_items. Si monitorea solo unidades, también puede usar events/update_units.

Si el parámetro evt_flags establecido en events/update_items o events/update_units incluye el flag 0x200, las actualizaciones se entregan en los datos units_update de avl_evts. En este caso, events/check_updates devuelve {}.

Endpoint

Copied!
svc=events/check_updates&params={
    "lang": <text>,
    "measure": <uint>,
    "detalization": <uint>
}

Parámetros

Todos los parámetros son opcionales.

Parámetro Descripción Valor por defecto
lang Idioma (código de 2 caracteres). en
measure Sistema de medidas:

  • 0 para SI;
  • 1 para EE. UU.;
  • 2 para imperial.
 0
detalization Flags de salida (ver más abajo). Debe especificarse en formato decimal. 7

Flags de salida

Flag Descripción
0x1 Datos básicos del evento: posiciones de inicio y fin, tiempos y flags de servicio del evento.
0x2 Datos específicos del detector.
0x4 Parámetros del mensaje asociado con el evento.
0x8 Datos de detalle extendidos del detector para detectores compatibles.
0x10 Datos detallados de mensaje para detectores compatibles.
0x20 Valores formateados del detector.

Tipo de sensor

Valor de tipo Descripción Registro de eventos
1 Sensores conmutadores:

  • funcionamiento del motor;
  • digital;
  • eficiencia del motor;
  • modo privado;
  • detector de movimiento instantáneo;
  • activación de alarma;
  • contador (cambio a ON/OFF).
 Los eventos están activos mientras el valor sea distinto de cero.
2 Sensores instantáneos:

  • odómetro;
  • horas de motor relativas;
  • consumo instantáneo de combustible;
  • contador (instantáneo).
 Los eventos están activos mientras el valor sea distinto de cero.
3 Sensores diferenciales:

  • kilometraje;
  • horas de motor;
  • consumo de combustible por impulsos;
  • consumo absoluto de combustible;
  • contador (diferencial, diferencial con desbordamiento).
 Los eventos están activos mientras el contador calculado sea distinto de cero.
4 Sensores analógicos:

  • temperatura;
  • RPM del motor;
  • voltaje;
  • peso;
  • acelerómetro;
  • sensor de nivel de combustible por impulsos;
  • coeficiente de temperatura;
  • sensor personalizado;
  • conductor;
  • remolque;
  • etiqueta (pasajero).
 Proporciona solo el estado actual del sensor; el detector sensors no registra eventos de intervalo para este tipo.

La tabla anterior no incluye los sensores de nivel de combustible ni de nivel de batería. El sistema procesa sus datos con detectores separados: lls, fuel_level, filling y theft para los sensores de nivel de combustible, y battery_level, charge y ev para los sensores de nivel de batería. El sensor de nivel de combustible por impulsos no se ve afectado: pertenece a los sensores analógicos (tipo 4). Para ver la lista completa de detectores, consulte Tipos de detectores de eventos.

Respuesta

La respuesta se agrupa por ID de elemento. Para cada elemento, la respuesta contiene un array de objetos de detector:

Copied!
{
    "<item_id_1>": [
        { "<detector_name>": { ... } },
        { "<detector_name>": { ... } },
        ...
    ],
    "<item_id_2>": [ ... ]
}

Cada llamada devuelve actualizaciones de eventos desde la llamada anterior a events/check_updates en la misma sesión. El método devuelve un objeto vacío cuando no hay nuevas actualizaciones.

A menos que se indique lo contrario, los valores de la respuesta (sensor, combustible, distancia, velocidad, altitud y kilometraje) utilizan el sistema de medidas del parámetro measure. Los valores en segundos, bytes, KiB, km/h y tiempo UNIX no se convierten.

La estructura de cada objeto de detector depende de los flags de salida habilitados. Combine los flags en el parámetro detalization según sea necesario. Las secciones siguientes describen cada flag por separado.

Flag 0x1

Devuelve datos básicos para cada evento. La estructura de la respuesta depende del detector. Los detectores ignition, sensors, lls, filling, theft, fuel_level, ev, charge y battery_level utilizan el ID del sensor de la unidad como clave del objeto <detector_specific_id>. El detector eco_driving utiliza el ID del criterio de conducción eficiente, health_check utiliza el ID del incidente, resource_drivers utiliza el ID del conductor y speedings utiliza 0. Los detectores como trips y counters devuelven sus datos directamente, sin agrupación.

El detector eco_driving no está disponible en Wialon Local.

Para los detectores que agrupan datos por ID, la estructura es la siguiente:

Copied!
{
    "<detector_name>": {
        "<detector_specific_id>": {
            "from": {
                "t": <uint>,    /* tiempo (tiempo UNIX) */
                "y": <double>,  /* latitud */
                "x": <double>   /* longitud */
            },
            "to": {
                "t": <uint>,    /* tiempo (tiempo UNIX) */
                "y": <double>,  /* latitud */
                "x": <double>   /* longitud */
            },
            "m": <uint>,       /* tiempo del último mensaje asociado con el evento */
            "f": <uint>        /* flags de servicio del evento */
        }
    }
}

Para los detectores que devuelven datos directamente, como trips y counters, no se incluye el nivel <detector_specific_id>:

Copied!
{
    "<detector_name>": {
        "from": {
            "t": <uint>,    /* tiempo (tiempo UNIX) */
            "y": <double>,  /* latitud */
            "x": <double>   /* longitud */
        },
        "to": {
            "t": <uint>,    /* tiempo (tiempo UNIX) */
            "y": <double>,  /* latitud */
            "x": <double>   /* longitud */
        },
        "m": <uint>,       /* tiempo del último mensaje asociado con el evento */
        "f": <uint>        /* flags de servicio del evento */
    }
}

Para una posición de inicio o fin privada, por ejemplo, cuando el modo privado oculta la ubicación de la unidad, los valores x e y se devuelven como 0.

Flag 0x2

Devuelve datos específicos del detector. La estructura depende del detector.

Detectores de sensores

Para ignition y sensors, la estructura devuelta para cada sensor corresponde al tipo del sensor. El campo type muestra el tipo de sensor.

Copied!
"ignition": {
    "<sensor_id>": {
        "state": <double>,    /* estado: 0 para apagado, 1 para encendido */
        "type": 1,            /* tipo de sensor: sensor conmutador */
        "hours": <uint>,      /* horas de motor para todo el historial, en segundos */
        "switches": <uint>,   /* número de conmutaciones para todo el historial */
        "value": <double>     /* último valor del sensor */
    }
}

Objetos posibles para sensors:

Copied!
"sensors": {
    "<sensor_id1>": {
        "state": <double>,         /* estado: 0 para apagado, 1 para encendido */
        "type": 1,                 /* tipo de sensor: sensor conmutador */
        "hours": <uint>,           /* horas de motor para todo el historial, en segundos */
        "switches": <uint>,        /* número de conmutaciones para todo el historial */
        "value": <double>          /* último valor del sensor */
    },
    "<sensor_id2>": {
        "type": 2,                 /* tipo de sensor: sensor instantáneo */
        "counter": <uint>,         /* número de mensajes consecutivos en el evento */
        "summary": <double>,       /* suma de valores en el evento */
        "total_counter": <uint>,   /* número total de mensajes en todo el historial */
        "total_summary": <double>, /* suma total de valores en todo el historial */
        "value": <double>          /* último valor; si es -348201.3876, el valor es desconocido */
    },
    "<sensor_id3>": {
        "type": 3,                 /* tipo de sensor: sensor diferencial */
        "counter": <double>,       /* suma de valores en el evento */
        "total_counter": <double>, /* suma de valores en el historial */
        "value": <double>          /* último valor; si es -348201.3876, el valor es desconocido */
    },
    "<sensor_id4>": {
        "type": 4,                 /* tipo de sensor: sensor analógico */
        "value": <double>          /* último valor; si es -348201.3876, el valor es desconocido */
    }
}

Detectores de nivel de combustible

Los detectores lls, filling, theft y fuel_level devuelven la misma estructura.

Copied!
"lls": {
    "<sensor_id>": {
        "value": <double>,     /* último nivel de combustible calculado */
        "raw_value": <double>, /* último valor sin procesar del sensor */
        "filled": <double>,    /* cambio de volumen de combustible: positivo para llenado, negativo para descarga */
        "timeDiff": <uint>,    /* tiempo del mensaje con la máxima diferencia de volumen, tiempo UNIX */
        "latDiff": <double>,   /* latitud de ese mensaje */
        "lonDiff": <double>    /* longitud de ese mensaje */
    }
}

Detectores de batería

El detector battery_level funciona con sensores de nivel de batería y devuelve los valores procesados y sin procesar del nivel de batería actual.

Copied!
"battery_level": {
    "<sensor_id>": {
        "value": <double>,     /* último nivel de batería calculado */
        "raw_value": <double>  /* último valor sin procesar del sensor */
    }
}

El detector charge devuelve la siguiente estructura:

Copied!
"charge": {
    "<sensor_id>": {
        "charge": <double>,  /* cambio de volumen de recarga */
        "timeDiff": <uint>,  /* tiempo del mensaje con la máxima diferencia de recarga, tiempo UNIX */
        "latDiff": <double>, /* latitud de ese mensaje */
        "lonDiff": <double>  /* longitud de ese mensaje */
    }
}

El detector ev combina los dos tipos de eventos de la batería de un vehículo eléctrico. Devuelve la estructura battery_level para los eventos de nivel de batería y la estructura charge para los eventos de recarga. Use ev para obtener tanto los eventos de nivel de batería como los eventos de recarga desde un solo detector, o use battery_level y charge para obtenerlos por separado.

resource_drivers

El detector agrupa los datos por ID de conductor y devuelve el estado actual de la asignación.

Copied!
"resource_drivers": {
    "<driver_id>": {
        "state": <uint>,     /* estado de asignación: 0 para no asignado, 1 para asignado */
        "aflags": <uint>,    /* flags de asignación */
        "unit_id": <long>,   /* ID de la unidad a la que está asignado el conductor, la unidad de la que se desasignó el conductor o 0 */
        "propitem_cr_time": <uint>, /* hora de creación del conductor, tiempo UNIX */
        "switched_to": <long>,      /* ID de la unidad a la que se cambió el conductor; se devuelve solo cuando el conductor se asignó a otra unidad sin desasignarse de esta */
        "real_time_from": <uint>,   /* hora real de inicio de la asignación, tiempo UNIX */
        "validate_sensor_id": <uint> /* ID del sensor usado para validar la asignación automática y la desasignación que le sigue; 0 cuando no se usa la validación */
    }
}

Para obtener información detallada sobre estos campos, consulte resource_drivers en la página events/get.

El campo aflags puede contener los siguientes flags:

Flag Descripción
0x1 La asignación finalizó porque el conductor se cambió a otra unidad. El ID de esa unidad se devuelve en switched_to.
0x2 La asignación se inició porque el conductor se cambió desde otra unidad. Esto finalizó la asignación anterior en esa unidad.
0x4 La asignación se inició manualmente.
0x8 La asignación finalizó manualmente.
0x10 La asignación empieza con state 0 porque se asignó otro conductor exclusivo a la misma unidad.
0x20 La asignación finalizó porque se asignó otro conductor exclusivo a la misma unidad.

trips

El detector devuelve sus datos directamente, sin agruparlos por ID.

Copied!
"trips": {
    "state": <uint>,       /* estado del viaje: 0 para estacionamiento, 1 para viaje, 2 para parada */
    "max_speed": <uint>,   /* velocidad máxima durante el viaje */
    "curr_speed": <uint>,  /* velocidad actual */
    "avg_speed": <uint>,   /* velocidad promedio basada en la distancia */
    "distance": <uint>,    /* kilometraje GPS durante el viaje */
    "odometer": <uint>,    /* distancia total de todos los viajes en el historial */
    "course": <uint>,      /* rumbo */
    "altitude": <uint>,    /* altitud */
    "pos_flags": <uint>    /* flags de posición: 1 para error del sensor, 2 cuando el sensor no muestra movimiento */
}

speedings

El detector utiliza el único ID específico del detector 0.

Copied!
"speedings": {
    "0": {
        "max_speed": <uint>,  /* velocidad máxima durante el evento */
        "last_speed": <uint>, /* velocidad en el último mensaje del evento */
        "limit": <uint>       /* límite de velocidad */
    }
}

counters

El detector devuelve sus datos directamente, sin agruparlos por ID.

Copied!
"counters": {
    "engine_hours": <uint>,   /* contador de horas de motor, en segundos */
    "mileage": <uint>,        /* contador de kilometraje */
    "bytes": <uint>           /* contador de tráfico GPRS, en bytes */
}

eco_driving

El detector agrupa los datos por ID de criterio de conducción eficiente.

Copied!
"eco_driving": {
    "<eco_driving_id>": {
        "criterion_type": <text>,   /* tipo de criterio: "acceleration", "brake", "turn", "speeding", "sensor", "harsh", "idling" */
        "index": <uint>,            /* índice del criterio */
        "max_speed": <uint>,        /* velocidad máxima registrada durante la infracción, en km/h */
        "mark": <double>            /* puntos de penalización; pueden ser decimales y depender de la configuración del criterio y de la duración de la infracción */
    }
}

El detector eco_driving no está disponible en Wialon Local.

health_check

El detector agrupa los datos por ID de incidente.

Copied!
"health_check": {
    "<incident_id>": {
        "incident_type": <text>, /* tipo de incidente de diagnóstico */
        "duration": <uint>,      /* duración del incidente, en segundos */
        "sensor_id": <uint>      /* ID del sensor de la unidad; se omite cuando el incidente no está asociado con un sensor */
    }
}

Flag 0x4

Devuelve los parámetros disponibles del mensaje asociado con el evento. El objeto p puede omitirse o devolverse como un objeto vacío cuando no hay parámetros disponibles.

Cuando se devuelve, el objeto p utiliza la agrupación descrita para el flag 0x1.

Copied!
"<detector_name>": {
    "<detector_specific_id>": {
        "p": {
            "<parameter_name>": <any>
        }
    }
}

Para los detectores que devuelven datos directamente, no se incluye el nivel <detector_specific_id>:

Copied!
"<detector_name>": {
    "p": {
        "<parameter_name>": <any>
    }
}

Flag 0x8

Devuelve datos de detalle adicionales cuando están disponibles: track para trips y speedings, y data para eventos de sensores instantáneos y diferenciales.

Flag 0x10

Devuelve mensajes detallados para los detectores que los admiten. El array msgs se devuelve cuando el evento tiene datos de mensaje detallados.

Para sensores instantáneos y diferenciales (tipos 2 y 3), excepto sensores de nivel de combustible, se devuelve la siguiente respuesta:

Copied!
"sensors": {
    "<sensor_id>": {
        "msgs": [
            {
                "tm": <uint>,      /* hora del mensaje, tiempo UNIX */
                "v": <double>      /* valor */
            },
            ...
        ]
    },
    ...
}

El valor del campo v depende del tipo de sensor.

Para sensores de nivel de combustible, se devuelve la siguiente respuesta:

Copied!
"lls": {
    "<sensor_id>": {
        "msgs": [
            {
                "tm": <uint>,      /* hora del mensaje, tiempo UNIX */
                "v": <double>,     /* nivel de combustible procesado */
                "rv": <double>     /* valor sin procesar del sensor */
            },
            ...
        ]
    },
    ...
}

Los detectores filling, theft y fuel_level utilizan la misma estructura de mensaje detallado que lls cuando hay datos de mensaje detallados disponibles.

Para viajes, se devuelve la siguiente respuesta:

Copied!
"trips": {
    "msgs": [
        {
            "tm": <uint>,     /* hora del mensaje, tiempo UNIX */
            "x": <double>,    /* longitud */
            "y": <double>,    /* latitud */
            "c": <uint>,      /* rumbo */
            "z": <uint>,      /* altitud */
            "s": <uint>,      /* velocidad */
            "m": <double>,    /* kilometraje en el mensaje */
            "pf": <uint>      /* flags de posición; se omite cuando es 0 */
        },
        ...
    ]
}

Si la posición es privada, x, y y c se devuelven como 0.

Para excesos de velocidad, se devuelve la siguiente respuesta:

Copied!
"speedings": {
    "0": {
        "msgs": [
            {
                "tm": <uint>, /* hora del mensaje, tiempo UNIX */
                "x": <double>,/* longitud */
                "y": <double>,/* latitud */
                "c": <uint>,  /* rumbo */
                "s": <uint>,  /* velocidad */
                "l": <uint>,  /* límite de velocidad */
                "pf": <uint>  /* flags de posición; se omite cuando es 0 */
            },
            ...
        ]
    }
}

Si la posición es privada, x, y y c se devuelven como 0.

Para eventos de asignación de conductor, se devuelve la siguiente respuesta:

Copied!
"resource_drivers": {
    "<driver_id>": {
        "msgs": [
            {
                "tm": <uint>  /* hora de repetición de la asignación, tiempo UNIX */
            },
            ...
        ]
    }
}

Flag 0x20

Devuelve valores formateados del detector. La salida depende de la configuración de la unidad y de los parámetros measure y lang.

Los detectores eco_driving, health_check y resource_drivers no devuelven un objeto format para este flag.

Detectores de sensores

Los detectores ignition y sensors utilizan el siguiente objeto format:

Copied!
"<sensor_detector>": {
    "<sensor_id>": {
        "format": {
            "value": <text>,        /* valor formateado del sensor */
            "custom_value": <text>  /* valor personalizado del sensor correspondiente a value */
        }
    }
}

Detectores de nivel de combustible

Los detectores lls, filling, theft y fuel_level devuelven el siguiente objeto format:

Copied!
"lls": {
    "<sensor_id>": {
        "format": {
            "value": <text>,        /* nivel de combustible procesado formateado */
            "raw_value": <text>,    /* valor sin procesar del sensor formateado */
            "filled": <text>,       /* volumen de combustible llenado formateado; 0 cuando no hay llenado */
            "theft": <text>,        /* volumen de combustible descargado formateado; 0 cuando no hay descarga */
            "custom_value": <text>  /* valor personalizado del sensor correspondiente a value */
        }
    }
}

Detectores de batería

El detector battery_level devuelve el siguiente objeto format:

Copied!
"battery_level": {
    "<sensor_id>": {
        "format": {
            "value": <text>,        /* nivel de batería formateado */
            "raw_value": <text>,    /* valor sin procesar del sensor formateado */
            "custom_value": <text>  /* valor personalizado del sensor correspondiente a value */
        }
    }
}

El detector charge devuelve el siguiente objeto format:

Copied!
"charge": {
    "<sensor_id>": {
        "format": {
            "charge": <text>  /* volumen de recarga formateado */
        }
    }
}

El detector ev devuelve el objeto format de la estructura battery_level para eventos de nivel y de la estructura charge para eventos de recarga.

Para los sensores de nivel de batería, los campos value y raw_value del objeto format tienen en cuenta la clave show_as_percentage de la configuración del sensor. Si la clave está establecida en 1 y battery_capacity es mayor que 0, los campos devuelven el nivel de batería como un porcentaje de la capacidad, incluido el signo de porcentaje. De lo contrario, devuelven el nivel en kWh.

El porcentaje se aplica únicamente a los valores formateados del flag 0x20. El campo charge, los valores numéricos devueltos con el flag 0x2 y los datos de los informes y notificaciones siempre están en kWh.

trips

El detector devuelve el siguiente objeto format:

Copied!
"trips": {
    "format": {
        "distance": <text>,  /* distancia del viaje formateada */
        "avg_speed": <text>  /* velocidad promedio del viaje formateada */
    }
}

speedings

El detector devuelve el siguiente objeto format:

Copied!
"speedings": {
    "0": {
        "format": {
            "last_speed": <text>, /* velocidad formateada en el último mensaje */
            "limit": <text>,      /* límite de velocidad formateado */
            "max_speed": <text>   /* velocidad máxima formateada durante el evento */
        }
    }
}

counters

El detector devuelve el siguiente objeto format:

Copied!
"counters": {
    "format": {
        "engine_hours": <text | uint>, /* horas de motor formateadas; horas completas cuando no hay formato disponible */
        "mileage": <text>,             /* kilometraje formateado */
        "bytes": <uint>                /* tráfico GPRS, en KiB */
    }
}

Códigos de error

Si la solicitud no se completa, se devuelve un código de error.

Código de error Descripción
1 SID de solicitud no válido u obsoleto.
4 Error de validación de parámetros.
7 El servicio de eventos no está disponible.

Si nota un error en el texto, por favor resáltelo y presione Ctrl+Intro.