Central Location Services Deployment Guide

• 1: Overview
• 2: Wi-Fi Analytics Solutions
• 3: Architecture
• 4: Design and Deployment Considerations
• 5: Partner Integration
• 6: Troubleshooting

1 - Overview

Use cases

Calculated data provided by CLE can be consumed by Central’s Presence Analytics application or by third-party analytics applications using Central’s rich set of contextual APIs.

The Presence Analytics dashboard provides insights into customer behavior and intent, showing a condensed overview of visitor behavior and patterns, data on dwell time, draw rate, loyalty, visitors, and browsing habits. Central also integrates with several solution partners to unlock various use cases. To learn more about our technology partner programs, refer to the partners portal.

• Tracking the Impact of Promotions: By monitoring foot traffic before, during, and after a promotion, businesses can determine if a particular campaign successfully increased user footprint.

• Identifying Returning Users: Presence Analytics can identify returning customers based on their device’s unique identifiers, such as MAC addresses. By recognizing repeat visitors, retailers can gain insights into customer loyalty and engagement.

• Dwell Time Analytics: In addition to foot traffic, presence analytics can provide insights into how long customers spend in different areas of a store. This data reveals which sections are more engaging and attract longer dwell times.

• Comparing Store Performance: Retailers can gather data and later use it to compare it to the other stores in terms of user footprint.

• Operational Efficiency: Real-time location and geofencing data can be utilized to construct traffic heatmaps or path-movement maps that could then be used to optimize staffing levels in high-density hotspots or to help redirect traffic flow for venue attendees or retail customers to reduce space congestion.

• Workplace Optimization: Analytics partners can use contextual data from the network and combine it with access card readers or HVAC systems to provide deeper insights into how workplaces are being utilized so businesses can make more informed decisions around upsizing or downsizing their workplaces.

Most of these use cases can either be enabled through Central’s Presence Analytics solution or by integrating with our analytics partners through a rich API set, some of the popular APIs being presence, station, location and geofence. For more details on available APIs and their usage, refer to the Partner Integration section. APIs allow third-party applications to access and utilize the data for various purposes, such as custom dashboards, integration with other software, or the development of new applications that leverage analytics.

APs send information to CLE for every associated and unassociated client within their range. CLE uses that information to perform two main functions:

• Calculating locations of associated and unassociated clients.

• Storing contextual information in its database that can be exposed to third-party applications through APIs.

CLE provides many advantages including:

• Ease of Installation – Eliminates the need for on-site hardware and infrastructure.

• Fast updates - Cloud-driven platforms enable consistent feature updates.

• Redundancy and Disaster Recovery - Uninterrupted service availability with built-in redundancy and disaster recovery strategies.

• Unified Third-Party Integration - Cloud-centric location services provide a unified interface for integrating seamlessly with third-party applications through APIs.

Understanding CLE, ALE and Meridian

2 - Wi-Fi Analytics Solutions

Presence analytics

This solution is designed to help businesses and organizations gain insights into how people move within physical spaces, such as retail stores, airports, offices, and other locations. By leveraging data from Wi-Fi networks, presence analytics offers a wealth of information that helps retailers answer important questions and make informed decisions.

Presence analytics functions by analyzing over-the-air data that is captured by HPE Aruba Networking Access Points. When a Wi-Fi-enabled device (such as a smartphone or tablet) comes within range of the access point, the client device sends out probe requests to discover available networks. These probe requests can be captured by CLE for Presence Analytics.

To learn more about Presence Analytics including how to monitor and configure metrics and thresholds, refer to the Presence Analytics Central page.

Location analytics

By using a trilateration algorithm, the Central Location Engine utilizes data from the APs to precisely determine the client’s location on the floor plan, enabling detailed location analytics.

3 - Architecture

High-level architecture and workflow

Access Points transmit the RSSI of wireless devices and neighboring Access Points to the CLE an integral component of Central, through HTTPS on port 443. CLE processes the RSSI information from Access Points to calculate device locations. Subsequently, RSSI is distributed to the Presence Analytics dashboard within Central and the computed device location data is sent to the APIs and the data store. The architecture that supports the functionality of the Central Location Engine resides primarily within the cloud, specifically Central, at a high level for location engine operations.

Workflow

By following this workflow, the location engine can effectively handle changes in Access Point placement and new floor plans, and provide accurate client location information for various applications, including real-time tracking and visualization through the Floor Plan manager.

Floorplan The floorplan manager on Central allows the user to upload the map file and provide information to accurately scale the map.

APs placed on the map Once Access Points are placed on the map, APs will transmit RSSI data to the Location Engine.

Central Location Engine The Location Engine processes the incoming RSSI data and calculates the location of the clients.

APIs CLE publishes the location data to streaming services that can be used by third-party applications and systems for gaining contextual insights.

Hazelcast CLE efficiently writes data into Hazelcast, a real-time data platform, ensuring data integrity and accessibility.

VisualRF VisualRF initiates a query to Hazelcast for location data upon receiving an API call from the UI in the backend.

Floor Plan View (UI) The Floor Plan View (UI) elevates user experience and displays client locations on the floorplan.

Security

Central places a strong emphasis on security, ensuring that administrators have a wide range of protective features to keep their networks safe and sound. The platform delivers robust security measures. For detailed insights into Central’s security features, refer to the Central Security Overview page.

One of Central’s security approaches involves addressing the evolving landscape of device security. Central employs anonymization by facilitating the hashing of client MAC addresses. When enabled, anonymization ensures the anonymity of client identities by employing a one-way hash function. It is important to note that the same hash will consistently correspond to the same client, maintaining a unique yet secure identifier. For added flexibility and privacy, administrators can configure the system to change the “secret key” used for generating hashes at customizable intervals, such as weekly or monthly.

Data retention

Central is not designated to store historical location data. The database is specifically designed to provide an instantaneous view rather than an aggregated perspective, showcasing the current distribution of associated clients on the floorplan. It is important to note that the time-to-live (TTL) for any location data related to a device is approximately 17 minutes.

Accuracy

The client’s location is determined by analyzing the RSSI detected by Access Points, considering the maximum four strongest RSSI values on the same channel.

Considering the prerequisites are met, the typical accuracy of location calculations is in the range of 5-7 meters.

Impact of MAC address randomization

Most mobile device vendors use random MAC addresses during probe requests as a privacy-enhancing feature to protect the user’s identity and location while scanning for Wi-Fi networks.

Central excludes unassociated devices that use random MAC address data from the data analysis. Central, however, does monitor and record data for associated clients using random MAC addresses.

Before AOS 8.7.1.5, all clients using randomized MAC addresses were subject to monitoring, and their data was recorded. However, starting from AOS 8.7.1.5 onwards, and in AOS 10, random MAC addresses are handled at the AP as follows:

• AP filters random MAC addresses seen from probe request frames and discards them. As a result, location-based services do not have visibility for these MAC addresses.
• Random MAC addresses & legitimate MAC addresses seen from management frames other than probe requests will be stored and forwarded by AP.
• Random MAC addresses & legitimate MAC addresses coming from data frames and control frames such as Block ACK will be stored and forwarded by AP. These frames typically indicate connected clients.

The analytics trends and metrics from client devices using MAC address randomization are still relevant for customers to leverage. Since the focus of Presence Analytics is on aggregate trends and insights and not on individual clients, the impact would be minimal for trends observed over some time. There is close to zero impact of MAC address randomization on trends involving associated/connected client devices.

MAC randomization will not impact the insights provided by Presence Analytics. Only metrics such as dwell time, visitor, and passer-by may be minimally impacted.

In the case of an iPhone, the device needs to meet these four conditions for using a randomized MAC address while probing:

• Wi-Fi must be turned on, but the device is not associated with an actual Wi-Fi service.
• The phone needs to be in sleep mode. iPhones go into sleep mode when all the services in the phone are inactive, and not just when the screen is turned off.
• Location Services set to off in the Privacy & Security settings.
• Cellular data must be turned off.

As all these conditions need to be met, there may be a much lower percentage of devices using randomized MAC addresses on the network.

4 - Design and Deployment Considerations

Network design

Some network design considerations are essential for a location-ready network deployment. The detection of a wireless device (client) by a minimum of three access points is required for the computation of the X and Y coordinates of the client. The client’s location is established based on the RSSI (signal strength) detected by access points, using the four strongest RSSI values on the same channel.

In general, having a good density and proper placement of APs that detect the clients increases the likelihood of more precise device location. To learn more about the accuracy, refer to the Accuracy section.

AP placement

​Most non-location-ready deployments are designed such that APs are placed in the inner spaces of the floor plan. APs are generally not placed on the perimeters or corners since their coverage cells would bleed outside the floor, which may not be necessary as the WLAN, in most cases, is not required to serve clients outside the floor boundaries.

In a location-ready network, APs are not only placed in the center spaces but also spread across the perimeters and corners of the floor. This helps in improving location accuracy as it increases the likelihood that a device at any coordinate on the floor is seen by more than three APs for trilateration at better signal strength.

Distance between the access points

Utilize the grid line functionality within Central to optimize the AP layout, ensuring consistent spacing in all directions. Maintaining a recommended 10-15-meter gap between APs is advised, allowing the grid lines to be configured accordingly.

Minimum RSSI and AP separation

The distance between APs can impact the location accuracy of a wireless client. Radio signals are subject to the inverse square law, which for this purpose means that every time the distance between the signal generator (client) and the signal receiver (AP) doubles, the received signal power, sometimes referred to as received signal strength indicator (RSSI), will be quartered. Once the received signal has diminished to a certain point, typically around -65 dBm received at the AP, the ability to determine a specific distance based on the signal has diminished to the point of uselessness. Too much distance between access points means that accurately locating client devices will be difficult or result in incorrect positioning.

For accurate trilateration of a client within an area, the recommendation is for APs to be placed so that at least three APs can hear the client at -65dBm or better. This will usually correlate to the APs being separated by 40-50 feet but placed no more than 60 feet apart.

Air monitors

Air Monitors are APs deployed in a mode specifically dedicated to the purpose of listening to the Wi-Fi environment, allowing for more data to be collected.

An access point should be spending as many cycles as possible to serve WLAN clients, and so the AP may capture data frame RSSI from associated clients, as both the AP and clients exchange data on the same channel. However, for the same AP to capture data frame RSSI from clients associated with other APs, the AP must go off-channel to listen on the same channel where the clients are exchanging data frames. For instance, if AP1 serves client X on channel 1, and AP2 serves client Y on channel 11, the probability of AP1 switching to channel 11 simultaneously while client Y transmits data is statistically low. An Air Monitor scans channels more aggressively than an AP, and has a higher likelihood of picking up data frame RSSI from both channels 1 and 11, contributing more data to location computations.

For a deployment that demands analytics concerning associated devices, the incorporation of a combination of APs and AMs (for example, one AM for every four to five APs) is advised. For additional information on setting an AP to monitor mode, refer to AOS10 documentation for AOS10 APs and Instant AP Radio Mode - Monitor for Instant APs.

Best practice summary

In summary, the best practices for an installation that provides the best location results are:

• Deploy the APs with a sufficient density for trilateration within the entirety of the coverage area.

• Make sure to deploy APs at the edges of the coverage area.

• Deploy access points meant to be used in Air Monitor mode, in the prescribed ratio.

  • Using Air Monitors is especially important for analytics around associated devices that don’t have a high usage pattern.

• When testing Central Location Services, use enough devices to get accurate results.

  • When testing with only three APs, the data collected will almost certainly not show the minimum 3 APs needed for trilateration; insufficient data causes the location algorithm to attempt locations based on the Single AP method.

  • Better test results will be obtained by using seven to eight APs, with one or two of those deployed as an Air Monitor.

Pre-requisites

Before deploying and testing Central Location Services, ensure that the following prerequisites have been met:

1. Central account: An active Central account with online access points; Central serves as the management platform for various network services, including Presence Analytics and Floor Plan Manager. For more details on getting started with Central, visit the Central onboarding and provisioning.

2. Upload a floor plan to Central: A floor plan of the area to be tracked must be uploaded to Central and scaled correctly. For more details, refer to the Central documentation on creating, importing, and modifying floor plans.

3. Place access points on the map: Position the APs on the uploaded floor plan in Central. This step is crucial for the system to calculate the location of connected wireless devices. Refer to the Central documentation for more details on placing APs on the floor plan.

4. Connect clients to the APs from the floor: Connect clients (devices like smartphones, laptops, etc.) to visualize the devices on the Central floor plan. Refer to the Central documentation for more details on creating a WLAN SSID. This allows CLE to track and analyze the client device’s location based on signal strength and other factors.

Correctly following these prerequisites should allow for contextual information for clients including tracking their locations.

5 - Partner Integration

Central offers two types of APIs: Polling APIs for querying specific information and Publish/Subscribe APIs for near real-time updates. The Polling API provides a current snapshot of the network environment. Thereafter, any real-time updates in the network are learned through Publish/Subscribe APIs. Publish/Subscribe APIs are recommended for location updates.

Polling or REST APIs

Among the many Polling APIs supported by Central are the Location, Presence, Geofence and Station REST APIs. These are some of the most commonly utilized APIs by analytics applications, and some of them are elaborated below.

Location API

The Location REST API can be used to access near real-time data around device location, status, and identity within a specific campus, building and its various floors. Customers can securely access the REST API using their credentials and an API key. They can make requests to specific endpoints on the API to retrieve data. For example, to retrieve the location of a specific client, the endpoint would be - /visualrf_api/v1/client_location/{macaddr}.

For more information on how to access the REST API using Central refer to the REST API developer docs.

The output for this message type displays the following information:

Example Response for Location REST API GET https://example.com/visualrf_api/v1/client_location/{macaddr}

{  
  "location": {  
    "x": "185.55978",  
    "y": "35.71597",  
    "units": "FEET",  
    "error_level": 61,  
    "campus_id":
"201610193176__1b99400c-f5bd-4a17-9a1c-87da89941381",  
    "building_id":
"201610193176__f2267635-d1b5-4e33-be9b-2bf7dbd6f885",  
    "floor_id":
"201610193176__39295d71-fac8-4837-8a91-c1798b51a2ad",  
    "associated": true,  
    "device_mac": "ac:37:43:a9:ec:10"  
  }  
}

Presence API

Retail customers can leverage the REST API data to create relevant applications by utilizing the various endpoints provided for Presence Analytics.

Visitor status

Endpoint: GET https://example.com/presence/v3/visitor_status

• Utilize this endpoint to retrieve the number of connected and non-connected visitors within a selected time range.

• If needed, filter data by passing the tag_id to retrieve information for a specific tag/site.

• Applications can display real-time visitor status, helping staff manage crowd control and understand store occupancy.

{  
  "data": {  
    "visitor_status": [  
      {  
        "count": 0,  
        "status": "Connected"  
      },  
      {  
        "count": 0,  
        "status": "Not Connected"  
      },  
      {  
        "total_visitors": 0  
      }  
    ]  
  }  
}

Visit frequency

Endpoint: GET https://example.com/presence/v3/visit_frequency

• Use this endpoint to get details for loyal visitors, including the number of visits made by a customer at a specific site or customer level.

• Applications can provide insights into customer loyalty, enabling targeted marketing campaigns or loyalty programs.

{  
  "result": [  
    {  
      "bucket": "2-10",  
      "count": 7  
    }  
  ],  
  "status": "success",  
  "unique_visitor_count": 0  
}

Analytics trends for loyal visitors

Endpoint: GET https://example.com/presence/v3/analytics/trends/loyal_visitors

• Retrieves discrete (samples) values for each time interval from start time to stop time, for presence indicators ( passerby, visitor, draw rate, dwell time) at a site or customer level based on input. The time interval depends on what timeframe is selected and if the sample value is aggregated value for that time interval. If 1 day is selected, the interval is 1 hour and the sample is aggregated value for each one hour.

• Applications can visualize trends in customer behavior, allowing retailers to optimize store layouts and offerings.

[  
  {  
    “allowed_frequency”: [  
      [  
        “hourly”,  
        “daily”,  
        “weekly”  
      ]  
    ],  
    “fields”: [  
      [  
        “time”,  
        “loyal_visitors”,  
        “unique_visitors”  
      ]  
    ],  
    “samples”: [  
      [  
        [  
          [  
            1590949800000,  
            0,  
            0  
          ],  
          [  
            1590953400000,  
            0,  
            0  
          ],  
          [  
            1590957000000,  
            0,  
            0  
          ],  
          [  
            1590962400000,  
            1,  
            1  
          ]  
        ]  
      ]  
    ]  
  }  
]

Analytics trends for passerby visitors

Endpoint: GET https://example.com/presence/v3/analytics/trends/passerby_visitors

• Similar to the endpoint for loyal visitors, retrieve discrete values for presence indicators for passerby visitors.
• Applications can analyze passerby trends to understand foot traffic and improve store marketing strategies.

{  
  "datapoints": [  
    {  
      "allowed_frequency": [  
        "hourly"  
      ],  
      "customer_id": "123456789",  
      "category": "visitor",  
      "xunits": "dwelltime",  
      "yunits": "visitor_count",  
      "data": {  
        "count": 35,  
        "sample": [  
          [  
            1591243200000,  
            2  
          ],  
          [  
            1591246800000,  
            2  
          ],  
          [  
            1591250400000,  
            4  
          ]  
        ]  
      }  
    }  
  ]  
}

Aggregate values for list of sites

Endpoint: GET https://example.com/presence/v3/insights/sites/aggregates

• Obtain aggregated/average values for various categories (passerby, visits, draw rate, dwell time, loyal visitors, visitors, connected visitors) at a site or customer level.

• Applications can present a comprehensive overview of key metrics, aiding in strategic decision-making for each site.

{  
  "category": "all",  
  "data": [  
    {  
      "drawrate_count": 76,  
      "dwelltime_count": 67,  
      "loyal_visitors": 45,  
      "new_visitors": 35,  
      "passerby_count": 35,  
      "site_id": 65,  
      "site_name": "c2cLab",  
      "store_id": 65,  
      "store_name": "c2cLab",  
      "total_connected": 55,  
      "visitor_count": 45,  
      "visits": 65  
    }  
  ],  
  "limit": 10,  
  "offset": 0,  
  "sort": "asc",  
  "total": 10  
}

Publish/Subscribe or streaming APIs

These are also called “Streaming APIs” and serve as the primary tool for subscribing to and receiving real-time updates from Central. They operate on the publish-subscribe model, ensuring that any message published on a specific topic is promptly distributed to all subscribers interested in that topic. These types of APIs find versatile applications in event-driven architecture and real-time monitoring.

Central adopts the Web Socket Secure (WSS) protocol for the Streaming API. In this setup, the publisher is represented by Central, functioning as the WebSocket Server, while the subscriber is the WebSocket client application designed and used by end-point applications.

Streaming APIs are categorized into different topics, some of the most popular ones being the Presence, Location and Geofence topics.

Presence topic

The Presence topic contains details of all associated and unassociated clients detected by Access Points. Event updates for each device are sent once every 60 seconds.

Below are descriptions of crucial parameters contained within the Presence topic that help enable some of the Presence Analytics use cases:

• Proximity—The pa_proximity_event reports which AP hears the client at the strongest RSSI, indicating which AP is closest to the client/station, and this event will be provided for each device once every 60 seconds.

• RSSI—The pa_rssi_event contains a list of RSSI information of all unassociated and associated clients/stations, detected by an AP device, and this event will be provided for each device once every 60 seconds.

The streaming API delivers data updates containing the following information for each client device:

Example of an event from the Presence topic:

sta_eth_mac {
addr: "B827EBD9CEB2"
}
radio_mac {
addr: "B45D5062FCF0"
}
rssi_val: -66
noise_floor: 92
associated: false
device_id: "CNCFJSS4WF"
ap_eth_mac {
addr: "B45D50CE2FCE"
}

Location topic

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

The output for this message type displays the following information:

Example of 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: "320323340262p"
 }
 campus_id_string: "77d249ac35b548cab35fb48a8a1e7dd5__default"
 building_id_string: "77d249ac35b548cab35fb48a8a1e7dd5__1"
 floor_id_string:
 "77d249ac35b548cab35fb48a8a1e7dd5__ee80edb6-0476-4c9e-93a4-d79acd2c6f7a"
 target_type: TARGET_TYPE_STATION
 associated: false

Geofence notify

The Geofence Notify message returns information when a device enters or leaves a geofence region. Geofence Notify events are only available under the Location topic on Central.

The output for this message type displays the following information:

Decode data for customer location  
{'customer_id': '416bc832bc6111ed961e6aa14dbf31f1',  
'data': {'associated': False,  
          'dwell_time': 172,  
          'geofence_event': 'ZONE_OUT',  
          'geofence_id':
'NDE2YmM4MzJiYzYxMTFlZDk2MWU2YWExNGRiZjMxZjFfXzU2OTE2ZGUxLTg0MzgtNDNhYi04NTZhLTNkY2QwNDkwNTRjOQ==',  
          'geofence_name':
'416bc832bc6111ed961e6aa14dbf31f1__Zone-1',  
          'sta_eth_mac': {'addr': 'IEwDTSRj'}},  
'msp_ip': '',  
'timestamp': 1699915771139221492,  
'topic': 'location'}

Useful resources

• Overview of Foundation and Advanced Licenses

• REST API- Get Started with REST API for Configuration, on-demand polling, and monitoring data via HTTP Requests.

• Streaming API- Get Started with Streaming API to subscribe to selected topics, get statistics, and state changes over Secure WebSocket (WSS).

• Webhook - Get Started with Webhooks to integrate external applications and implement actions based on real-time alerts.

6 - Troubleshooting

Listed below are some verifications that can be performed while testing the Central Location Services.

Clients not visible on the floor plan

• Ensure that the Clients field is selected.

Navigate to Central Global → Sites → choose the desired site for viewing → click on the displayed view.

• Use the REST API to further verify client information. For more details on REST APIs, refer to the Polling API section.

• Ensure that Access Point is sending RSSI messages to Central. Use the command show running-config | include rssi.

  AP-3-Loc# show running-config | include rssi
  report-rssi-to-central unassociated-and-associated-clients
  

• Ensure that the message length exceeds a couple of hundred bytes; otherwise, the IAP is transmitting RSSI for its BSSIDs. Use the command show log ap-debug | include rssi.

  AP-3-Loc# show log ap-debug | include rssi
  Nov 6 15:23:11 awc[6232]: [cloud] wsc: insert queue a message to
  websocket server, topic iap.rssi, msg_len=10714.
  
  Nov 6 15:24:10 awc[6232]: [cloud] wsc: receive a post request from
  application, topic rssi, data len 13123, ce_ctx , len 0.
  
  Nov 6 15:24:10 awc[6232]: [cloud] wsc: insert queue a message to
  websocket server, topic iap.rssi, msg_len=13136.
  
  Nov 6 15:25:10 awc[6232]: [cloud] wsc: receive a post request from
  application, topic rssi, data len 10629, ce_ctx , len 0.
  
  Nov 6 15:25:10 awc[6232]: [cloud] wsc: insert queue a message to
  websocket server, topic iap.rssi,
  

• Make sure that the AP has subscribed to RSSI reporting with Central. Use the command show ap debug msg-subscription.

  AP-3-Loc# show ap debug msg-subscription
  Subscription modules List
  -------------------------
  message type Central ALE
  ------------ ------- ---
  state FALSE FALSE
  stat FALSE FALSE
  rssi TRUE FALSE
  clarity TRUE FALSE
  apprf TRUE FALSE
  trap FALSE FALSE
  speedtest FALSE FALSE
  telemetry TRUE FALSE
  

Clients placed on top of APs

When this scenario is encountered there is a high likelihood that only one or two APs are present on the floor. This is expected behavior for this situation and the recommendation is to consider optimizing AP placement. A minimum of three APs is required for trilateration to work effectively. For more details on the AP placement, refer to the Network Design section.