Справочный центр Wialon

check_updates

Чтобы получить обновления событий для всех элементов, добавленных в сессию, используйте метод events/check_updates. Элементами могут быть объекты или ресурсы.

Перед вызовом этого метода добавьте элементы в сессию и установите детекторы для отслеживания с помощью events/update_items. Если вы отслеживаете только объекты, можно также использовать events/update_units.

Если параметр evt_flags, установленный в events/update_items или events/update_units, включает флаг 0x200, обновления возвращаются в поле units_update метода avl_evts. В этом случае events/check_updates возвращает {}.

Конечная точка

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

Параметры

Все параметры необязательны.

Параметр Описание Значение по умолчанию
lang Язык (двухсимвольный код). en
measure Система измерения:

  • 0 — СИ;
  • 1 — американская;
  • 2 — имперская.
0
detalization Флаги состава ответа (см. ниже). Должны быть указаны в десятичном формате. 7

Флаги состава ответа

Флаг Описание
0x1 Основные данные события: позиции и время начала и окончания, а также служебные флаги событий.
0x2 Данные, зависящие от типа детектора.
0x4 Параметры сообщения, связанного с событием.
0x8 Расширенные подробные данные детектора для поддерживаемых детекторов.
0x10 Подробные данные сообщений для поддерживаемых детекторов.
0x20 Отформатированные значения детектора.

Тип датчика

Значение type Описание Регистрация событий
1 Датчики-переключатели:

  • датчик зажигания;
  • произвольный цифровой датчик;
  • датчик полезной работы двигателя;
  • частный режим;
  • датчик мгновенного определения движения;
  • тревожная кнопка;
  • счетчик (переключатель с ВЫКЛ на ВКЛ/с ВКЛ на ВЫКЛ).
События активны, пока значение ненулевое.
2 Мгновенные датчики:

  • относительный одометр;
  • относительные моточасы;
  • датчик мгновенного расхода топлива;
  • счетчик (мгновенный).
События активны, пока значение ненулевое.
3 Дифференциальные датчики:

  • датчик пробега;
  • абсолютные моточасы;
  • импульсный датчик расхода топлива;
  • датчик абсолютного расхода топлива;
  • счетчик (дифференциальный, дифференциальный с переполнением).
События активны, пока рассчитанный счётчик ненулевой.
4 Аналоговые датчики:

  • датчик температуры;
  • датчик оборотов двигателя;
  • датчик напряжения;
  • датчик веса;
  • акселерометр;
  • импульсный датчик уровня топлива;
  • коэффициент температуры;
  • произвольный датчик;
  • назначение водителя;
  • назначение прицепа;
  • датчик пассажиров.
Предоставляет только текущее состояние датчика; детектор sensors не регистрирует интервальные события для этого типа.

Таблица выше не включает датчики уровня топлива и уровня заряда батареи. Система обрабатывает их данные с помощью отдельных детекторов: lls, fuel_level, filling и theft для датчиков уровня топлива, а также battery_level, charge и ev для датчиков уровня заряда батареи. Это не касается импульсного датчика уровня топлива: он относится к аналоговым датчикам (тип 4). Полный список детекторов см. в разделе Типы детекторов событий.

Ответ

Ответ сгруппирован по ID элемента. Для каждого элемента ответ содержит массив объектов детекторов:

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

Каждый вызов возвращает обновления событий с момента предыдущего вызова events/check_updates в той же сессии. Метод возвращает пустой объект, если новых обновлений нет.

Если не указано иное, значения в ответе (датчики, топливо, расстояние, скорость, высота и пробег) используют систему измерения из параметра measure. Значения в секундах, байтах, КиБ, км/ч и UNIX time не преобразуются.

Структура каждого объекта детектора зависит от включённых флагов состава ответа. Комбинируйте флаги в параметре detalization по мере необходимости. В разделах ниже описывается каждый флаг отдельно.

Флаг 0x1

Возвращает основные данные для каждого события. Структура ответа зависит от детектора. Детекторы ignition, sensors, lls, filling, theft, fuel_level, ev, charge и battery_level используют ID датчика объекта в качестве ключа объекта <detector_specific_id>. Детектор eco_driving использует ID критерия качества вождения, health_check использует ID инцидента, resource_drivers использует ID водителя, а speedings использует 0. Детекторы, такие как trips и counters, возвращают данные напрямую, без группировки.

Для детекторов, которые группируют данные по ID, структура следующая:

Copied!
{
    "<detector_name>": {
        "<detector_specific_id>": {
            "from": {
                "t": <uint>,    /* время (UNIX time) */
                "y": <double>,  /* широта */
                "x": <double>   /* долгота */
            },
            "to": {
                "t": <uint>,    /* время (UNIX time) */
                "y": <double>,  /* широта */
                "x": <double>   /* долгота */
            },
            "m": <uint>,       /* время последнего сообщения, связанного с событием */
            "f": <uint>        /* служебные флаги событий */
        }
    }
}

Для детекторов, которые возвращают данные напрямую, таких как trips и counters, уровень <detector_specific_id> не включается:

Copied!
{
    "<detector_name>": {
        "from": {
            "t": <uint>,    /* время (UNIX time) */
            "y": <double>,  /* широта */
            "x": <double>   /* долгота */
        },
        "to": {
            "t": <uint>,    /* время (UNIX time) */
            "y": <double>,  /* широта */
            "x": <double>   /* долгота */
        },
        "m": <uint>,       /* время последнего сообщения, связанного с событием */
        "f": <uint>        /* служебные флаги событий */
    }
}

Для приватной начальной или конечной позиции, например, когда частный режим скрывает местоположение объекта, значения x и y возвращаются как 0.

Флаг 0x2

Возвращает данные, зависящие от детектора. Структура зависит от детектора.

Детекторы датчиков

Для ignition и sensors структура, возвращаемая для каждого датчика, зависит от типа датчика. Поле type показывает тип датчика.

Copied!
"ignition": {
    "<sensor_id>": {
        "state": <double>,    /* состояние: 0 — выключен, 1 — включен */
        "type": 1,            /* тип датчика: переключатель */
        "hours": <uint>,      /* моточасы за всю историю, в секундах */
        "switches": <uint>,   /* количество переключений за всю историю */
        "value": <double>     /* последнее значение датчика */
    }
}

Возможные объекты для sensors:

Copied!
"sensors": {
    "<sensor_id1>": {
        "state": <double>,         /* состояние: 0 — выключен, 1 — включен */
        "type": 1,                 /* тип датчика: переключатель */
        "hours": <uint>,           /* моточасы за всю историю, в секундах */
        "switches": <uint>,        /* количество переключений за всю историю */
        "value": <double>          /* последнее значение */
    },
    "<sensor_id2>": {
        "type": 2,                 /* тип датчика: мгновенный датчик */
        "counter": <uint>,         /* число последовательных сообщений в событии */
        "summary": <double>,       /* сумма значений в событии */
        "total_counter": <uint>,   /* общее число сообщений за всю историю */
        "total_summary": <double>, /* общая сумма значений за всю историю */
        "value": <double>          /* последнее значение; -348201.3876 означает, что значение неизвестно */
    },
    "<sensor_id3>": {
        "type": 3,                 /* тип датчика: дифференциальный датчик */
        "counter": <double>,       /* сумма значений в событии */
        "total_counter": <double>, /* сумма значений за всю историю */
        "value": <double>          /* последнее значение; -348201.3876 означает, что значение неизвестно */
    },
    "<sensor_id4>": {
        "type": 4,                 /* тип датчика: аналоговый датчик */
        "value": <double>          /* последнее значение; -348201.3876 означает, что значение неизвестно */
    }
}

Детекторы уровня топлива

Детекторы lls, filling, theft и fuel_level возвращают одну и ту же структуру.

Copied!
"lls": {
    "<sensor_id>": {
        "value": <double>,     /* последний рассчитанный уровень топлива */
        "raw_value": <double>, /* последнее исходное значение датчика */
        "filled": <double>,    /* изменение объёма топлива: положительное — заправка, отрицательное — слив */
        "timeDiff": <uint>,    /* время сообщения с максимальной разницей объёма, UNIX time */
        "latDiff": <double>,   /* широта этого сообщения */
        "lonDiff": <double>    /* долгота этого сообщения */
    }
}

Детекторы батареи

Детектор battery_level работает с датчиками уровня заряда батареи и возвращает обработанное и исходное значения текущего уровня заряда батареи.

Copied!
"battery_level": {
    "<sensor_id>": {
        "value": <double>,     /* последний рассчитанный уровень заряда батареи */
        "raw_value": <double>  /* последнее исходное значение датчика */
    }
}

Детектор charge возвращает следующую структуру:

Copied!
"charge": {
    "<sensor_id>": {
        "charge": <double>,  /* изменение объёма зарядки */
        "timeDiff": <uint>,  /* время сообщения с максимальной разницей объёма зарядки, UNIX time */
        "latDiff": <double>, /* широта этого сообщения */
        "lonDiff": <double>  /* долгота этого сообщения */
    }
}

Детектор ev объединяет оба типа событий батареи электромобиля. Он возвращает структуру battery_level для событий уровня заряда батареи и структуру charge для событий зарядки. Используйте ev, чтобы получать события уровня заряда батареи и зарядки через один детектор, или используйте battery_level и charge, чтобы получать их отдельно.

resource_drivers

Детектор группирует данные по ID водителя и возвращает текущее состояние назначения.

Copied!
"resource_drivers": {
    "<driver_id>": {
        "state": <uint>,     /* состояние назначения: 0 — снят, 1 — назначен */
        "aflags": <uint>,    /* флаги назначения */
        "unit_id": <long>,   /* ID объекта, на который назначен водитель, с которого водитель снят, или 0 */
        "propitem_cr_time": <uint>, /* время создания водителя, UNIX time */
        "switched_to": <long>,      /* ID объекта, на который был переключен водитель; возвращается только в том случае, если водитель был назначен на другой объект без снятия с этого */
        "real_time_from": <uint>,   /* фактическое время начала назначения, UNIX time */
        "validate_sensor_id": <uint> /* ID датчика, используемого для подтверждения автоматического назначения и следующего за ним снятия; 0, если подтверждение не используется */
    }
}

Подробную информацию об этих полях см. в разделе resource_drivers на странице events/get.

Поле aflags может содержать следующие флаги:

Флаг Описание
0x1 Назначение завершилось из-за переключения водителя на другой объект. ID этого объекта возвращается в поле switched_to.
0x2 Назначение началось из-за переключения водителя с другого объекта. При этом предыдущее назначение на том объекте завершилось.
0x4 Назначение было начато вручную.
0x8 Назначение было завершено вручную.
0x10 Назначение начинается со state 0, потому что на тот же объект был назначен другой эксклюзивный водитель.
0x20 Назначение завершилось, потому что на тот же объект был назначен другой эксклюзивный водитель.

trips

Детектор возвращает данные напрямую, без группировки по ID.

Copied!
"trips": {
    "state": <uint>,       /* состояние поездки: 0 — стоянка, 1 — поездка, 2 — остановка */
    "max_speed": <uint>,   /* максимальная скорость во время поездки */
    "curr_speed": <uint>,  /* текущая скорость */
    "avg_speed": <uint>,   /* средняя скорость на основе расстояния */
    "distance": <uint>,    /* GPS-пробег во время поездки */
    "odometer": <uint>,    /* общее расстояние для всех поездок в истории */
    "course": <uint>,      /* курс */
    "altitude": <uint>,    /* высота */
    "pos_flags": <uint>    /* флаги позиции: 1 — ошибка датчика, 2 — датчик не фиксирует движение */
}

speedings

Детектор использует единственный специфичный для детектора ID 0.

Copied!
"speedings": {
    "0": {
        "max_speed": <uint>,  /* максимальная скорость во время события */
        "last_speed": <uint>, /* скорость в последнем сообщении события */
        "limit": <uint>       /* ограничение скорости */
    }
}

counters

Детектор возвращает данные напрямую, без группировки по ID.

Copied!
"counters": {
    "engine_hours": <uint>,   /* счётчик моточасов, в секундах */
    "mileage": <uint>,        /* счётчик пробега */
    "bytes": <uint>           /* счётчик GPRS-трафика, в байтах */
}

eco_driving

Детектор группирует данные по ID критерия качества вождения.

Copied!
"eco_driving": {
    "<eco_driving_id>": {
        "criterion_type": <text>,   /* тип критерия: "acceleration", "brake", "turn", "speeding", "sensor", "harsh", "idling" */
        "index": <uint>,            /* индекс критерия */
        "max_speed": <uint>,        /* максимальная скорость, зафиксированная во время нарушения, в км/ч */
        "mark": <double>            /* штрафные баллы; может включать дробную часть и зависит от настроек критерия и длительности нарушения */
    }
}

health_check

Детектор группирует данные по ID инцидента.

Copied!
"health_check": {
    "<incident_id>": {
        "incident_type": <text>, /* тип инцидента диагностики */
        "duration": <uint>,      /* длительность инцидента, в секундах */
        "sensor_id": <uint>      /* ID датчика объекта; не включается, если инцидент не связан с датчиком */
    }
}

Флаг 0x4

Возвращает доступные параметры сообщения, связанного с событием. Объект p не включается или возвращается как пустой объект, если параметры недоступны.

Если объект возвращается, он использует группировку, описанную для флага 0x1.

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

Для детекторов, которые возвращают данные напрямую, уровень <detector_specific_id> не включается:

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

Флаг 0x8

Возвращает дополнительные подробные данные, если они доступны: track для trips и speedings, data для событий мгновенных и дифференциальных датчиков.

Флаг 0x10

Возвращает подробные сообщения для детекторов, которые их поддерживают. Массив msgs возвращается, когда доступны подробные данные сообщений события.

Для мгновенных и дифференциальных датчиков (типы 2 и 3), кроме датчиков уровня топлива, возвращается следующий ответ:

Copied!
"sensors": {
    "<sensor_id>": {
        "msgs": [
            {
                "tm": <uint>,      /* время сообщения, UNIX time */
                "v": <double>      /* значение */
            },
            ...
        ]
    },
    ...
}

Значение поля v зависит от типа датчика.

Для датчиков уровня топлива возвращается следующий ответ:

Copied!
"lls": {
    "<sensor_id>": {
        "msgs": [
            {
                "tm": <uint>,      /* время сообщения, UNIX time */
                "v": <double>,     /* рассчитанный уровень топлива */
                "rv": <double>     /* исходное значение датчика */
            },
            ...
        ]
    },
    ...
}

Детекторы filling, theft и fuel_level используют ту же структуру подробных сообщений, что и lls, если подробные данные сообщений доступны.

Для поездок возвращается следующий ответ:

Copied!
"trips": {
    "msgs": [
        {
            "tm": <uint>,     /* время сообщения, UNIX time */
            "x": <double>,    /* долгота */
            "y": <double>,    /* широта */
            "c": <uint>,      /* курс */
            "z": <uint>,      /* высота */
            "s": <uint>,      /* скорость */
            "m": <double>,    /* пробег на момент сообщения */
            "pf": <uint>      /* флаги позиции; не включается, если равно 0 */
        },
        ...
    ]
}

Если позиция приватная, значения x, y и c возвращаются как 0.

Для превышений скорости возвращается следующий ответ:

Copied!
"speedings": {
    "0": {
        "msgs": [
            {
                "tm": <uint>, /* время сообщения, UNIX time */
                "x": <double>,/* долгота */
                "y": <double>,/* широта */
                "c": <uint>,  /* курс */
                "s": <uint>,  /* скорость */
                "l": <uint>,  /* ограничение скорости */
                "pf": <uint>  /* флаги позиции; не включается, если равно 0 */
            },
            ...
        ]
    }
}

Если позиция приватная, значения x, y и c возвращаются как 0.

Для событий назначения водителей возвращается следующий ответ:

Copied!
"resource_drivers": {
    "<driver_id>": {
        "msgs": [
            {
                "tm": <uint>  /* время повторного назначения в рамках  события, UNIX-время */
            },
            ...
        ]
    }
}

Флаг 0x20

Возвращает отформатированные значения детектора. Вывод зависит от настроек объекта и параметров measure и lang.

Детекторы eco_driving, health_check и resource_drivers не возвращают объект format для этого флага.

Детекторы датчиков

Детекторы ignition и sensors используют следующий объект format:

Copied!
"<sensor_detector>": {
    "<sensor_id>": {
        "format": {
            "value": <text>,        /* отформатированное значение датчика */
            "custom_value": <text>  /* пользовательское значение датчика, соответствующее value */
        }
    }
}

Детекторы уровня топлива

Детекторы lls, filling, theft и fuel_level возвращают следующий объект format:

Copied!
"lls": {
    "<sensor_id>": {
        "format": {
            "value": <text>,        /* отформатированный рассчитанный уровень топлива */
            "raw_value": <text>,    /* отформатированное исходное значение датчика */
            "filled": <text>,       /* отформатированный объём заправленного топлива; 0, если заправки не было */
            "theft": <text>,        /* отформатированный объём слитого топлива; 0, если слива не было */
            "custom_value": <text>  /* пользовательское значение датчика, соответствующее value */
        }
    }
}

Детекторы батареи

Детектор battery_level возвращает следующий объект format:

Copied!
"battery_level": {
    "<sensor_id>": {
        "format": {
            "value": <text>,        /* отформатированный уровень заряда батареи */
            "raw_value": <text>,    /* отформатированное исходное значение датчика */
            "custom_value": <text>  /* пользовательское значение датчика, соответствующее value */
        }
    }
}

Детектор charge возвращает следующий объект format:

Copied!
"charge": {
    "<sensor_id>": {
        "format": {
            "charge": <text>  /* отформатированный объём зарядки */
        }
    }
}

Детектор ev возвращает объект format из структуры battery_level для событий уровня заряда батареи и из структуры charge для событий зарядки.

Для датчиков уровня заряда батареи поля value и raw_value объекта format учитывают ключ show_as_percentage в настройках датчика. Если для этого ключп установлено значение 1, а значение battery_capacity больше 0, в этих полях возвращается уровень заряда батареи в процентах от ёмкости, со знаком процента. В противном случае в них возвращается уровень в кВт·ч.

trips

Детектор возвращает следующий объект format:

Copied!
"trips": {
    "format": {
        "distance": <text>,  /* отформатированное расстояние поездки */
        "avg_speed": <text>  /* отформатированная средняя скорость поездки */
    }
}

speedings

Детектор возвращает следующий объект format:

Copied!
"speedings": {
    "0": {
        "format": {
            "last_speed": <text>, /* отформатированная скорость в последнем сообщении */
            "limit": <text>,      /* отформатированное ограничение скорости */
            "max_speed": <text>   /* отформатированная максимальная скорость во время события */
        }
    }
}

counters

Детектор возвращает следующий объект format:

Copied!
"counters": {
    "format": {
        "engine_hours": <text | uint>, /* отформатированные моточасы; целые часы, если форматирование недоступно */
        "mileage": <text>,             /* отформатированный пробег */
        "bytes": <uint>                /* GPRS-трафик, в КиБ */
    }
}

Коды ошибок

Если запрос не выполнен, возвращается код ошибки.

Код ошибки Описание
1 Неверный или устаревший SID запроса.
4 Ошибка валидации параметров.
7 Сервис событий недоступен.

Если вы заметили ошибку в тексте, пожалуйста, выделите её и нажмите Ctrl+Enter.