Wialon for developers User guide API reference events check_updates

check_updates

To get event updates for all items added to the session, use the events/check_updates method. Items can be units or resources.

Before calling this method, add the items to the session and set the detectors to monitor with events/update_items. If you monitor only units, you can also use events/update_units.

If the evt_flags parameter set in events/update_items or events/update_units includes the 0x200 flag, the updates are delivered in the units_update data of avl_evts. In this case, events/check_updates returns {}.

Endpoint

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

Parameters

All parameters are optional.

Parameter Description Default value
lang Language (2-character code). en
measure Measurement system:

  • 0 for SI;
  • 1 for US;
  • 2 for imperial.
 0
detalization Output flags (see below). Must be specified in decimal format. 7

Output flags

Flag Description
0x1 Basic event data: start and end positions, times, and event service flags.
0x2 Detector-specific data.
0x4 Parameters from the message associated with the event.
0x8 Extended detector detail data for supported detectors.
0x10 Detailed message data for supported detectors.
0x20 Formatted detector values.

Sensor type

Type value Description Event registration
1 Switcher sensors:

  • engine operation;
  • digital;
  • engine efficiency;
  • private mode;
  • real-time motion sensor;
  • alarm trigger;
  • counter (switch to ON/OFF).
 Events are active while the value is non-zero.
2 Instant sensors:

  • odometer;
  • relative engine hours;
  • instant fuel consumption;
  • counter (instant).
 Events are active while the value is non-zero.
3 Differential sensors:

  • mileage;
  • engine hours;
  • impulse fuel consumption;
  • absolute fuel consumption;
  • counter (differential, differential with overflow).
 Events are active while the calculated counter is non-zero.
4 Analog sensors:

  • temperature;
  • engine RPM;
  • voltage;
  • weight;
  • accelerometer;
  • fuel level impulse sensor;
  • temperature coefficient;
  • custom sensor;
  • driver;
  • trailer;
  • tag (passenger).
 Provides the current sensor state only; the sensors detector doesn’t register interval events for this type.

The table above doesn’t include fuel level and battery level sensors. The system processes their data with separate detectors: lls, fuel_level, filling, and theft for fuel level sensors, and battery_level, charge, and ev for battery level sensors. The impulse fuel level sensor isn’t affected: it belongs to the analog sensors (type 4). For the full list of detectors, see Event detector types.

Response

The response is grouped by item ID. For each item, the response contains an array of detector objects:

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

Each call returns event updates since the previous events/check_updates call in the same session. The method returns an empty object when there are no new updates.

Unless noted otherwise, values in the response (sensor, fuel, distance, speed, altitude, and mileage) use the measurement system from the measure parameter. Values in seconds, bytes, KiB, km/h, and UNIX time aren’t converted.

The structure of each detector object depends on the enabled output flags. Combine flags in the detalization parameter as needed. The sections below describe each flag separately.

0x1 flag

Returns basic data for each event. The response structure depends on the detector. The ignition, sensors, lls, filling, theft, fuel_level, ev, charge, and battery_level detectors use the unit sensor ID as the <detector_specific_id> object key. The eco_driving detector uses the eco driving criterion ID, health_check uses the incident ID, resource_drivers uses the driver ID, and speedings uses 0. Detectors such as trips and counters return their data directly, without grouping.

The eco_driving detector isn’t available in Wialon Local.

For detectors that group data by ID, the structure is as follows:

Copied!
{
    "<detector_name>": {
        "<detector_specific_id>": {
            "from": {
                "t": <uint>,    /* time (UNIX time) */
                "y": <double>,  /* latitude */
                "x": <double>   /* longitude */
            },
            "to": {
                "t": <uint>,    /* time (UNIX time) */
                "y": <double>,  /* latitude */
                "x": <double>   /* longitude */
            },
            "m": <uint>,       /* time of the last message associated with the event */
            "f": <uint>        /* event service flags */
        }
    }
}

For detectors that return data directly, such as trips and counters, the <detector_specific_id> level is not included:

Copied!
{
    "<detector_name>": {
        "from": {
            "t": <uint>,    /* time (UNIX time) */
            "y": <double>,  /* latitude */
            "x": <double>   /* longitude */
        },
        "to": {
            "t": <uint>,    /* time (UNIX time) */
            "y": <double>,  /* latitude */
            "x": <double>   /* longitude */
        },
        "m": <uint>,       /* time of the last message associated with the event */
        "f": <uint>        /* event service flags */
    }
}

For a private start or end position, for example when private mode hides the unit location, the x and y values are returned as 0.

0x2 flag

Returns detector-specific data. The structure depends on the detector.

Sensor detectors

For ignition and sensors, the returned structure for each sensor depends on the sensor type. The type field shows the sensor type.

Copied!
"ignition": {
    "<sensor_id>": {
        "state": <double>,    /* state: 0 for off, 1 for on */
        "type": 1,            /* sensor type: switcher sensor */
        "hours": <uint>,      /* engine hours for all history, in seconds */
        "switches": <uint>,   /* number of switches for all history */
        "value": <double>     /* last sensor value */
    }
}

Possible objects for sensors:

Copied!
"sensors": {
    "<sensor_id1>": {
        "state": <double>,         /* state: 0 for off, 1 for on */
        "type": 1,                 /* sensor type: switcher sensor */
        "hours": <uint>,           /* engine hours for all history, in seconds */
        "switches": <uint>,        /* number of switches for all history */
        "value": <double>          /* last sensor value */
    },
    "<sensor_id2>": {
        "type": 2,                 /* sensor type: instant sensor */
        "counter": <uint>,         /* number of consecutive messages in the event */
        "summary": <double>,       /* sum of values in the event */
        "total_counter": <uint>,   /* total number of messages in all history */
        "total_summary": <double>, /* total value sum in all history */
        "value": <double>          /* last value; if -348201.3876, the value is unknown */
    },
    "<sensor_id3>": {
        "type": 3,                 /* sensor type: differential sensor */
        "counter": <double>,       /* sum of values in the event */
        "total_counter": <double>, /* sum of values in the history */
        "value": <double>          /* last value; if -348201.3876, the value is unknown */
    },
    "<sensor_id4>": {
        "type": 4,                 /* sensor type: analog sensor */
        "value": <double>          /* last value; if -348201.3876, the value is unknown */
    }
}

Fuel level detectors

The lls, filling, theft, and fuel_level detectors return the same structure.

Copied!
"lls": {
    "<sensor_id>": {
        "value": <double>,     /* last calculated fuel level */
        "raw_value": <double>, /* last raw sensor value */
        "filled": <double>,    /* fuel volume change: positive for filling, negative for theft */
        "timeDiff": <uint>,    /* time of the message with the maximum volume difference, UNIX time */
        "latDiff": <double>,   /* latitude of that message */
        "lonDiff": <double>    /* longitude of that message */
    }
}

Battery detectors

The battery_level detector works with battery level sensors and returns the processed and raw values of the current battery level.

Copied!
"battery_level": {
    "<sensor_id>": {
        "value": <double>,     /* last calculated battery level */
        "raw_value": <double>  /* last raw sensor value */
    }
}

The charge detector returns the following structure:

Copied!
"charge": {
    "<sensor_id>": {
        "charge": <double>,  /* charge volume change */
        "timeDiff": <uint>,  /* time of the message with the maximum charge difference, UNIX time */
        "latDiff": <double>, /* latitude of that message */
        "lonDiff": <double>  /* longitude of that message */
    }
}

The ev detector combines both event types of an electric vehicle battery. It returns the battery_level structure for battery level events and the charge structure for charge events. Use ev to get both battery level and charge events from one detector, or use battery_level and charge to get them separately.

resource_drivers

The detector groups the data by driver ID and returns the current state of the assignment.

Copied!
"resource_drivers": {
    "<driver_id>": {
        "state": <uint>,     /* assignment state: 0 for unassigned, 1 for assigned */
        "aflags": <uint>,    /* assignment flags */
        "unit_id": <long>,   /* ID of the unit to which the driver is assigned, the unit from which the driver was unassigned, or 0 */
        "propitem_cr_time": <uint>, /* driver creation time, UNIX time */
        "switched_to": <long>,      /* ID of the unit to which the driver was switched; returned only when the driver was assigned to another unit without being unassigned from this one */
        "real_time_from": <uint>,   /* actual assignment start time, UNIX time */
        "validate_sensor_id": <uint> /* ID of the sensor used to validate the automatic assignment and the unassignment which follows it; 0 when validation isn't used */
    }
}

For details about these fields, see resource_drivers on the events/get page.

The aflags field can contain the following flags:

Flag Description
0x1 The assignment ended because the driver was switched to another unit. The ID of that unit is returned in switched_to.
0x2 The assignment started because the driver was switched from another unit. This ended the previous assignment on that unit.
0x4 The assignment was started manually.
0x8 The assignment was ended manually.
0x10 The assignment starts with state 0 because another exclusive driver was assigned to the same unit.
0x20 The assignment ended because another exclusive driver was assigned to the same unit.

trips

The detector returns its data directly, without grouping by ID.

Copied!
"trips": {
    "state": <uint>,       /* trip state: 0 for parking, 1 for trip, 2 for stop */
    "max_speed": <uint>,   /* maximum speed during the trip */
    "curr_speed": <uint>,  /* current speed */
    "avg_speed": <uint>,   /* average speed based on distance */
    "distance": <uint>,    /* GPS mileage during the trip */
    "odometer": <uint>,    /* total distance for all trips in the history */
    "course": <uint>,      /* course */
    "altitude": <uint>,    /* altitude */
    "pos_flags": <uint>    /* position flags: 1 for a sensor error, 2 when the sensor shows no movement */
}

speedings

The detector uses the single detector-specific ID 0.

Copied!
"speedings": {
    "0": {
        "max_speed": <uint>,  /* maximum speed during the event */
        "last_speed": <uint>, /* speed in the last message of the event */
        "limit": <uint>       /* speed limit */
    }
}

counters

The detector returns its data directly, without grouping by ID.

Copied!
"counters": {
    "engine_hours": <uint>,   /* engine hours counter, in seconds */
    "mileage": <uint>,        /* mileage counter */
    "bytes": <uint>           /* GPRS traffic counter, in bytes */
}

eco_driving

The detector groups the data by eco driving criterion ID.

Copied!
"eco_driving": {
    "<eco_driving_id>": {
        "criterion_type": <text>,   /* criterion type: "acceleration", "brake", "turn", "speeding", "sensor", "harsh", "idling" */
        "index": <uint>,            /* criterion index */
        "max_speed": <uint>,        /* maximum speed recorded during the violation, in km/h */
        "mark": <double>            /* penalty points; may be a decimal and depend on the criterion settings and violation duration */
    }
}

The eco_driving detector isn’t available in Wialon Local.

health_check

The detector groups the data by incident ID.

Copied!
"health_check": {
    "<incident_id>": {
        "incident_type": <text>, /* health check incident type */
        "duration": <uint>,      /* incident duration, in seconds */
        "sensor_id": <uint>      /* unit sensor ID; omitted when the incident isn't associated with a sensor */
    }
}

0x4 flag

Returns available parameters of the message associated with the event. The p object can be omitted or returned as an empty object when no parameters are available.

When returned, the p object uses the grouping described for the 0x1 flag.

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

For detectors that return data directly, the <detector_specific_id> level is not included:

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

0x8 flag

Returns additional detail data when available: track for trips and speedings, and data for instant and differential sensor events.

0x10 flag

Returns detailed messages for detectors that support them. The msgs array is returned when the event has detailed message data.

For instant and differential sensors (types 2 and 3), except fuel level sensors, the following response is returned:

Copied!
"sensors": {
    "<sensor_id>": {
        "msgs": [
            {
                "tm": <uint>,      /* message time, UNIX-time */
                "v": <double>      /* value */
            },
            ...
        ]
    },
    ...
}

The v field value depends on the sensor type.

For fuel level sensors, the following response is returned:

Copied!
"lls": {
    "<sensor_id>": {
        "msgs": [
            {
                "tm": <uint>,      /* message time, UNIX-time */
                "v": <double>,     /* processed fuel level */
                "rv": <double>     /* raw sensor value */
            },
            ...
        ]
    },
    ...
}

The filling, theft, and fuel_level detectors use the same detailed-message structure as lls when detailed message data is available.

For trips, the following response is returned:

Copied!
"trips": {
    "msgs": [
        {
            "tm": <uint>,     /* message time, UNIX time */
            "x": <double>,    /* longitude */
            "y": <double>,    /* latitude */
            "c": <uint>,      /* course */
            "z": <uint>,      /* altitude */
            "s": <uint>,      /* speed */
            "m": <double>,    /* mileage at the message */
            "pf": <uint>      /* position flags; omitted when 0 */
        },
        ...
    ]
}

If the position is private, x, y, and c are returned as 0.

For speedings, the following response is returned:

Copied!
"speedings": {
    "0": {
        "msgs": [
            {
                "tm": <uint>, /* message time, UNIX time */
                "x": <double>,/* longitude */
                "y": <double>,/* latitude */
                "c": <uint>,  /* course */
                "s": <uint>,  /* speed */
                "l": <uint>,  /* speed limit */
                "pf": <uint>  /* position flags; omitted when 0 */
            },
            ...
        ]
    }
}

If the position is private, x, y, and c are returned as 0.

For driver assignment events, the following response is returned:

Copied!
"resource_drivers": {
    "<driver_id>": {
        "msgs": [
            {
                "tm": <uint>  /* time of a repeated assignment within the event, UNIX time */
            },
            ...
        ]
    }
}

0x20 flag

Returns formatted detector values. The output depends on the unit settings and the measure and lang parameters.

The eco_driving, health_check, and resource_drivers detectors don’t return a format object for this flag.

Sensor detectors

The ignition and sensors detectors use the following format object:

Copied!
"<sensor_detector>": {
    "<sensor_id>": {
        "format": {
            "value": <text>,        /* formatted sensor value */
            "custom_value": <text>  /* custom sensor value corresponding to value */
        }
    }
}

Fuel level detectors

The lls, filling, theft, and fuel_level detectors return the following format object:

Copied!
"lls": {
    "<sensor_id>": {
        "format": {
            "value": <text>,        /* formatted processed fuel level */
            "raw_value": <text>,    /* formatted raw sensor value */
            "filled": <text>,       /* formatted filled fuel volume; 0 when there is no filling */
            "theft": <text>,        /* formatted stolen fuel volume; 0 when there is no theft */
            "custom_value": <text>  /* custom sensor value corresponding to value */
        }
    }
}

Battery detectors

The battery_level detector returns the following format object:

Copied!
"battery_level": {
    "<sensor_id>": {
        "format": {
            "value": <text>,        /* formatted battery level */
            "raw_value": <text>,    /* formatted raw sensor value */
            "custom_value": <text>  /* custom sensor value corresponding to value */
        }
    }
}

The charge detector returns the following format object:

Copied!
"charge": {
    "<sensor_id>": {
        "format": {
            "charge": <text>  /* formatted charge volume */
        }
    }
}

The ev detector returns the format object from the battery_level structure for level events and from the charge structure for charge events.

For battery level sensors, the value and raw_value fields of the format object take the show_as_percentage key of the sensor configuration into account. If the key is set to 1 and battery_capacity is greater than 0, the fields return the battery level as a percentage of the capacity, with the percent sign included. Otherwise, they return the level in kWh.

The percentage applies to the formatted values of the 0x20 flag only. The charge field, the numeric values returned with the 0x2 flag, and the data in reports and notifications are always in kWh.

trips

The detector returns the following format object:

Copied!
"trips": {
    "format": {
        "distance": <text>,  /* formatted trip distance */
        "avg_speed": <text>  /* formatted average trip speed */
    }
}

speedings

The detector returns the following format object:

Copied!
"speedings": {
    "0": {
        "format": {
            "last_speed": <text>, /* formatted speed in the last message */
            "limit": <text>,      /* formatted speed limit */
            "max_speed": <text>   /* formatted maximum speed during the event */
        }
    }
}

counters

The detector returns the following format object:

Copied!
"counters": {
    "format": {
        "engine_hours": <text | uint>, /* formatted engine hours; whole hours when no formatting is available */
        "mileage": <text>,             /* formatted mileage */
        "bytes": <uint>                /* GPRS traffic, in KiB */
    }
}

Error codes

If the request isn’t completed, an error code is returned.

Error code Description
1 Invalid or obsolete request SID.
4 Parameter validation error.
7 The event service is unavailable.

If you find a mistake in the text, please select it and press Ctrl+Enter.