mc-webui/docs/dm-retry-logic.md

# DM Delivery & Retry Logic

This document explains how mc-webui delivers direct messages (DMs) and retries them when the recipient doesn't confirm receipt.

## How delivery confirmation works

When you send a DM, the MeshCore device transmits it over radio and waits for an **ACK** (acknowledgment) from the recipient's device. If no ACK arrives within the expected time, the app retries the message — possibly changing the route to improve the chances of delivery.

The progress is shown in real time next to the message bubble: **"Attempt 3/11"**, and when delivery is confirmed, the route used is displayed (e.g. `5E->05->58->D1`).

## Settings (Settings > Messages)

All retry parameters are configurable in **Settings > Messages**:

| Setting | Section | Default | Description |
|---|---|---|---|
| **Direct retries** | When path is known | 3 | How many times to resend via the current route before trying alternatives |
| **Flood retries** | When path is known | 1 | How many flood attempts after direct retries (when no extra paths are configured) |
| **Interval (s)** | When path is known | 30 | Minimum seconds between direct retry attempts |
| **Max retries** | When no path | 3 | How many flood retry attempts |
| **Interval (s)** | When no path | 60 | Minimum seconds between flood retry attempts |
| **Grace period (s)** | Other | 60 | After all retries fail, keep listening for a late ACK this long before giving up |

> **Note:** "Retries" means attempts *after* the initial send. So "3 retries" = 4 total attempts (1 initial + 3 retries).

### Why the actual wait time can be longer than the configured interval

The device firmware reports a **suggested timeout** for each message — this is its best estimate of how long the ACK might take, based on the route length, signal quality, and network conditions.

The actual wait between attempts is:

```
actual_wait = max(firmware_suggested_timeout * 1.2, configured_interval)
```

In other words: the configured interval is a **minimum floor**, not a fixed value. If the firmware says "this route needs ~32 seconds for an ACK to come back", the app will wait at least `32 * 1.2 = 38 seconds` — even if your interval is set to 15s. This prevents premature retries that would waste airtime.

You can see the actual wait in the System Log:

```
DM retry task started: dm_id=2107, scenario=S4, ..., wait=38s
```

## The four delivery scenarios

The app picks one of four strategies depending on two factors:

1. **Does the contact have a known route?** (visible as a path in Contact Info, e.g. `5E->05->58->D1`)
2. **Are there extra configured paths?** (the "Paths" list in Contact Info)

| | No configured paths | Has configured paths |
|---|---|---|
| **No known route** | Scenario 1: Flood only | Scenario 3: Flood, then path rotation |
| **Has known route** | Scenario 2: Direct, then flood | Scenario 4: Direct, path rotation, then flood |

Each scenario is also affected by the **Keep path** toggle in the contact's DM window.

---

### Scenario 1: No route, no configured paths

The simplest case. The app has no route information at all — it can only send via **flood** (broadcast to the entire mesh network).

**Steps:**
1. Send message (flood)
2. Wait for ACK
3. If no ACK: retry up to **Max retries** times, waiting **Interval (flood)** between attempts

**Total attempts:** 1 + Max retries (default: 4)

The **Keep path** toggle has no effect here — there is no path to keep.

---

### Scenario 2: Has route, no configured paths

The contact has a known route but no extra paths are configured.

**Steps:**
1. Send message via the known route (direct)
2. Wait for ACK
3. If no ACK: retry up to **Direct retries** times via the same route, waiting **Interval (direct)** between attempts
4. If still no ACK and **Keep path is OFF**: reset to flood and retry **Flood retries** times (from the "When path is known" section)
5. If **Keep path is ON**: stop after direct retries (no flood fallback)

**Total attempts:**
- Keep path OFF: 1 + Direct retries + Flood retries (default: 5)
- Keep path ON: 1 + Direct retries (default: 4)

---

### Scenario 3: No route, has configured paths

The contact has no current route, but you've saved one or more paths in Contact Info. The app first tries flood (hoping to discover a fresh route), then rotates through your configured paths.

**Steps:**
1. Send via flood
2. Wait for ACK
3. If no ACK: retry via flood up to **Max retries** times
4. If still no ACK: switch to configured paths, trying each one in order (primary path first, then the rest by sort order)
5. For each configured path: retry up to **Direct retries** times (minimum 1)
6. After finishing (success or failure): restore the primary path on the device

**Total attempts:** 1 + Max retries + (number of paths * Direct retries) (default with 3 paths: 13)

The **Keep path** toggle has no effect here — there is no current path to protect.

---

### Scenario 4: Has route + has configured paths

The most complete scenario. The contact has both a current route and extra configured paths.

**Steps:**
1. Send message via the current route (direct)
2. Wait for ACK
3. If no ACK: retry up to **Direct retries** times via the same route
4. If still no ACK: rotate through configured paths (skipping any path that matches the already-tried current route)
5. For each configured path: retry up to **Direct retries** times (minimum 1)
6. If still no ACK and **Keep path is OFF**: reset to flood and retry **Max retries** times (from the "When no path" section)
7. If **Keep path is ON**: stop after path rotation (no flood fallback)
8. After finishing (success or failure): restore the primary path on the device

**Total attempts:**
- Keep path OFF: 1 + Direct retries + (unique paths * Direct retries) + Max retries
- Keep path ON: 1 + Direct retries + (unique paths * Direct retries)

> **Deduplication:** If one of your configured paths is identical to the contact's current route, it is skipped during rotation to avoid trying the same route twice.

---

## After all retries fail

When all attempts are exhausted:
- The message gets a **failed** icon (X)
- The app continues to listen for a late ACK during the **Grace period** (default: 60s)
- If a late ACK arrives during the grace period, the message is still marked as delivered
- In scenarios with configured paths: the **primary path** is restored on the device, regardless of outcome

## Monitoring in System Log

The retry process logs to the `device_manager` module. At **INFO** level you'll see the key events:

```
DM retry task started: dm_id=2107, scenario=S4_DIRECT_SD_FLOOD,
    configured_paths=4, no_auto_flood=True, max_attempts=21, wait=38s
DM retry: direct retries exhausted, rotating through configured paths
DM retry: switched to path 'Device path' (5e0558d1)
DM retry: switched to path 'Device path' (5e9005a68a4bf0d1)
DM retry: all paths exhausted, falling back to FLOOD
DM retry exhausted (21 total attempts, scenario=S4) for dm_id=2107
```

At **DEBUG** level (for advanced troubleshooting) you'll also see each individual attempt:

```
DM retry: waiting 38s for initial ACK c53e8870...
DM retry attempt #1: sending dm_id=2107
DM retry #1: waiting 38s for ACK a1b2c3d4...
DM retry: skipping path 'Primary' (5e0558d1) — matches current device path
```

### Scenario names in logs

| Log name | Meaning |
|---|---|
| `S1_FLOOD` | Scenario 1: flood only |
| `S2_DIRECT_FLOOD` | Scenario 2: direct + flood fallback |
| `S3_FLOOD_SD` | Scenario 3: flood + path rotation |
| `S4_DIRECT_SD_FLOOD` | Scenario 4: direct + path rotation + flood |