Usm gps 2: различия между версиями

Материал из WiKi - UserSide
Нет описания правки
 
(не показано 89 промежуточных версий 3 участников)
Строка 1: Строка 1:
[[Usm_gps_2_EN|en]] | [[Usm_gps_2|ru]]
'''Данный модуль является заменой устаревшему модулю [[us_gps]]'''
== Описание ==
== Описание ==


Строка 16: Строка 20:
== Поддерживаемые протоколы GPS-трекеров ==
== Поддерживаемые протоколы GPS-трекеров ==


На данный момент модуль поддерживает работу восьми протоколов. Ниже перечислены протоколы и модели GPS-устройств, работающих по этим протоколам.
На данный момент поддерживаются следующие протоколы. Обратите внимание, что список поддерживаемых устройств может быть не полным, так как нам неизвестны все устройства, выпускаемые с поддержкой того или иного протокола. Также важно знать, что вовсе не обязательно модель устройства должна быть похожа на протокол, который фактически прошит в этом устройстве.


=== OsmAnd ===
=== OsmAnd ===
Строка 22: Строка 26:
Порт по умолчанию: '''5055'''
Порт по умолчанию: '''5055'''


Поддерживаемые устройства: Данный протокол используется в основном мобильными приложениями, такими как OsmAnd, SendLocation, Locus Pro Android, Custodium, Traccar
Поддерживаемые устройства: Данный протокол используется в основном мобильными приложениями, такими как OsmAnd, [https://gpslogger.app/ GpsLogger for Android], SendLocation, Locus Pro Android, Custodium, Traccar и другими.
 
Так как данный протокол основан на HTTP-запросе с передачей всех данных через параметры этого запроса, то может использоваться в любых приложениях. Для передачи координат достаточно выполнить HTTP запрос:
<code><nowiki>http://module.ip.address:5055/?id={id}&lat={lat}&lon={lon}&timestamp={timestamp}&hdop={hdop}&speed={speed}</nowiki></code>
где вместо следующих переменных подставить нужные:
* {id} - идентификатор устройства (IMEI, серийный номер или любой другой, позволяющий идентифицировать конкретный трекер)
* {lat} - географическая широта в десятичном формате градусов, например, 46.488085
* {lon} - географическая долгота в десятичном формате градусов, например, 30.741091
* {timestamp} - целочисленная метка времени в формате UNIXTIME
* {hdop} - коэффициент снижения точности в горизонтальной плоскости позиционирования (HDOP). Число с плавающей точкой. Параметр можно не передавать.
* {speed} - моментальная скорость в км/ч. Число с плавающей точкой.
 
Например, для GpsLogger в настройке [https://gpslogger.app/#customurl CustomURL] нужно ввести следующий адрес: <code><nowiki>http://module.ip.address:5055/?id=%ser&lat=%lat&lon=%lon&timestamp=%timestamp&hdop=%hdop&speed=%spd</nowiki></code>.


=== GT02A ===
=== GT02A ===


Порт по умолчанию: '''8822'''
Порт по умолчанию: '''5022'''
 
Поддерживаемые устройства: Данный протокол реализован в большом количестве "китайских" устройств, так что точно составить их список невозможно. Однако это один из самых распространенных протоколов, встречающихся в дешевых GPS-трекерах типа noname.


Поддерживаемые устройства: Данный протокол реализован в большом количестве "китайских" устройств, так что точно составить их список довольно сложно. Однако это один из самых распространенных протоколов, встречающихся в дешевых GPS-трекерах типа noname.
Сообщения этого протокола начинаются с заголовочных символов <code>hh</code> или в виде HEX: <code>0x68 0x68</code>.


=== GT06 ===
=== GT06 ===


Порт по умолчанию: '''8833'''
Порт по умолчанию: '''5023'''


Поддерживаемые устройства: GT06, GT06N, GT09, Heacent 908, GT03A, GT03B, GS503, ET100, GT100, GT06D, GK301, JM01, JM08, GT02D, IB-GT102, CRX1, JV200, TP06A, BW08, TR06, JI09, Concox GT300, WeTrack 2
Поддерживаемые устройства: GT06, GT06N, GT09, Heacent 908, GT03A, GT03B, GS503, ET100, GT100, GT06D, GK301, JM01, JM08, GT02D, IB-GT102, CRX1, JV200, TP06A, BW08, TR06, JI09, Concox GT300, WeTrack 2
Сообщения этого протокола начинаются с заголовочных символов <code>xx</code> или в виде HEX: <code>0x78 0x78</code>.


=== Meiligao ===
=== Meiligao ===


Порт по умолчанию: '''8844'''
Порт по умолчанию: '''5009'''


Поддерживаемые устройства: GT30i, GT60, VT300, VT310, VT400, GT30, GT30X, PST-AVL01, PT03, PT60, PT300X, PT30, GT-110P, GT-110K, GT-110M, GT-110ES, GT-110ZS, AVL-011, VT900, P008, GT 30, CT01, CT03, CT04, CT04-R, CT04-X, OCT600, MT01, MT02, PT01, PT03, VT1000, GSY007, T200, iStartek, VT310N
Поддерживаемые устройства: GT30i, GT60, VT300, VT310, VT400, GT30, GT30X, PST-AVL01, PT03, PT60, PT300X, PT30, GT-110P, GT-110K, GT-110M, GT-110ES, GT-110ZS, AVL-011, VT900, P008, GT 30, CT01, CT03, CT04, CT04-R, CT04-X, OCT600, MT01, MT02, PT01, PT03, VT1000, GSY007, T200, iStartek, VT310N
Сообщения этого протокола начинаются с заголовочных символов <code>$$</code> или в виде HEX: <code>0x24 0x24</code>.


=== Autofon v4 ===
=== Autofon v4 ===


Порт по умолчанию: '''8854'''
Порт по умолчанию: '''5079'''


Поддерживаемые устройства: AutoFon 4.4, AutoFon 4.5
Поддерживаемые устройства: AutoFon 4.4, AutoFon 4.5
Строка 50: Строка 72:
=== Autofon v5 ===
=== Autofon v5 ===


Порт по умолчанию: '''8855'''
Порт по умолчанию: '''5077'''


Поддерживаемые устройства: AutoFon SE, AutoFon SE+, AutoFon D, AutoFon D-Moto, AutoFon Dialog Mayak, AutoFon S, AutoFon GL Mayak
Поддерживаемые устройства: AutoFon SE, AutoFon SE+, AutoFon D, AutoFon D-Moto, AutoFon Dialog Mayak, AutoFon S, AutoFon GL Mayak
Строка 56: Строка 78:
=== Autofon v7 ===
=== Autofon v7 ===


Порт по умолчанию: '''8857'''
Порт по умолчанию: '''5099'''


Поддерживаемые устройства: AutoFon Alpha, AutoFon Alpha XL, AutoFon Alpha 2XL
Поддерживаемые устройства: AutoFon Alpha, AutoFon Alpha XL, AutoFon Alpha 2XL
=== Autofon v9 (Микро-маяк) ===
Порт по умолчанию: '''9109'''
Поддерживаемые устройства: АвтоФон Микро-Маяк, АвтоФон Микро-Маяк+
Начиная с версии модуля 2.3


=== Wialon ===
=== Wialon ===


Порт по умолчанию: '''8866'''
Порт по умолчанию: '''5039'''
 
Поддерживаемые устройства: Wialon IPS, MasterKit, MasterKit BM8009, NeoTech TR­1000, а также по данному протоколу передает навигационную информацию сервис uonline.com.ua (если у вас есть трекеры, подключенные к этому сервису, то он может выступать в роли прокси-сервера, передавая информацию в модуль usm_gps_2).
 
Сообщения этого протокола начинаются с заголовочного символа <code>#</code> или в виде HEX: <code>0x23</code>.
 
'''Важно!''' Мобильное приложение GpsTag от компании Gurtam (разработчика протокола Wialon) '''не поддерживается''' (разработчики Gurtam [https://forum.gurtam.com/viewtopic.php?pid=85137#p85137 специально изменили протокол], чтобы бесплатное приложение было возможно использовать только на серверах Gurtam).
 
=== OKO-NAVI ===
 
Порт по умолчанию: '''5098'''
 
Поддерживаемые устройства: Все устройства компании [https://xn--j1ahb.xn--j1amh/ OKO]
 
Сообщения этого протокола заключены в фигурные скобки <code>{...}</code> или в виде HEX: <code>0x7b ... 0x7d</code>.
 
=== MikroTik ===
 
Порт по умолчанию: '''5200'''
 
Поддерживаемые устройства: Все, оснащенные модулем GSP, например, [https://mikrotik.com/product/ltap_mini LtAP mini] Протокол основан на передаче в теле запроса HTTP-POST данных в виде JSON:
{
  "tracker_id": "12345678",
  "lat": "N 12 34' 5.678''",
  "lon": "E 87 65' 4.321''",
  "speed": "1.234567 km/h",
  "heading": "128.039993 deg. True",
  "hdop": 122
}
Поэтому может использоваться не только для MikroTik.
 
Модуль рассчитан на прием координат в формате DMS — этот режим включен в MikroTik по умолчанию. Если вы изменяли формат координат ранее, то нужно переключиться на использование именно этого формата командой:
/system gps set coordinate-format=dms
 
Простейший скрипт, который следует добавить в планировщик MikroTik, предварительно изменив значения первых трех переменных:
{
:local trackerID "12345678"
:local url "http://usm_gps-url-here/"
:local port 5200
:local lat
:local lon
:local spd
:local heading
:local hdop
/system gps monitor once do={
    :set $lat $("latitude")
    :set $lon $("longitude")
    :set $spd $("speed")
    :set $heading $("true-bearing")
    :set $hdop $("horizontal-dilution")
}
/tool fetch mode=http url=$url port=$port http-method=post http-header-field="Content-Type: application/json" \
http-data=("{\"tracker_id\": \"".$trackerID."\",\"lat\": \"".$lat."\",\"lon\": \"".$lon."\",\"speed\": \"".$spd."\",\"heading\": \"".$heading."\",\"hdop\":
\"".$hdop."\"}")
}
 
Переменная '''trackerID''' содержит уникальный в пределах USERSIDE идентификатор данного Микротика. Придумайте его сами. В классических GPS-трекерах идентификатор вшит в каждый трекер и представляет собой обычно целиком или частично IMEI или серийный номер трекера. Но так как в Микротике нет никаких подобных идентификаторов, вы должны реализовать его самостоятельно. Он может быть любой символьной строкой, не обязательно состоящей из цифр.
 
Также Вы можете доработать этот скрипт, чтобы, например, идентификатором был МАС-адрес первого интерфейса (чтобы не вводить вручную, если так проще), а также можно доработать скрипт, чтобы он хранил предыдущее состояние в глобальных переменных и передавать на сервер информацию только в случае, если новые значения отличаются от предыдущих - это сэкономит трафик, а также избавит от "клякс" на местах стоянки, когда скорость 0 км/ч.


Поддерживаемые устройства: Wialon IPS, MasterKit, MasterKit BM8009, NeoTech TR­1000, а также по данному протоколу передает навигационную информацию сервис uonline.com.ua (если у вас есть трекеры, подключенные к этому сервису, то он может выступать в роли прокси-сервера, передавая информацию в модуль usm_gps_2)
=== H02 ===
 
Порт по умолчанию: '''5013'''
 
Поддерживаемые устройства: H02, H-02A, H-02B, TX-2, H-06, H08, GTLT3, TK110, TK102B-MT61, NT201, NT202, S31, LK109, LK106, LK208, LK206, LK310, LK206A, LK206B, MI-G6, CC830, CCTR, CCTR-630, AT-18, GRTQ, LK210, TR-02
 
Поддерживается как текстовый, так и бинарный протоколы (начиная с версии модуля 2.3).
 
Сообщения текстового протокола начинаются с заголовочных символов <code>*HQ</code> или в виде HEX: <code>0x2A 0x48 0x51</code>.
 
Сообщения бинарного протокола начинаются с заголовочного символа <code>$</code> или в виде HEX: <code>0x24</code>.
 
=== GPS103 (GPS102, Coban) ===
 
Порт по умолчанию: '''5001'''
 
Поддерживаемые устройства: TK103-B, TK103-2B, TK104, TK106, GPS-103, GPS-103-A, TW-MD1101, GPS102B, GPS104, TK110
 
Сообщения этого протокола начинаются с заголовочных символов <code>##</code> или в виде HEX: <code>0x68 0x68</code>.
 
=== TK103 ===
 
Порт по умолчанию: '''5002'''
 
Поддерживаемые устройства: EC-546, TT0024, T1024, T1080, T2024, T2124, T12, T4400, T8800, T15400, TK05, TK10, TK15, TK20, TK110, T18, T18H, T16, GPS105, P168
 
Сообщения этого протокола заключены в круглые скобки <code>(...)</code> или в виде HEX: <code>0x28 ... 0x29</code>.
 
=== Teltonika ===
 
Порт по умолчанию: '''5027'''
 
Поддерживаются различные устройства, использующие кодеки: 8, 8 Extended
 
Сообщения этого протокола начинаются с HEX: <code>0x00</code>.
 
=== Navtelecom (NTCB+FLEX) ===
 
Порт по умолчанию: '''9000'''
 
Поддерживаемые устройства: все устройства компании Navtelecom
 
Сообщения этого протокола начинаются с заголовочных символов <code>@NTC</code> или в виде HEX: <code>0x40 0x4e 0x54 0x43</code>.
 
=== ТЕСТ ===
 
Порт по умолчанию: '''9999'''
 
Протокол необходим для съема сэмплов с неизвестного трекера с целью передачи их в запросе на разработку нового протокола либо для определения фактического протокола устройства, основываясь на заголовочных (и хвостовых) символах.
 
Настройте свой трекер на порт 9999 и наблюдайте за логом. В нем будут появляться строки с отметкой <code>RX-SAMPLE:</code> - это и есть те данные в hex виде, которые присылает ваш трекер. Попробуйте среди описанных выше протоколов найти подходящий по 2..3 заголовочным символам (в формате hex). Если не удалось найти, напишите нам. Возможно протокол для вашего трекера еще не реализован в Userside.


== Установка модуля ==
== Установка модуля ==


=== Загрузка ===
=== Загрузка ===
Загрузите модуль из личного кабинета со страницы загрузок: http://my.userside.eu/customer/downloads Обратите внимание, что вам нужна именно вторая версия модуля '''usm_gps_2.x.x'''.
Загрузите модуль из личного кабинета со страницы загрузок: https://my.userside.eu/soft/downloads.


Разархивируйте содержимое архива, например, в каталог <code>/var/userside/</code>. В конечном итоге в каталоге <code>/var/userside/</code> будет образован каталог <code>usm_gps_2</code>, содержащий файлы модуля. В дальнейших инструкциях будет использоваться именно каталог <code>/var/userside/usm_gps_2</code>. Если Вы расположили файлы в другом месте - учитывайте это при выполнении дальнейших инструкций.
Разархивируйте содержимое архива, например, в каталог <code>/opt/usm</code>. В конечном итоге в каталоге <code>/opt/usm</code> будет образован каталог <code>usm_gps</code>, содержащий файлы модуля. В дальнейших инструкциях будет использоваться именно каталог <code>/opt/usm/usm_gps</code>. Если Вы расположили файлы в другом месте - учитывайте это при выполнении дальнейших инструкций.


=== Остановка и удаление старой версии ===
=== Остановка и удаление старой версии ===
Удалите записи в crontab, относящиеся к старой версии модуля us_gps или usm_gps для Traccar. Остановите работу этих модулей. Убедитесь, что модули выгружены из памяти, а порт 5005, используемый старой версией модуля, не занят.
Если вы использовали до этого старую (первую) версию модуля, то остановите его и удалите все записи из crontab для запуска модуля.
 
''Файлы старой версии пока что лучше не удалять, пока не закончено тестирование новой версии модуля.''


=== Установка Python3 и зависимостей ===
=== Установка Python3 и зависимостей ===
Для работы модуля необходим Python3. Минимальная версия, с которой работает модуль, пока неизвестна. Но лучше все же использовать последнюю версию, или хотя бы версию не ниже 3.4. Дальше будут указаны инструкции на примере Debian-like дистрибутивов Linux.
Для работы модуля необходим Python3 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "[https://devguide.python.org/versions/ Status of Python versions]". Рекомендуется использовать версию с состоянием "security" или "bugfix". Версии отмеченные как "end-of-life" не поддерживаются. Отмеченные как "feature" не рекомендуется использовать. Также рекомендуется использовать пакет venv для создания виртуального окружения Python и всех зависимостей, необходимых модулю, чтобы не засорять операционную систему.


Установите python3, а также пакет python3-dev:
Если у вас по какой-то причине более старая версия, то установите последнюю версию. Также установите менеджер пакетов pip3 и пакет venv для реализации виртуального окружения:
    sudo apt install -y python3 python3-dev
sudo apt install -y python3 python3-dev python3-venv python3-pip


Установите пакетный менеджер pip3 любым из приведенных способов на выбор (какой сработает на вашем дистрибутиве):
Для контролируемой работы модуля рекомендуется использовать supervisor. Если вы его еще не установили (он необходим для USERSIDE 3.17 и новее), то установите:
    sudo python3 -m ensurepip
sudo apt install -y supervisor
    sudo apt install python3-pip


Убедитесь, что вам доступны команды <code>python3 -V</code> (отобразит версию Python) и <code>pip3 -V</code> (отобразит версию пакетного менеджера). Если при вызове этих команд возникли проблемы (команда не найдена), то необходимо создать соответствующие сомиволические ссылки для бинарных файлов, например, для python3.5 создать симлинк python3 - такое может быть в некоторых дистрибутивах или в FreeBSD.
Перейдите в каталог с модулем и создайте там виртуальное окружение:
cd /opt/usm/usm_gps
sudo python3 -m venv venv
sudo ./venv/bin/pip install --upgrade pip setuptools


Установите зависимости. Для этого необходимо перейти в каталог с файлами:
Теперь установите зависимости для модуля:
    cd /var/userside/usm_gps_2
sudo ./venv/bin/pip install --upgrade -r requirements.txt
Самый простой способ - установить зависимости глобально, как показано далее:
    pip3 install -r requirements.txt
Эта команда установит зависимости глобально в автоматическом режиме.


Вместо этого можно использовать виртуальное окружение '''virtualenv''', чтобы установить зависимости локально. Дополнительную информацию по созданию виртуального окружения смотрите в сети.
Теперь произведите настройку и первый пробный запуск модуля не в фоне. Подробней о запуске модуля ниже в разделе [[usm_gps_2#Первый запуск и отладка|Первый запуск и отладка]].


=== Настройка ===
=== Настройка ===
Если это первая установка модуля usm_gps_2, то вам необходимо скопировать файл с примером конфигурации settings.ini-example под новым именем settings.ini:
Если это первая установка модуля usm_gps_2, то вам необходимо скопировать файл с примером конфигурации .env-example под новым именем .env:
    cp settings.ini-example settings.ini
cp .env-example .env
Если же вы обновляете модуль usm_gps_2, то проверьте файл settings.ini-example на наличие новых параметров и добавьте их в свой settings.ini с нужными значениями.
Если же вы обновляете модуль usm_gps, то вам вероятно придется перенести настройки из файла settings.ini в файл .env.


==== Блок api ====
Вместо этого вы можете использовать переменные окружения, описанные в файле .env-example в самом окружении.
Данный блок содержит настройки подключения к ядру USERSIDE по средством API. Вам необходимо указать '''url''' вашего USERSIDE (без /oper/), а также '''key''', который вы указали в конфигурационном файле userside/userside3/main/config/config.php в переменной $zapikey. Если ваш USERSIDE использует https соединение с самоподписанным сертификатом, то установите опцию '''ssl_verify''' в значение '''no'''.


Опция '''trackers_auth_required''' определяет необходимость аутентификации трекеров на сервере. Если она установлена в '''yes''', то трекерам с серийными номерами (или IMEI), отсутствующими в USERSIDE, будет отказано в авторизации и данные с них не будут попадать в базу. Это рекомендуемый режим, необходимый для отсеивания трекеров, не зарегистрированных в системе. Если вам такое поведение не подходит, можете отключить аутентификацию трекеров, установив данную опцию в '''no'''.
Переменые окружения имеют префиксы (следуют между USM_GPS__ и следующими __).


Опция '''hdop_threshold''' определяет пороговое значения для значения фактора потери горизонтальной точности позиционирования (HDOP). По умолчанию предустановленное значение = 10. Все полученные от трекера навигационные данные со значением HDOP выше порогового будут отброшены и не будут передаваться в USERSIDE. Вы можете настроить это пороговое значение на свое усмотрение, либо отключить, установив его значение в 100. Следующие значения HDOP принято считать стандартными: <1 - Идеально, 1..2 - Отлично, 2..5 - Хорошо, 5..10 - Посредственно, 10..20 - Плохо, >20 - Очень плохо. Чтобы в базу данных попадали только точки с нормальной точностью, установите пороговое значение в 5. При этом следует понимать, что если координаты были определены с погрешностью, превышающей указанный фактор потери точности, то эти координаты будут отброшены (в лог-файл попадет соответствующая запись об этом). Если протоколом GPS-трекера не предусмотрено вычисление и передача значения фактора потери точности в сторону сервера, то это значение принимается за '''0'''.
==== Префикс API ====
Данный блок содержит настройки подключения к ядру USERSIDE по средством API. Вам необходимо указать '''URL''' вашего USERSIDE, а также '''KEY''', который вы указали в конфигурационном файле (см.: [[UserSide API Key]]). Если ваш USERSIDE использует https соединение с самоподписанным сертификатом, то установите опцию '''SSL_VERIFY''' в значение '''False'''.


==== Блок log ====
Опция '''TRACKERS_AUTH_REQUIRED''' определяет необходимость аутентификации трекеров на сервере. Если она установлена в '''True''', то трекерам с серийными номерами (или IMEI), отсутствующими в USERSIDE, будет отказано в авторизации и данные с них не будут попадать в базу. Это рекомендуемый режим, необходимый для отсеивания трекеров, не зарегистрированных в системе. Если вам такое поведение не подходит, можете отключить аутентификацию трекеров, установив данную опцию в '''False'''.
 
==== Префикс PROC (processing) ====
В данном блоке находятся настройки обработчика позиций. Обработчик содержит три фильтра, которые помогут исключить предположительно неверные данные. Эти фильтры должны настраиваться индивидуально. Также следует понимать, что фильтры игнорируют некоторые географические позиции на основании их анализа, что при некорректной настройке может привести к потере нормальных данных. Будьте осторожны при подборе параметров.
 
Опция '''HDOP_THRESHOLD''' определяет пороговое значения для значения фактора потери горизонтальной точности позиционирования (HDOP). По умолчанию предустановленное значение = 10. Все полученные от трекера навигационные данные со значением HDOP выше порогового будут отброшены и не будут передаваться в USERSIDE. Вы можете настроить это пороговое значение на свое усмотрение, либо отключить, установив его значение в 100. Следующие значения HDOP принято считать стандартными: <1 - Идеально, 1..2 - Отлично, 2..5 - Хорошо, 5..10 - Посредственно, 10..20 - Плохо, >20 - Очень плохо. Чтобы в базу данных попадали только точки с нормальной точностью, установите пороговое значение в 5. При этом следует понимать, что если координаты были определены с погрешностью, превышающей указанный фактор потери точности, то эти координаты будут отброшены (в лог-файл попадет соответствующая запись об этом). Если протоколом GPS-трекера не предусмотрено вычисление и передача значения фактора потери точности в сторону сервера, то это значение принимается за '''0'''.
 
===== Фильтр Парковки (дрифт GPS) =====
Данный фильтр предназначен для определения и отсеивания дрифта GPS во время парковки. Когда транспортное средство стоит на месте и при этом GPS-трекер работает и передает позицию на сервер, на карте можно увидеть следующее:
 
[[Файл:Парковка.png]]
 
GPS приемники имеют среднюю погрешность определения позиции около 6 метров. При каждой попытке GPS-приемника определить свою позицию, она будет определена с точностью около 6 метров, не зависимо от предыдущей позиции (GPS-приемники не хранят состояние). Причиной такого поведения может быть неуверенный прием сигналов со спутника, интерференция (автомобиль находится в районе плотной многоэтажной застройки), либо же частичная видимость всей доступной группировки спутников. Например, если антенна расположена внутри автомобиля, то она "видит" только часть неба. Это вполне нормальная штатная ситуация для гражданского GPS. Чтобы детектировать стоянку и отбросить такие позиции, используется фильтр парковки. Включить его можно параметром '''PARKED_FILTER_ENABLE''' установленным в '''True'''. Этот фильтр начинает работать в том случае, если предыдущая и текущая позиции имели значение скорости, не выше "близкой к нулевой" - она настраивается в параметре '''PARKED_SPEED_THRESHOLD''', а также если расстояние между предыдущей и текущей позицией не более "отклонения позиции" - оно настраивается в параметре '''PARKED_POSITION_DEVIATION''' (в среднем это 6 метров). Как только автомобиль начнет движение (переместится на расстояние, большее чем "отклонение позиции", либо же разовьет скорость, большую чем "близкую к нулевой", фильтр перестанет действовать и все позиции будут переданы на сервер. Чтобы примерно определить "отклонение позиции", просто измерьте линейкой на карте длину средней по величине полоски. Уменьшайте и увеличивайте это значение для достижения наилучшего эффекта. Помните, что слишком большие значения могут также отсеивать и нужные позиции.
 
Чтобы улучшить качество определения географических координат, используйте современные GNSS-приёмники, способные работать минимум с двумя GNSS системами одновременно (GPS, Galileo, Glonass) и внешние антенны, закрепленные таким образом, чтобы небо не перекрывалось кузовом автомобиля даже частично.
 
===== Фильтр Вылетов =====
Данный фильтр предназначен для определения и отсеивания ошибочных вылетов трека. На карте это может выглядеть вот так:
 
[[Файл:Вылет.png]]
 
Такое иногда бывает из-за некачественного приема, интерференции или просто некачественного приемника. Выглядит как точка, отстоящая от трека на таком расстоянии, куда транспортное средство не могло попасть никаким образом. Фильтр вылетов сравнивает фактическое расстояние между предыдущей точкой и текущей и определяет, могло ли это расстояние быть достигнуто при движении транспортного средства с максимальной скоростью этих двух точек. Чтобы включить фильтр вылетов, установите параметр '''RANGE_FILTER_ENABLE''' в '''True'''. Этот фильтр также имеет несколько настроек. Первая настройка '''RANGE_DELTA_TIME''' - это максимальное время в секундах между точками, для которых будет работать фильтр. Нет смысла использовать фильтр, если между точками прошло слишком много времени, так как транспортное средство между двумя точками могло двигаться быстрее, чем зафиксировано в этих точках, и действие фильтра уже может быть неточным или вообще ошибочным. Вторая настройка '''RANGE_DISTANCE_FACTOR''' - коэффициент длины предполагаемого пути, с которым сравнивается фактически пройденное расстояние. Этот коэффициент позволяет немного "удлинить" расчетное значение пути, чтобы исключить погрешность, возникающую на границах вычислений. По умолчанию используется коэффициент 1.1 и максимальное время между точками 60 секунд, однако при включении фильтра вы сами должны более корректно настроить его.
 
И помните - фильтр отсеивает географическое позиции, ничего не зная при этом о будущих позициях! Будьте аккуратны при использовании. Если у вас появились проблемы с определением координат в Userside, выполняя диагностику отключите этот фильтр в первую очередь.
 
==== Префикс LOG ====
В данном блоке находятся настройки журналирования событий.
В данном блоке находятся настройки журналирования событий.


Опция '''path''' определяет путь к каталогу, в котором будет размещаться файл журнала модуля. Опция '''level''' определяет уровень журналирования от самого детального (для отладки) '''1''' до "критического" '''5'''. Однако не рекомендуется в данном модуле использовать уровень журналирования выше '''3''' и лучше остановиться на выбранном по умолчанию уровне '''2'''.
Опция '''FILE''' определяет путь к каталогу, в котором будет размещаться файл журнала модуля. Для вывода сообщений в консоль вместо вывода в файл можно использовать значение '''STDOUT'''. Опция '''LEVEL''' определяет уровень журналирования. По умолчанию '''INFO''' (возможны '''DEBUG''', '''WARNING''', '''ERROR''', '''CRITICAL''').


Опция '''to_console''' определяет назначение вывода событий журнала. Если опция включена (установлена в '''yes'''), то все журнальные записи будут выведены в консоль. Это может быть удобно при отладке модуля, а также является стандартным поведением для работы модуля в контейнере Docker. По умолчанию используется '''no'''.
==== Префикс PROTO ====
В данном блоке префиксов перечислены номера TCP портов, на которых находятся слушатели протоколов. Вы можете переопределить номера портов на свое усмотрение, однако следует помнить, что два разных протокола не могут занимать один и тот же порт.


==== Блок port ====
Также можно закомментировать неиспользуемые порты при помощи символов # чтобы отключить работу протоколов. Например, если все ваши трекеры взаимодействуют по одному и тому же протоколу.
В данном блоке перечислены номера TCP портов, на которых находятся слушатели протоколов. Вы можете переопределить номера портов на свое усмотрение, однако следует помнить, что два разных протокола не могут занимать один и тот же порт.
 
Также можно закомментировать неиспользуемые порты при помощи символов # или ; чтобы отключить работу протоколов. Например, если все ваши трекеры взаимодействуют по одному и тому же протоколу.


=== Первый запуск и отладка ===
=== Первый запуск и отладка ===
Если вы первый раз запускаете модуль usm_gps_2, а также если возникли проблемы в работе, то выполните следующие действия.
Если вы первый раз запускаете модуль usm_gps_2, а также если возникли проблемы в работе, то выполните следующие действия.


* В файле settings.ini в блоке '''log''' установите следующие значения:
* В файле .env для переменой '''USM_GPS__LOG__FILE''' установите значение '''STDOUT''':
    [log]
<pre>
    level = 1
USM_GPS__LOG__FILE=STDOUT
    to_console = yes
</pre>
 
* А также в блоке префиксов '''USM_GPS__PROTO__''' раскомментируйте необходимый вам протокол(ы).


* Запустите модуль вручную (предварительно убедившись, что модуль не загружен, а также супервизор отключен в crontab):
* Запустите модуль вручную:
    python3 usm_gps.py
sudo venv/bin/python3 main.py


* Вы должны увидеть в консоли примерно следующее:
* Вы должны увидеть в консоли примерно следующее:
    2018-04-25 12:37:16,604 | INFO    | *** Module usm_gps version 2.0.0-alpha-3 is starting...
2018-04-25 12:37:16,604 | INFO    | *** Module usm_gps version 2.4.0 is starting...
    2018-04-25 12:37:16,801 | INFO    | GT02A protocol listener started at port 8822
2018-04-25 12:37:16,801 | INFO    | GT02A protocol listener started at port 8822
    2018-04-25 12:37:16,802 | INFO    | GT06 protocol listener started at port 8833
2018-04-25 12:37:16,802 | INFO    | GT06 protocol listener started at port 8833
    2018-04-25 12:37:16,802 | INFO    | MEILIGAO protocol listener started at port 8844
2018-04-25 12:37:16,802 | INFO    | MEILIGAO protocol listener started at port 8844
    2018-04-25 12:37:16,803 | INFO    | AUTOFON4 protocol listener started at port 8854
2018-04-25 12:37:16,803 | INFO    | AUTOFON4 protocol listener started at port 8854
    2018-04-25 12:37:16,804 | INFO    | AUTOFON5 protocol listener started at port 8855
2018-04-25 12:37:16,804 | INFO    | AUTOFON5 protocol listener started at port 8855
    2018-04-25 12:37:16,804 | INFO    | AUTOFON7 protocol listener started at port 8856
2018-04-25 12:37:16,804 | INFO    | AUTOFON7 protocol listener started at port 8856
    2018-04-25 12:37:16,805 | INFO    | WIALON protocol listener started at port 8866
2018-04-25 12:37:16,805 | INFO    | WIALON protocol listener started at port 8866
    2018-04-25 12:37:16,806 | INFO    | TELTONIKA protocol listener started at port 8877
2018-04-25 12:37:16,806 | INFO    | OSMAND (Traccar) protocol listener started at port 5055
    2018-04-25 12:37:16,806 | INFO    | OSMAND (Traccar) protocol listener started at port 5055
2018-04-25 12:37:16,807 | INFO    | *** Module usm_gps was started and ready to receive connections. PID=13878
    2018-04-25 12:37:16,807 | INFO    | *** Module usm_gps was started and ready to receive connections. PID=13878


* Подождите, пока трекеры начнут подключаться к модулю. Информацию об этом процессе вы будете наблюдать в консоли. Если подключение происходит корректно, авторизация трекеров выполняется верно, трекеры начинают присылать информацию, которая передается в USERSIDE корректно, то можно считать, что тестовый запуск прошел успешно. Если возникают какие-то проблемы на данном этапе, обратитесь пожалуйста в службу поддержки создав тикет или задайте вопрос сообществу в нашей Телеграм-группе.
* Подождите, пока трекеры начнут подключаться к модулю. Информацию об этом процессе вы будете наблюдать в консоли. Если подключение происходит корректно, авторизация трекеров выполняется верно, трекеры начинают присылать информацию, которая передается в USERSIDE корректно, то можно считать, что тестовый запуск прошел успешно. Если возникают какие-то проблемы на данном этапе, обратитесь пожалуйста в службу поддержки создав тикет или задайте вопрос сообществу в нашей Телеграм-группе.


* Остановите работу модуля клавишами ctrl+c и восстановите настройки блока '''log''' файла settings.ini:
* Остановите работу модуля клавишами ctrl+c и укажите для переменной '''USM_GPS__LOG__FILE''' имя файла лога:
    [log]
<pre>
    level = 2
USM_GPS__LOG__FILE=/var/log/userside/usm_gps/usm_gps.log
    to_console = no
</pre>


Теперь модуль готов к эксплуатации.
Теперь модуль готов к эксплуатации.


=== Эксплуатация модуля ===
=== Supervisor ===
Для запуска модуля используется супервизор - отдельный скрипт, выполняющий функцию контроля наличия модуля в памяти, а также перезапуска модуля в случае падения модуля. После того, как выполнен тестовый прямой запуск модуля, дальнейшие запуски лучше осуществлять через супервизор.
Для автоматического контроля работы модуля и его перезапуска в случае проблем, рекомендуем использовать supervisor.
Пример конфигурационного файла для supervisord поставляется вместе с модулем - это файл etc/supervisor/conf.d/usm_gps.conf-example. Находясь в каталоге с модулем, скопируйте конфиг в вашу файловую систему сохраняя путь, но с другим именем (без -example):
sudo cp etc/supervisor/conf.d/usm_gps.conf-example /etc/supervisor/conf.d/usm_gps.conf
 
По умолчанию пример содержит пути, такие же как в инструкции, но если вы использовали другой каталог для размещения модуля, то измените пути на соответствующие.
 
Перезапустите supervisor, чтобы он перечитал конфигурационные файлы:
sudo systemctl restart supervisor
 
Теперь можно посмотреть, в каком состоянии находится модуль:
sudo supervisorctl status usm_gps
 
Также следите за логами модуля и супервайзера.
 
Если понадобится остановить модуль, например, для обновления, используйте команду:
sudo supervisorctl stop usm_gps
 
Чтобы запустить модуль снова:
sudo supervisorctl start usm_gps
 
== Ротация файлов журнала ==
 
Файлы журнала, создаваемые модулем, нуждаются в ротации. Для этого следует использовать стандартные инструменты ротации логов в операционной системе.
 
Следующая настройка будет выполнять ротацию всех файлов *.log ежесуточно и хранить 7 архивных копий (за 7 дней)
 
=== Ротация в FreeBSD ===
 
В FreeBSD за ротацию отвечает демон newsyslog. Создайте файл /usr/local/etc/newsyslog.conf.d/userside, в который поместите следующую строку (не забудьте про путь, если Вы его изменили):


Модуль рассчитан на постоянное функционирование. Предполагается, что модуль постоянно находится в оперативной памяти и постоянно обслуживает соединение. Но контроль правильности этого процесса все же необходим.
/var/log/userside/*.log        644 7    *  @T00  GJC    /путь_к_модулю/usm_gps_2/usm_gps.pid


* Убедитесь, что модуль остановлен после тестового запуска и выполните запуск модуля через супервизор:
=== Ротация в Linux ===
    python3 usm_gps_supervisor.py


* Супервизор попытается определить наличие модуля в оперативной памяти, но, так как его там нет, он произведет запуск модуля, о чем сообщит в консоль сообщением вроде:
В Linux за ротацию отвечает демон logrotate. Создайте файл /etc/logrotate.d/userside, в который поместите следующий текст (не забудьте про путь, если Вы его изменили):
    Process #### not found. Restarting.


* Убедитесь, что модуль загрузился и работает:
/var/log/userside/*.log {
    ps -p `cat usm_gps.pid`
    rotate 7
    daily
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}


* Также проверьте, что файл журнала создался и в него выполнены первые записи:
== Обновление модуля ==
    tail /var/log/userside/usm_gps.log


* После этого запустите супервизор еще раз и убедитесь, что он просто завершил работу, ничего не написав в консоль:
* Скачайте архив с новой версией из личного кабинета на сервер, где работает модуль
    python3 usm_gps_supervisor.py
* Остановите работу модуля
  sudo supervisorctl stop usm_gps
* Удалите все файлы модуля, '''за исключением settings.ini'''
* Разархивируйте файлы из архива с новой версией на место старых файлов
* Обязательно установите (обновите) зависимости:
  sudo ./venv/bin/pip install --upgrade -r requirements.txt
* Запустите модуль
  sudo supervisorctl start usm_gps


Теперь можно настроить автоматический запуск супервизора.


=== Автоматический запуск супервизора ===
== Запросы на реализацию нового протокола ==
Просто добавьте в crontab запись, запускающую супервизор раз в 10 минут.
    */10 * * * *    root    python3 usm_gps_supervisor.py >> /var/log/userside/usm_gps_cron.log 2 >> /var/log/userside/usm_gps_cron_error.log


По мере работы супервизора будут созданы дополнительные файлы журналов usm_gps_cron.log и usm_gps_cron_error.log, в которые будет записываться информация о работе супервизора. По содержимому этих файлов можно будет определить факт перезагрузки модуля, что может быть вызвано падением модуля или перезагрузкой системы. Эта информация может пригодиться для диагностики проблем работы модуля.
Трекеры одной и той же модели могут иметь разные телекоммуникационные протоколы взаимодействия с сервером. Особенно это касается дешевых "китайских" трекеров вроде GT06. Оборудование трекера может изготавливать один и тот же завод, а вендор-заказчик может устанавливать в трекер собственную прошивку.


Не забудьте настроить ротацию логов для каталога <code>/var/log/userside</code>
Поэтому мы не используем понятие поддержки модели трекера, а используем понятие поддержки протокола.


== TL;DR ==
Если Вы приобрели трекер, то первым делом нужно узнать, какой протокол он поддерживает. Обычно такая информация находится в описании устройства. Если же такой информации нет, вы можете попробовать подобрать протокол по модели трекера в списке, указанном выше. Включите все имеющиеся в модуле протоколы и перезапустите его. Затем изменяйте в настройках трекера порт таким образом, чтобы использовались различные протоколы модуля. Если подходящий протокол найден — вам повезло. Используйте его. Если же нет, то вы можете воспользоваться специальным протоколом "тест" (порт по умолчанию 9999), который просто выводит в лог принятый от трекера пакет в шестнадцатиричном представлении. Далее вам нужно создать тикет через тикет-систему с темой '''usm_gps поддержка протокола...'''. В тексте тикета опишите ваш трекер и приложите строки модуля, начинающиеся с <code>RX-SAMPLE:</code>.


* Убедитесь, что версия USERSIDE не ниже 3.12.24 для модуля версий v2.0.0-alpha, v2.0.0-beta или не ниже 3.13 для модулей версий v2.0.0-RC и релиза.
Если вы располагаете информацией о протоколе, поддержку которого необходимо добавить в модуль, а также любой другой информацией (документацией или где ее получить) - обязательно прикрепляйте всю имеющуюся информацию к тикету. Это очень сильно увеличит шансы на более быструю разработку для вас.
* Скачайте модуль usm_gps_2 v2.0.0 из личного кабинета и извлеките из архива в /var/userside (или любую другу по вашему усмотрению). В итоге файлы модуля должны находиться в /var/userside/usm_gps_2. Перейдите в этот каталог.
* Установите python3, python3-dev, pip3
    sudo apt install -y python3 python3-dev python3-pip
* Важно. Проверьте доступность символической ссылки python3, выполнив:
    python3 -V
* Если символическая ссылка не доступна, создайте ее вручную (например, если у вас pyhon версии 3.5):
    ln -s /usr/bin/python3.5 /usr/bin/python3
* Скопируйте пример конфигурационного файла с именем settings.ini
    cp settings.ini-example settings.ini
* Настройте settings-ini. Укажите параметры подключения к API Userside, настройте номера портов. Порты не должны повторяться. Неиспользуемые протоколы можно закомментировать.
* Для тестового запуска настройте settings.ini таким образом, чтобы журнал выводился в консоль в полной детализации:
    [log]
    level = 1
    to_console = yes
* Запустите модуль и убедитесь, что все слушатели протоколов, необходимые вам, запустились на нужных портах. Это будет видно в журнале, который выводится в консоль:
    python3 usm_gps.py
* Убедитесь, что ваши трекеры подключаются к модулю, авторизация трекеров проходит успешно и данные с модуля попадают в USERSIDE. Если что-то работает не так, как ожидалось, обратитесь в техподдержку или к сообществу в Телеграме.
* Если все работает верно, остановите работу модуля ctrl+c и верните настройки журналирования в settings.ini:
    [log]
    level = 2
    to_console = no
* Теперь больше никогда не запускайте модуль вручную. Для этого существует супервизор. Запустите супервизор. Он отработает, запустит модуль и завершит свою работу.
    python3 usm_gps_supervisor.py
* Убедитесь, что модуль запустился, логи пишутся, трекеры соединились и начинают взаимодействовать, в Userside появилась информация:
    ps -p `cat usm_gps.pid`
    tail -f /var/log/userside/usm_gps.log
* Если все в порядке - добавляйте супервизор (не модуль) в cron раз в 10 минут. Он будет проверять наличие модуля в оперативной памяти и запускать его, если он вдруг не окажется там.
    */10 * * * *    root    python3 usm_gps_supervisor.py >> /var/log/userside/usm_gps_cron.log 2 >> /var/log/userside/usm_gps_cron_error.log
* Настройте ротацию логов

Текущая версия от 09:57, 18 октября 2024

en | ru

Данный модуль является заменой устаревшему модулю us_gps

Описание

usm_gps_2 - модуль, который может принимать информацию от GPS-трекеров и программ мониторинга с целью фиксирования позиции персонала и автотранспорта. Информация о позиции этих объектов и их маршрутах может помогать в более быстром решении аварийных ситуаций, т.к. эти объекты выводятся на карту покрытия и можно оперативно понимать какого сотрудника, что рядом находится следует отправить на решение проблем.

Вторая версия модуля отличается от первой версии своей внутренней структурой. Теперь для каждого из GPS протоколов запускается свой независимый "слушатель", а в качестве сетевого ядра используется мощный асинхронный суперсервер, способный обрабатывать сотни тысяч TCP-соединений одновременно. Это делает модуль довольно стабильным и надежным.

Соглашение

Мы не позиционируем этот модуль как систему мониторинга транспортом и потому не стоит ожидать от модуля подобный функционал. Его основная задача - отобразить текущее местонахождение сотрудника или автомобиля, а не контролировать пробег, расход топлива и т.п.

Требования

Для работы предрелизной версии (alpha, beta) необходима версия USERSIDE не ниже 3.12.24

Для работы релизной версии (RC, release) необходима версия USERSIDE не ниже 3.13 (еще в разработке)

Поддерживаемые протоколы GPS-трекеров

На данный момент поддерживаются следующие протоколы. Обратите внимание, что список поддерживаемых устройств может быть не полным, так как нам неизвестны все устройства, выпускаемые с поддержкой того или иного протокола. Также важно знать, что вовсе не обязательно модель устройства должна быть похожа на протокол, который фактически прошит в этом устройстве.

OsmAnd

Порт по умолчанию: 5055

Поддерживаемые устройства: Данный протокол используется в основном мобильными приложениями, такими как OsmAnd, GpsLogger for Android, SendLocation, Locus Pro Android, Custodium, Traccar и другими.

Так как данный протокол основан на HTTP-запросе с передачей всех данных через параметры этого запроса, то может использоваться в любых приложениях. Для передачи координат достаточно выполнить HTTP запрос: http://module.ip.address:5055/?id={id}&lat={lat}&lon={lon}&timestamp={timestamp}&hdop={hdop}&speed={speed} где вместо следующих переменных подставить нужные:

  • {id} - идентификатор устройства (IMEI, серийный номер или любой другой, позволяющий идентифицировать конкретный трекер)
  • {lat} - географическая широта в десятичном формате градусов, например, 46.488085
  • {lon} - географическая долгота в десятичном формате градусов, например, 30.741091
  • {timestamp} - целочисленная метка времени в формате UNIXTIME
  • {hdop} - коэффициент снижения точности в горизонтальной плоскости позиционирования (HDOP). Число с плавающей точкой. Параметр можно не передавать.
  • {speed} - моментальная скорость в км/ч. Число с плавающей точкой.

Например, для GpsLogger в настройке CustomURL нужно ввести следующий адрес: http://module.ip.address:5055/?id=%ser&lat=%lat&lon=%lon&timestamp=%timestamp&hdop=%hdop&speed=%spd.

GT02A

Порт по умолчанию: 5022

Поддерживаемые устройства: Данный протокол реализован в большом количестве "китайских" устройств, так что точно составить их список невозможно. Однако это один из самых распространенных протоколов, встречающихся в дешевых GPS-трекерах типа noname.

Сообщения этого протокола начинаются с заголовочных символов hh или в виде HEX: 0x68 0x68.

GT06

Порт по умолчанию: 5023

Поддерживаемые устройства: GT06, GT06N, GT09, Heacent 908, GT03A, GT03B, GS503, ET100, GT100, GT06D, GK301, JM01, JM08, GT02D, IB-GT102, CRX1, JV200, TP06A, BW08, TR06, JI09, Concox GT300, WeTrack 2

Сообщения этого протокола начинаются с заголовочных символов xx или в виде HEX: 0x78 0x78.

Meiligao

Порт по умолчанию: 5009

Поддерживаемые устройства: GT30i, GT60, VT300, VT310, VT400, GT30, GT30X, PST-AVL01, PT03, PT60, PT300X, PT30, GT-110P, GT-110K, GT-110M, GT-110ES, GT-110ZS, AVL-011, VT900, P008, GT 30, CT01, CT03, CT04, CT04-R, CT04-X, OCT600, MT01, MT02, PT01, PT03, VT1000, GSY007, T200, iStartek, VT310N

Сообщения этого протокола начинаются с заголовочных символов $$ или в виде HEX: 0x24 0x24.

Autofon v4

Порт по умолчанию: 5079

Поддерживаемые устройства: AutoFon 4.4, AutoFon 4.5

Autofon v5

Порт по умолчанию: 5077

Поддерживаемые устройства: AutoFon SE, AutoFon SE+, AutoFon D, AutoFon D-Moto, AutoFon Dialog Mayak, AutoFon S, AutoFon GL Mayak

Autofon v7

Порт по умолчанию: 5099

Поддерживаемые устройства: AutoFon Alpha, AutoFon Alpha XL, AutoFon Alpha 2XL

Autofon v9 (Микро-маяк)

Порт по умолчанию: 9109

Поддерживаемые устройства: АвтоФон Микро-Маяк, АвтоФон Микро-Маяк+

Начиная с версии модуля 2.3

Wialon

Порт по умолчанию: 5039

Поддерживаемые устройства: Wialon IPS, MasterKit, MasterKit BM8009, NeoTech TR­1000, а также по данному протоколу передает навигационную информацию сервис uonline.com.ua (если у вас есть трекеры, подключенные к этому сервису, то он может выступать в роли прокси-сервера, передавая информацию в модуль usm_gps_2).

Сообщения этого протокола начинаются с заголовочного символа # или в виде HEX: 0x23.

Важно! Мобильное приложение GpsTag от компании Gurtam (разработчика протокола Wialon) не поддерживается (разработчики Gurtam специально изменили протокол, чтобы бесплатное приложение было возможно использовать только на серверах Gurtam).

OKO-NAVI

Порт по умолчанию: 5098

Поддерживаемые устройства: Все устройства компании OKO

Сообщения этого протокола заключены в фигурные скобки {...} или в виде HEX: 0x7b ... 0x7d.

MikroTik

Порт по умолчанию: 5200

Поддерживаемые устройства: Все, оснащенные модулем GSP, например, LtAP mini Протокол основан на передаче в теле запроса HTTP-POST данных в виде JSON:

{
  "tracker_id": "12345678",
  "lat": "N 12 34' 5.678",
  "lon": "E 87 65' 4.321",
  "speed": "1.234567 km/h",
  "heading": "128.039993 deg. True",
  "hdop": 122
}

Поэтому может использоваться не только для MikroTik.

Модуль рассчитан на прием координат в формате DMS — этот режим включен в MikroTik по умолчанию. Если вы изменяли формат координат ранее, то нужно переключиться на использование именно этого формата командой:

/system gps set coordinate-format=dms

Простейший скрипт, который следует добавить в планировщик MikroTik, предварительно изменив значения первых трех переменных:

{
:local trackerID "12345678" 
:local url "http://usm_gps-url-here/" 
:local port 5200
:local lat
:local lon
:local spd
:local heading
:local hdop
/system gps monitor once do={
    :set $lat $("latitude")
    :set $lon $("longitude")
    :set $spd $("speed")
    :set $heading $("true-bearing")
    :set $hdop $("horizontal-dilution")
}

/tool fetch mode=http url=$url port=$port http-method=post http-header-field="Content-Type: application/json" \
http-data=("{\"tracker_id\": \"".$trackerID."\",\"lat\": \"".$lat."\",\"lon\": \"".$lon."\",\"speed\": \"".$spd."\",\"heading\": \"".$heading."\",\"hdop\": 
\"".$hdop."\"}")
}

Переменная trackerID содержит уникальный в пределах USERSIDE идентификатор данного Микротика. Придумайте его сами. В классических GPS-трекерах идентификатор вшит в каждый трекер и представляет собой обычно целиком или частично IMEI или серийный номер трекера. Но так как в Микротике нет никаких подобных идентификаторов, вы должны реализовать его самостоятельно. Он может быть любой символьной строкой, не обязательно состоящей из цифр.

Также Вы можете доработать этот скрипт, чтобы, например, идентификатором был МАС-адрес первого интерфейса (чтобы не вводить вручную, если так проще), а также можно доработать скрипт, чтобы он хранил предыдущее состояние в глобальных переменных и передавать на сервер информацию только в случае, если новые значения отличаются от предыдущих - это сэкономит трафик, а также избавит от "клякс" на местах стоянки, когда скорость 0 км/ч.

H02

Порт по умолчанию: 5013

Поддерживаемые устройства: H02, H-02A, H-02B, TX-2, H-06, H08, GTLT3, TK110, TK102B-MT61, NT201, NT202, S31, LK109, LK106, LK208, LK206, LK310, LK206A, LK206B, MI-G6, CC830, CCTR, CCTR-630, AT-18, GRTQ, LK210, TR-02

Поддерживается как текстовый, так и бинарный протоколы (начиная с версии модуля 2.3).

Сообщения текстового протокола начинаются с заголовочных символов *HQ или в виде HEX: 0x2A 0x48 0x51.

Сообщения бинарного протокола начинаются с заголовочного символа $ или в виде HEX: 0x24.

GPS103 (GPS102, Coban)

Порт по умолчанию: 5001

Поддерживаемые устройства: TK103-B, TK103-2B, TK104, TK106, GPS-103, GPS-103-A, TW-MD1101, GPS102B, GPS104, TK110

Сообщения этого протокола начинаются с заголовочных символов ## или в виде HEX: 0x68 0x68.

TK103

Порт по умолчанию: 5002

Поддерживаемые устройства: EC-546, TT0024, T1024, T1080, T2024, T2124, T12, T4400, T8800, T15400, TK05, TK10, TK15, TK20, TK110, T18, T18H, T16, GPS105, P168

Сообщения этого протокола заключены в круглые скобки (...) или в виде HEX: 0x28 ... 0x29.

Teltonika

Порт по умолчанию: 5027

Поддерживаются различные устройства, использующие кодеки: 8, 8 Extended

Сообщения этого протокола начинаются с HEX: 0x00.

Navtelecom (NTCB+FLEX)

Порт по умолчанию: 9000

Поддерживаемые устройства: все устройства компании Navtelecom

Сообщения этого протокола начинаются с заголовочных символов @NTC или в виде HEX: 0x40 0x4e 0x54 0x43.

ТЕСТ

Порт по умолчанию: 9999

Протокол необходим для съема сэмплов с неизвестного трекера с целью передачи их в запросе на разработку нового протокола либо для определения фактического протокола устройства, основываясь на заголовочных (и хвостовых) символах.

Настройте свой трекер на порт 9999 и наблюдайте за логом. В нем будут появляться строки с отметкой RX-SAMPLE: - это и есть те данные в hex виде, которые присылает ваш трекер. Попробуйте среди описанных выше протоколов найти подходящий по 2..3 заголовочным символам (в формате hex). Если не удалось найти, напишите нам. Возможно протокол для вашего трекера еще не реализован в Userside.

Установка модуля

Загрузка

Загрузите модуль из личного кабинета со страницы загрузок: https://my.userside.eu/soft/downloads.

Разархивируйте содержимое архива, например, в каталог /opt/usm. В конечном итоге в каталоге /opt/usm будет образован каталог usm_gps, содержащий файлы модуля. В дальнейших инструкциях будет использоваться именно каталог /opt/usm/usm_gps. Если Вы расположили файлы в другом месте - учитывайте это при выполнении дальнейших инструкций.

Остановка и удаление старой версии

Если вы использовали до этого старую (первую) версию модуля, то остановите его и удалите все записи из crontab для запуска модуля.

Установка Python3 и зависимостей

Для работы модуля необходим Python3 любой поддерживаемой на данный момент версии. Статус версий можно посмотреть здесь: "Status of Python versions". Рекомендуется использовать версию с состоянием "security" или "bugfix". Версии отмеченные как "end-of-life" не поддерживаются. Отмеченные как "feature" не рекомендуется использовать. Также рекомендуется использовать пакет venv для создания виртуального окружения Python и всех зависимостей, необходимых модулю, чтобы не засорять операционную систему.

Если у вас по какой-то причине более старая версия, то установите последнюю версию. Также установите менеджер пакетов pip3 и пакет venv для реализации виртуального окружения:

sudo apt install -y python3 python3-dev python3-venv python3-pip

Для контролируемой работы модуля рекомендуется использовать supervisor. Если вы его еще не установили (он необходим для USERSIDE 3.17 и новее), то установите:

sudo apt install -y supervisor

Перейдите в каталог с модулем и создайте там виртуальное окружение:

cd /opt/usm/usm_gps
sudo python3 -m venv venv
sudo ./venv/bin/pip install --upgrade pip setuptools

Теперь установите зависимости для модуля:

sudo ./venv/bin/pip install --upgrade -r requirements.txt

Теперь произведите настройку и первый пробный запуск модуля не в фоне. Подробней о запуске модуля ниже в разделе Первый запуск и отладка.

Настройка

Если это первая установка модуля usm_gps_2, то вам необходимо скопировать файл с примером конфигурации .env-example под новым именем .env:

cp .env-example .env

Если же вы обновляете модуль usm_gps, то вам вероятно придется перенести настройки из файла settings.ini в файл .env.

Вместо этого вы можете использовать переменные окружения, описанные в файле .env-example в самом окружении.

Переменые окружения имеют префиксы (следуют между USM_GPS__ и следующими __).

Префикс API

Данный блок содержит настройки подключения к ядру USERSIDE по средством API. Вам необходимо указать URL вашего USERSIDE, а также KEY, который вы указали в конфигурационном файле (см.: UserSide API Key). Если ваш USERSIDE использует https соединение с самоподписанным сертификатом, то установите опцию SSL_VERIFY в значение False.

Опция TRACKERS_AUTH_REQUIRED определяет необходимость аутентификации трекеров на сервере. Если она установлена в True, то трекерам с серийными номерами (или IMEI), отсутствующими в USERSIDE, будет отказано в авторизации и данные с них не будут попадать в базу. Это рекомендуемый режим, необходимый для отсеивания трекеров, не зарегистрированных в системе. Если вам такое поведение не подходит, можете отключить аутентификацию трекеров, установив данную опцию в False.

Префикс PROC (processing)

В данном блоке находятся настройки обработчика позиций. Обработчик содержит три фильтра, которые помогут исключить предположительно неверные данные. Эти фильтры должны настраиваться индивидуально. Также следует понимать, что фильтры игнорируют некоторые географические позиции на основании их анализа, что при некорректной настройке может привести к потере нормальных данных. Будьте осторожны при подборе параметров.

Опция HDOP_THRESHOLD определяет пороговое значения для значения фактора потери горизонтальной точности позиционирования (HDOP). По умолчанию предустановленное значение = 10. Все полученные от трекера навигационные данные со значением HDOP выше порогового будут отброшены и не будут передаваться в USERSIDE. Вы можете настроить это пороговое значение на свое усмотрение, либо отключить, установив его значение в 100. Следующие значения HDOP принято считать стандартными: <1 - Идеально, 1..2 - Отлично, 2..5 - Хорошо, 5..10 - Посредственно, 10..20 - Плохо, >20 - Очень плохо. Чтобы в базу данных попадали только точки с нормальной точностью, установите пороговое значение в 5. При этом следует понимать, что если координаты были определены с погрешностью, превышающей указанный фактор потери точности, то эти координаты будут отброшены (в лог-файл попадет соответствующая запись об этом). Если протоколом GPS-трекера не предусмотрено вычисление и передача значения фактора потери точности в сторону сервера, то это значение принимается за 0.

Фильтр Парковки (дрифт GPS)

Данный фильтр предназначен для определения и отсеивания дрифта GPS во время парковки. Когда транспортное средство стоит на месте и при этом GPS-трекер работает и передает позицию на сервер, на карте можно увидеть следующее:

GPS приемники имеют среднюю погрешность определения позиции около 6 метров. При каждой попытке GPS-приемника определить свою позицию, она будет определена с точностью около 6 метров, не зависимо от предыдущей позиции (GPS-приемники не хранят состояние). Причиной такого поведения может быть неуверенный прием сигналов со спутника, интерференция (автомобиль находится в районе плотной многоэтажной застройки), либо же частичная видимость всей доступной группировки спутников. Например, если антенна расположена внутри автомобиля, то она "видит" только часть неба. Это вполне нормальная штатная ситуация для гражданского GPS. Чтобы детектировать стоянку и отбросить такие позиции, используется фильтр парковки. Включить его можно параметром PARKED_FILTER_ENABLE установленным в True. Этот фильтр начинает работать в том случае, если предыдущая и текущая позиции имели значение скорости, не выше "близкой к нулевой" - она настраивается в параметре PARKED_SPEED_THRESHOLD, а также если расстояние между предыдущей и текущей позицией не более "отклонения позиции" - оно настраивается в параметре PARKED_POSITION_DEVIATION (в среднем это 6 метров). Как только автомобиль начнет движение (переместится на расстояние, большее чем "отклонение позиции", либо же разовьет скорость, большую чем "близкую к нулевой", фильтр перестанет действовать и все позиции будут переданы на сервер. Чтобы примерно определить "отклонение позиции", просто измерьте линейкой на карте длину средней по величине полоски. Уменьшайте и увеличивайте это значение для достижения наилучшего эффекта. Помните, что слишком большие значения могут также отсеивать и нужные позиции.

Чтобы улучшить качество определения географических координат, используйте современные GNSS-приёмники, способные работать минимум с двумя GNSS системами одновременно (GPS, Galileo, Glonass) и внешние антенны, закрепленные таким образом, чтобы небо не перекрывалось кузовом автомобиля даже частично.

Фильтр Вылетов

Данный фильтр предназначен для определения и отсеивания ошибочных вылетов трека. На карте это может выглядеть вот так:

Такое иногда бывает из-за некачественного приема, интерференции или просто некачественного приемника. Выглядит как точка, отстоящая от трека на таком расстоянии, куда транспортное средство не могло попасть никаким образом. Фильтр вылетов сравнивает фактическое расстояние между предыдущей точкой и текущей и определяет, могло ли это расстояние быть достигнуто при движении транспортного средства с максимальной скоростью этих двух точек. Чтобы включить фильтр вылетов, установите параметр RANGE_FILTER_ENABLE в True. Этот фильтр также имеет несколько настроек. Первая настройка RANGE_DELTA_TIME - это максимальное время в секундах между точками, для которых будет работать фильтр. Нет смысла использовать фильтр, если между точками прошло слишком много времени, так как транспортное средство между двумя точками могло двигаться быстрее, чем зафиксировано в этих точках, и действие фильтра уже может быть неточным или вообще ошибочным. Вторая настройка RANGE_DISTANCE_FACTOR - коэффициент длины предполагаемого пути, с которым сравнивается фактически пройденное расстояние. Этот коэффициент позволяет немного "удлинить" расчетное значение пути, чтобы исключить погрешность, возникающую на границах вычислений. По умолчанию используется коэффициент 1.1 и максимальное время между точками 60 секунд, однако при включении фильтра вы сами должны более корректно настроить его.

И помните - фильтр отсеивает географическое позиции, ничего не зная при этом о будущих позициях! Будьте аккуратны при использовании. Если у вас появились проблемы с определением координат в Userside, выполняя диагностику отключите этот фильтр в первую очередь.

Префикс LOG

В данном блоке находятся настройки журналирования событий.

Опция FILE определяет путь к каталогу, в котором будет размещаться файл журнала модуля. Для вывода сообщений в консоль вместо вывода в файл можно использовать значение STDOUT. Опция LEVEL определяет уровень журналирования. По умолчанию INFO (возможны DEBUG, WARNING, ERROR, CRITICAL).

Префикс PROTO

В данном блоке префиксов перечислены номера TCP портов, на которых находятся слушатели протоколов. Вы можете переопределить номера портов на свое усмотрение, однако следует помнить, что два разных протокола не могут занимать один и тот же порт.

Также можно закомментировать неиспользуемые порты при помощи символов # чтобы отключить работу протоколов. Например, если все ваши трекеры взаимодействуют по одному и тому же протоколу.

Первый запуск и отладка

Если вы первый раз запускаете модуль usm_gps_2, а также если возникли проблемы в работе, то выполните следующие действия.

  • В файле .env для переменой USM_GPS__LOG__FILE установите значение STDOUT:
USM_GPS__LOG__FILE=STDOUT
  • А также в блоке префиксов USM_GPS__PROTO__ раскомментируйте необходимый вам протокол(ы).
  • Запустите модуль вручную:
sudo venv/bin/python3 main.py
  • Вы должны увидеть в консоли примерно следующее:
2018-04-25 12:37:16,604 | INFO     | *** Module usm_gps version 2.4.0 is starting...
2018-04-25 12:37:16,801 | INFO     | GT02A protocol listener started at port 8822
2018-04-25 12:37:16,802 | INFO     | GT06 protocol listener started at port 8833
2018-04-25 12:37:16,802 | INFO     | MEILIGAO protocol listener started at port 8844
2018-04-25 12:37:16,803 | INFO     | AUTOFON4 protocol listener started at port 8854
2018-04-25 12:37:16,804 | INFO     | AUTOFON5 protocol listener started at port 8855
2018-04-25 12:37:16,804 | INFO     | AUTOFON7 protocol listener started at port 8856
2018-04-25 12:37:16,805 | INFO     | WIALON protocol listener started at port 8866
2018-04-25 12:37:16,806 | INFO     | OSMAND (Traccar) protocol listener started at port 5055
2018-04-25 12:37:16,807 | INFO     | *** Module usm_gps was started and ready to receive connections. PID=13878
  • Подождите, пока трекеры начнут подключаться к модулю. Информацию об этом процессе вы будете наблюдать в консоли. Если подключение происходит корректно, авторизация трекеров выполняется верно, трекеры начинают присылать информацию, которая передается в USERSIDE корректно, то можно считать, что тестовый запуск прошел успешно. Если возникают какие-то проблемы на данном этапе, обратитесь пожалуйста в службу поддержки создав тикет или задайте вопрос сообществу в нашей Телеграм-группе.
  • Остановите работу модуля клавишами ctrl+c и укажите для переменной USM_GPS__LOG__FILE имя файла лога:
USM_GPS__LOG__FILE=/var/log/userside/usm_gps/usm_gps.log

Теперь модуль готов к эксплуатации.

Supervisor

Для автоматического контроля работы модуля и его перезапуска в случае проблем, рекомендуем использовать supervisor. Пример конфигурационного файла для supervisord поставляется вместе с модулем - это файл etc/supervisor/conf.d/usm_gps.conf-example. Находясь в каталоге с модулем, скопируйте конфиг в вашу файловую систему сохраняя путь, но с другим именем (без -example):

sudo cp etc/supervisor/conf.d/usm_gps.conf-example /etc/supervisor/conf.d/usm_gps.conf

По умолчанию пример содержит пути, такие же как в инструкции, но если вы использовали другой каталог для размещения модуля, то измените пути на соответствующие.

Перезапустите supervisor, чтобы он перечитал конфигурационные файлы:

sudo systemctl restart supervisor

Теперь можно посмотреть, в каком состоянии находится модуль:

sudo supervisorctl status usm_gps

Также следите за логами модуля и супервайзера.

Если понадобится остановить модуль, например, для обновления, используйте команду:

sudo supervisorctl stop usm_gps

Чтобы запустить модуль снова:

sudo supervisorctl start usm_gps

Ротация файлов журнала

Файлы журнала, создаваемые модулем, нуждаются в ротации. Для этого следует использовать стандартные инструменты ротации логов в операционной системе.

Следующая настройка будет выполнять ротацию всех файлов *.log ежесуточно и хранить 7 архивных копий (за 7 дней)

Ротация в FreeBSD

В FreeBSD за ротацию отвечает демон newsyslog. Создайте файл /usr/local/etc/newsyslog.conf.d/userside, в который поместите следующую строку (не забудьте про путь, если Вы его изменили):

/var/log/userside/*.log         644 7    *  @T00  GJC    /путь_к_модулю/usm_gps_2/usm_gps.pid

Ротация в Linux

В Linux за ротацию отвечает демон logrotate. Создайте файл /etc/logrotate.d/userside, в который поместите следующий текст (не забудьте про путь, если Вы его изменили):

/var/log/userside/*.log {
    rotate 7
    daily
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}

Обновление модуля

  • Скачайте архив с новой версией из личного кабинета на сервер, где работает модуль
  • Остановите работу модуля
 sudo supervisorctl stop usm_gps
  • Удалите все файлы модуля, за исключением settings.ini
  • Разархивируйте файлы из архива с новой версией на место старых файлов
  • Обязательно установите (обновите) зависимости:
 sudo ./venv/bin/pip install --upgrade -r requirements.txt
  • Запустите модуль
 sudo supervisorctl start usm_gps


Запросы на реализацию нового протокола

Трекеры одной и той же модели могут иметь разные телекоммуникационные протоколы взаимодействия с сервером. Особенно это касается дешевых "китайских" трекеров вроде GT06. Оборудование трекера может изготавливать один и тот же завод, а вендор-заказчик может устанавливать в трекер собственную прошивку.

Поэтому мы не используем понятие поддержки модели трекера, а используем понятие поддержки протокола.

Если Вы приобрели трекер, то первым делом нужно узнать, какой протокол он поддерживает. Обычно такая информация находится в описании устройства. Если же такой информации нет, вы можете попробовать подобрать протокол по модели трекера в списке, указанном выше. Включите все имеющиеся в модуле протоколы и перезапустите его. Затем изменяйте в настройках трекера порт таким образом, чтобы использовались различные протоколы модуля. Если подходящий протокол найден — вам повезло. Используйте его. Если же нет, то вы можете воспользоваться специальным протоколом "тест" (порт по умолчанию 9999), который просто выводит в лог принятый от трекера пакет в шестнадцатиричном представлении. Далее вам нужно создать тикет через тикет-систему с темой usm_gps поддержка протокола.... В тексте тикета опишите ваш трекер и приложите строки модуля, начинающиеся с RX-SAMPLE:.

Если вы располагаете информацией о протоколе, поддержку которого необходимо добавить в модуль, а также любой другой информацией (документацией или где ее получить) - обязательно прикрепляйте всю имеющуюся информацию к тикету. Это очень сильно увеличит шансы на более быструю разработку для вас.