> ## Documentation Index
> Fetch the complete documentation index at: https://docs.owlintegrations.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Map View

> Track and visualize your Duck mesh network devices with GPS location data and real-time updates

The Map View provides a geographic visualization of your Duck mesh network, showing device locations, message activity, and real-time GPS tracking.

## Getting Started

<Steps>
  <Step title="Select a Papa Duck">
    Choose a Papa Duck from the selection panel to view its network on the map
  </Step>

  <Step title="Optional: Adjust Time Range">
    Select a time range filter (5 min, 1 hour, 24 hours, 1 week, 2 weeks, 1 month) to control which messages appear
  </Step>

  <Step title="View Markers">
    Device markers appear on the map showing the latest GPS location for each device
  </Step>
</Steps>

<Warning>
  You must select a Papa Duck before any data or markers will appear on the map.
</Warning>

## Papa Duck Selection Panel

The left panel displays all your Papa Duck gateways as cards:

### Card Information

Each Papa Duck card shows:

* **Device Name**: Papa Duck identifier
* **Mama Count**: Number of connected Mama Ducks
* **Last Message**: Time since the last message was received
* **Message Count**: Total messages in the selected time window

<Tip>
  Papa Ducks are sorted by most recent activity, so active networks appear at the top.
</Tip>

## Map Controls

### Map Style Options

Switch between different map visualizations using the toolbar at the bottom of the map:

<CardGroup cols={3}>
  <Card title="Satellite" icon="satellite">
    Aerial imagery view
  </Card>

  <Card title="Terrain" icon="mountain">
    Topographic map highlighting elevation and landscape features
  </Card>

  <Card title="Monochrome" icon="circle-half-stroke">
    Greyscale map that makes device markers easier to spot
  </Card>
</CardGroup>

### Measure Tool

Use **Measure** (in the map toolbar) to calculate distances directly on the map:

* Click to place your first point, then click again to place additional points along a path
* The total distance updates as you add each point
* Click your last point to finish, or press `Escape` to cancel

This is useful for estimating coverage area or the distance between two devices in the field.

### Navigation Controls

* **Zoom**: Use the +/- buttons or scroll wheel
* **Geolocation**: Click the location icon to center on your current position
* **Rotation**: Right-click and drag to rotate the map
* **Pan**: Click and drag to move around

## Device Markers

### Marker Display

<Accordion title="Marker Behavior">
  * One marker per device showing the **latest GPS location**
  * Markers update in real-time as new GPS messages arrive
  * Device name appears above each marker
  * Markers cluster together when zoomed out for better visibility
</Accordion>

### Clicking on Markers

Click any device marker to open a popout with detailed information:

<Steps>
  <Step title="Device Info">
    View device name, unique ID, and parent Papa Duck
  </Step>

  <Step title="Online Status">
    See if the device is currently online (based on messages in the last 5 minutes)
  </Step>

  <Step title="Battery Status">
    View battery percentage, voltage, charging status, and temperature (if available within last 2 hours)
  </Step>

  <Step title="Last Seen">
    Timestamp of the most recent message from the device
  </Step>

  <Step title="Message History">
    Scroll through recent messages with event types, payloads, and timestamps
  </Step>

  <Step title="Actions">
    Click "View Device" to navigate to the full device detail page
  </Step>
</Steps>

<Info>
  The device popout stays anchored to the marker even when you pan or zoom the map.
</Info>

## Message Feed

The right panel displays real-time message activity for the selected Papa Duck:

### Event Types

Messages are color-coded by event type:

| Event Type  | Icon | Description                                     |
| ----------- | ---- | ----------------------------------------------- |
| **GPS**     | 📍   | Location updates with coordinates               |
| **Health**  | ❤️   | Battery, temperature, and device health metrics |
| **Status**  | ℹ️   | General device status messages                  |
| **Sensor**  | 🌡️  | Environmental sensor readings                   |
| **Unknown** | ❓    | Other event types                               |

### Feed Interaction

<Steps>
  <Step title="Click Messages">
    Click any message in the feed to open the device popout
  </Step>

  <Step title="GPS Navigation">
    Clicking messages with GPS data will center the map on that device's location
  </Step>

  <Step title="Live Updates">
    New messages appear at the top with a highlight animation
  </Step>
</Steps>

<Warning>
  If a device doesn't have GPS coordinates, clicking its message will show a notification instead of opening the popout.
</Warning>

## GPS Location Tracking

### How GPS Works

<Accordion title="Location Data Sources">
  * **GPS Events**: Standard GPS messages with lat/lng coordinates
  * **JSON Payloads**: Messages with embedded location data
  * **Space-Separated Format**: Legacy format with `LAT:` and `LNG:` properties
</Accordion>

### Location Updates

* The system automatically processes GPS data from all supported formats
* Only the **latest location** for each device is displayed
* Older GPS coordinates are replaced when new ones arrive
* Locations update in real-time via WebSocket connection

## Time Range Filtering

Adjust the time range to control which messages and GPS data appear:

| Time Range   | Use Case                                  |
| ------------ | ----------------------------------------- |
| **5 min**    | Active debugging and real-time monitoring |
| **1 hour**   | Recent activity tracking                  |
| **24 hours** | Daily operations overview                 |
| **1 week**   | Weekly pattern analysis                   |
| **2 weeks**  | Medium-term trends                        |
| **1 month**  | Long-term historical view                 |

<Info>
  Changing the time range updates both the message feed and the GPS markers on the map.
</Info>

## Tips

<Tip>
  **Performance**: Start with a shorter time range (5 min or 1 hour) when monitoring active networks to reduce data load.
</Tip>

<Tip>
  **Popout controls**: Press `Escape` or click outside the device popout to close it.
</Tip>

<Tip>
  **Reset filters**: Click the "Reset to Default" button to clear all filters and return to the default view.
</Tip>

<Tip>
  **Connection status**: Check the connection indicator in the corner to verify your WebSocket connection is active for live updates.
</Tip>