Interactive Floor Plan
The Floor Plan page is the primary situational awareness screen in the NISC Mustering System. It displays a live, interactive map of a selected building floor showing the real-time positions of personnel, gateways, ambient BLE devices, and tracked assets. The map updates automatically as new data arrives from the BLE gateway network.
Table of Contents
- Overview
- Selecting a Building and Floor
- Understanding the Map
- Marker Types
- Layer Toggles
- Filtering Personnel
- Searching for a Person
- Map Controls
- Measuring Distance and Area
- Heatmap Visualization
- RSSI Signal Lines
- Accuracy Circles
- Zones
- Marker Clustering
- Personnel Staleness and Fading
- Clicking a Marker for Details
- Edit Mode — Gateway Placement (Administrators)
- Historical Playback
- Mobile View
- Troubleshooting
Overview
The floor plan uses an interactive OpenLayers map rendered over a static floor plan image. All marker positions are expressed as percentages of the image dimensions so they remain correct regardless of the screen size or zoom level.
Data is delivered in real time via a WebSocket connection to the self-hosted Centrifugo relay. When you pick a floor the page subscribes to that floor's channel (floor:<id>) and receives only that floor's position updates — other floors' telemetry never leaves the backend. Ambient-device updates arrive on a shared global:all channel. The Current Time and Last Realtime Update timestamps in the toolbar let you see at a glance whether the stream is live; if they diverge for more than a minute or two, something has stalled upstream. If the WebSocket is unavailable, the page falls back to polling the context API every 10 seconds.
Personnel markers that would otherwise stack on top of a gateway (a common artefact when the position is derived from the nearest receiver) are nudged off on a deterministic RSSI-scaled radial offset so multiple people at the same receiver fan out rather than overlap (PRs #331 / #333).
Selecting a Building and Floor
Before the map loads you must choose a building and a floor.
- In the toolbar at the top of the page, click the Building drop-down and select the building you want to view.
- After selecting a building the Floor drop-down will populate. Select the floor you want to view.
- The map will load the floor plan image and begin placing markers.
Note: Changing the building or floor while edit mode is active will exit edit mode automatically and discard any unsaved gateway position changes.
Understanding the Map
Once a floor is loaded you will see:
- The floor plan image as the base layer.
- Coloured markers overlaid on the image representing different entity types.
- Optional zone polygons drawn over the image.
- Optional heatmap or signal line overlays.
The map supports standard pan and zoom interactions:
- Pan — click and drag anywhere on the map background.
- Zoom — use the scroll wheel, pinch gesture (touch screens), or the zoom buttons in the bottom-left corner of the map.
- Fit to image — click the Reset View button to return the map to its default zoom and centred position.
The coordinate system uses pixel percentages internally (0–100 on both axes). This means marker positions are independent of the floor plan image resolution.
Marker Types
Four entity types are displayed as markers on the map. Each type has a distinct colour and icon.
| Marker type | Colour | Icon | Description |
|---|---|---|---|
| Personnel | Blue (circle with initials) | Person's initials | Staff members wearing BLE beacons |
| Gateways | Green / Red | Grid square icon | BLE receiver hardware installed on the floor |
| Ambient devices | Orange (gear icon) | Gear / settings icon | BLE devices that are not assigned to a person (e.g. equipment tags, environmental sensors) |
| Assets | Purple | Tag icon | Tracked assets assigned in the asset register |
Tip: Gateway markers turn red or show an offline indicator when the gateway has not reported data recently. An online gateway shows in green.
Default marker sizes:
- Gateway: 24 px
- Personnel: 32 px
- Ambient: 20 px
- Asset: 20 px
Marker sizes scale automatically with map zoom level. You can also adjust the size and opacity of each marker type independently using the appearance controls in the layer panel.
Layer Toggles
The panel on the left side of the screen contains toggles that show or hide individual layers. Use these to reduce visual clutter when you only need to see specific information.
| Toggle | What it controls |
|---|---|
| Personnel | Show or hide all personnel markers |
| Gateways | Show or hide all gateway markers |
| Ambient devices | Show or hide ambient BLE device markers |
| Assets | Show or hide tracked asset markers |
| Zones | Show or hide zone polygons (rooms, boundaries) |
| Heatmap | Show or hide the device density / signal strength heatmap |
| RSSI lines | Show or hide signal strength lines between devices and gateways |
| Accuracy circles | Show or hide position accuracy radius circles around personnel |
Note: Hiding a layer does not stop the system from collecting data. It only affects what is drawn on screen. Heatmap data continues to accumulate even when the heatmap toggle is off.
When there are more than 200 ambient devices on a single floor, the system automatically switches ambient rendering to a GPU-accelerated mode for performance. Individual ambient markers are replaced by a canvas-rendered point cloud. This is transparent to the user.
Filtering Personnel
You can narrow the personnel markers shown on the map by department or by zone.
- In the left panel, find the Department drop-down and select a department. Only personnel in that department will appear on the map.
- Use the Zone drop-down to further restrict markers to personnel currently detected within a named zone.
- To remove a filter, clear the drop-down (select the blank option at the top of the list).
The personnel table below the map also reflects the active filters.
Note: Department options are loaded from the personnel register. If a department does not appear in the list, check that the department is configured in the Admin section.
Searching for a Person
Use the search box in the toolbar to find a specific person by name.
- Type at least two characters of the person's name into the search field.
- A drop-down list will show up to 10 matching results from the current floor.
- Click a result to centre the map on that person's marker and open their details panel.
Map Controls
The following controls are available on the map canvas:
- Zoom in / Zoom out buttons — located at the bottom-left of the map.
- Reset view — fits the entire floor plan back into the visible area with a smooth animation.
- Full screen — expands the map to fill the browser window. Press Escape or click the button again to exit.
- Scale line — shows a distance scale bar in the lower portion of the map when the floor's physical dimensions (width and depth in metres) are configured.
- Overview map — a collapsed miniature of the floor plan shown in the corner. Click the arrow to expand it.
Measuring Distance and Area
The measure tool lets you draw on the map to calculate distances and areas. This is useful for estimating coverage gaps between gateways or the size of a zone.
Measure a distance
- Click the Measure button in the toolbar.
- Select Distance.
- Click on the map to place the start point. Click again to place intermediate points. Double-click to finish the line.
- The measured distance is shown in the results area. If the floor dimensions are configured in metres, the result is shown in metres. Otherwise it is shown in pixels.
Measure an area
Click the Measure button in the toolbar.
Select Area.
Click on the map to place each corner of the polygon. Double-click to close the shape.
The enclosed area is shown in the results area (square metres if floor dimensions are available, square pixels otherwise).
Click Clear to remove the measurement drawing from the map.
Note: Measurements are visual only and are not saved. They are cleared when you navigate away or change floors.
Heatmap Visualization
The heatmap layer shows a colour-coded density overlay based on signal strength from all detected BLE devices. Areas with more devices and stronger signals appear warmer (red/orange) while sparse or weak-signal areas appear cooler (blue/green).
To enable the heatmap:
- In the layer panel, turn on the Heatmap toggle.
The colour gradient runs from dark blue (weakest/lowest density) through green and yellow to red/orange (strongest/highest density). The heatmap uses the same data that drives marker positions, so it updates in real time.
Tip: The heatmap is most useful for identifying coverage gaps. A floor area that shows consistently cool colours may indicate that no gateway is within range of that area.
The heatmap layer renders below zone polygons and above the floor plan image (z-index 8 in the rendering stack).
RSSI Signal Lines
RSSI signal lines draw a coloured line between each tracked device and its nearest gateway. The line colour and thickness indicate signal strength:
| Signal strength | RSSI value | Line colour | Thickness |
|---|---|---|---|
| Strong | -50 dBm or above | Green | 3 px solid |
| Medium | -51 to -70 dBm | Amber | 2 px solid |
| Weak | Below -70 dBm | Grey | 1 px dashed |
To show RSSI lines:
- In the layer panel, turn on the RSSI lines toggle.
Lines are drawn below zone polygons and markers in the rendering stack. You can hover over a line to see a tooltip with the device name and exact RSSI value in dBm.
Note: RSSI lines are only drawn for devices that have a known nearest gateway with a placed position on the current floor. If a gateway has not been placed on the floor plan, no line can be drawn to it.
Accuracy Circles
Accuracy circles are dashed rings drawn around each personnel marker to indicate the estimated position accuracy from the trilateration or weighted centroid calculation.
- A teal dashed ring indicates the position was calculated using trilateration.
- An amber dashed ring indicates a weighted centroid calculation.
- A red/pink dashed ring indicates a position calculated by another or unknown method.
The radius of each circle corresponds to the estimated accuracy in metres. Smaller circles mean higher confidence in the position.
To show accuracy circles:
- In the layer panel, turn on the Accuracy circles toggle.
Note: Circles only appear for personnel that have a reported position accuracy value. Personnel located by simple nearest-gateway lookup (no trilateration) will not show a circle.
Zones
Zone polygons mark named areas on the floor such as conference rooms, muster points, restricted areas, or building boundaries.
- Boundary zones are displayed with a dashed stroke and low fill opacity, indicating the outer perimeter of the building or a section.
- Other zone types are filled with their assigned colour at a configurable opacity.
Clicking on a zone polygon on the map opens a popup showing the zone name and type.
Zones are managed in the Admin section of the application. The floor plan displays whatever zones have been configured for the selected floor.
To toggle zone visibility, use the Zones toggle in the layer panel.
Marker Clustering
When multiple personnel are positioned very close together on the map, their markers are automatically combined into a cluster marker to prevent overlap and improve readability.
Cluster markers are displayed as a filled circle with the count of personnel it represents:
| Count range | Circle size | Circle colour |
|---|---|---|
| 1 (single person) | 16 px radius | NISC red (#9C1B30) — shows initials |
| 2 – 9 | 18 px radius | NISC red (#9C1B30) |
| 10 – 49 | 21 px radius | NISC red (#9C1B30) |
| 50 and above | 24 px radius | Dark red (#7A1526) |
Zooming in on the map will break large clusters into smaller groups and eventually into individual personnel markers as the positions spread out. The clustering distance threshold is 50 pixels at the current zoom level.
Tip: If personnel markers are not visible even after zooming in, check whether the Personnel layer toggle is on and whether a department filter is active.
Personnel Staleness and Fading
Personnel markers fade out progressively as their last-seen time increases to indicate how recent the position data is:
| Time since last update | Marker opacity | Status label |
|---|---|---|
| 0 – 5 minutes | Full (1.0) | Active |
| 5 – 15 minutes | Faded (0.5) | Last Seen |
| 15 – 30 minutes | Ghost (0.25) | Stale |
| 30 – 60 minutes | Hidden from map | — |
| Over 60 minutes | Removed from map entirely | — |
The system checks for stale markers every 30 seconds. Personnel who have not been seen for more than an hour are removed from the floor plan display but remain in the system database.
Clicking a Marker for Details
Clicking on any marker opens a details panel or modal with additional information.
Personnel details
Clicking a personnel marker (or a cluster to expand it, then clicking an individual) opens a panel showing:
- Full name and department
- Current presence status (Active / Last Seen / Stale)
- Time elapsed since last seen
- Assigned beacon MAC address
- Battery level (if reported)
- Current zone (if inside a named zone)
- Position method (trilateration, weighted centroid, or nearest gateway)
Gateway details
Clicking a gateway marker opens a panel showing:
- Gateway name and hardware identifier
- Online / offline status
- Last seen timestamp
- Number of devices currently detected
Ambient device details
Clicking an ambient device marker opens a panel showing:
- Device ID and manufacturer
- Device type classification
- Current RSSI (signal strength in dBm)
- Nearest gateway name
- Battery level (if reported)
Edit Mode — Gateway Placement (Administrators)
Administrators can position gateways on the floor plan to tell the system where each piece of BLE receiver hardware is physically located. Accurate gateway positions are required for trilateration and RSSI line rendering to work correctly.
Important: Edit mode changes are not applied until you click Save. Navigating away or changing floors without saving will discard all pending position changes.
Enter edit mode
- Click the Edit Gateways button in the toolbar. This button is only visible to users with administrator permissions.
- The map enters edit mode. Gateway markers change to a grab cursor to indicate they are draggable.
- Gateways that have not yet been placed appear in an unpositioned gateways panel on the side.
Place or move a gateway
- In edit mode, click and drag a gateway marker to its correct physical location on the floor plan image.
- Release the mouse button to drop the gateway at the new position.
- Dragging a gateway does not open the details modal — the click event is suppressed after a drag completes.
Place an unpositioned gateway
- If a gateway does not yet have coordinates, it appears in the unpositioned list rather than on the map.
- Click the gateway in the list to activate placement mode, then click the desired location on the map to place it.
Save gateway positions
- When you have finished positioning all gateways, click Save in the toolbar.
- The positions are saved to the database. A success or error notification will appear.
- The map exits edit mode and returns to normal view.
Exit without saving
- Click Cancel to exit edit mode and discard all pending changes.
- Gateway markers return to their last saved positions.
Historical Playback
The floor plan includes a historical playback mode that lets you scrub back through recorded position data.
- Click the Playback button in the toolbar to open the playback controls.
- Set the start and end time for the playback window using the date/time pickers.
- Use the slider to move to a specific point in time, or click Play to animate positions forward automatically.
- Click Stop to pause playback.
- Click Close or navigate away to exit playback mode and return to live data.
Note: While in historical playback mode, live real-time updates are suppressed. The map will not reflect new BLE events until you exit playback.
Mobile View
The floor plan page is accessible on mobile browsers and tablets. The layout adapts for smaller screens:
- The layer panel collapses into a slide-out drawer accessible from a button in the toolbar.
- Marker sizes are automatically reduced on mobile to prevent overlap on smaller displays.
- Touch gestures (pinch to zoom, swipe to pan) are fully supported.
- The personnel table below the map uses horizontal scrolling on small screens.
The mobile BLE scanner feature (virtual gateway) is available on supported mobile devices. This allows a mobile phone or tablet to act as a temporary BLE receiver and report detected devices to the system.
- Tap Mobile Scanner in the toolbar (mobile only).
- Enable scanning to start detecting nearby BLE devices.
- Tap the floor plan to drop a pin marking your current physical location. The system uses this as the gateway position for the devices your phone detects.
Troubleshooting
No markers appear after selecting a floor
- Verify that gateways have been placed on the floor plan using edit mode. Without positioned gateways the system cannot calculate device locations.
- Check that personnel are assigned BLE beacons in the Personnel admin page.
- Confirm the BLE gateways on that floor are online by looking for green gateway markers. Red or missing gateways indicate connectivity problems with the hardware.
Personnel markers are not moving
- The real-time connection status indicator in the toolbar shows whether the WebSocket is connected. If it shows offline, positions are only updated via the 10-second polling fallback.
- Verify that the BLE gateways on the floor are actively reporting to the Azure IoT pipeline.
Positions seem inaccurate
- Accuracy improves when three or more gateways can detect the same BLE beacon simultaneously. Floors with only one or two gateways will use nearest-gateway placement rather than trilateration.
- Ensure gateway positions on the floor plan match their real physical locations. Even small errors in placement degrade position accuracy.
- Enable Accuracy circles to visualise the confidence radius for each personnel position.
The heatmap or RSSI lines are not visible
- Confirm the corresponding toggles are turned on in the layer panel.
- RSSI lines require at least one online gateway with a valid placed position on the current floor.
- The heatmap requires at least one ambient or personnel device to be detected on the floor.
A zone does not appear on the map
- Zones must be created and assigned to the correct floor in the Admin > Zones section.
- Check that the Zones toggle is enabled in the layer panel.
- Zones with fewer than three coordinate points will not render (a polygon requires at least three vertices).