The live tracking results can be delivered through AMQP or MQTT.

We suggest to use AMQP for backend to backend integration and MQTT for client (mobile app, webapp) integration.

• AMQP
  • All results are delivered via AMQP as an event stream.
  • Credentials will be provided by Favendo.
  • For each output type, 5 queues will be provided.
  • Intervals are configurable, but in the default configuration one can expect:
    • TrackerHeartbeat: one message per tracker every 5 minutes.
    • BeaconBattery: one message per beacon every 1 hour.
    • TrackingResult: one message per beacon every 2 seconds.

• MQTT

  • All results are delivered via MQTT as an event stream.
  • User credential will be provided by Favendo.
  • In order to connect to the MQTT broker, the user needs to authenticate and fetch the mqtt credentials first (see bellow)
  • All output types will be delivered with different topics:
    • TrackerHeartbeat: one message per tracker every 5 minutes: f/z/e/*/fav/tracker-heartbeat/
    • BeaconBattery: one message per beacon every 1 hour: f/z/e/*/fav/beacon-battery/
    • TrackingResult: one message per beacon every 2 seconds: f/z/e/*/fav/tracking-result/

02. Examples

02.01. TrackingResult example

{
	"type": "Feature",
	"id": "ib/20635f00-0041-0041-20635f00c900/0/0",
	"trackingResultSource": "GPS",
	"levelNumber": 0,
	"properties": {
		"level_id": "0",
		"favendo:assigned_asset": {
			"name": "Mary-41",
			"externalId": "Mary-41",
			"customProperties": {
				"custProp": "custProp"
			}
		},
		"favendo:tracking": true,
		"favendo:geofence_ids": [],
		"timestamp": "2022-07-13T15:03:10.198Z"
	},
	"geometry": {
		"type": "Point",
		"coordinates": [
			113.90373500672054,
			22.303839816750422
		]
	}
}

02.02. BeaconBattery example

{
	"id": "ib/0c05b9ce-057f-4a0d-8a37-e17125f1c37f/1/2",
	"timestamp": "2020-09-17T14:38:46.732Z",
	"milliVolts": 3021
}

02.03. TrackerHeartbeat example

{
	"id": "fad0cafefad0babe",
	"timestamp": "2020-09-17T14:38:46.732Z",
	"model": "ed0",
	"firmwareVersion": "1.2.3.4"
}

03. MQTT integration flow

03.01. The client authenticates and retrieves the authentication token and MQTT credentials (1),(2),(3)

• Endpoint path: /authentication/user 
• Method: POST 
• Parameters: Credentials provided by Favendo as Basic authentication

Output example:

{ 
    "username": "username", 
    "authToken": "AUTH_TOKEN", 
    "roles": [ 
        "SUPERUSER" 
    ], 
    "mqttUser": "MQTT_USER", 
    "mqttKey": "MQTT_KEY" 
} 

03.02. The client fetches the available venues (4),(5)

• Endpoint path: /backspin-backend/zircon/api/v1/user-profile/venues/
• Method: GET 
• Parameters: Token authentication as bearer token

Output example:

[ 
    { 
        "scopeId": "SCOPE_ID_1", 
        "venueName": "Venue name" 
    }, 
    { 
        "scopeId": "SCOPE_ID_2", 
        "venueName": "Venue name 2" 
    } 
] 

03.03. The user selects a venue and fetches the venue available levels (6),(7),(8)

• Endpoint path: /backspin-backend/zircon/api/v1/floorplans/SCOPE_ID_1/levels 
• Method: GET 
• Parameters: SCOPE_ID retrieved in the previous endpoint

Output example:

[ 
    { 
        "levelName": "Level 0", 
        "levelNumber": LEVEL_NUMBER, 
        "levelId": "LEVEL_ID" 
    }, 
    { 
        "levelName": "Level 1", 
        "levelNumber": LEVEL_NUMBER, 
        "levelId": "LEVEL_ID" 
    } 
] 

03.04. The user build the mqtt topic and connects to the tracking result stream (9),(10)

• Tracking result topic : f/z/e/fav/tracking-result/*SCOPE_ID_1/LEVEL_NUMBER/* 
• MQTT username: MQTT_USER
• MQTT password: MQTT_KEY