База знаний Waviot

API модуля telecom

ID статьи: 53
Последнее обновление: 26 May, 2020

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

Чтение дополнительной статистики БС

/telecom/api/ststats

GET

Чтение истории БС

/telecom/api/sthistory

GET

Типы пакетов:
UL uniq - uplink пакет транспортного уровня протокола, имеющий длину всегда 8 байт.
UL copy - копия этого пакета, принятая другой базовой станцией(первый который пришел на сервер, это UL uniq, последующие  - UL copy)
У пакетов UL uniq и UL copy частота приема, SNR и RSSI соответствуют действительности.
ULAPP - это uplink пакет уровня приложения, который может иметь длину от 1 до 240 байт и может формироваться из одного либо нескольких пакетов UL uniq. У пакетов  ULAPP номер БС, частота приема SNR и RSSI определяются для  самой мощной копии UL пакета среди принятых разными БС. Так как ULAPP пакет формируется, непосредственно сразу после прихода не сервер первой копии UL пакета, то информация о самой мощной копии, имеется только по предыдущему UL пакету. По этой причине, данные в ULAPP пакетах различаются от данных в UL пакетах, из которых они сформированы.
DL - downlink пакет транспортного уровня, имеющий длину всегда 8 байт.
INFO - уведомления, сформированные сервером, не являющиеся передаваемыми пакетами.
Для получение UL uniq, UL copy, ULAPP, DL и INFO пакетов из базы данных, используется метод /telecom/api/messages 
DLAPP - это downlink пакет уровня приложения.
Для получение DLAPP пакетов из базы данных, используется метод /telecom/api/dl_messages

Чтение списка 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,
            3
        ],
        "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,
            26
        ],
        "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,
            3
        ],
        "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,
            26
        ],
        "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,
            3
        ],
        "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,
            26
        ],
        "ul_messages_per_ack": 1,
    },
    {
        "modem_id": 7769791,
        "dl_base_freq": 446000000,
        "dl_bitrates": [
            0,
            1,
            2,
            3
        ],
        "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,
            26
        ],
        "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": [
                    9500
                ]
            },
            "total_uplinks": 115133,
            "uniq_uplinks": 19,
            "x_ids": [
                7395129,
                7433238,
                7454102,
                7504761,
                7565846,
                7571070,
                7697503,
                7850754
            ]
        },
        "filtered": {
            "aver_nsnr": 41.86799621582031,
            "friend_stations": {
                "8228": 16,
                "9322": 7,
                "stations": [
                    8228,
                    9322
                ]
            },
            "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,
                7851950
            ]
        }
    }
}

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

Имя параметра

Тип

Описание

Значение по умолчанию

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

<your license file>

Ответ:

BODY

{
  "result": true
}

Чтение дополнительной статистики БС.

GET запрос:

URL

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

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

/telecom/api/ststats

bs_ids,  timefrom, timeto,  period, limit

telecom/api/ststats?bs_ids=8800&timeto=1585318469&period=60&imit=2

Ответ:

BODY

[
    {
        "aver_noise": -140,
        "bs_id": 8800,
        "dl_aver_power": 23,
        "dl_modems_total": 2,
        "dl_total": 3,
        "period": 60,
        "ts": 1585318469,
        "ts_ms": 1585318469,
        "ul_aver_rssi": -98,
        "ul_modems_total": 3,
        "ul_total": 4
    },
    {
        "aver_noise": -141,
        "bs_id": 8800,
        "dl_aver_power": 0,
        "dl_modems_total": 0,
        "dl_total": 0,
        "period": 60,
        "ts": 1585558051,
        "ts_ms": 1585558051,
        "ul_aver_rssi": -128,
        "ul_modems_total": 3,
        "ul_total": 3
    }
]

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

Имя параметра

Тип

Описание

Значение по умолчанию

bs_ids

int

номер(а) БС

все номера

timefrom

int

таймстамп времени начала данных

0

timeto

int

таймстамп времени окончания данных

текущее время

limit

int

ограничение количества пакетов

100

period

int

Период статистики. Возможные значения: минутная (period=60), часовая (3600), суточная (86400).

0

Чтение истории БС.

GET запрос:

URL

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

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

/telecom/api/sthistory

bs_ids,  timefrom, timeto,  limit

telecom/api/sthistory?bs_ids=9881,8980,9748&timefrom=1585560789&timeto=1585560827&limit=3

Ответ:

BODY

[
    {
        "bs_id": 8980,
        "bs_state": 15,
        "dl_aver_busyness": 15,
        "dl_busyness": 16,
        "dl_status": 2,
        "fpga_temperature": 0,
        "gps_lasttime": 1585560,
        "gps_lasttime_mc": 1585560.954,
        "last_hb_time": 1585560790,
        "last_hb_time_ms": 1585560790,
        "latitude": 56.123119,
        "lbt": 0,
        "longitude": 40.103175,
        "max_duty_cycle": 0,
        "max_power": 0,
        "noise": -153,
        "temperature": 62
    },
    {
        "bs_id": 9748,
        "bs_state": 15,
        "dl_aver_busyness": 6,
        "dl_busyness": 0,
        "dl_status": 1,
        "fpga_temperature": 0,
        "last_hb_time": 1585560819,
        "last_hb_time_ms": 1585560819,
        "lbt": 0,
        "max_duty_cycle": 0,
        "max_power": 0,
        "noise": -150,
        "temperature": 58
    },
    {
        "bs_id": 9881,
        "bs_state": 15,
        "dl_aver_busyness": 2,
        "dl_busyness": 0,
        "dl_status": 1,
        "fpga_temperature": 0,
        "gps_lasttime": 1585560,
        "gps_lasttime_mc": 1585560.954,
        "last_hb_time": 1585560790,
        "last_hb_time_ms": 1585560790,
        "latitude": 55.722699,
        "lbt": 0,
        "longitude": 37.645947,
        "max_duty_cycle": 0,
        "max_power": 0,
        "noise": -142,
        "temperature": 45
    }
]

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

Имя параметра

Тип

Описание

Значение по умолчанию

bs_ids

int

номер(а) БС

все номера

timefrom

int

таймстамп времени начала данных

0

timeto

int

таймстамп времени окончания данных

текущее время

limit

int

ограничение количества пакетов

100

Эта статья была:   Полезна | Не полезна
Сообщить об ошибке
ID статьи: 53
Последнее обновление: 26 May, 2020
Ревизия: 17
Просмотры: 343
Комментарии: 0