NB-Fi server API
NB-Fi server API allows to get and send NB-Fi messages, configure the NB-Fi devices and base stations, monitor the NB-Fi network parameters and handle with NB-Fi licenses.
###
List of NB-Fi server API methods
| Description | URL | HTTP method |
|---|---|---|
| Get the list of UL, DL, ULAPP and INFO packets | /telecom/api/messages | GET |
| Get the list of DLAPP packets | /telecom/api/dl_messages | GET |
| Send the DLAPP packet | /telecom/api/send_dl | GET |
| Get the DLAPP packet status | /telecom/api/dl_message_status | GET |
| Delete UL, DL, ULAPP or INFO packet | /telecom/api/deletemessage | GET |
| Get devices parameters | /telecom/api/device | GET |
| Get average NB-Fi network quality indicators for recieved NB-Fi UPLINK packets | /telecom/api/devsnr | GET |
| Get base stations parameters | /telecom/api/bs | GET |
| Configure the base station parameters | /telecom/api/bs | POST |
| Get base stations statistics | /telecom/api/stinfo | GET |
| Get the NB-Fi server statistics | /telecom/api/stats | GET |
| Upload NB-Fi licences to the NB-Fi server | /telecom/api/license | POST |
| Get detailed statistics from base stations | /telecom/api/ststats | GET |
| Get history of base stations statistics data | /telecom/api/sthistory | GET |
UL uniq – NB-Fi Transport-layer UPLINK packet, with length of user data (Data field) of 8 bytes.
UL copy – copy of UL uniq packet, received by other NB-Fi base stations. The first packet came to the NB-Fi server is a UL uniq packet, the next are UL copy packets.
ULAPP – NB-Fi Transport-layer GROUP UPLINK packet (Application-layer data), with length of user data from 1 to 240 bytes. ULAPP packet is combined from one or several UL uniq packets.
The NB-Fi base station ID, SNR and RSSI parameters for the ULAPP packet are defined based on better parameters among all received UL packets. Therefore, these parameters for ULAPP packet may differ from the parameters of UL packets, which it consists of.
DL – NB-Fi Transport-layer DOWNLINK packet, with length of user data (Data field) of 8 bytes.
INFO – notification messages, generated by NB-Fi server. INFO packets are not the transmitted packets.
Use /telecom/api/messages method to get UL uniq, UL copy, ULAPP, DL and INFO packets.
DLAPP – NB-Fi Transport-layer GROUP DOWNLINK packet (Application-layer data), with length of user data from 1 to 240 bytes.
Use /telecom/api/dl_messages method to get DLAPP packets.
XX
Get the list of UL, DL, ULAPP and INFO packets
| /telecom/api/messages | GET method | ||
| Query Parameter | Type | Description | Default value |
| message_types | int |
Type of packet (1 - UL uniq, 2 - UL copy, 3 – ULAPP, 10 – DL, 20 - INFO) |
3 |
| bs_ids | int |
IDs of NB-Fi base stations | All IDs |
| devices | int |
IDs of NB-Fi devices | All IDs |
| timefrom | int |
Timestamp of From date | 0 |
| timeto | int |
Timestamp of To date | Current time |
| time_saved | int |
0 – Query by date of packet receiving, 1 – Query by date of packet saving at the NB-Fi server |
0 |
| limit | int |
Limit for the number of returned results | 100 |
| Example: | telecom/api/messages?message_types=3&devices=7769790&bs_ids=8249&timeto=1554991680&limit=40 | ||
XX
Get the list of DLAPP packets
| /telecom/api/dl_messages | GET method | ||
| Query Parameter | Type | Description | Default value |
| statuses | int |
Status of packet (1 - Queued, 2 - In progress, 4 – Delivered, 5 – Lost) |
1,2,4,5 |
| bs_ids | int |
IDs of NB-Fi base stations | All IDs |
| devices | int |
IDs of NB-Fi devices | All IDs |
| timefrom | int |
Timestamp of From date | 0 |
| timeto | int |
Timestamp of To date | Current time |
| limit | int |
Limit for the number of returned results | 100 |
| Example: | telecom/api/dl_messages?statuses=4&devices=7769790&bs_ids=8249&timeto=1554991680&limit=400 | ||
XX
Send the DLAPP packet
| /telecom/api/send_dl | GET method | ||
| Query Parameter | Type | Description | Default value |
| modem_id | int |
ID of the NB-Fi device to which the DLAPP packet should be sent | Mandatory parameter |
| payload | hex |
Data to be sent in Hex form | Mandatory parameter |
| tag_id | string |
Tag of the DLAPP packet | Parameter could be either set explicitly or absent. In case parameter is absent, the automatically generated Tag of the of the DLAPP packet will be returned. |
| Example: | telecom/api/send_dl?modem_id=7607371&payload=abcdef | ||
XX
Get the DLAPP packet status
| /telecom/api/dl_message_status | GET method | ||
| Query Parameter | Type | Description | Default value |
| tag_id | int |
Tag of the DLAPP packet | Mandatory parameter |
| Example: | telecom/api/dl_message_status?tag_id=342519d9-9738-42f0-bd3d-1caddd15d3ca | ||
XX
Delete UL, DL, ULAPP or INFO packet
| /telecom/api/deletemessage | GET method | ||
| Query Parameter | Type | Description | Default value |
| modem_id | int |
ID of the NB-Fi device which packet should be deleted | Mandatory parameter |
| type | int |
Type of packet (1 - UL uniq, 2 - UL copy, 3 – ULAPP, 10 – DL) | Mandatory parameter |
| station_id | int |
ID of NB-Fi base station | Mandatory parameter |
| iter | int |
The Iter field of the packet | Mandatory parameter |
| time_detected | int |
The time_detected value of the packet | Mandatory parameter |
| Example: | telecom/api/deletemessage?modem_id=7769790&type=3&station_id=8249&iter=35&time_detected=1554990636 | ||
XX
Get devices parameters
| /telecom/api/device | GET method | ||
| Query Parameter | Type | Description | Default value |
| dev_ids | int |
ID(s) of NB-Fi device(s) | All IDs |
| total | bool |
true for returning the total number of devices | false |
| list | bool |
true for returning the list of IDs | false |
| type | string |
hw_type ID filter | All hw_type values |
| protocol | string |
MDM protocol filter | All protocol values |
| dl_mode | string |
dl_mode filter (NRX, DRX, CRX, OFF) | All dl_mode values |
| ul_phy | string |
ul_phy filter (e.g. UL_DBPSK_3200_PROT_E) | All ul_phy values |
| dl_phy | string |
dl_phy filter (e.g. DL_DBPSK_3200_PROT_D) | All dl_phy values |
| ul_lasttime_from | int |
Last recieved time of UL packet (UTC timestamp from) |
0 |
| ul_lasttime_to | int |
Last recieved time of UL packet (UTC timestamp to) |
Current time |
| geolocation | bool |
Calculate the devices distance rating based on data from NB-Fi base stations | false |
| limit | int |
Limit for the number of returned results (must be a multiple of 32) |
320*N (N is from 1 to 32 based on NB-Fi server configuration) |
| offset | int |
Offset for the list of returned results (must be a multiple of 32) |
0 |
| Example: | telecom/api/device?dev_ids=8148928,8290056&geolocation=true telecom/api/device?list=true&type=aqua2_stm&limit=32 telecom/api/device?total=true&dl_mode=DRX |
||
XX
Get average NB-Fi network quality indicators for recieved NB-Fi UPLINK packets
| /telecom/api/devsnr | GET method | ||
| Query Parameter | Type | Description | Default value |
| dev_id | int |
ID of the NB-Fi device | Mandatory parameter |
| Example: | telecom/api/devsnr?dev_id=7769790 | ||
XX
Get base stations parameters
| /telecom/api/bs | GET method | ||
| Query Parameter | Type | Description | Default value |
| bs_ids | int |
ID(s) of NB-Fi base station(s) | Mandatory parameter |
| online_status | int |
Status of NB-Fi base station (0 - All, 1 - Online, 2 - Offline) | 0 |
| total | bool |
true for returning the total number of devices | false |
| list | bool |
true for returning the list of IDs | false |
| limit | int |
Limit for the number of returned results | 1000 |
| offset | int |
Offset for the list of returned results | 0 |
| Example: | telecom/api/bs?bs_ids=10325 telecom/api/bs?online_status=1&total=true telecom/api/bs?online_status=2&list=true&limit=10&offset=20 |
||
XX
Configure the base station parameters
| /telecom/api/bs | POST method | ||
| Query Parameter | Type | Description | Default value |
| bs_id | int |
ID of NB-Fi base station | Mandatory parameter |
| address | string |
Address of the NB-Fi base station | Optional user parameter |
| comment | string |
Comment | Optional user parameter |
| latitude | int |
Latitude of the NB-Fi base station's coordinates | Optional user parameter |
| longitude | int |
longitude of the NB-Fi base station's coordinates | Optional user parameter |
| timezone | string |
Name of the timezone for the NB-Fi base station (e.g. "Europe/Paris") | Optional user parameter |
| timezone_offset | int |
Timezone offset (seconds ahead to GMT time, e.g. 3600) | Optional user parameter |
XX
Get base stations statistics
| /telecom/api/stinfo | GET method | ||
| Query Parameter | Type | Description | Default value |
| bs_ids | int |
ID(s) of NB-Fi base station(s) | Mandatory parameter |
| hours | int |
Period for statistics, number of last hours | 24 |
| dev_ids | int |
ID(s) of NB-Fi device(s) | All IDs |
| snr | int |
Mimimum SNR for NB-Fi device(s) | 6 |
| max_uls | int |
Maximum number of UL packets sent by NB-Fi device(s) | ∞ |
| type | string |
Hardware type hw_type ID filter | All hw_type values |
| protocol | string |
MDM protocol filter | All protocol values |
| Example: | telecom/api/stinfo?bs_ids=9500&protocol=water7 | ||
XX
Get the NB-Fi server statistics
| /telecom/api/stats | GET method | ||
| Query Parameter | Type | Description | Default value |
| - | - | - | - |
| Example: | telecom/api/stats | ||
XX
Upload NB-Fi licences to the NB-Fi server
| /telecom/api/license | POST method | ||
| Body | Answer | ||
| <your license file> | {
"result": true
}
|
||
| Example: | /telecom/api/license | ||
XX
Get detailed statistics from base stations
| /telecom/api/ststats | GET method | ||
| Query Parameter | Type | Description | Default value |
| bs_ids | int |
IDs of NB-Fi base stations | All IDs |
| timefrom | int |
Timestamp of From date | 0 |
| timeto | int |
Timestamp of To date | Current time |
| limit | int |
Limit for the number of returned results | 100 |
| period | int |
Data aggregation period, sec (possible values: 60, 3600 or 86400) | Mandatory parameter |
| Example: | telecom/api/ststats?bs_ids=8800&timeto=1585318469&period=60&limit=2 | ||
XX
Get history of base stations statistics data
| /telecom/api/sthistory | GET method | ||
| Query Parameter | Type | Description | Default value |
| bs_ids | int |
IDs of NB-Fi base stations | All IDs |
| timefrom | int |
Timestamp of From date | 0 |
| timeto | int |
Timestamp of To date | Current time |
| limit | int |
Limit for the number of returned results | 100 |
| Example: | telecom/api/sthistory?bs_ids=9881,8980,9748&timefrom=1585560789&timeto=1585560827&limit=3 | ||