# API
Source: https://docs.owlintegrations.com/api-reference/introduction

Access your OWL Mesh Network data programmatically

## Overview

The **OWL DMS API** provides a clean, reliable interface for accessing data from the OWL Mesh Network. Instead of dealing with the complexity of distributed data sources, you can use a single, consistent API to query and retrieve the information you need.

This makes it easy to plug mesh-network data into your dashboards, analytics pipelines, or internal tools without needing to understand the underlying network architecture.

## Create API Key

Follow these steps to create your API key:

1. Log into your OWL DMS
2. Navigate to `Settings` > `API Keys`
3. Click on `New API Key`
4. Fill in the details and click on `Create Key`
5. OWL DMS will generate an API Key for you. **Save the key for your application**

<Warning>
  Keep your API keys secure and never share them publicly. Treat them like passwords. Once created, you won't be able to view the full key again.
</Warning>

## Use API Key

Once you have your API key from the steps above, you can integrate it into your application. Here are some ways to use the API key to get access to your OWL Mesh data.

### Python Example

```python theme={null}
import requests

url = "https://{YOUR OWN OWL INSTANCE}.owldms.com/public_api/Data"

headers = {
   "accept": "application/json",
   "X-API-Key": "YOUR API KEY HERE"
}

params = {
   "startDate": YOUR_START_DATE_HERE,  # Unix timestamp (type:int)
   # "endDate" : YOUR_END_DATE_HERE    # Unix timestamp (type:int) (OPTIONAL)
}

response = requests.get(url, headers=headers, params=params)
data = response.json()
print(data)
```

### JavaScript Example

```javascript theme={null}
const url = "https://{YOUR OWN OWL INSTANCE}.owldms.com/public_api/Data";

const headers = {
  "accept": "application/json",
  "X-API-Key": "YOUR API KEY HERE"
};

const params = new URLSearchParams({
  startDate: YOUR_START_DATE_HERE, // Unix timestamp (type:int)
  // endDate: YOUR_END_DATE_HERE   // Unix timestamp (type:int) (OPTIONAL)
});

async function getData() {
  try {
    const response = await fetch(`${url}?${params.toString()}`, {
      method: "GET",
      headers: headers
    });

    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    const data = await response.json();
    console.log(data);
  } catch (err) {
    console.error("API call failed:", err);
  }
}

getData();
```

## API Parameters

| Parameter   | Type    | Required | Description                                                                                   |
| ----------- | ------- | -------- | --------------------------------------------------------------------------------------------- |
| `startDate` | integer | Yes      | Unix timestamp for the start of the data range                                                |
| `endDate`   | integer | No       | Unix timestamp for the end of the data range. If omitted, returns data up to the current time |

<Note>
  Use Unix timestamps (seconds since January 1, 1970) for the date parameters. You can convert dates to Unix timestamps using online converters or programming language utilities.
</Note>

## Data Format

Every request returns a JSON payload, where each entry is itself a JSON object representing an individual message from the mesh. No protocol wrangling. No decoding headaches. Just structured data delivered in a predictable format.

Here is an example of how the retrieved data will look:

```json theme={null}
{
  {
    "deviceId": "PAPADUCK",
    "timestamp": "2025-11-30T17:08:54.137Z",
    "eventType": "health",
    "payload": {
      "hops": 1,
      "Payload": {
        "voltage": 3.65,
        "percentage": 17,
        "charging": true,
        "temp": 57.0
      },
      "DeviceID": "DUCK0001",
      "duckType": 2,
      "MessageID": "SB6W"
    }
  },
  {
    "deviceId": "PAPADUCK",
    "timestamp": "2025-11-30T17:08:54.137Z",
    "eventType": "health",
    "payload": {
      "hops": 1,
      "Payload": {
        "voltage": 3.65,
        "percentage": 17,
        "charging": true,
        "temp": 57.0
      },
      "DeviceID": "DUCK1234",
      "duckType": 2,
      "MessageID": "SB6W"
    }
  }
}
```

### Response Fields

| Field               | Type    | Description                                                                                  |
| ------------------- | ------- | -------------------------------------------------------------------------------------------- |
| `deviceId`          | string  | Identifier of the device that reported this message                                          |
| `timestamp`         | string  | ISO 8601 timestamp when the message was received                                             |
| `eventType`         | string  | Type of event (e.g., "health", "sensor", "alert")                                            |
| `payload.hops`      | integer | Number of hops this message traveled through the mesh                                        |
| `payload.Payload`   | object  | Device-specific data including voltage, battery percentage, charging status, and temperature |
| `payload.DeviceID`  | string  | Unique identifier of the originating device                                                  |
| `payload.duckType`  | integer | Type of device (e.g., 2 for standard duck)                                                   |
| `payload.MessageID` | string  | Unique message identifier                                                                    |

## Complete Example

Here's a complete working example that fetches data from the last 24 hours:

<CodeGroup>
  ```python Python theme={null}
  import requests
  from datetime import datetime, timedelta

  # Configuration
  OWL_INSTANCE = "yourcompany"  # Replace with your instance name
  API_KEY = "your_api_key_here"  # Replace with your API key

  # Calculate Unix timestamp for 24 hours ago
  start_time = int((datetime.now() - timedelta(days=1)).timestamp())

  # API endpoint
  url = f"https://{OWL_INSTANCE}.owldms.com/public_api/Data"

  # Headers
  headers = {
      "accept": "application/json",
      "X-API-Key": API_KEY
  }

  # Parameters
  params = {
      "startDate": start_time
  }

  # Make the request
  response = requests.get(url, headers=headers, params=params)

  # Check if request was successful
  if response.status_code == 200:
      data = response.json()
      print(f"Retrieved {len(data)} messages")
      for message in data:
          print(f"Device: {message['deviceId']}, Time: {message['timestamp']}")
  else:
      print(f"Error: {response.status_code}")
  ```

  ```javascript JavaScript theme={null}
  // Configuration
  const OWL_INSTANCE = "yourcompany"; // Replace with your instance name
  const API_KEY = "your_api_key_here"; // Replace with your API key

  // Calculate Unix timestamp for 24 hours ago
  const startTime = Math.floor((Date.now() - 24 * 60 * 60 * 1000) / 1000);

  // API endpoint
  const url = `https://${OWL_INSTANCE}.owldms.com/public_api/Data`;

  // Headers
  const headers = {
    "accept": "application/json",
    "X-API-Key": API_KEY
  };

  // Parameters
  const params = new URLSearchParams({
    startDate: startTime.toString()
  });

  // Fetch data
  async function fetchMeshData() {
    try {
      const response = await fetch(`${url}?${params.toString()}`, {
        method: "GET",
        headers: headers
      });

      if (!response.ok) {
        throw new Error(`HTTP error! Status: ${response.status}`);
      }

      const data = await response.json();
      console.log(`Retrieved ${data.length} messages`);
      
      data.forEach(message => {
        console.log(`Device: ${message.deviceId}, Time: ${message.timestamp}`);
      });
    } catch (err) {
      console.error("API call failed:", err);
    }
  }

  fetchMeshData();
  ```
</CodeGroup>

## Support

Need help with the API?

<CardGroup>
  <Card title="OWL IoT Discord Community" icon="discord" href="https://discord.gg/9HPQBwhd2E">
    Get help from other developers
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@owlintegrations.com">
    Get direct support via email
  </Card>
</CardGroup>


# June 2026
Source: https://docs.owlintegrations.com/changelog/2026-06

New terminal, redesigned Devices page, live WebSocket updates, and visual refresh

## What's New in June 2026

This release brings significant improvements to OWL DMS — including real-time live data streaming, a brand-new device terminal, a redesigned Devices page, and a refreshed visual experience across the platform.

***

## Live Data Streaming via WebSocket

<Note>
  This is the most impactful change in this release — your dashboard and device data now update in real time without any manual refresh.
</Note>

OWL DMS now uses **WebSocket connections** to stream data from your mesh network directly to the platform as it arrives. Previously, you needed to refresh the page to see updated sensor readings, message counts, or device status. That's no longer the case.

**What this means for you:**

* Device status changes (online/offline) appear on screen the moment they happen
* Incoming messages and sensor readings populate your dashboard feed in real time
* Network alerts and anomalies surface immediately — no polling, no delays
* Map view device positions update live as GPS data arrives

This is especially useful when monitoring active deployments or responding to field events.

***

## Device Terminal

You can now open a **live terminal** for any connected device directly from OWL DMS.

From the Devices page, select a device and open the **Terminal** tab to:

* Send commands to your device and see the output in real time
* View the device's serial log as it streams in
* Debug connectivity or sensor issues without needing physical access or a separate serial monitor

The terminal session uses the same live WebSocket connection, so output appears instantly as the device responds.

***

## Redesigned Devices Page

The Devices page has been rebuilt with a cleaner layout that makes it easier to find and manage devices in larger networks.

**Improvements include:**

* Clearer device cards showing key info at a glance (type, status, last seen)
* Faster filtering and search across device name, type, and network
* Improved navigation between device detail views
* Better handling of offline and disconnected devices

***

## Updated Styling & Icons

We've rolled out a visual refresh across the platform — updated icons, tighter spacing, and consistent styling throughout every view. The changes are subtle but cumulative: the interface should feel more polished and easier to scan.

***

## How to Access These Features

All changes are live in your OWL DMS account — no action needed on your part. If you have any questions or run into issues, reach out on [Discord](https://discord.gg/9HPQBwhd2E).


# July 2026
Source: https://docs.owlintegrations.com/changelog/2026-07

Archive and restore devices, expanded filters, and a refreshed look

## Device Archiving

You can now archive Gateways and Nodes you no longer need to see day-to-day — like test or decommissioned devices — without deleting them.

* The Network page now has **Active** and **Archived** tabs
* Archive a Gateway or Node from its overflow menu; archiving a Gateway archives its connected Nodes too
* Restore any archived device at any time — nothing is ever deleted, and message history is preserved
* Archived devices are hidden from the home page, the Map's Gateway selector, and the Add Device / firmware flash wizard

See [Network Management](/guides/network-management#archiving-devices) for the full walkthrough.

## More Filtering & Topic Options

Added more ways to narrow down what you're looking at across the platform, including additional topic-based filtering.

## Updated Components & Styling

Refreshed the look of components across the platform for a more consistent, polished experience.


# July 8, 2026
Source: https://docs.owlintegrations.com/changelog/2026-07-08

Send commands to your gateways right from OWL DMS

## Gateway Commands

You can now send commands to a Papa Duck gateway directly from its detail page — no reflashing required.

* Open a gateway and use the new **Commands** section to trigger an action
* **Ping** a gateway to check it's reachable right now
* Set the **sleep thresholds** — the battery voltage window the gateway sleeps and wakes within — with a live estimated battery percentage as you type
* Set the gateway's **radio transmit power** to balance range and battery life
* Track everything in **Recent activity**, which shows each command's status as it moves from dispatched to complete

See [Commands](/guides/commands) for the full walkthrough.

## Message Activity by Topic

A Node's detail page now includes a chart showing the history of how many messages it has sent per topic, so you can see what a device is reporting and how its activity changes over time at a glance.


# Overview
Source: https://docs.owlintegrations.com/changelog/index

All OWL DMS platform updates and release notes

This page tracks all notable updates to OWL DMS. We publish release notes here whenever we ship new features, significant improvements, or changes that affect how you use the platform.

Backend infrastructure changes and internal fixes are generally not listed unless they affect something you can see or do.

## Releases

<CardGroup>
  <Card title="July 8, 2026" icon="terminal" href="/changelog/2026-07-08">
    Send commands to your gateways right from OWL DMS, plus per-topic message activity charts.
  </Card>

  <Card title="July 2026" icon="sparkles" href="/changelog/2026-07">
    Archive and restore devices, expanded filters, and a refreshed look.
  </Card>

  <Card title="June 2026" icon="sparkles" href="/changelog/2026-06">
    Live WebSocket streaming, device terminal, redesigned Devices page, and updated icons and styling.
  </Card>
</CardGroup>


# Commands
Source: https://docs.owlintegrations.com/guides/commands

Send commands to a Papa Duck gateway and track their status

Commands let you trigger an action on a Papa Duck gateway directly from OWL DMS — no reflashing required. Use them to check that a gateway is reachable, adjust its battery sleep window, or change its radio transmit power.

Commands are sent from the gateway's detail page and reach every gateway in range of that Papa Duck.

## Sending a Command

<Steps>
  <Step title="Open the gateway">
    Go to a Papa Duck's detail page and find the **Commands** section.
  </Step>

  <Step title="Choose a command">
    Pick a command from the dropdown. A short description explains what it does.
  </Step>

  <Step title="Enter values">
    If the command needs parameters, fill them in. OWL DMS checks your values as you type and flags anything out of range.
  </Step>

  <Step title="Send and confirm">
    Click **Send command**, then confirm in the dialog. Your command is on its way.
  </Step>
</Steps>

## Available Commands

<CardGroup>
  <Card title="Ping" icon="satellite-dish">
    Checks that the gateway is reachable right now. No parameters needed.
  </Card>

  <Card title="Sleep thresholds" icon="battery-half">
    Sets the battery voltage window the gateway sleeps and wakes within. Enter a **minimum** and **maximum** voltage between 2.5V and 4.5V — the minimum must be lower than the maximum. As you type, an estimated battery percentage is shown to help you pick sensible values.
  </Card>

  <Card title="Set radios" icon="tower-broadcast">
    Sets the gateway's radio transmit power. Enter a whole number between 14 and 22 — higher values increase range but use more power.
  </Card>
</CardGroup>

## Tracking Command Status

The **Recent activity** list under the Commands section shows the commands you've sent to this gateway, newest first. Each entry shows the command name, a status badge, and when it was last updated.

| Status         | Meaning                                                |
| -------------- | ------------------------------------------------------ |
| **Dispatched** | The command has been sent and is on its way.           |
| **Accepted**   | The gateway received the command.                      |
| **Complete**   | The command finished successfully.                     |
| **Rejected**   | The gateway received the command but could not run it. |
| **Failed**     | The command could not be delivered.                    |
| **Timed out**  | No response was received in time.                      |
| **Cancelled**  | The command was cancelled before it completed.         |

Use the refresh button to update the list. If a command fails, its error message appears beneath the entry.

<Note>
  If the command history can't be reached, your commands still go through — only their status won't show up in the activity list.
</Note>

## Troubleshooting

* **The Commands section says the gateway can't receive commands.** The gateway is missing its network target and isn't ready for commands yet. Confirm the device is set up and reporting in.
* **My values won't send.** Check the on-screen hints — voltages must be between 2.5V and 4.5V (minimum lower than maximum), and radio transmit power must be a whole number between 14 and 22.


# Dashboard Overview
Source: https://docs.owlintegrations.com/guides/dashboard

Monitor your Duck mesh network with real-time message feeds, analytics, and device status

The Dashboard is your central hub for monitoring the OWL DMS network. It provides real-time visibility into message traffic, device activity, and network health.

## Summary Cards

At the top of the dashboard, three cards display key metrics:

<CardGroup>
  <Card title="Papa Ducks" icon="tower-broadcast">
    Shows the number of Papa Duck gateways connected to your account
  </Card>

  <Card title="Mama Ducks" icon="satellite-dish">
    Displays the total count of Mama Duck devices across all Papa Ducks
  </Card>

  <Card title="Messages (24h)" icon="message">
    Shows the message count received in the last 24 hours, updates every minute
  </Card>
</CardGroup>

## Message Chart

The interactive chart visualizes message traffic over the last 14 days:

<Steps>
  <Step title="Toggle Chart Type">
    Click the chart icon to switch between bar and line charts
  </Step>

  <Step title="View Options">
    Toggle between total messages and per-device breakdown using the grid icon
  </Step>

  <Step title="Interactive Tooltips">
    Hover over any data point to see:

    * Date and day of week
    * Total message count
    * Breakdown by device (with color-coded indicators)
  </Step>
</Steps>

<Info>
  The chart always displays the last 14 days of data, independent of the message table filters.
</Info>

## Recent Messages Table

The table shows your most recent messages with powerful filtering options:

### Time Window Selection

Filter messages by selecting a time range:

* Last 30 minutes
* Last hour
* Today
* Yesterday
* Last 7 days (default)
* Last 30 days
* Month to date
* Last month

<Warning>
  The table displays a maximum of 1,000 messages to ensure optimal performance.
</Warning>

### Table Features

| Feature        | Description                                              |
| -------------- | -------------------------------------------------------- |
| **Papa Name**  | Click to view Papa Duck details                          |
| **Mama Name**  | Color-coded by device with clickable link to device page |
| **Topic**      | Event type (GPS, Health, Status, Sensor, etc.)           |
| **Date**       | Message timestamp in `YYYY-MM-DD HH:mm:ss` format        |
| **Message ID** | Unique identifier for each message                       |
| **Payload**    | Message content (hover for full text)                    |
| **Hops**       | Number of mesh network hops                              |
| **Actions**    | Eye icon to view Mama Duck details                       |

### Sorting and Filtering

<Steps>
  <Step title="Sort Columns">
    Click column headers to sort. Hold Shift to sort by multiple columns.
  </Step>

  <Step title="Filter Data">
    Use the filter icon in column headers to filter by:

    * Mama Name (text search)
    * Topic (text search)
    * Date (date picker)
  </Step>

  <Step title="Reset View">
    Click the refresh icon to clear all sorting and filters
  </Step>
</Steps>

## Real-Time Updates

The dashboard automatically updates with live data:

<Accordion title="WebSocket Connection">
  Messages are streamed in real-time via WebSocket. New messages appear with a highlight animation and automatically scroll into view. The connection status is monitored and will reconnect automatically if interrupted.
</Accordion>

<Accordion title="Automatic Refresh">
  * **Message count**: Updates every 30 seconds
  * **Message table**: Refreshes every 60 seconds
  * **Chart data**: Updates every 5 minutes
</Accordion>

## Tips

<Tip>
  **New message indicator**: Newly arrived messages appear with a green highlight animation that fades after 3 seconds.
</Tip>

<Tip>
  **Quick device access**: Click on device names in the table to navigate directly to their detail pages.
</Tip>

<Tip>
  **Performance**: If you have a large number of messages, use the time window filter to narrow the data range for faster loading.
</Tip>


# Data Export
Source: https://docs.owlintegrations.com/guides/data-export

Export message data from your Duck mesh network for analysis, reporting, and archival

The Data Export page allows you to filter and download historical message data from your Duck mesh network in CSV format for external analysis or archival purposes.

## Overview

Use the Data Export tool to:

* Extract specific time ranges of message data
* Filter by Papa Duck gateways, Mama Duck nodes, and message types
* Preview and refine data before downloading
* Export to CSV format for use in spreadsheets or analysis tools

## Setting Up Your Export

<Steps>
  <Step title="Select Date Range">
    Choose the start and end dates (and times) for your data export
  </Step>

  <Step title="Filter by Papa Ducks (Optional)">
    Select specific Papa Duck gateways, or leave empty to include all devices
  </Step>

  <Step title="Click Search">
    Click the **Search** button to load the matching data
  </Step>

  <Step title="Refine Results (Optional)">
    Use the Mama Duck and Message Type filters to narrow down the results
  </Step>

  <Step title="Review Preview">
    Check the data table to ensure you're exporting the correct information
  </Step>

  <Step title="Export to CSV">
    Click the **Export CSV** button to download the data
  </Step>
</Steps>

## Filter Options

### Date Range Selection

<Accordion title="Start Date & Time">
  Select the beginning date and time for your export range. Use the 24-hour time picker to set a precise start time.
</Accordion>

<Accordion title="End Date & Time">
  Select the ending date and time for your export range. Use the 24-hour time picker to set a precise end time.
</Accordion>

<Warning>
  **Date range limit**: Exports are limited to a maximum of 90 days. If you need data for a longer period, create multiple exports with consecutive date ranges.
</Warning>

### Papa Duck Filter

The multi-select dropdown allows you to choose which Papa Duck gateways to include:

* **All Papa Ducks** (default): Leave the selection empty to include all devices
* **Specific Papa Ducks**: Select one or more Papa Ducks to filter messages from only those gateways

<Info>
  Filtering by Papa Duck includes all messages from both the Papa Duck itself and its connected Mama Duck devices.
</Info>

### Refine Filters

After running a search, two additional filters appear to help you narrow down the results. These filters are populated dynamically based on what was found in your search — only devices and message types actually present in the results will be shown.

<Accordion title="Mama Duck Filter">
  Select one or more Mama Duck nodes to show only messages from those specific devices. Leave empty to include all nodes in the results.
</Accordion>

<Accordion title="Message Type Filter">
  Select one or more message types to show only those events. Available types include GPS, Health, Status, Sensor, BMP (covers BMP180, BMP280, and BMP390), and DHT — only types present in your results will appear.
</Accordion>

The record count at the top of the results updates as you apply refine filters, showing how many messages match your current selection versus the total returned (e.g., **42 / 200 messages**).

<Tip>
  Use **Reset** to clear all filters and start a new search.
</Tip>

## Data Preview Table

After clicking Search, the table displays a preview of your filtered data:

### Table Columns

| Column         | Description                                         |
| -------------- | --------------------------------------------------- |
| **Gateway**    | Name of the Papa Duck gateway                       |
| **Node**       | Name of the message sender (Papa or Mama Duck)      |
| **Event Type** | Type of message (GPS, Health, Status, Sensor, etc.) |
| **Date**       | Message timestamp in `YYYY-MM-DD HH:mm:ss` format   |
| **Message ID** | Unique identifier for each message                  |
| **Payload**    | Message content or sensor data                      |
| **# of Hops**  | Number of mesh network hops the message traveled    |

## Exporting Data

Once you've reviewed the preview and confirmed it contains the data you need:

<Steps>
  <Step title="Verify Data">
    Check the preview table and record count to ensure the correct data is selected
  </Step>

  <Step title="Click Export CSV">
    Click the **Export CSV** button in the table header
  </Step>

  <Step title="Download File">
    Your browser will download a CSV file with a descriptive filename that reflects your applied filters, for example:

    `data-export_from-20260401_to-20260430_gateways-2_nodes-3_types-2.csv`
  </Step>

  <Step title="Open in Analysis Tool">
    Open the CSV file in Excel, Google Sheets, or your preferred data analysis tool
  </Step>
</Steps>

### Public API

<CardGroup>
  <Card title="Check out our API" icon="code" href="/api-reference/introduction">
    Explore the full public API — click here for documentation and integration guides.
  </Card>
</CardGroup>


# Device Types
Source: https://docs.owlintegrations.com/guides/device-types

Understanding PapaDuck, MamaDuck, and DetectorDuck devices

## PapaDuck (Gateway)

Gateway device that connects your mesh network to the internet via WiFi. Receives messages from MamaDucks and uploads data to OWL DMS in real-time.

**Requirements**: WiFi access and USB/wall power

***

## MamaDuck (Node)

Battery-powered sensor device that collects data and relays messages through the mesh network to a PapaDuck.

### Supported Sensors

Configure sensors during the [firmware flashing process](/guides/flash-device):

* **GPS**: Track location (5-60 minute intervals)
* **BMP180**: Temperature and pressure monitoring
* **BMP390**: High-precision temperature and pressure
* **DHT11**: Temperature and humidity monitoring
* **LED Control**: Visual indicators with configurable LED count

**Sensor intervals**: 30 seconds to 60 minutes (configurable per sensor)

***

## DetectorDuck

Testing tool that measures signal strength between devices. Use for optimizing device placement and identifying coverage gaps before deploying your network.

***

## How They Work Together

```
Internet → [PapaDuck] → [MamaDuck 1, 2, 3...] → Sensors
```

1. MamaDucks collect sensor data or relay messages
2. Data is sent to PapaDuck through the mesh network
3. PapaDuck uploads to cloud via WiFi
4. OWL DMS displays data in real-time

***

## Next Steps

<CardGroup>
  <Card title="Flash Firmware" icon="microchip" href="/guides/flash-device">
    Configure and flash devices
  </Card>

  <Card title="Network Management" icon="network-wired" href="/guides/network-management">
    Manage devices in OWL DMS
  </Card>
</CardGroup>


# FAQs
Source: https://docs.owlintegrations.com/guides/faqs

Frequently asked questions about OWL DMS

## General Questions

<AccordionGroup>
  <Accordion title="What is OWL DMS?">
    OWL DMS (Device Management System) is a web-based platform for managing Duck mesh networks. It provides real-time monitoring, web-based firmware flashing, GPS visualization, and data export capabilities for ClusterDuck Protocol devices.

    Key features:

    * Web-based firmware flashing via USB
    * Real-time message monitoring with WebSocket updates
    * Interactive map visualization with GPS tracking
    * CSV data export for analysis
    * Multi-user support with device assignments
  </Accordion>

  <Accordion title="What are Duck devices?">
    Duck devices are based on the ClusterDuck Protocol, our open-source LoRa mesh network library (made and maintained by OWL). There are three types:

    * **PapaDuck (Gateway)**: Connects to WiFi and sends data to the cloud
    * **MamaDuck (Node)**: Battery-powered sensor devices
    * **DetectorDuck**: Network testing and optimization tool
  </Accordion>

  <Accordion title="Do I need special software to use OWL DMS?">
    No! OWL DMS runs entirely in your web browser. You only need:

    * Google Chrome or Microsoft Edge (for firmware flashing)
    * A modern web browser for monitoring and management
    * No command-line tools or external software required
  </Accordion>
</AccordionGroup>

## Device Setup

<AccordionGroup>
  <Accordion title="How do I flash firmware to a device?">
    1. Navigate to the "Add Device" page
    2. Connect your device via USB
    3. Follow the 4-step wizard:
       * Connect Device
       * Select Device Type (Papa/Mama/Detector)
       * Configure Firmware (WiFi, sensors, intervals)
       * Review & Flash

    See the [Flash Firmware guide](/guides/flash-device) for detailed instructions.
  </Accordion>

  <Accordion title="What browsers support firmware flashing?">
    **Supported:**

    * Google Chrome (version 89+)
    * Microsoft Edge (version 89+)

    **Not Supported:**

    * Firefox
    * Safari

    The flashing feature requires Web Serial API, which is only available in Chrome and Edge.
  </Accordion>

  <Accordion title="How do I register a new device?">
    Devices are registered through the Network Management page:

    1. Go to **Network** page
    2. Click **Add Device**
    3. Enter device name (3-8 characters)
    4. Select device type (PAPA or MAMA)
    5. For MamaDucks, select parent PapaDuck
    6. Add description and location (optional)
    7. Click **Save**

    After registration, flash firmware to the device to configure it.
  </Accordion>

  <Accordion title="What sensors do MamaDucks support?">
    MamaDucks support multiple sensor types:

    * **GPS Location**: Track device coordinates
    * **BMP180**: Temperature and pressure
    * **BMP390**: High-precision temperature and pressure
    * **DHT11**: Temperature and humidity
    * **LED Control**: Visual indicators

    Choose one sensor type per device during firmware flashing.
  </Accordion>
</AccordionGroup>

## Using the Platform

<AccordionGroup>
  <Accordion title="How do I view device messages?">
    Messages appear in multiple places:

    * **Dashboard**: Recent messages table with real-time updates
    * **Map View**: Message feed for selected PapaDuck
    * **Device Detail Page**: Recent messages for specific Mama Duck (last 100)

    All tables support sorting, filtering, and time range selection.
  </Accordion>

  <Accordion title="How do I know if a device is online?">
    A device is considered **online** if it has sent a message within the last 5 minutes.

    Check status in:

    * Network Management page (online/offline badges)
    * Device detail pages
    * Map View device markers
  </Accordion>

  <Accordion title="How do I export data?">
    Use the Data Export page:

    1. Select date range (max 30 days)
    2. Optionally filter by PapaDuck
    3. Click **Search** to preview
    4. Click **Export CSV** to download

    See the [Data Export guide](/guides/data-export) for details.
  </Accordion>

  <Accordion title="Can I see device locations on a map?">
    Yes! The Map View page shows GPS locations for devices with GPS-enabled firmware.

    Requirements:

    * MamaDuck must have GPS firmware flashed
    * Device must have sent GPS coordinates within last 24 hours
    * GPS data appears as markers on the interactive map
  </Accordion>

  <Accordion title="How do I monitor battery status?">
    Battery information appears on MamaDuck device detail pages:

    * Battery percentage
    * Charging status
    * Voltage and temperature (if available)
    * Last updated timestamp

    **Note**: Battery data only appears if a health message was received within the last 2 hours.
  </Accordion>
</AccordionGroup>

## Network Management

<AccordionGroup>
  <Accordion title="What's the difference between PapaDuck and MamaDuck?">
    **PapaDuck (Gateway)**:

    * Connects to WiFi
    * Sends data to cloud
    * Manages multiple MamaDucks
    * Requires power (USB/wall adapter)
    * No sensors

    **MamaDuck (Node)**:

    * Battery powered
    * Collects sensor data
    * Must connect through a PapaDuck
    * Mobile/portable
    * Multiple sensor options
  </Accordion>

  <Accordion title="Can I change which PapaDuck a MamaDuck connects to?">
    Yes! Edit the MamaDuck device:

    1. Go to MamaDuck device detail page
    2. Edit the **Parent PapaDuck** dropdown
    3. Select a different PapaDuck
    4. Click **Save Changes**

    The change takes effect after the device reboots and reconnects.
  </Accordion>

  <Accordion title="How many MamaDucks can one PapaDuck support?">
    There's no hard limit in the platform, but practical limits depend on:

    * Message frequency from each MamaDuck
    * PapaDuck's WiFi connection quality
    * Network congestion

    For most deployments, 10-20 MamaDucks per PapaDuck works well.
  </Accordion>
</AccordionGroup>

## Firmware & Configuration

<AccordionGroup>
  <Accordion title="What is ClusterDuck Protocol (CDP)?">
    The ClusterDuck Protocol is our open-source LoRa mesh network library. Duck devices use CDP to communicate.

    Learn more at the [ClusterDuck Protocol website](https://clusterduckprotocol.org/).
  </Accordion>

  <Accordion title="Can I update firmware on an already-flashed device?">
    Yes! Simply reconnect the device via USB and flash it again through the Add Device page. The new firmware will overwrite the existing configuration.
  </Accordion>

  <Accordion title="What WiFi networks are supported for PapaDuck?">
    **Supported**:

    * 2.4 GHz WiFi networks
    * WPA/WPA2 secured networks
    * Open networks (no password)

    **Not Supported**:

    * 5 GHz WiFi networks
    * Enterprise WiFi (RADIUS authentication)
    * Captive portal networks (hotels, coffee shops)
  </Accordion>

  <Accordion title="How often should devices send data?">
    **GPS Interval**: 5-60 minutes

    * Lower = more frequent updates, higher battery drain
    * Recommended: 15-30 minutes for normal use

    **Sensor Interval**: 30 seconds to 60 minutes

    * Lower = more data points, higher battery drain
    * Recommended: 5 minutes for continuous monitoring
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="My device won't connect to WiFi (PapaDuck)">
    Check:

    * SSID is correct (case-sensitive)
    * Password is correct
    * Network is 2.4 GHz (not 5 GHz)
    * Device is within WiFi range
    * Network doesn't use captive portal

    **Solution**: Reflash the device with correct WiFi credentials.
  </Accordion>

  <Accordion title="Device shows as offline but is powered on">
    A device shows offline if no message received in 5 minutes.

    **For PapaDuck**:

    * Check WiFi connection
    * Check serial monitor for errors
    * Verify internet connectivity

    **For MamaDuck**:

    * Ensure PapaDuck is online
    * Check device is within range
    * Verify sensor configuration
    * Check battery level
  </Accordion>

  <Accordion title="I can't see GPS location on the map">
    GPS locations only appear if:

    * Device has GPS firmware flashed
    * GPS coordinates received within last 24 hours
    * Device has clear view of sky for GPS lock

    Check the device detail page to see if GPS messages are being received.
  </Accordion>

  <Accordion title="Firmware flashing fails">
    Common solutions:

    * Use high-quality USB cable (not charge-only cables)
    * Try different USB port
    * Ensure device has sufficient power
    * Close other programs using the serial port
    * Use Chrome or Edge browser
    * Try a different cable

    See [Flash Firmware Troubleshooting](/guides/flash-device#troubleshooting) for more help.
  </Accordion>

  <Accordion title="Battery drains too quickly">
    To extend battery life:

    * Increase GPS interval (30-60 minutes)
    * Increase sensor reading interval
    * Disable external LED
    * Reduce transmission frequency

    Reconfigure via firmware flashing with adjusted intervals.
  </Accordion>

  <Accordion title="Messages not appearing in dashboard">
    Check:

    * Device is showing as online
    * PapaDuck has WiFi connection
    * Time range filter includes recent data
    * No search filters are active

    Try clicking "Reset Sort & Filters" in the messages table.
  </Accordion>
</AccordionGroup>

## Getting Help

<CardGroup>
  <Card title="OWL IoT Discord Community" icon="discord" href="https://discord.gg/9HPQBwhd2E">
    Join our community for support and discussions
  </Card>

  <Card title="Documentation" icon="book" href="/">
    Browse the complete documentation
  </Card>

  <Card title="ClusterDuck Protocol" icon="link" href="https://clusterduckprotocol.org/">
    Learn about the underlying mesh protocol
  </Card>

  <Card title="ClusterDuck Protocol (GitHub)" icon="github" href="https://github.com/ClusterDuck-Protocol/ClusterDuck-Protocol">
    Our open-source LoRa mesh network library.
  </Card>
</CardGroup>


# Firmware Types
Source: https://docs.owlintegrations.com/guides/firmware-types

Understanding different Duck firmware options and sensor configurations

## Overview

OWL DMS supports multiple firmware types for Duck devices, each designed for specific use cases. This guide covers firmware options for both PapaDuck (gateway) and MamaDuck (sensor node) devices.

***

## PapaDuck Firmware Variants

PapaDuck devices serve as the gateway between your mesh network and the cloud. Choose the variant that matches your connectivity requirements.

<AccordionGroup>
  <Accordion title="PapaDuck WiFi - Standard gateway (WiFi connection)" icon="wifi">
    **Description:**
    The standard PapaDuck firmware connects to your WiFi network to relay mesh network data to the cloud. This is the recommended option when you have reliable WiFi coverage at your gateway location.

    **Features:**

    * Connects to 2.4GHz WiFi networks
    * Secure TLS connection to AWS IoT Core
    * Receives and forwards all mesh network messages
    * Queues messages when temporarily disconnected
    * LED status indicator for connection state

    **Requirements:**

    | Component    | Details                                  |
    | ------------ | ---------------------------------------- |
    | Hardware     | Any supported PapaDuck device            |
    | WiFi Network | 2.4GHz network (5GHz not supported)      |
    | Power        | Continuous USB or wall power recommended |

    **LED Status Indicators:**

    | LED Color | Status                                   |
    | --------- | ---------------------------------------- |
    | Green     | WiFi connected, communicating with cloud |
    | Red       | No WiFi connection                       |
    | Blue      | Transmitting data                        |

    **Use Cases:**

    * Indoor gateway installations
    * Locations with reliable WiFi coverage
    * Office or building deployments
    * Home mesh network setups
  </Accordion>

  <Accordion title="PapaDuck WiFi + LTE - Dual connectivity gateway (WiFi with cellular fallback)" icon="signal">
    **Description:**
    This advanced PapaDuck variant provides dual connectivity using both WiFi and LTE cellular. WiFi is the primary connection, but if WiFi becomes unavailable, the device automatically falls back to LTE to ensure your mesh network data always reaches the cloud.

    **Features:**

    * Primary WiFi connection with automatic LTE fallback
    * Seamless switching between WiFi and cellular
    * Periodic WiFi reconnection attempts (every 10 minutes when on LTE)
    * Secure TLS connection over both WiFi and cellular
    * Message queuing during connection transitions
    * LED status indicator for connection state

    <Warning>
      **Special Hardware Required**: This firmware requires specific hardware - see requirements below.
    </Warning>

    **Hardware Requirements:**

    | Component | Details                                       |
    | --------- | --------------------------------------------- |
    | Board     | LilyGo T-SIM7000G with LoRa Hat               |
    | SIM Card  | Activated IoT SIM card (Hologram recommended) |
    | Antenna   | LTE antenna (included with board)             |
    | Power     | USB or battery power                          |

    <Note>
      The LilyGo T-SIM7000G board combines the SIM7000G cellular modem with an ESP32. You need the version with the LoRa hat attachment to enable mesh network communication.
    </Note>

    **What You Need to Provide:**

    1. **LilyGo T-SIM7000G board with LoRa Hat** - Available from LilyGo or electronics retailers
    2. **Hologram SIM card** - The firmware is configured for Hologram SIM cards. You must activate the SIM and add a data plan on the Hologram dashboard at [hologram.io](https://hologram.io) before use. Other IoT SIM providers may work but are not officially supported.
    3. **WiFi credentials** - Your 2.4GHz network SSID and password
    4. **LTE antenna** - Usually included with the board

    <Note>
      **Hologram SIM setup required before flashing:** Create an account at [hologram.io](https://hologram.io), activate your SIM, and add a data plan. The device will not connect over LTE until the SIM has an active plan.
    </Note>

    **Connection Priority:**

    | Priority | Connection | When Used                                |
    | -------- | ---------- | ---------------------------------------- |
    | 1        | WiFi       | Always preferred when available          |
    | 2        | LTE        | Automatic fallback when WiFi unavailable |

    **LED Status Indicators:**

    | LED Color | Status                               |
    | --------- | ------------------------------------ |
    | Green     | Connected (WiFi or LTE)              |
    | Red       | No connection (neither WiFi nor LTE) |
    | Blue      | Transmitting data                    |

    **Connection Behavior:**

    * On startup, attempts WiFi connection first
    * If WiFi fails after 3 retries, initializes LTE modem
    * When on LTE, periodically checks for WiFi availability (every 10 minutes)
    * Automatically switches back to WiFi when it becomes available
    * Messages are queued if both connections temporarily fail

    **Use Cases:**

    * Remote or outdoor gateway installations
    * Locations with unreliable WiFi
    * Mobile gateway deployments
    * Disaster response and emergency networks
    * Agricultural or rural deployments
    * Backup connectivity for critical networks
  </Accordion>
</AccordionGroup>

***

## MamaDuck Firmware Types

MamaDuck devices collect sensor data and relay messages through the mesh network. Some firmware types require physical sensors to be connected to GPIO pins.

<AccordionGroup>
  <Accordion title="GPS Location - Track device location (No external sensors required)" icon="location-dot">
    **Description:**\
    Sends GPS coordinates periodically through the mesh network, perfect for asset tracking and mobile monitoring applications.

    **Features:**

    * Built-in GPS functionality (no external sensors needed)
    * Periodic location updates
    * Configurable update intervals to optimize battery life
    * Latitude, longitude, and altitude tracking

    **Configuration Options:**

    | Setting          | Options                      | Recommendation                          |
    | ---------------- | ---------------------------- | --------------------------------------- |
    | GPS Interval     | 5, 10, 15, 30, or 60 minutes | 15-30 min for balanced battery/accuracy |
    | Update Frequency | Low to High                  | Higher frequency = more battery drain   |

    **Hardware Requirements:**

    * **No external sensors required**
    * GPS module included in standard MamaDuck hardware
  </Accordion>

  <Accordion title="Barometric Pressure Sensor - Temperature & pressure (Requires sensor)" icon="temperature-half">
    **Description:**\
    Monitors temperature and atmospheric pressure. The BMP180, BMP280, and BMP390 are all covered under this single firmware type — you select your specific sensor model during configuration.

    **Features:**

    * Temperature measurement (-40°C to +85°C)
    * Barometric pressure monitoring
    * Low power consumption
    * I2C communication protocol

    **Sensor Model Comparison:**

    | Feature              | BMP180       | BMP280       | BMP390       |
    | -------------------- | ------------ | ------------ | ------------ |
    | Pressure Range       | 300–1100 hPa | 300–1100 hPa | 300–1250 hPa |
    | Pressure Accuracy    | ±1 hPa       | ±1 hPa       | ±0.5 hPa     |
    | Temperature Accuracy | ±1°C         | ±1°C         | ±0.5°C       |
    | Power Consumption    | Standard     | Lower        | Lowest       |

    **Configuration Options:**

    | Setting         | Options                         | Notes                                                                    |
    | --------------- | ------------------------------- | ------------------------------------------------------------------------ |
    | Sensor Model    | BMP180, BMP280, BMP390          | Choose your sensor model from the dropdown after selecting this firmware |
    | Sensor Interval | 30 sec to 60 min                | How often sensor readings are taken                                      |
    | I2C SDA Pin     | Configurable (default: GPIO 21) | GPIO pin for I2C data line                                               |
    | I2C SCL Pin     | Configurable (default: GPIO 22) | GPIO pin for I2C clock line                                              |

    <Warning>
      **Hardware Required**: You must physically connect a BMP sensor to your MamaDuck device before using this firmware.
    </Warning>

    **Hardware Connection:**

    All BMP variants use I2C and share the same wiring.

    **Required Components:**

    * BMP180, BMP280, or BMP390 sensor module
    * 4 jumper wires

    **Wiring Diagram:**

    | BMP Pin | MamaDuck Pin      | Description  |
    | ------- | ----------------- | ------------ |
    | VCC     | 3.3V              | Power supply |
    | GND     | GND               | Ground       |
    | SDA     | GPIO 21 (default) | I2C Data     |
    | SCL     | GPIO 22 (default) | I2C Clock    |

    <Tip>
      Most BMP modules operate at 3.3V. Double-check your module's voltage requirements before connecting.
    </Tip>
  </Accordion>

  <Accordion title="DHT11 Sensor - Temperature & humidity (Requires sensor)" icon="droplet">
    **Description:**\
    Monitors temperature and relative humidity using the DHT11 sensor. Perfect for indoor climate monitoring and agricultural applications.

    **Features:**

    * Temperature measurement (0-50°C)
    * Relative humidity (20-90%)
    * Cost-effective solution
    * Simple single-wire digital interface

    **Configuration Options:**

    | Setting         | Options          | Notes                       |
    | --------------- | ---------------- | --------------------------- |
    | Sensor Interval | 30 sec to 60 min | Reading frequency           |
    | GPIO Pin        | Configurable     | Digital pin for sensor data |

    <Warning>
      **Hardware Required**: You must physically connect a DHT11 sensor to your MamaDuck device before using this firmware.
    </Warning>

    **Hardware Connection:**

    **Required Components:**

    * DHT11 sensor module
    * 3 jumper wires

    **Wiring Diagram:**

    <img alt="DHT11 Sensor Wiring Diagram" />

    | DHT11 Pin | MamaDuck Pin      | Description  |
    | --------- | ----------------- | ------------ |
    | VCC       | 5V (or 3.3V)      | Power supply |
    | GND       | GND               | Ground       |
    | DATA      | GPIO 15 (default) | Data signal  |

    <Note>
      DHT11 sensors can work with both 3.3V and 5V. Check your module's specifications. Some modules have built-in pull-up resistors.
    </Note>

    <Tip>
      Make sure you choose an available GPIO pin on your device and enter the correct pin number in the firmware configuration when flashing.
    </Tip>

    **Sensor Specifications:**

    | Specification        | Range/Value               |
    | -------------------- | ------------------------- |
    | Humidity Range       | 20-90% RH                 |
    | Humidity Accuracy    | ±5% RH                    |
    | Temperature Range    | 0-50°C                    |
    | Temperature Accuracy | ±2°C                      |
    | Sampling Rate        | Max 1Hz (once per second) |
  </Accordion>

  <Accordion title="LED Control - Rainbow LED patterns (Requires LEDs)" icon="lightbulb">
    **Description:**\
    Controls external addressable LEDs (NeoPixel/WS2812B) to display rainbow patterns. Useful for visual indicators, device testing, and demonstrations.

    **Features:**

    * Rainbow pattern display
    * Supports multiple LEDs in series
    * Addressable RGB control
    * Configurable LED count

    **Configuration Options:**

    | Setting        | Options           | Notes                         |
    | -------------- | ----------------- | ----------------------------- |
    | Number of LEDs | 1-60              | Total LEDs in your strip/ring |
    | GPIO Pin       | Configurable      | Digital pin for LED data      |
    | Pattern        | Rainbow (default) | Pattern display mode          |

    <Warning>
      **Hardware Required**: You must physically connect WS2812B/NeoPixel LEDs to your MamaDuck device before using this firmware.
    </Warning>

    **Hardware Connection:**

    **Required Components:**

    * WS2812B LED strip or NeoPixel ring
    * External power supply (for >8 LEDs)
    * Jumper wires

    **Basic Wiring (1-8 LEDs):**

    <img alt="LED Wiring Diagram" />

    | LED Pin | MamaDuck Pin     | Description  |
    | ------- | ---------------- | ------------ |
    | VCC     | 3.3V             | Power supply |
    | GND     | GND              | Ground       |
    | DIN     | GPIO 4 (default) | Data input   |

    <Tip>
      Make sure you choose an available GPIO pin on your device and enter the correct pin number in the firmware configuration when flashing.
    </Tip>

    **For More LEDs (>8):**

    <Tip>
      When using more than 8 LEDs, use an external 5V power supply. Connect the power supply ground to MamaDuck GND, but power the LEDs from the external supply's 5V output.
    </Tip>

    **Power Considerations:**

    | LED Count | Current Draw | Power Source           |
    | --------- | ------------ | ---------------------- |
    | 1-8 LEDs  | \<400mA      | USB power OK           |
    | 9-30 LEDs | 400mA-2A     | External 5V required   |
    | 30+ LEDs  | 2A+          | Dedicated power supply |
  </Accordion>
</AccordionGroup>

***

## Configuration Best Practices

<AccordionGroup>
  <Accordion title="Extend Battery Life">
    * **Disable external LEDs**: Turn off when not needed for testing
    * **Choose appropriate sensors**: BMP390 uses less power than DHT11 at high sampling rates
  </Accordion>

  <Accordion title="Improve Data Accuracy">
    * **BMP sensors**: Allow 2-3 minutes warm-up time after power-on
    * **DHT11**: Don't sample faster than once every 2 seconds
    * **GPS**: Allow clear view of sky for best accuracy
    * **All sensors**: Protect from direct sunlight and moisture
  </Accordion>

  <Accordion title="Sensor Installation Tips">
    * **Verify voltage levels**: Most sensors use 3.3V, some tolerate 5V
    * **Use quality jumper wires**: Poor connections cause intermittent failures
    * **Secure connections**: Use hot glue or electrical tape to prevent disconnections
    * **Test before deployment**: Verify sensor readings before field installation
    * **Document GPIO pins**: Note which pins you used for future reference
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sensor not detected">
    **Check:**

    * Sensor is properly connected to correct GPIO pins
    * Power and ground connections are secure
    * GPIO pin number matches firmware configuration
    * Sensor is compatible (voltage levels)

    **Solution:**

    * Verify wiring with multimeter
    * Try different GPIO pins
    * Check sensor with example code
  </Accordion>

  <Accordion title="Inaccurate sensor readings">
    **Common causes:**

    * Sensor needs warm-up time
    * Poor electrical connections
    * Sensor damaged or counterfeit
    * Sampling rate too high

    **Solution:**

    * Wait 2-3 minutes after power-on
    * Replace jumper wires
    * Source sensors from reputable suppliers
    * Increase sensor interval
  </Accordion>

  <Accordion title="GPS not getting fix">
    **Check:**

    * Device has clear view of sky
    * GPS antenna is connected
    * Allow 1-2 minutes for initial fix
    * Not indoors or under heavy foliage

    **Solution:**

    * Move to open area
    * Check antenna connection
    * Wait for initial satellite lock
  </Accordion>

  <Accordion title="LEDs not lighting up">
    **Check:**

    * LED data pin connected to correct GPIO
    * LEDs powered (5V for WS2812B)
    * Ground shared between Duck and LEDs
    * Number of LEDs matches configuration

    **Solution:**

    * Verify wiring connections
    * Test LEDs with separate power supply
    * Reduce number of LEDs if underpowered
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Flash Firmware" icon="microchip" href="/guides/flash-device">
    Ready to flash? Follow the flashing guide
  </Card>

  <Card title="Device Types" icon="layer-group" href="/guides/device-types">
    Learn more about Duck device types
  </Card>

  <Card title="Network Management" icon="network-wired" href="/guides/network-management">
    Manage your deployed devices
  </Card>

  <Card title="Dashboard" icon="gauge" href="/guides/dashboard">
    View sensor data in real-time
  </Card>
</CardGroup>

***

## Support

Need help with firmware or connecting sensors?

<CardGroup>
  <Card title="OWL IoT Discord Community" icon="discord" href="https://discord.gg/9HPQBwhd2E">
    Ask the community for help
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@owlintegrations.com">
    Contact our support team
  </Card>
</CardGroup>


# Flash Firmware
Source: https://docs.owlintegrations.com/guides/flash-device

Install firmware to your Duck devices via USB

## Overview

The Flash Firmware page allows you to install firmware to your Duck devices directly from your web browser using USB. No external software or command-line tools required - everything is done through the OWL DMS interface.

<Warning>
  **Browser Requirement**: This feature requires Google Chrome or Microsoft Edge browser with Web Serial API support.
</Warning>

## Prerequisites

<CardGroup>
  <Card title="Chrome Browser" icon="chrome">
    Chrome or Edge (version 89+) required
  </Card>

  <Card title="USB Cable" icon="usb">
    USB connection to your computer
  </Card>

  <Card title="Device Registered" icon="check">
    Device must exist in Network page
  </Card>

  <Card title="Serial Permissions" icon="shield">
    Grant browser serial port access
  </Card>
</CardGroup>

***

## 4-Step Flashing Process

The firmware flashing wizard guides you through four simple steps:

### Step 1: Connect Device

<Steps>
  <Step title="Connect via USB">
    Plug your Duck device into your computer using a USB cable.
  </Step>

  <Step title="Click Connect Device">
    The interface will detect available serial ports.
  </Step>

  <Step title="Grant Browser Permission">
    When prompted, select your device's serial port and click "Connect".
  </Step>

  <Step title="Wait for Connection">
    The system will establish a connection with your device.
  </Step>
</Steps>

<Note>
  If you don't see your device in the serial port list, check your USB connection and ensure drivers are installed.
</Note>

***

### Step 2: Select Device Type

Choose which type of Duck device you're flashing:

<Tabs>
  <Tab title="Gateway (PapaDuck)">
    **Network Hub**

    * Connects to WiFi
    * Sends data to cloud
    * Manages MamaDucks
    * Always powered on

    **Best For**: Central hub locations with WiFi and power access
  </Tab>

  <Tab title="Node (MamaDuck)">
    **Sensor & Relay Device**

    * Collects sensor data
    * Battery powered
    * Mobile deployment
    * Multiple sensor options

    **Best For**: Field data collection and mobile sensing
  </Tab>

  <Tab title="DetectorDuck">
    **Network Testing Tool**

    * Signal strength measurement
    * Deployment optimization
    * Range testing
    * LED feedback

    **Best For**: Planning deployments and troubleshooting
  </Tab>
</Tabs>

***

### Step 3: Configure Firmware

Configuration options vary by device type.

<Card title="View All Firmware Types" icon="code-branch" href="/guides/firmware-types">
  See detailed information about each firmware type, including sensor wiring diagrams and GPIO pin configurations
</Card>

<AccordionGroup>
  <Accordion title="MamaDuck Configuration">
    **1. Select Your MamaDuck**

    * Choose from existing MamaDucks in your account
    * Devices are grouped by their assigned PapaDuck

    **2. Firmware Version**

    * Select ClusterDuck Protocol (CDP) version
    * Latest stable version recommended

    **3. GPS Interval** (Optional)

    * Set how often GPS coordinates are sent
    * Options: 5, 10, 15, 30, or 60 minutes
    * Lower intervals = more frequent updates, higher battery usage

    **4. External LED** (Optional)

    * Enable external LED indicator
    * Configure GPIO pin (default: 4)

    **5. Firmware Type** - Choose ONE:

    **GPS Location**

    * Sends GPS coordinates periodically
    * Use for: Asset tracking, mobile monitoring

    **BMP180 Sensor**

    * Temperature and pressure monitoring
    * Configure sensor interval (30 sec to 60 min)
    * Configure sensor GPIO pin
    * Use for: Weather monitoring

    **BMP390 Sensor**

    * Advanced temperature and pressure
    * Higher precision than BMP180
    * Configure sensor interval and GPIO pin
    * Use for: Precision environmental monitoring

    **DHT11 Sensor**

    * Temperature and humidity monitoring
    * Configure sensor interval and GPIO pin
    * Use for: Climate monitoring

    **LED Control**

    * Rainbow LED pattern display
    * Configure number of LEDs
    * Use for: Visual indicators, testing
  </Accordion>

  <Accordion title="PapaDuck Configuration">
    **1. Select Your PapaDuck**

    * Choose from existing PapaDucks in your account

    **2. Firmware Variant**

    * **WiFi** - Standard gateway, connects via WiFi only
    * **WiFi + LTE** - Dual connectivity with cellular fallback (requires LilyGo T-SIM7000G with LoRa Hat)

    **3. Firmware Version**

    * Select CDP version

    **4. WiFi Credentials** (Required)

    * **SSID**: Your WiFi network name
    * **Password**: Your WiFi password
    * Device will use this to connect and upload data

    **5. External LED** (Optional)

    * Enable external LED indicator
    * Configure GPIO pin

    <Note>
      For WiFi + LTE firmware, ensure you have an activated IoT SIM card installed in your LilyGo T-SIM7000G board before flashing.
    </Note>
  </Accordion>

  <Accordion title="DetectorDuck Configuration">
    **External LED Configuration**

    * Configure LED settings for visual feedback
    * See [deployment documentation](https://docs.owlintegrations.com) for usage guide
  </Accordion>
</AccordionGroup>

***

### Step 4: Review & Flash

**Review Your Configuration**

Before flashing, you'll see a summary of all your selections:

* Device type
* Selected device
* Firmware version
* WiFi settings (for PapaDuck)
* Sensor type and intervals (for MamaDuck)
* LED configuration

**Flash Progress**

Once you click "Flash Device", the system will:

1. **Prepare** - Validate configuration

2. **Build Firmware** (\~20 seconds)
   * Compiles custom firmware with your settings
   * Progress bar shows build status

3. **Erase Flash** - Clears existing firmware

4. **Write Firmware** - Uploads new firmware
   * File-by-file progress shown
   * Multiple files uploaded sequentially

5. **Verify** - Confirms successful installation

<Warning>
  **Do not disconnect the device during flashing!** The process takes 1-3 minutes. Disconnecting may corrupt the firmware.
</Warning>

**Serial Monitor**

The Review step includes a serial terminal that shows:

* Real-time flash progress
* Device boot messages
* Error messages (if any)
* Firmware version confirmation

You can:

* **Reconnect** if connection is lost
* **Change baud rate** (default: 115200)
* **Send commands** to the device
* **Clear terminal** output

***

## After Flashing

### LED Status Indicators

LED colors indicate the current status of your device. MamaDuck and PapaDuck use different indicators:

<img alt="MamaDuck and PapaDuck LED Status Colors" />

**MamaDuck**

| LED Color            | Status           | Description                                      |
| -------------------- | ---------------- | ------------------------------------------------ |
| **Orange**           | Boot/Setup       | Device is starting up and initializing           |
| **Blue**             | Normal Operation | Device is running and operating normally         |
| **Green** (flashing) | Sending Data     | Device is actively transmitting data to the mesh |

**PapaDuck**

| LED Color | Status       | Description                                     |
| --------- | ------------ | ----------------------------------------------- |
| **Green** | Connected    | WiFi connected and communicating with the cloud |
| **Red**   | Disconnected | No WiFi connection or network issue             |

<Note>
  The LED indicator helps you quickly identify your device's status without needing to check the serial monitor or dashboard.
</Note>

### Next Steps

<CardGroup>
  <Card title="Network Management" icon="network-wired" href="/guides/network-management">
    View your device in the Network page
  </Card>

  <Card title="Dashboard" icon="gauge" href="/guides/dashboard">
    Monitor device messages
  </Card>

  <Card title="Map View" icon="map" href="/guides/map-view">
    See device location (if GPS enabled)
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Serial port not found">
    **Solutions**:

    * Check USB cable is properly connected
    * Try a different USB port
    * Install CP210x USB drivers (if needed)
    * Restart your browser
    * Ensure no other program is using the serial port
  </Accordion>

  <Accordion title="Flash process fails">
    **Common Causes**:

    * Device disconnected during flash
    * Insufficient power via USB
    * Corrupted USB cable
    * Wrong device type selected

    **Solutions**:

    * Use a high-quality USB cable
    * Try connecting directly to computer (not via hub)
    * Ensure correct device type is selected
    * Retry the flash process
  </Accordion>

  <Accordion title="Device won't boot after flashing">
    **Solutions**:

    * Check serial monitor for error messages
    * Verify WiFi credentials (for PapaDuck)
    * Try reflashing with default settings
    * Check sensor GPIO pin assignments
    * Power cycle the device
  </Accordion>

  <Accordion title="PapaDuck won't connect to WiFi">
    **Check**:

    * SSID is correct (case-sensitive)
    * Password is correct
    * WiFi network is 2.4GHz (5GHz not supported)
    * Device is within WiFi range
    * Serial monitor shows connection attempts

    **Solution**: Reflash with correct credentials
  </Accordion>

  <Accordion title="MamaDuck not sending data">
    **Check**:

    * Device is assigned to correct PapaDuck
    * PapaDuck is online
    * Sensor is connected to correct GPIO pin
    * Sensor interval is reasonable
    * Battery is charged

    **View**: Check Dashboard for messages
  </Accordion>

  <Accordion title="PapaDuck LTE not connecting">
    **Check**:

    * SIM card is properly inserted in the LilyGo T-SIM7000G
    * SIM card is activated with your IoT provider
    * LTE antenna is connected
    * Device has cellular coverage in your area
    * Serial monitor shows modem initialization

    **Common Issues**:

    * **"No response from modem"**: Check that SIM card is seated correctly
    * **"Network registration timeout"**: SIM may not be activated, or no coverage
    * **"MQTT connection failed"**: Check that certificates are properly configured

    **Solution**: Verify SIM activation with your provider, try a different location with better signal
  </Accordion>

  <Accordion title="Browser doesn't support Web Serial">
    **Requirements**:

    * Google Chrome 89+ or Microsoft Edge 89+
    * Web Serial API enabled (enabled by default)
    * Not supported: Firefox, Safari

    **Solution**: Use Chrome or Edge browser
  </Accordion>
</AccordionGroup>

***

## Configuration Tips

<CardGroup>
  <Card title="Battery Life" icon="battery-three-quarters">
    **Extend Battery**:

    * Increase GPS interval (30-60 min)
    * Increase sensor interval
    * Disable external LED when not needed
  </Card>

  <Card title="Data Frequency" icon="clock">
    **More Frequent Data**:

    * Decrease GPS interval (5-10 min)
    * Decrease sensor interval
    * Note: Higher battery drain
  </Card>

  <Card title="WiFi Stability" icon="wifi">
    **Better Connectivity**:

    * Place PapaDuck near WiFi router
    * Use 2.4GHz network (better range)
    * Avoid WiFi with captive portals
  </Card>

  <Card title="Sensor Selection" icon="temperature-half">
    **Choose Right Sensor**:

    * GPS: Location tracking
    * BMP180/390: Weather monitoring
    * DHT11: Indoor climate
    * LED: Visual testing
  </Card>
</CardGroup>

***

## Firmware Versions

**ClusterDuck Protocol (CDP)**

The firmware is based on the [ClusterDuck Protocol](https://clusterduckprotocol.org/), our open-source LoRa mesh network library. The CDP is made by OWL and maintained by OWL.

* **Stable Versions**: Recommended for production use
* **Beta Versions**: Latest features, may have bugs
* **Version Numbers**: e.g., "v4.0 (Stable)"

<Tip>
  Always use the latest stable version unless you need specific beta features.
</Tip>

***

## Related Pages

<CardGroup>
  <Card title="Firmware Types" icon="code-branch" href="/guides/firmware-types">
    Detailed firmware options and sensor wiring
  </Card>

  <Card title="Device Types" icon="layer-group" href="/guides/device-types">
    Learn about Papa/Mama/Detector differences
  </Card>
</CardGroup>


# Getting Started
Source: https://docs.owlintegrations.com/guides/getting-started

Set up your first Duck device and start monitoring your network

## What You'll Need

Before you begin, gather these essentials:

* **Duck device** - PapaDuck (gateway) or MamaDuck (sensor node)
* **USB cable** - For connecting device to your computer
* **Chrome or Edge browser** - Required for Web Serial API support
* **OWL DMS account** - Contact your administrator for access
* **WiFi credentials** - For PapaDuck devices (2.4GHz only)

***

## Step 1: Log In to OWL DMS

1. Navigate to your OWL DMS platform URL
2. Enter your email and password
3. Click **Sign In**

If this is your first time logging in, check your email for the registration link sent by your administrator.

***

## Step 2: Add Your Device

Before flashing firmware, register your device in the system:

1. Go to **Network** in the navigation
2. Click **Add Device**
3. Enter a device name (3-8 characters, letters and numbers only)
4. Click **Create**

**Device Types:**

* **PapaDuck**: Gateway device that connects to WiFi and uploads data to the cloud
* **MamaDuck**: Sensor node that collects data and relays messages through the mesh network

***

## Step 3: Flash Firmware

Navigate to **Add Device** in the navigation to access the firmware flashing wizard.

### Connect Your Device

1. Click **Connect to Device**
2. Select your device from the browser popup
3. Wait for the connection confirmation

### Configure Firmware

1. **Select device type**: PapaDuck or MamaDuck
2. **Enter WiFi credentials** (PapaDuck only):
   * SSID (network name)
   * Password
   * *WiFi must be 2.4GHz - 5GHz networks are not supported*
3. **Choose sensors** (MamaDuck only):
   * GPS, BMP180/390, DHT11, or LED control
   * Set sensor intervals (30 seconds to 60 minutes)

### Flash & Monitor

1. Review your configuration
2. Click **Flash Firmware**
3. Monitor the serial output for progress
4. Wait for "Flash complete" confirmation

<Warning>
  Do not disconnect the device during flashing. The process takes 1-2 minutes.
</Warning>

***

## Step 4: Deploy Your Device

Once flashing is complete:

**For PapaDuck:**

1. Disconnect from computer
2. Connect to power source (USB or wall adapter)
3. Device will automatically connect to WiFi and start uploading data

**For MamaDuck:**

1. Disconnect from computer
2. Power with battery or USB
3. Device will connect to the nearest PapaDuck in range

***

## Step 5: Monitor Your Network

### Check Device Status

1. Go to **Network** page
2. Verify your device appears in the list
3. Devices are **online** if a message was received within the last 5 minutes

### View Real-Time Data

1. Go to **Dashboard** to see message statistics and charts
2. Go to **Map View** to see GPS locations (if GPS sensor is enabled)
3. Click on devices to view battery status and recent messages

<Tip>
  Messages appear in real-time. If your device shows offline, check WiFi connection (PapaDuck) or verify it's within range of a PapaDuck (MamaDuck).
</Tip>

***

## Next Steps

<CardGroup>
  <Card title="Dashboard" icon="chart-line" href="/guides/dashboard">
    Monitor messages and device activity
  </Card>

  <Card title="Map View" icon="map" href="/guides/map-view">
    Visualize device locations
  </Card>

  <Card title="Network Management" icon="network-wired" href="/guides/network-management">
    Manage devices and assignments
  </Card>

  <Card title="Data Export" icon="download" href="/guides/data-export">
    Export message data to CSV
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Device won't connect in browser">
    * Make sure you're using Chrome or Edge browser
    * Try a different USB cable or port
    * Check that the device is powered on
  </Accordion>

  <Accordion title="PapaDuck won't connect to WiFi">
    * Verify you're using a 2.4GHz network (5GHz not supported)
    * Double-check SSID and password for typos
    * Ensure the network doesn't require captive portal login
  </Accordion>

  <Accordion title="Device shows offline">
    * Wait 5 minutes - devices are marked offline after 5 minutes without messages
    * For PapaDuck: check WiFi connection and power
    * For MamaDuck: verify it's within range of a PapaDuck
  </Accordion>

  <Accordion title="No GPS data showing">
    * GPS data only displays if received within the last 24 hours
    * Ensure device has clear view of sky for GPS satellite lock
    * Check that GPS sensor was enabled during firmware flashing
  </Accordion>
</AccordionGroup>

<Note>
  Need help? Contact [support@owlintegrations.com](mailto:support@owlintegrations.com)
</Note>


# Map View
Source: https://docs.owlintegrations.com/guides/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>
  <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>


# Network Management
Source: https://docs.owlintegrations.com/guides/network-management

Add, configure, and manage Papa Duck gateways and Mama Duck devices in your mesh network

The Network Management page allows you to configure and monitor all devices in your Duck mesh network, including both Papa Duck gateways and their connected Mama Duck devices.

## Device Hierarchy

OWL DMS uses a two-tier device structure:

<CardGroup>
  <Card title="Papa Duck" icon="tower-broadcast">
    Gateway devices that connect to the internet and relay messages to the cloud. Each Papa Duck can support multiple Mama Ducks.
  </Card>

  <Card title="Mama Duck" icon="satellite-dish">
    Mesh network devices that relay messages between end devices and Papa Ducks. Each Mama Duck must be assigned to a parent Papa Duck.
  </Card>
</CardGroup>

## Device Table

The main table displays your Papa Duck devices with expandable rows:

### Table Columns

| Column           | Description                                            |
| ---------------- | ------------------------------------------------------ |
| **Name**         | Device display name (clickable link to device details) |
| **Unique ID**    | Hardware identifier for the device                     |
| **Description**  | Optional device description                            |
| **Location**     | Physical location or deployment area                   |
| **Status**       | Online/Offline (based on messages in last 5 minutes)   |
| **Mama Devices** | Number of connected Mama Duck devices                  |
| **Created**      | Date the device was added to the system                |
| **Actions**      | Edit and delete buttons                                |

### Expandable Rows

Click the expand arrow next to a Papa Duck to view its connected Mama Ducks:

<Steps>
  <Step title="View Mama Ducks">
    Expand a Papa Duck row to see all associated Mama Duck devices
  </Step>

  <Step title="Mama Details">
    Each Mama Duck shows the same information as Papa Ducks (name, ID, description, location, status)
  </Step>

  <Step title="Manage Mama Ducks">
    Click on a Mama Duck name to view its detail page, or use the edit/delete actions
  </Step>
</Steps>

## Adding Devices

### Add Papa Duck

<Steps>
  <Step title="Click Add Device">
    Click the "Add Device" button in the top-right corner
  </Step>

  <Step title="Select Device Type">
    Choose "PAPA" from the device type dropdown
  </Step>

  <Step title="Enter Device Info">
    Fill in the required and optional fields:

    * **Name** (required, 3-8 characters): Short identifier for the device
    * **Description** (optional): Purpose or notes about the device
    * **Location** (optional): Physical location or deployment area
  </Step>

  <Step title="Submit">
    Click "Submit" to create the Papa Duck. The system will generate gateway credentials automatically.
  </Step>
</Steps>

<Info>
  Papa Duck credentials (Device ID and Token) are generated automatically and can be viewed in the device details page.
</Info>

### Add Mama Duck

<Steps>
  <Step title="Click Add Device">
    Click the "Add Device" button
  </Step>

  <Step title="Select Device Type">
    Choose "MAMA" from the device type dropdown
  </Step>

  <Step title="Select Parent Papa">
    Choose which Papa Duck this Mama Duck will connect to (required)
  </Step>

  <Step title="Enter Device Info">
    Fill in the required and optional fields:

    * **Name** (required, 3-8 characters): Short identifier
    * **Parent PAPA** (required): Select the parent Papa Duck
    * **Description** (optional): Purpose or notes
    * **Location** (optional): Physical location
  </Step>

  <Step title="Submit">
    Click "Submit" to create the Mama Duck
  </Step>
</Steps>

<Warning>
  Every Mama Duck must be assigned to a Papa Duck. You cannot create a Mama Duck without first having at least one Papa Duck in your account.
</Warning>

## Editing Devices

Click the edit icon (pencil) next to any device to modify its information:

### Editable Fields

* **Description**: Update the device purpose or notes
* **Location**: Change the deployment location
* **Parent Papa** (Mama Ducks only): Reassign a Mama Duck to a different Papa Duck

<Accordion title="What Cannot Be Changed">
  - Device Name (set during creation)
  - Unique ID (hardware identifier)
  - Device Type (PAPA or MAMA)
  - Gateway credentials (Papa Ducks only)
</Accordion>

## Archiving Devices

Archiving lets you hide Gateways and Nodes you no longer need to see day-to-day — test devices, decommissioned hardware — without deleting them or losing any of their history. Archived devices can be restored at any time.

The Network page has two tabs:

* **Active** — your normal, working device list
* **Archived** — devices you've hidden from view, each with its own search box

### Archiving a Gateway

<Steps>
  <Step title="Open the overflow menu">
    Click the **⋯** menu on a Papa Duck row
  </Step>

  <Step title="Select Archive">
    Choose **Archive**. A confirmation dialog explains that the Gateway will move to Archived and stop appearing in your active network
  </Step>

  <Step title="Confirm">
    Check the box confirming you want to archive the device, then confirm
  </Step>
</Steps>

<Info>
  Archiving a Gateway also archives all of its connected Nodes. You can still restore individual Nodes separately afterward.
</Info>

### Archiving a Node

Open the **⋯** menu on a Mama Duck row and choose **Archive**. This only affects that Node — its parent Gateway stays active.

### Restoring an Archived Device

From the **Archived** tab, open the **⋯** menu on a Gateway or Node and choose **Unarchive**. A confirmation dialog appears; confirm to move the device back to Active.

<Tip>
  Restoring a Gateway only brings back the Nodes that were archived along with it. If you archived a Node individually *before* archiving its Gateway, that Node stays archived — you'll need to restore it separately.
</Tip>

In the Archived tab, a Node whose parent Gateway is still active shows a **Gateway Still Active** badge, so you know it was archived on its own rather than as part of a Gateway archive.

### What Archiving Affects

Once a device is archived, it disappears from:

* The home page device list
* The Gateway selector on the Map page
* The Node dropdown in the Add Device / firmware flash wizard

Nothing is deleted — message history is preserved, and you can still open an archived device directly by its detail page URL.

## Device Status

### Online/Offline Detection

Devices are automatically marked as online or offline based on recent message activity:

<Steps>
  <Step title="Online Status">
    A device is considered **online** if it has sent a message within the last 5 minutes
  </Step>

  <Step title="Offline Status">
    A device is marked **offline** if no messages have been received for more than 5 minutes
  </Step>

  <Step title="Status Indicators">
    * **Green dot**: Device is online
    * **Gray dot**: Device is offline
  </Step>
</Steps>

<Info>
  Device status updates automatically based on real-time message activity from the WebSocket connection.
</Info>

## Viewing Device Details

### Papa Duck Details

Click on a Papa Duck name to view its detail page, which includes:

* Device information (name, ID, description, location)
* Gateway credentials (Device ID and Token for cloud connectivity)
* Last seen timestamp
* Battery status (if available)
* Online/offline status
* Connected Mama Ducks list
* Recent message history

### Mama Duck Details

Click on a Mama Duck name to view its detail page, which shows:

* Device information
* Parent Papa Duck
* Last seen timestamp
* Battery and health metrics
* Online/offline status
* Recent message history
* GPS location history (if equipped)

## Tips

<Tip>
  **Naming convention**: Use descriptive, location-based names for devices (e.g., "PAPA-HQ", "MAMA-FIELD1") to easily identify them in large deployments.
</Tip>

<Tip>
  **Bulk organization**: Use the description and location fields to group devices by project, deployment area, or purpose for easier management.
</Tip>


# User Management
Source: https://docs.owlintegrations.com/guides/user-management

Manage user accounts, permissions, and device access in your OWL DMS system

The User Management page allows administrators to create, edit, and manage user accounts for the OWL DMS platform.

<Warning>
  **Admin Only**: User management features are only available to users with administrator privileges.
</Warning>

## User Table

The main table displays all users in your OWL DMS system:

### Table Columns

| Column           | Description                                        |
| ---------------- | -------------------------------------------------- |
| **Name**         | Full name of the user                              |
| **Username**     | Email address used for login                       |
| **Phone**        | Contact phone number                               |
| **Admin Status** | Indicates if the user has administrator privileges |
| **Created**      | Date the account was created                       |
| **Actions**      | Edit user settings or assign devices               |

### Table Features

* **Search**: Use the search box to filter users by name, email, or phone
* **Sorting**: Click column headers to sort users
* **Reset**: Click the refresh icon to clear filters and sorting

## Adding New Users

<Steps>
  <Step title="Click Add User">
    Click the "Add User" button in the top-right corner
  </Step>

  <Step title="Enter User Details">
    Fill in the required information:

    * **Name** (required): User's full name
    * **Username** (required): Email address for login
  </Step>

  <Step title="Submit">
    Click "Submit" to create the user account
  </Step>

  <Step title="Registration Email Sent">
    The system automatically sends a registration email to the provided email address with instructions to complete account setup
  </Step>
</Steps>

<Info>
  **Email verification**: The system checks if the email address already exists before creating the account. Duplicate emails are not allowed.
</Info>

## Registration Email

When a new user is added, they receive an automated email containing:

* A unique registration link valid for account activation
* Instructions to complete their account setup
* Steps to set their password
* Link to the OWL DMS platform

<Warning>
  Registration links expire after a certain period for security. Users should complete registration promptly after receiving the email.
</Warning>

## Security Considerations

<Warning>
  **Admin privileges**: Be cautious when granting administrator access, as admins can modify critical system settings and access all data.
</Warning>

<Info>
  **Email validation**: The system automatically validates email addresses and prevents duplicate accounts for security.
</Info>

<Info>
  **Session management**: Users are automatically logged out after periods of inactivity to protect against unauthorized access.
</Info>


# OWL DMS
Source: https://docs.owlintegrations.com/index

Manage your Duck mesh network with real-time monitoring and web-based firmware flashing

OWL DMS (Device Management System) is a web-based platform for managing Duck mesh networks powered by the ClusterDuck Protocol. Monitor devices in real-time, flash firmware from your browser, visualize GPS locations, and export message data.

## What is a Duck Mesh Network?

A mesh network where devices connect directly to each other, creating multiple pathways for data transmission. This creates a resilient network that continues operating even when individual devices fail.

**How it works:**

1. MamaDucks (sensor nodes) collect data and relay messages
2. Messages route through the mesh network to a PapaDuck (gateway)
3. PapaDuck uploads data to the cloud via WiFi
4. OWL DMS displays messages in real-time

## Device Types

**PapaDuck (Gateway)**: Connects to WiFi and uploads data to the cloud. Manages multiple MamaDucks.

**MamaDuck (Node)**: Battery-powered sensor device with GPS, temperature, pressure, and humidity support.

**DetectorDuck**: Testing tool for measuring signal strength and optimizing device placement.

<Card title="Device Types Guide" icon="layer-group" href="/guides/device-types">
  Learn more about each device type
</Card>

***

## Getting Started

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/guides/getting-started">
    Set up your first Duck device
  </Card>

  <Card title="Flash Firmware" icon="microchip" href="/guides/flash-device">
    Install firmware via USB
  </Card>

  <Card title="Dashboard" icon="gauge" href="/guides/dashboard">
    Monitor messages and activity
  </Card>

  <Card title="Map View" icon="map" href="/guides/map-view">
    Visualize device locations
  </Card>
</CardGroup>

## Platform Features

<CardGroup>
  <Card title="Network Management" icon="network-wired" href="/guides/network-management">
    Manage devices and assignments
  </Card>

  <Card title="Data Export" icon="download" href="/guides/data-export">
    Export message data to CSV
  </Card>

  <Card title="User Management" icon="users" href="/guides/user-management">
    Manage users and permissions
  </Card>

  <Card title="FAQs" icon="messages-question" href="/guides/faqs">
    Common questions and answers
  </Card>
</CardGroup>