# Halo and Keymind Branch Settings

This file covers only CLI settings and helper commands added by the Halo or
Keymind branches. Use `docs/cli_commands.md` for the general MeshCore CLI.
See [Repeater Flood Filtering and Moderation](flood_filtering.md) for a focused
filter setup and troubleshooting guide.

## Quick Start

```text
set retry.preset rooftop
set direct.retry.heard on
set flood.retry.advert off
set flood.retry.bridge off
set flood.retry.prefixes none
set flood.retry.ignore none
```

Then verify:

```text
get retry.preset
get direct.retry.heard
get flood.retry.advert
get flood.retry.prefixes
get flood.retry.ignore
```

Use prefixes from the analyzer or neighbors list or `get recent.repeater` after the repeater has been online for a few hours.

## Common Examples

Disable retrying advert packets:

```text
set flood.retry.advert off
get flood.retry.advert
```

Ignore a repeater as a successful flood retry echo:
Use this if you have a car repeater and a house repeater; have the house ignore the car.

```text
set flood.retry.ignore 71CE82,C7618C
get flood.retry.ignore
```

Only accept specific downstream relays as flood retry success:
You're in a hole and need to hit a mountain top repeater to get out; keep trying till one you see one of these send out your packet.

```text
set flood.retry.prefixes A58296,860CCA,425E5C
get flood.retry.prefixes
```

Bridge two groups of repeaters:

```text
set flood.retry.bridge on
set flood.retry.bucket 1 71CE82,C7618C
set flood.retry.bucket 2 BEEBB0,425E5C
get flood.retry.bucket.1
get flood.retry.bucket.2
```

Return to simple non-bridge flood retry:

```text
set flood.retry.bridge off
set flood.retry.prefixes none
set flood.retry.ignore none
```

## Added Settings

| Setting | What it does | How to use | Example |
| --- | --- | --- | --- |
| `battery.alert` | Sends opt-in, region-scoped low-battery warnings to `#repeaters` after 30 minutes of uptime. | `get battery.alert`, `get battery.alert.region`, `set battery.alert on [region]`, `set battery.alert off` | `set battery.alert on sea` |
| `battery.alert.low` | Warning threshold percentage. Must be greater than `battery.alert.critical`. | `get battery.alert.low`, `set battery.alert.low <1-100>` | `set battery.alert.low 20` |
| `battery.alert.critical` | Critical threshold percentage. Critical and warning alerts use the same 12-hour resend cooldown. | `get battery.alert.critical`, `set battery.alert.critical <0-99>` | `set battery.alert.critical 10` |
| `recent.repeater` | Shows, seeds, or clears the recent repeater prefix/SNR table used by direct retry and bridge freshness checks. Entries older than 24 hours are removed by a three-hour sweep. | `get recent.repeater`, `get recent.repeater <page>`, `set recent.repeater <prefix> <snr_db>`, `clear recent.repeater` | `set recent.repeater A1B2C3 -8.5` |
| `flood.channel.data` | Turns forwarding of flood `GRP_DATA` channel packets on or off. With the default `on`, `GRP_DATA` repeats normally even when `flood.channel.block.hops` is set. | `get flood.channel.data`, `set flood.channel.data on/off` | `set flood.channel.data off` |
| `flood.channel.data.hops` | Separate hop gate used only when `flood.channel.data` is `off`; `all` blocks `GRP_DATA` at any hop count, `1`-`7` repeats at that hop count or lower and blocks longer paths. | `get flood.channel.data.hops`, `set flood.channel.data.hops <all|1-7>` | `set flood.channel.data.hops 7` |
| `flood.channel.block` | Blocks selected flood `GRP_TXT`/`GRP_DATA` channels when the key validates the packet. New repeater block lists start with editable/deletable `#wardriving h=4`. Add `h=<all|1-7|default>` for a per-channel hop override. | `get flood.channel.block`, `set flood.channel.block[.n] <key|#channel> [name] [h=...]`, `del flood.channel.block[.n]` | `set flood.channel.block #wardriving h=4` |
| `flood.channel.block.hops` | Limits keyed channel-block matches to short flood paths. `all` blocks matching packets at any hop count; `1`-`7` repeats packets at that hop count or lower and blocks longer matches. This does not restrict unkeyed `GRP_DATA`; use `flood.channel.data.hops` for that. | `get flood.channel.block.hops`, `set flood.channel.block.hops <all|1-7>` | `set flood.channel.block.hops 3` |
| `flood.channel.scope` | Assigns a transport-region scope to received unscoped floods. Exact channel keys beat `txt:*`; `login:*` covers the remote-login family, and `other:*` covers every remaining flood type except TRACE, including OTA. TRACE remains unchanged across scope boundaries. ACL permission `4` can manage the table. | `get flood.channel.scope[.n]`, `set flood.channel.scope[.n] <channel|txt:*|login:*|other:*> <region>`, `del flood.channel.scope.<n>|all` | `set flood.channel.scope login:* west` |
| `flood.filter` | Persistent repeater-only forwarding rules for flood routes `0x00`/`0x01`, selected by payload type and optional received hop count/range (omitted means `all`). New tables seed slot 1 with `ota all suspend=tempradio`; only rows marked `suspend=tempradio` are skipped during temporary-radio operation. Login-capable `anon_req`/`path`/`response` types become filterable at hop `7`; flood `txt_msg` becomes filterable at hop `5`. Standard direct traceroute, other direct routing, and local receive/logging are unchanged. | `get flood.filter[.n]`, `set flood.filter[.n] <type> [N|N+|N-M|all] [suspend=tempradio]`, `del flood.filter.<n>|all` | `set flood.filter.1 0x0C all suspend=tempradio` |
| `flood.moderation` | Decrypts keyed `GRP_TXT` channels and applies drop, per-username messages/minute, and maximum-hop controls, optionally matched against the first 1-3 path hashes. Supports `public`, `#channel`, and 128/256-bit channel keys. Sender names and truncated path hashes are moderation hints, not authenticated identities. | `get flood.moderation[.n]`, `set flood.moderation[.n] <channel> <sender> <drop|rate=X/min|hops=N> [path=...]`, `del flood.moderation.<n>|all` | `set flood.moderation public "Noisy User" rate=5/min hops=4` |
| `clock.sync.mesh` | After 30 minutes of uptime, estimates UTC from a configurable consensus of fresh signed-advert or valid Public-channel sources. Only timestamps from firmware build time through build time plus ten years are recorded. Successful CLI, GPS, or WiFi/NTP clock updates suppress LoRa time collection until reboot; after reboot LoRa is the fallback if NTP cannot sync. | `get clock.sync.mesh`, `set clock.sync.mesh <on|off>`, `get clock.sync.status` | `set clock.sync.mesh on` |
| `clock.sync.internet` | Adds a read-only internet/NTP estimate at the same delayed check on WiFi MQTT repeater-observer builds. Other builds retain the setting but report internet unavailable. | `get clock.sync.internet`, `set clock.sync.internet <on|off>` | `set clock.sync.internet on` |
| `clock.sync.drift` | Absolute correction threshold in seconds. The clock is moved forward or backward only when the estimate differs by more than this value. | `get clock.sync.drift`, `set clock.sync.drift <30-86400>` | `set clock.sync.drift 3600` |
| `clock.sync.samples` | Minimum number of distinct, in-window receive paths that must agree before mesh time can be used. A strict majority of all fresh samples is also required. Range `3-16`; default `9`. | `get clock.sync.samples`, `set clock.sync.samples <3-16>` | `set clock.sync.samples 9` |
| `outpath` | Overrides the primary direct route used for replies to the current remote client. | `get outpath`, `set outpath <hops>`, `set outpath direct`, `set outpath clear`, `set outpath flood` | `set outpath A1B2C3,D4E5F6` |
| `altpath` | Adds a secondary direct route for repeater replies to the current remote client. | `get altpath`, `set altpath <hops>`, `set altpath direct`, `set altpath clear`, `set altpath flood` | `set altpath 71CE82,BA09F0` |

## Other Keymind Commands

| Command | What it does | How to use | Example |
| --- | --- | --- | --- |
| `send text.flood` | Sends a `#repeaters` flood text message formatted as `<node_name>: <message>`, with `:` in the node name sent as `;`. | `send text.flood <message>` | `send text.flood checking ridge link` |

## Battery Alerts

Battery alerts are off by default. Enabling requires a named region. With no
region argument, the repeater selects the single deepest (most narrow) region
in the hierarchy; if multiple regions tie, the command asks for an explicit
region. For example, after `region def west pnw wa w-wa sea`, `set
battery.alert on` selects `sea`, while `set battery.alert on w-wa` overrides
the default. Alerts are never sent as unscoped floods, and removing the selected
region stops alerts until a valid scope is selected again.

The repeater suppresses alerts for its first 30 minutes of uptime. It then
checks every 30 minutes and sends a flood text warning to `#repeaters` when
voltage is above `1 V` and the estimated battery percent is below
`battery.alert.low`.

Warnings and critical alerts both use a `12`-hour resend cooldown, beginning
only after the radio reports that the alert transmission completed.

Defaults:

| Setting | Default |
| --- | ---: |
| `battery.alert` | `off` |
| `battery.alert.region` | `<unset>` |
| `battery.alert.low` | `20` |
| `battery.alert.critical` | `10` |

Example:

```text
set battery.alert.low 20
set battery.alert.critical 10
set battery.alert on
get battery.alert
get battery.alert.region
```

CPU power saving remains compatible with the check. The battery timer never
requests a wake earlier than its 30-minute deadline; when the normal loop is
already awake after that deadline, no additional wake is needed. Sleeping time
counts toward the startup delay, and an outbound warning prevents another sleep
until the queued packet has been handled. This is separate from RX duty-cycle
power saving, which only cycles the LoRa receiver and does not stop the main
loop's battery timer.

## Recent Repeater Table

Direct retry uses the recent repeater table when `direct.retry.heard` is `on`.
Bridge buckets also use this table: a configured bucket prefix is active only
when it was heard within the last hour.

Show learned rows:

```text
get recent.repeater
get recent.repeater 2
get recent.repeaters 2
get recent.repeater page 3
```

Seed or correct a prefix:

```text
set recent.repeater A1B2C3 8.5
```

Clear learned and manually seeded rows:

```text
clear recent.repeater
```

Rows are sorted by prefix width, then SNR. A full direct retry failure lowers
the matching row by `0.25 dB`.

Serial CLI pages contain up to `128` rows. Remote LoRa CLI pages contain up to
`7` rows.

## Direct Path Overrides

`outpath` and `altpath` apply to the current remote client ACL entry. They need
remote client context, so they are not useful from the local serial CLI.

Set paths with comma-separated hop hashes. Each hop must be `2`, `4`, or `6`
hex characters, and all hops in one path must use the same width. Hex input is
case-insensitive. Replies use uppercase hex and retain the commas, so the value
can be copied directly into another `set outpath` or `set altpath` command.

```text
get outpath
set outpath A1B2C3,D4E5F6
set outpath direct
set outpath clear
set outpath flood
get altpath
set altpath 71CE82,BA09F0
set altpath clear
```

For example, both `set altpath 600000,0d2784,f8dada` and
`Set altpath 600000,0d2784,f8dada` store the same path and reply with:

```text
> 600000,0D2784,F8DADA
```

The first CLI word is case-insensitive (`set`, `Set`, and `SET` are the same,
as are `get`, `Get`, and the other command verbs). Argument case is preserved.

`set outpath direct` sets a zero-hop direct route for a client reachable without
repeaters. `set outpath clear` forgets the override and lets normal path
discovery fill it again. `set outpath flood` forces replies to use flood packets
until the client logs in again.

When `outpath` is a valid direct path and `altpath` is also a valid, different
direct path, repeater DM replies send two packets: one on `outpath` and one on
`altpath`. The secondary `altpath` copy does not create its own direct-retry
state, so retry tracking stays attached to the primary `outpath` packet.
`altpath clear` disables the secondary direct reply. `altpath flood` is accepted
for command symmetry, but it does not create a second flood reply; only a valid
direct `altpath` sends the second packet.

## Direct Retry Settings

Direct retry applies to direct-routed packets. A queued resend is canceled when the next-hop echo is heard. Repeaters expose the settings below; non-repeater firmware uses the same packet-type timing rules with fixed shared base/step timing.

| Setting | What it does | How to use | Example |
| --- | --- | --- | --- |
| `retry.preset` | Applies shared direct and flood retry defaults. Values: `infra`, `rooftop`, `mobile` or `0`, `1`, `2`. | `get retry.preset`, `set retry.preset <value>` | `set retry.preset rooftop` |
| `direct.retry.heard` | Uses the recent repeater table as the direct retry eligibility gate. | `get direct.retry.heard`, `set direct.retry.heard on/off` | `set direct.retry.heard on` |
| `direct.retry.margin` | SNR margin in dB above the SF-specific receive floor. | `get direct.retry.margin`, `set direct.retry.margin <0-40>` | `set direct.retry.margin 5` |
| `direct.retry.count` | Maximum direct retry attempts after initial TX. Direct-routed type 2 text packets always use 21 attempts regardless of this setting or the short-path cap. | `get direct.retry.count`, `set direct.retry.count <1-15>` | `set direct.retry.count 15` |
| `direct.retry.base` | Base wait in milliseconds before retry; packet-length add-on is 3x for TRACE and ANON_REQ/type 7, 7x for TXT_MSG/type 2, and 6x for other direct retry packets. | `get direct.retry.base`, `set direct.retry.base <10-5000>` | `set direct.retry.base 175` |
| `direct.retry.step` | Milliseconds added per retry attempt after the base, packet-length add-on, and random forwarding jitter. | `get direct.retry.step`, `set direct.retry.step <0-5000>` | `set direct.retry.step 100` |
| `direct.retry.cr` | Adaptive coding-rate thresholds for repeater direct retry packets. Repeaters use `CR4`, `CR5`, `CR7`, or `CR8`, then escalate by attempt: CR4, CR5, CR7, CR7, then CR8 from a CR4 start; CR5, CR7, CR7, then CR8 from a CR5 start. Non-repeaters start at the current radio CR and follow the same escalation pattern, clamped at CR8. | `get direct.retry.cr`, `set direct.retry.cr <cr4_min>,<cr5_min>,<cr7_min>,<cr8_max>`, `set direct.retry.cr off` | `set direct.retry.cr 10.0,7.5,2.5,0` |

The default adaptive coding-rate profile is `10.0,7.5,2.5,2.5`.
SNR `10.0 dB` and up uses `CR4`, `7.5 dB` and up uses `CR5`,
`2.5 dB` and down uses `CR8`, and the middle band uses `CR7`. If no
recent repeater table entry is available, retry packets use `CR5`. Use
`set direct.retry.cr off` to disable adaptive coding-rate overrides. Repeater
attempts escalate from the adaptive starting CR: `CR4`, `CR5`, `CR7`, `CR7`,
then `CR8` from a `CR4` start; `CR5`, `CR7`, `CR7`, then `CR8` from a `CR5`
start. Non-repeaters use the current radio CR as the first retry CR and follow
the same pattern up to `CR8`.

Preset details:

| Preset | Base | Count | Step | SNR gate |
| --- | ---: | ---: | ---: | --- |
| `infra` | `275 ms` | `4` | `150 ms` | SF floor + `15 dB` |
| `rooftop` | `175 ms` | `15` | `100 ms` | SF floor + `5 dB` |
| `mobile` | `175 ms` | `15` | `50 ms` | SF floor |

Example for a quiet fixed repeater:

```text
set retry.preset rooftop
set direct.retry.heard on
set direct.retry.margin 5
```

Example for a moving or weak-link node:

```text
set retry.preset mobile
set direct.retry.margin 0
```

## Flood And Advert Settings

Flood retry applies to flood-routed packets. A queued retry is canceled when the
same packet is heard from a qualifying, non-ignored repeater. Bridge mode uses
the bucket rules below instead.

| Setting | What it does | How to use | Example |
| --- | --- | --- | --- |
| `flood.retry.count` | Base flood retry attempts after initial TX. Role path scaling happens first, then all builds apply payload caps: `REQ` is `0`; `GRP_TXT` keeps up to `15`; remote-login `RESPONSE`, `TXT_MSG`, `ANON_REQ`, and `PATH` keep up to `15` at path count 0 and cap at `2` in transit; every other flood type caps at `1`. A lower calculated value is preserved, and `0` disables flood retry. | `get flood.retry.count`, `set flood.retry.count <0-15>` | `set flood.retry.count 7` |
| `flood.retry.path` | Maximum path hash count eligible for flood retry, or `off` to disable the gate. | `get flood.retry.path`, `set flood.retry.path <0-63/off>` | `set flood.retry.path 1` |
| `flood.retry.group.path` | Additional path gate for group data (`type=6`) flood retries. The stricter of this and `flood.retry.path` applies; `off` disables only this additional gate. Setting the general path gate to `0` forces this setting to `off`; a named preset restores the default of `1`. | `get flood.retry.group.path`, `set flood.retry.group.path <0-63/off>` | `set flood.retry.group.path 1` |
| `flood.retry.advert` | Allows or blocks retry for node advert packets (`type=4`). Default is `off`. | `get flood.retry.advert`, `set flood.retry.advert on/off` | `set flood.retry.advert off` |
| `flood.retry.prefixes` | Target prefixes. If set, only same-packet echoes from matching last-hop prefixes cancel a retry. | `get flood.retry.prefixes`, `set flood.retry.prefixes <prefixes/none/off>` | `set flood.retry.prefixes BEEBB0,425E5C` |
| `flood.retry.ignore` | Ignored prefixes. In non-bridge retry, ignored last-hop echoes do not cancel retry. | `get flood.retry.ignore`, `set flood.retry.ignore <prefixes/none/off>` | `set flood.retry.ignore 71CE82,C7618C` |
| `flood.retry.bridge` | Enables bucket-based bridge retry logic. | `get flood.retry.bridge`, `set flood.retry.bridge on/off` | `set flood.retry.bridge on` |
| `flood.retry.bucket.<n>` | Shows one bridge bucket. Buckets are numbered `1`-`6`. | `get flood.retry.bucket.<n>` | `get flood.retry.bucket.1` |
| `flood.retry.bucket` | Sets bridge bucket prefixes. | `set flood.retry.bucket <1-6> <prefixes/none/off>` | `set flood.retry.bucket 1 71CE82,C7618C` |

Forwarded neighbor adverts also use an automatic echo guard in every build. If this node hears a downstream, longer-path echo after transmitting an advert whose signed timestamp is less than six hours old, it will not forward that exact advert again during the six-hour age window. This guard works even when `flood.retry.advert` is off and does not affect self-originated adverts.

Self-originated advert retries are deliberately slow: the first retry waits at least one extra minute beyond the normal airtime-aware delay. Queueing a newer self advert retires queued and future retry attempts for older self adverts without disturbing other flood retry sequences. Companion firmware allows the one slow retry for its own adverts but not for neighbor adverts it relays.

The shared retry preset sets these flood defaults:

| Preset | Retry count | Path gate | Group-data path gate |
| --- | ---: | ---: | ---: |
| `infra` | `1` | `1` | `1` |
| `rooftop` | `3` | `2` | `1` |
| `mobile` | `15` | `1` | `1` |

Example for path-gated retry:

```text
set retry.preset rooftop
set flood.retry.path 1
set flood.retry.group.path 1
set flood.retry.advert off
set flood.retry.ignore 71CE82,C7618C
```

## North South Buckets

Buckets describe groups of repeaters on different sides of this relay. Bucket
numbers do not have built-in meanings; this example uses bucket `1` for North
and bucket `2` for South.

```text
              North bucket 1
        +-----------------------+
        | A1B2C3       D4E5F6   |
        | North A      North B  |
        +-----------+-----------+
                    |
                    v
              +-----------+
              | This node |
              +-----------+
                    ^
                    |
        +-----------+-----------+
        | 71CE82       C7618C   |
        | South A      South B  |
        +-----------------------+
              South bucket 2
```

Configure the buckets:

```text
set flood.retry.bridge on
set flood.retry.bucket 1 A1B2C3,D4E5F6
set flood.retry.bucket 2 71CE82,C7618C
set flood.retry.ignore none
```

Packet heard from the North:

```text
     heard source
         |
         v
  +--------------+        retry targets
  | North bucket | -----> South bucket
  | bucket 1     | -----> Other fresh/unbucketed relays
  +--------------+
```

Packet heard from the South:

```text
     heard source
         |
         v
  +--------------+        retry targets
  | South bucket | -----> North bucket
  | bucket 2     | -----> Other fresh/unbucketed relays
  +--------------+
```

Packet heard from an unbucketed or pathless source:

```text
     heard source
         |
         v
  +--------------+        retry targets
  | Other bucket | -----> North bucket
  | implicit     | -----> South bucket
  +--------------+
```

Bridge retry stays eligible until every target bucket has been heard or
`flood.retry.count` is exhausted. A configured bucket is a target only when at
least one of its prefixes is fresh in `recent.repeater`. Prefixes in
`flood.retry.ignore` never count as bucket hits.

Configuration reports a warning when prefixes in different buckets, including
bucket 7 (`flood.retry.prefixes`), share the same first byte. A 1-byte path cannot
distinguish those buckets. Bridge mode therefore excludes every matching bucket
when that short prefix is the source, and credits every matching target bucket
when it is heard as an echo. This prevents an ambiguous short prefix from keeping
an impossible target outstanding through every retry.

Each flood retry wait retains the fixed maximum-frame plus 20 packet-airtime
delay, then adds random jitter from zero to 200 percent of one additional packet
airtime. This keeps nearby repeaters from repeating a collision on fixed timing
while capping the added wait at two frames.

Only one enhanced retry sequence can be active for the same logical flood
packet. Identical floods still receive their normal transmission, but do not
multiply the extra attempts. Evicted queued retries release their bridge state,
and the final echo wait does not reserve a packet-pool entry.

Earlier path hops from a successful bridge echo refresh a separate per-bucket
reachability cache without an SNR value. Only the final hop, which actually sent
the received RF frame, updates `recent.repeater` and its SNR. Indirect path hops
therefore cannot change direct-retry SNR gating or coding-rate selection.

## Troubleshooting

If advert packets are still retrying:

```text
get flood.retry.advert
set flood.retry.advert off
```

If ignored prefixes still appear in `flood retry good` logs:

```text
get flood.retry.ignore
set flood.retry.ignore <prefix>
```

The ignored prefix must match the last hop shown as `heard=<prefix>`. For example, this log needs `C7618C` in the ignore list:

```text
flood retry good (... path=7773D0>C7618C, heard=C7618C ...)
```

If retries are too aggressive:

```text
set flood.retry.count 1
set flood.retry.path 1
set direct.retry.count 4
```

If retries are too sparse:

```text
set flood.retry.count 7
set flood.retry.path 2
```
