HomeGuidesAPI Reference
GuidesAPI ReferenceGitHubAirheads Developer CommunityLog In
Guides

Location Streaming Event

A location event is generated when the location of a client (station) is computed using RSSI values reported by the Instant Access Points (IAPs) periodically. The event message includes coordinates of the client on the VisualRF floor plan and GeoFence notification, which contains information on when a device enters or leaves a GeoFence region (if GeoFence is enabled). Therefore, an existing visualRF floor plan with AP location mapping is a prerequisite for the Location Streaming Events.

Location Event Protocol Buffer File

message mac_address
{
   optional bytes addr = 1;
}
enum target_dev_type
{
   TARGET_TYPE_UNKNOWN = 0; 
   TARGET_TYPE_STATION = 1; 
   TARGET_TYPE_ROGUE = 3;
}
enum algorithm
{
   ALGORITHM_TRIANGULATION = 0; 
}
enum measurement_unit 
{
   METERS = 0; 
   FEET = 1; 
}
message stream_location
{
   optional float sta_location_x = 1; 
   optional float sta_location_y = 2; 
   optional uint32 error_level = 3;
   optional algorithm loc_algorithm = 9; 
   optional measurement_unit unit = 14; 
   required mac_address sta_eth_mac = 15; 
   optional string campus_id_string = 16;
   optional string building_id_string = 17; 
   optional string floor_id_string = 18; 
   optional target_dev_type target_type = 19
   optional bool associated = 20;
}
enum zone_event {
	ZONE_IN = 0;
	ZONE_OUT = 1;
}
 
message stream_geofence_notify {
	optional zone_event geofence_event = 1;
	optional bytes geofence_id = 2;
	optional string geofence_name = 3;
	optional mac_address sta_eth_mac = 4;
	optional bool associated = 5;
	optional uint32 dwell_time = 6 [default=0];
	optional string hashed_sta_eth_mac = 7;
}

Parameter Descriptions

The following table lists the field, type, rule, and descriptions of the above mentioned protobuf file

Field

Type

Rule

Description

target_type

target_dev_type

optional

Indicates the type of the device. It contains the following:

  • UNKNOWN—Indicates the type of device as unknown.
  • STATION—Indicates the type of device as Wi-Fi station or client.
  • ROGUE—Indicates the type of device as rogue.

loc_algorithm

algorithm

optional

Indicates the algorithm that populated the X and Y coordinates. It contains the following:

  • TRIANGULATION—Indicates the estimated location of the unknown APs by triangulating location.

unit

measurement_unit

optional

Indicates the unit of measurement used for floor specifications. It contains the following:

  • METERS—Indicates the floor specifications, measured in meters.
  • FEET—Indicates the floor specifications, measured in feet.
sta_location_xfloatoptionalIndicates the X coordinate used to determine the client location on a floormap. This value is based on the number of feet or meters, if configured. The station is from the top left corner of the floormap.
sta_location_yfloatoptionalIndicates the Y coordinate used to determine the client location on a floormap. This value is based on the number of feet or meters, if configured. The station is from the top left corner of the floormap.
error_leveluint32optionalIndicates the radius of the horizontal uncertainty, computed at 95%. This is the sum of the probability of all the potential locations in this uncertainty circle that represents 95% probability of the whole venue. The unit of this radius is configured and published in the unit field.
sta_eth_macmac_addressrequiredIndicates the MAC address of the client station or rogue.
campus_id_stringstringoptionalIndicates the ID number that identifies a specific campus.
building_id_stringstringoptionalIndicates the ID number that identifies a specific campus building.
floor_id_stringstringoptionalIndicates the ID number that identifies a specific building floor.
associatedbooloptionalIndicates whether the client is associated with an AP on the network. For example, 1 indicates that the client is associated with an AP and 0 indicates that the client is not associated with an AP.

Example for the Location Message

sta_location_x: 333.671569824
sta_location_y: 220.563110352
error_level: 92
loc_algorithm: ALGORITHM_TRIANGULATION
unit: FEET
sta_eth_mac {
  addr: "\320\323\340\262@p"
}
campus_id_string: "77d249ac35b548cab35fb48a8a1e7dd5__default"
building_id_string: "77d249ac35b548cab35fb48a8a1e7dd5__1"
floor_id_string: "77d249ac35b548cab35fb48a8a1e7dd5__ee80edb6-0476-4c9e-93a4-d79acd2c6f7a"
target_type: TARGET_TYPE_ROGUE
associated: false