AMQP API
NB-Fi server supports sending and receiving of NB-Fi messages via AMQP message queue protocol.
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.
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#
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
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
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> }