From a5993dd934c93cfee691d23f93c5d13a1e732cb9 Mon Sep 17 00:00:00 2001 From: Simon Date: Wed, 17 Jun 2026 17:35:43 +0100 Subject: [PATCH] Add OPTIONS cheat sheet --- docs/options-cheatsheet.md | 186 +++++++++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 docs/options-cheatsheet.md diff --git a/docs/options-cheatsheet.md b/docs/options-cheatsheet.md new file mode 100644 index 0000000..c9b9cff --- /dev/null +++ b/docs/options-cheatsheet.md @@ -0,0 +1,186 @@ +# FreeDMR OPTIONS Cheat Sheet + +`OPTIONS` lets a connected repeater/hotspot request session settings from a +FreeDMR master. These settings last for the current client session. When the +client disconnects or times out, FreeDMR resets the session back to the server +configuration defaults. + +## Format + +Use semicolon-separated `KEY=VALUE` fields: + +```text +KEY=secret;TS1=91,92;TS2=235;DEFAULT_DIAL_TS1=4400;DEFAULT_DIAL_TS2=2350;TIMER=15 +``` + +Keep key names exact. Avoid spaces around key names. Commas inside TG lists may +have simple whitespace. + +## Common Examples + +Static TGs on both slots: + +```text +TS1=91,92;TS2=235 +``` + +Default dial-a-TG on slot 2: + +```text +DEFAULT_DIAL_TS2=2350 +``` + +Default dial-a-TG on both slots: + +```text +DEFAULT_DIAL_TS1=4400;DEFAULT_DIAL_TS2=2350 +``` + +Set slot 2 to no default dial-a-TG connection: + +```text +DEFAULT_DIAL_TS2=0 +``` + +or, using the legacy alias: + +```text +DIAL= +``` + +Disable dial-a-TG private-call control: + +```text +DIALTG=0 +``` + +Disable automatic dynamic conventional TG routing: + +```text +DYNAMIC=0 +``` + +Use a user API key: + +```text +KEY=my-secret-key +``` + +## Supported Fields + +| Field | Meaning | +| --- | --- | +| `KEY` | User/session API key. If a key is already set for the session, later OPTIONS must include the same key. | +| `TS1` | Comma-separated static TG list for slot 1. Empty means no static TGs. | +| `TS2` | Comma-separated static TG list for slot 2. Empty means no static TGs. | +| `DEFAULT_DIAL_TS1` | Default dial-a-TG target for slot 1. `0` or empty means not connected to any default TG. | +| `DEFAULT_DIAL_TS2` | Default dial-a-TG target for slot 2. `0` or empty means not connected to any default TG. | +| `TIMER` | Legacy/default user-activated timeout in minutes. `0` means effectively unlimited. | +| `TG_TIMER` | Conventional TG dynamic/static timeout in minutes. Falls back to `TIMER`. | +| `DIAL_TIMER` | Dial-a-TG timeout in minutes. Falls back to `TIMER`. | +| `TS1_TIMER` | Slot 1 timeout in minutes. Overrides `TG_TIMER`/`DIAL_TIMER` for slot 1 unless a more specific timer is set. | +| `TS2_TIMER` | Slot 2 timeout in minutes. Overrides `TG_TIMER`/`DIAL_TIMER` for slot 2 unless a more specific timer is set. | +| `TS1_TG_TIMER` | Slot 1 conventional TG timeout in minutes. | +| `TS2_TG_TIMER` | Slot 2 conventional TG timeout in minutes. | +| `TS1_DIAL_TIMER` | Slot 1 dial-a-TG timeout in minutes. | +| `TS2_DIAL_TIMER` | Slot 2 dial-a-TG timeout in minutes. | +| `DIALTG` | Enable/disable dial-a-TG private-call control. Use `1` or `0`. | +| `DYNAMIC` | Enable/disable automatic dynamic conventional TG routing. Use `1` or `0`. | +| `VOICE` | Enable/disable voice ident. Use `1` or `0`. | +| `SINGLE` | Enable/disable single-TG mode. Use `1` or `0`. | +| `IDENTTG` | Override voice ident TG. Integer TG value. | +| `VOICETG` | Alias for `IDENTTG`. | +| `LANG` | Announcement language, if installed on the server. Example: `en_GB`. | + +## Legacy Aliases + +These are still accepted for compatibility: + +| Legacy field | Current meaning | +| --- | --- | +| `DIAL` | Alias for `DEFAULT_DIAL_TS2`. Empty means slot 2 is not connected to any default TG. | +| `DEFAULT_REFLECTOR` | Alias for `DEFAULT_DIAL_TS2`. Deprecated. | +| `StartRef` | DMR+ style alias for `DEFAULT_DIAL_TS2`. | +| `RelinkTime` | DMR+ style alias for `TIMER`. | +| `TGTimer` | DMR+ style alias for `TG_TIMER`. | +| `DialTimer` | DMR+ style alias for `DIAL_TIMER`. | +| `TS1Timer` | DMR+ style alias for `TS1_TIMER`. | +| `TS2Timer` | DMR+ style alias for `TS2_TIMER`. | +| `IDENT` | Alias for `VOICE`. | +| `TS1_1` ... `TS1_9` | DMR+ style slot-1 static TG fields. Combined into `TS1`. | +| `TS2_1` ... `TS2_9` | DMR+ style slot-2 static TG fields. Combined into `TS2`. | +| `UserLink` | Accepted and ignored. | + +## Dial-a-TG Notes + +- Dial-a-TG uses RF-visible TG9 on the relevant slot. +- Slot 1 and slot 2 dial-a-TG state are independent. +- Private-call control on slot 1 controls slot 1. +- Private-call control on slot 2 controls slot 2. +- Voice prompts for dial-a-TG are sent on TG9 on the controlling slot. +- `DEFAULT_REFLECTOR`, `DIAL`, and `StartRef` only affect the slot-2 default. + Use `DEFAULT_DIAL_TS1` for slot 1. + +## Timer Precedence + +Timer fields are in minutes. `0` means effectively unlimited. + +For each active route, FreeDMR uses the most specific configured timer: + +1. `TS1_TG_TIMER`, `TS2_TG_TIMER`, `TS1_DIAL_TIMER`, or `TS2_DIAL_TIMER` +2. `TS1_TIMER` or `TS2_TIMER` +3. `TG_TIMER` or `DIAL_TIMER` +4. `TIMER` + +Examples: + +- `TIMER=15` gives all user-activated TG and dial-a-TG routes a 15 minute timer. +- `TG_TIMER=10;DIAL_TIMER=30` gives conventional TGs 10 minutes and dial-a-TG + routes 30 minutes. +- `TS1_DIAL_TIMER=5;TS2_DIAL_TIMER=30` gives slot 1 and slot 2 dial-a-TG + independent timers. + +## Valid Dial-a-TG Values + +- `0` or empty: not connected to any default TG. +- `1` to `999999`: valid range, except reserved/control targets. +- Reserved/control targets such as `6`, `7`, `8`, and the control range + `4001` to `4999` are not accepted as default dial-a-TG values. +- `4000` is disconnect control, not a default link target. +- `5000` is status control, not a default link target. + +## Practical Starter Strings + +Simple hotspot, no static TGs, default dial-a-TG on TS2: + +```text +TS1=;TS2=;DEFAULT_DIAL_TS2=2350;TIMER=15 +``` + +Repeater with static national TGs and dial-a-TG on both slots: + +```text +TS1=91,92;TS2=235;DEFAULT_DIAL_TS1=4400;DEFAULT_DIAL_TS2=2350;TIMER=15 +``` + +Control-heavy setup with API key and no dynamic conventional TG routing: + +```text +KEY=my-secret-key;TS1=91;TS2=235;DIALTG=1;DYNAMIC=0;TIMER=15 +``` + +Separate conventional TG and dial-a-TG timers: + +```text +TS1=91;TS2=235;DEFAULT_DIAL_TS1=4400;DEFAULT_DIAL_TS2=2350;TG_TIMER=10;DIAL_TIMER=30 +``` + +## Troubleshooting + +- Use `0` or an empty value when the slot should not connect to any default TG. +- Use only `0` or `1` for boolean fields such as `DIALTG`, `DYNAMIC`, `VOICE`, + and `SINGLE`. +- Invalid fields are logged by the server. Valid fields in the same OPTIONS + string may still be applied. +- If settings do not appear to change, check that the correct `KEY=...` is being + sent for the session.