API модуля telecom

Последние изменения: 29.08.2019

API - методы модуля telecom

Модуль telecom выполняет функции NB-Fi телеком-cервера. Данный HTTP API-интерфейс позволяет получать, отправлять NB-Fi пакеты данных, конфигурировать режимы работы устройств, базовых станций, выполнять мониторинг работы сети и загружать лицензии на новые устройства. Данные API - методы доступны на сервере https://api.waviot.ru

Таблица 1. Сводная таблица всех API методов модуля telecom

Описание	URL	Метод
Чтение списка UL, DL, ULAPP, INFO пакетов	/telecom/api/messages	GET
Чтение списка DLAPP пакетов	/telecom/api/dl_messages	GET
Чтение статуса DLAPP пакета	/telecom/api/dl_message_status	GET
Отправка DLAPP пакета	/telecom/api/send_dl	GET
Удаление UL, DL, ULAPP, INFO пакета	/telecom/api/deletemessage	GET
Чтение параметров устройств	/telecom/api/device	GET
Конфигурирование параметров устройств	/telecom/api/device	POST
Чтение среднего уровня приема устройствомUL пакетов	/telecom/api/devsnr	GET
Чтение параметров базовых станций	/telecom/api/bs	GET
Конфигурирование параметров базовых станций	/telecom/api/bs	POST
Чтение статистики БС	/telecom/api/stinfo	GET
Чтение общей статистики Telecom-сервера	/telecom/api/stats	GET
Загрузка лицензии на устройства	/telecom/api/license	POST

Чтение списка UL, DL, ULAPP, INFO пакетов

Чтение пакетов из базы данных с возможностью фильтрации по типу пакета, номерам устройств и/или БС и времени приема(отправки) пакета.

GET запрос:

URL	Список параметров	Пример запроса
/telecom/api/messages	message_types, bs_ids, devices, timefrom, timeto, time_saved, limit	telecom/api/messages?message_types=3&devices=7769790&bs_ids=8249&timeto=1554991680&limit=400

Ответ:

BODY

[

{

"bs_id": 8249,

"comment": "",

"freq": 868812800,

"iter": 35,

"modem_id": 7769790,

"payload": "420E245CAF1E3081890002382E8389000029978489000020A8816800000713",

"phy": 26,

"rssi": -75,

"snr": 60,

"time_detected": 1554990636,

"time_saved": 1554990636,

"type": 3

{

"bs_id": 8249,

"comment": "",

"freq": 868813867,

"iter": 222,

"modem_id": 7769790,

"payload": "EF121408",

"phy": 26,

"rssi": -74,

"snr": 60,

"time_detected": 1554990251,

"time_saved": 1554990252,

"type": 3

}

]

Описание параметров запроса

Имя параметра	Тип	Описание	Значение по умолчанию
message_types	int	тип пакета(1-UL uniq, 2- UL copy, 3 – ULAPP, 10 – DL, 20 - INFO)	3
bs_ids	int	номер(а) БС	все номера
devices	int	номера(а) устройств	все номера
timefrom	int	таймстамп времени начала данных	0
timeto	int	таймстамп времени окончания данных	текущее время
time_saved	int	0 – выборка по времени приема пакета 1 – выборка по времени сохранения пакета в БД	0
limit	int	ограничение количества пакетов	100

Чтение списка DLAPP пакетов

Чтение DLAPP пакетов из базы данных с возможностью фильтрации по статусу доставки пакета, номерам устройств и/или БС и времени изменения статуса пакета.

GET запрос:

URL	Список параметров	Пример запроса
/telecom/api/dl_messages	statuses, bs_ids, devices, timefrom, timeto, limit	telecom/api/dl_messages?statuses=4&devices=7769790&bs_ids=8249&timeto=1554991680&limit=400

Ответ:

BODY

[

{

"bs_id": 8249,

"modem_id": 7769790,

"noise": -114,

"payload": "EF121408",

"phy": 3,

"posted_time": 1554990250,

"snr": 50,

"status": 4,

"tag_id": "drvElectro5_15939795"

{

"bs_id": 8249,

"modem_id": 7769790,

"noise": -115,

"payload": "EF0A",

"phy": 3,

"posted_time": 1554718939,

"snr": 51,

"status": 4,

"tag_id": "drvElectro5_15579330"

}

]

Описание параметров запроса

Имя параметра	Тип	Описание	Значение по умолчанию
statuses	int	тип пакета(1-queued, 2- in process, 4 – delivered, 5 – lost)	1,2,4,5
bs_ids	int	номер(а) БС	все номера
devices	int	номера(а) устройств	все номера
timefrom	int	таймстамп времени начала данных	0
timeto	int	таймстамп времени окончания данных	текущее время
limit	int	ограничение количества пакетов	100

Отправка DLAPP-пакета

GET запрос:

URL	Список параметров	Пример запроса
/telecom/api/send_dl	modem_id, payload, tag_id	telecom/api/send_dl?modem_id=7607371&payload=deadbeaf

Ответ:

BODY

    "tag_id": "342519d9-9738-42f0-bd3d-1caddd15d3ca"

Описание параметров запроса

Имя параметра	Тип	Описание	Значение по умолчанию
modem_id	int	номер устройства, на которое необходимо отправить DLAPP-пакет	обязательный параметр
payload	hex string	отправляемые данные в формате HEX	обязательный параметр
tag_id	string	тэг DLAPP-пакета	параметр может отсутствовать, в этом случае тэг будет сформирован автоматически

Чтение статуса DLAPP-пакета

GET запрос:

URL	Список параметров	Пример запроса
/telecom/api/dl_message_status	tag_id	telecom/api/dl_message_status?tag_id=342519d9-9738-42f0-bd3d-1caddd15d3ca

Ответ:

BODY

    "ACK": 1,

    "bs_id": 0,

    "modem_id": 7607371,

    "payload": "DEADBEAF",

    "phy": 0,

    "posted_time": 1555329074,

    "status": 5,

    "tag_id": "342519d9-9738-42f0-bd3d-1caddd15d3ca"

Описание параметров запроса

Имя параметра	Тип	Описание	Значение по умолчанию
tag_id	int	тэг DLAPP-пакета	обязательный параметр

Удаление UL, DL, ULAPP пакета.

GET запрос:

URL	Список параметров	Пример запроса
/telecom/api/deletemessage	modem_id, type, station_id, iter, time_detected	telecom/api/deletemessage?modem_id=7769790&type=3&station_id=8249&iter=35&time_detected=1554990636

Ответ:

BODY

    "result": true

Описание параметров запроса

Имя параметра	Тип	Описание	Значение по умолчанию
modem_id	int	номер устройства	обязательный параметр
type	int	тип пакета(1-UL uniq, 2- UL copy, 3 – ULAPP, 10 – DL, 20 - INFO)	обязательный параметр
station_id	int	номер БС	обязательный параметр
iter	int	поле iter пакета	обязательный параметр
time_detected	int	поле time_detected пакета	обязательный параметр

Чтение параметров устройств

GET запрос:

URL

Список параметров

Пример запроса

/telecom/api/device

dev_ids

telecom/api/device?dev_ids=7769790,7769791

telecom/api/device?list=1

Ответ на запрос без ключа list=1:

BODY

        "bs_data": [

                "aver_snr": 76,

                "bs_id": 8249,

                "f_offset": -16,

                "last_hb_ts": 1555334055,

                "last_success_dl_ts": 1555312010,

                "last_unsuccess_dl_ts": 1554193669,

                "rating": 600

},

                "aver_snr": 9,

                "bs_id": 8252,

                "f_offset": 60,

                "last_hb_ts": 1554193569,

                "last_success_dl_ts": -1,

                "last_unsuccess_dl_ts": 1554171576,

                "rating": 100

],

        "dl_base_freq": 446000000,

        "dl_bitrates": [

0,

1,

2,

],

        "dl_messages_per_ack": 1,

        "dl_mode": "CRX",

        "dl_num_of_retries": 3,

        "dl_phy": "DL_PSK_FASTDL",

        "dl_strength": 0,

        "hw_type": "phobos3split_stm",

        "key": "B5D7E56067E5A0E1C2224896A79136284A4CB6194C4013B483BB2A284C9797B0",

        "last_success_dl_ts": 1555312010,

        "last_unsuccess_dl_ts": 1554193669,

        "modem_id": 7769790,

        "nbfi_ver": 4,

        "protocol": "electro5",

        "ul_base_freq": 868775000,

        "ul_bitrates": [

21,

24,

],

        "ul_messages_per_ack": 1,

        "work_bs": 8249

},

        "bs_data": [

                "aver_snr": 72,

                "bs_id": 8249,

                "f_offset": 0,

                "last_hb_ts": 1555334484,

                "last_success_dl_ts": 1555315229,

                "last_unsuccess_dl_ts": 1554990248,

                "rating": 600

],

        "dl_base_freq": 446000000,

        "dl_bitrates": [

0,

1,

2,

],

        "dl_messages_per_ack": 1,

        "dl_mode": "CRX",

        "dl_num_of_retries": 3,

        "dl_phy": "DL_PSK_FASTDL",

        "dl_strength": 0,

        "hw_type": "phobos3split_stm",

        "key": "3A20FC678C920613F5130E33D461F4B43BFFD454D833729A2452B5149EA70EFF",

        "last_success_dl_ts": 1555315229,

        "last_unsuccess_dl_ts": 1554990248,

        "modem_id": 7769791,

        "nbfi_ver": 4,

        "protocol": "electro5",

        "ul_base_freq": 868775000,

        "ul_bitrates": [

21,

24,

],

        "ul_messages_per_ack": 1,

        "work_bs": 8249

Ответ на запрос c ключом list=1:

BODY

{

"modems": 14,

"x_ids": [

7437096,

7437100,

7437105,

7437118,

7437145,

7437184,

7437192,

7437255,

7437262,

7437266,

7437271,

7437274,

7437275,

7437279]

}

Описание параметров запроса

Имя параметра	Тип	Описание	Значение по умолчанию
dev_ids	int	номер(а) устройств(а)	все номера
list	int	1 - вернуть результат в виде списка номеров	0

Конфигурирование параметров устройств

POST запрос:

URL	Список параметров	Пример запроса
/telecom/api/device		telecom/api/device

BODY

        "modem_id": 7769790,

        "dl_base_freq": 446000000,

        "dl_bitrates": [

0,

1,

2,

],

        "dl_messages_per_ack": 1,

        "dl_mode": "CRX",

        "dl_num_of_retries": 3,

        "dl_strength": 0,

        "hw_type": "phobos3split_stm",

        "key": "B5D7E56067E5A0E1C2224896A79136284A4CB6194C4013B483BB2A284C9797B0",

        "nbfi_ver": 4,

        "protocol": "electro5",

        "ul_base_freq": 868775000,

        "ul_bitrates": [

21,

24,

],

        "ul_messages_per_ack": 1,

},

        "modem_id": 7769791,

        "dl_base_freq": 446000000,

        "dl_bitrates": [

0,

1,

2,

],

        "dl_messages_per_ack": 1,

        "dl_mode": "CRX",

        "dl_num_of_retries": 3,

        "dl_strength": 0,

        "hw_type": "phobos3split_stm",

        "key": "3A20FC678C920613F5130E33D461F4B43BFFD454D833729A2452B5149EA70EFF",

        "nbfi_ver": 4,

        "protocol": "electro5",

        "ul_base_freq": 868775000,

        "ul_bitrates": [

21,

24,

],

        "ul_messages_per_ack": 1,

Чтение среднего уровня приема устройством UL пакетов

GET запрос:

URL	Список параметров	Пример запроса
/telecom/api/devsnr	dev_id	telecom/api/devsnr?dev_id=7769790

Ответ:

BODY

    "aver_nsnr": 77.05461120605469,

    "aver_rssi": -75.64028930664062,

    "total": 139

Описание параметров запроса

Имя параметра	Тип	Описание	Значение по умолчанию
dev_id	int	номер(а) устройств(а)	обязательный параметр

Чтение параметров базовых станций.

GET запрос:

URL	Список параметров	Пример запроса
/telecom/api/bs	bs_ids, online_status	telecom/api/bs?bs_ids=9500

Ответ:

BODY

        "address": "г. Москва,  Лесная 3",

        "bs_id": 9500,

        "bs_state": 15,

        "bs_type": "BS3",

        "comment": "BS3 v3.4",

        "dl_aver_busyness": 5,

        "dl_base_freqs": [

            "446000000",

            "864000000"

],

        "dl_bitrates": [

            "DL_DBPSK_50_PROT_D",

            "DL_DBPSK_400_PROT_D",

            "DL_DBPSK_3200_PROT_D",

            "DL_DBPSK_25600_PROT_D",

            "DL_PSK_200",

            "DL_PSK_500",

            "DL_PSK_5000",

            "DL_PSK_FASTDL"

],

        "dl_status": 1,

        "gps_lasttime": 0,

        "last_hb_time": 1555337330,

        "latitude": 0,

        "longitude": 0,

        "noise": -153,

        "online_status": 1,

        "rev_list": [

            "274",

            "2.8.4",

            "ax.20"

],

        "status_duration": 38549,

        "temperature": 74,

        "timezone": "Europe/Moscow",

        "timezone_offset": 10800,

        "ul_base_freqs": [

],

        "ul_bitrates": [

            "UL_DBPSK_50_PROT_C",

            "UL_DBPSK_50_PROT_D",

            "UL_DBPSK_400_PROT_C",

            "UL_DBPSK_400_PROT_D",

            "UL_DBPSK_3200_PROT_D",

            "UL_PSK_FASTDL"

Описание параметров запроса

Имя параметра	Тип	Описание	Значение по умолчанию
bs_ids	int	номер(а) БС	все номера
online_status	int	статус БС(0 – все, 1 – онлайн, 2 - оффлайн)	0

Конфигурирование параметров базовых станций

POST запрос:

URL	Список параметров	Пример запроса
/telecom/api/bs		telecom/api/bs

BODY

        "bs_id": 9500,

        "address": "г. Москва,  Лесная 3",

        "comment": "BS3 v3.4",

        "latitude": 0,

        "longitude": 0,

        "timezone": "Europe/Moscow",

        "timezone_offset": 10800

Чтение статистики базовой станции

GET запрос:

URL	Список параметров	Пример запроса
/telecom/api/stinfo	bs_ids, hours, dev_ids, snr, max_uls, type, protocol	telecom/api/stinfo?bs_ids=9500&protocol=water5

Ответ:

BODY

    "BS_Total": {

        "attached": {

            "AQUA2": 3,

            "DL_PSK_200": {

                "aver_nsnr": 53.54999923706055,

                "modems": 8

},

            "KARAT": 3,

            "Neptun": 1,

            "NeroWaterMeter": 1,

            "UL_DBPSK_50_PROT_D": {

                "aver_nsnr": 53.54999923706055,

                "modems": 8,

                "uniq_uplinks": 19

},

            "aver_message_rate": 2.375,

            "aver_nsnr": 53.54999923706055,

            "aver_snr": 53.54999923706055,

            "modems": 8,

            "stations": {

                "9500": 15,

                "stations": [

},

            "total_uplinks": 115133,

            "uniq_uplinks": 19,

            "x_ids": [

                7395129,

                7433238,

                7454102,

                7504761,

                7565846,

                7571070,

                7697503,

},

        "filtered": {

            "aver_nsnr": 41.86799621582031,

            "friend_stations": {

                "8228": 16,

                "9322": 7,

                "stations": [

                    8228,

},

            "modems": 23,

            "x_ids": [

                7414784,

                7421518,

                7421519,

                7421520,

                7435071,

                7437328,

                7520047,

                7520059,

                7520379,

                7558494,

                7560440,

                7561564,

                7581110,

                7581646,

                7584095,

                7585312,

                7697504,

                7722279,

                7780076,

                7851224,

                7851945,

                7851949,

Описание параметров запроса

Имя параметра	Тип	Описание	Значение по умолчанию
bs_ids	int	номер(а) БС	все номера
hours	int	период выгрузки статистики(кол-во последних часов)	24
dev_ids	int	фильтрация по номерам устройств	все номера
snr	int	порог уровня SNR(устройства с уровнем ниже данного порога попадают в список “low_snr_list”)	6
max_uls	int	порог кол-ва UL пакетов (устройства с кол-вом пакетов больше данного порога попадают в список “high_message_rate_list”)	∞
type	string	фильрация по типу(type) устройства	все типы
protocol	string	фильрация по протоколу(protocol) устройства	все протоколы

Чтение общей статистики telecom-сервера

GET запрос:

URL	Список параметров	Пример запроса
/telecom/api/stats		telecom/api/stats

Ответ:

BODY

    "TelecomVersion": "2.2.14",

    "bsOnline": 432,

    "dlAppMessLast24Hour": 219394,

    "dlAppMessLastHour": 11241,

    "dlMessLast24Hour": 3021925,

    "dlMessLastHour": 149975,

    "dlMessPerSec": 31.783333333333335,

    "modemsLast24Hour": 148590,

    "modemsLastHour": 71411,

    "runnedTime": "days: 3 hours: 4 minutes: 36 sconds: 30",

    "successRateOfDlAppDelivery": 68.3569107055664,

    "successRateOfDlAppDelivery_daily": 65.7647933959961,

    "ulAppMessLast24Hour": 2195185,

    "ulAppMessLastHour": 89194,

    "ulAppMessPerSec": 13.75,

    "ulMessLast24Hour": 23134335,

    "ulMessLastHour": 853664,

    "ulMessPerSec": 148.31666666666666

Загрузка лицензии на устройства

POST запрос:

URL	Список параметров	Пример запроса
/telecom/api/license		telecom/api/license

BODY

<em><your license file>
</em>

Ответ:

BODY

{
  "result": true
}

Помогла ли вам статья?