AMQP API

NB-Fi server supports sending and receiving of NB-Fi messages via AMQP message queue protocol.

XX

Connecting to the RabbitMQ message broker

AMQP API server: amqp://r.waviot.com (port 5671)
login: api_guest
pass: waviot
virtual host: /api
exchange name: strij.api

These parameters in the amqp://api_guest:waviot@r.waviot.com format are containing in the rabbit_guest_api_connection field of the WAVIOT_JWT token, received as a result of successful authorization on the authorization server.

XX

Creation of the AMQP queue for receiving UPLINK-packets and statuses of the sent DOWNLINK packets

To create the AMQP queue use AMQP publish method with routing key cmd.in.serversoft, containing the following JSON body:

{
             "msg_type":"create_queue",
             "bind": <Range of devices for which are subscribing to receive data>,
             "api_key": <One or more comma-separated client API_KEYs>,
             "max_length": 1000,
             "expires": 60,
             "name": <Queue name>
}

Possible options for the bind field:
# – subscription for all devices, available to the user with API_KEY provided
#.XXXXXXX – subscription for device with particular ID
#.HARDWARE_TYPE.# – subscription for device with particular Hardware Type
#.MDM_PROTOCOL_TYPE.*.*  – subscription for device with particular MDM Protocol Type

Possible options for the api_key field:
The api_key field must contain one or more user API_KEY identifiers, that authenticates requests associated with the user. API_KEY is a unique string identifier that NB-Fi server assigns for each user account. Each user has at least one API_KEY and may have more API_KEYs associated with company accounts which user belongs to. List of API_KEY values, available to the user, contain in the apiKeys field of the WAVIOT_JWT token.

The name field:
The name field is a final part of the name of the AMQP queue to be created. The AMQP queue will be created with the following name:  guest.#L#first api_key#R#.#L#name#R#

XX

Connecting to the existing AMQP queue

To connect to the AMQP queue use AMQP declare method with following parameters:

queue name: guest.<first api_key>.<name>
Durable: true
Autodelete: true
Passive: true
XX

Receiving NB-Fi messages via AMQP queue

To receive NB-Fi messages from the AMQP queue use AMQP consume method.
The message, containing the received UPLINK packet have the following structure:

{
             "msg_type":"ul_app",
             "bs_tz":10800,
             "dl_mode":"CRX",
             "dl_phy":"DL_PSK_FASTDL",
             "hw_type":"phobos1_stm",
             "iterator":21,
             "last_dl_bs":9784,
             "last_dl_bs_aver_busyness":28,
             "last_dl_bs_busyness":48,
             "last_success_dl_ts":1620904162,
             "modem_id":8158045,
             "payload":"420912609D3EF081890015CC0283890000BE8F8489000052B88168000000BF",
             "phy":"UL_DBPSK_3200_PROT_D",
             "protocol":"electro5",
             "rssi":-102,
             "snr":45,
             "station_id":9784,
             "time_detected":1620907364,
             "time_saved":1620907365
}

where:
"bs_tz"
– Time zone of the NB-Fi base station that received the UPLINK packet (seconds ahead to GMT time)
"dl_mode"
– Transport-layer operation mode of the NB-Fi protocol (NRX, DRX, CRX, OFF)
"dl_phy" – Current DOWNLINK channel data rate descriptor
"hw_type" – Device hardware type
"iterator" – NB-Fi packet iterator
"last_dl_bs" – ID of the NB-Fi base station from which the last DOWNLINK packet was received
"last_dl_bs_busyness" – NB-Fi base station transmitter load percentage
"last_dl_bs_aver_busyness" – Average NB-Fi base station transmitter load percentage
"last_success_dl_ts" – Timestamp of the last successfully received DOWNLINK packet
"modem_id" – Modem ID
"payload" – Payload of the user packet (actual data transferred from device)
"phy" – Current UPLINK channel data rate descriptor
"protocol" – MDM Protocol Type
"rssi" – RSSI of the received UPLINK packet, dBm
"snr" – SNR of the received UPLINK packet, dB
"station_id" – ID of the NB-Fi base station that received the UPLINK packet
"time_detected" – Timestamp of packet reception by the NB-Fi base station
"time_saved" – Timestamp of packet reception by the NB-Fi server

The message, containing information about status of the sent DOWNLINK packet, have the following structure:

{
             "msg_type":"dl_queued",
             "dl_phy":"DL_PSK_5000",
             "instance_id":9,
             "modem_id":8040809,
             "status_id":"609d156554902368f781207a"
}

where:
"modem_id" – Modem ID
"msg_type" – status of the sent DOWNLINK packet. The possible values are:
             "dl_queued" – DOWNLINK packet is queued in the Tx packet queue queued
             "dl_inprocess" – Tx is in progress
             "dl_success" – DOWNLINK packet was delivered
             "dl_fault" – DOWNLINK packet was not delivered
"dl_phy" – Current DOWNLINK channel data rate descriptor
"status_id" – Unique ID of DOWNLINK packet

XX

Sending NB-Fi messages via AMQP queue

To send NB-Fi messages via the AMQP queue use AMQP publish method with routing key cmd.in.serversoft, containing the following JSON body:

{
             "msg_type":"dl",
             "modem_id": <Modem ID>,
             "payload": <Payload of the user packet>
             "status_id": <Packet ID, set by the user, may be absent>,
             "priority": <Packet sending priority, from 0 (lowest) to 4 (highest)>
             "api_key": <One or more comma-separated client API_KEYs>
}