The MazeMap-CMX integration comprises of three services that must be configured to work together
- The Cisco CMX, configured and hosted by the customer
- The LIPI Server, configured and hosted by the customer
- The Siteresolver, configured and hosted by MazeMap
Pre-Installation checks
Requirements for the LIPI server
Can be virtual or physical, does not matter.
No OVA currently available, one of the supported OSes needs to be installed.
Supported Operating systems: Ubuntu 16.04 LTS, Debian Jessie, RHEL 7, Cent OS 7.
Server/Virtual Machine(VM) specs: Tested to work with single Core VM with 3.5 GB Ram and 7 GB HDD.
Requirements for the network
- Open port 443 from LIPI server to CMX (https for API).
- Open port 443 from all wireless clients to LIPI (https for position requests).
- Traffic from Wireless Clients to LIPI must not pass through NAT.
Requirements for the CMX
- CMX set up with Location services activated and sufficient licenses.
- Building maps, with correct map scaling and a minimum of 3 GPS markers per floor need to be set up on Cisco Prime, exported and imported into CMX.
- GPS markers should use coordinates created using MazeMaps own map. MazeMap provides a tool for generating these. You can find the POI inspector-tool here: https://debug.mazemap.com/
- Access points must be placed correctly (within a meter of actual location) in the maps in Cisco Prime.
- CMX GUI user for MazeMap with Full Read Only privileges set up on MSE/CMX.
- CMX CLI API user with full Read and API access. Both CMX GUI and CLI users should have the same username/password
Installation Instructions
The following assumes that reader is proficient in basic Linux usage and networking
LIPI
- Download the newest LIPI installation files from MazeMap: https://www.jottacloud.com/s/113950633e009454e379c2f969e9943666d
- Upload this file to the LIPI server and unzip it
- Read the included README file
- Read through the installation script to understand what it does. There are different installation scripts for different operating systems, pick the one that matches the operating system of your LIPI server
Siteresolver
The Siteresolver must be configured by MazeMap. MazeMap requires the following information in order to set this up:
- The private IP address of the LIPI server (the address that WiFi clients will use to connect to the LIPI without traversing NAT)
- The public IP address or range of addresses for the WiFI clients. This is most commonly the public IP address of the NAT
Testing the service
Does it work at all?: LIPI debug tool
When you believe the LIPI, CMX and Siteresolver are set up up correctly, the first step is to test it using the debug tool. This will show wether the CMX is able to provide positioning data to the wireless client
The person using the LIPI debug tool needs to be on site and connected to the WiFi
- Go to the following link: https://debug.mazemap.com/lipi/
- Click "refresh" in the top right hand corner
- If the Siteresolver is set up correctly, the LIPI server will show up on the list
Testing the quality: Visual Debug tool + CMX GUI
The person using the visual debug tool needs to be on site and connected to the WiFi
Once all tests pass in the LIPI debug tool, the next step is evaluate the quality of the position data. Using this tool, we will evaluate two aspects of the positioning data: update rate and accuracy
- The Visual Debug Tool can be found here: https://debug.mazemap.com/position/
- The URL for the CMX GUI will vary from customer to customer
- Find the client in the CMX GUI, and open the Visual Debug Tool
- Verify that the locations in the CMX GUI and the Visual Debug Tool Match
Common issues
| Issue | Symptom | Solution |
|---|---|---|
| Missing GPS markers | LIPI debug tool fails on test 6. No floor shown in client , position showing outside building | How To Add GPS markers to CMX |
| Broken/Poor GPS markers | Client location differs between CMX GUI and MazeMap/Visual Debug Tool | |
| Wrong z-mapping | Positioning works, but wrong floor is indicated. Z-level is visible in the LIPI Debug Tool. | Add explicit z-mapping for floor in LIPI config file |
| No z-mapping | Positioning works, but wrong floor or "outside" is indicated | Add explicit z-mapping for floor in LIPI config file |
| Firewall blocks Wireless clients from reaching LIPI | Debug tool fails on test 1. Position in client might appear outside building (since it falls back to the phones built-in positioning service) | Open firewall |
| Firewall blocks LIPI from contacting CMX | Debug tool fails on test 4 or 1 (depending on timeout limits). | Open firewall |
Checklist
1. Is the LIPI server (ubuntu server) accessible?
2. Is the LIPI service (geopos.service) running?
2. 1. If it is not running: Is the JSON config correct?
2.2. If it is not running: Are there issues with dependencies? JAVA?
3. If it is running but not working: Are the LIPI able to connect to CMX? Ping or CURL it?
3.1. If it is able to connect to CMX but not getting any data: Are the LIPI CMX user able to get any data? Is the username and password correct in the config.json?
3.2. If it is still not able to get any data: Does the CMX user have the right privileges (Read access)?
4. If the CMX user is correct and the LIPI are able to get data from CMX but it is still not working: Are there GPS markers placed on the floors set up in MazeMap?
4.1. If there are no GPS markers set on the floor where the device running the test are located: Add GPS markers on the floors.
5. If the LIPI are able to get data from CMX and there are GPS markers placed on the floor but MazeMap are showing the wrong floor: Check z-mapping of the config.json
Tip: to check output from journalctl geopos.service on the LIPI server, run the command: journalctl -u geopos.service -n 50
Maintenance
In order to ensure proper functioning of the positioning service, the service should be retested when changes are made to:
- Public addresses, NAT, IP ranges assigned to WiFi clients
- Virtual networks used by WiFi clients, LIPI, CMX
- Wireless infrastructure
- Routing of wireless clients, LIPI server or CMX
- Firewall configurations that affect Wireless clients, LIPI server or CMX