OpsLog/wiki/Connections.md

# Connections

Settings → **Connections** is where OpsLog talks to other programs and to
hardware over the network: what it **listens** to, what it **sends**, and
messages you write yourself.

It was called *UDP* until it grew a second transport — a row can now send an
**HTTP GET** instead of a datagram, which is what most home-made antenna
switches understand.

Each row has a name, a direction, a service type, a port, and an on/off switch.
**Everything sent and received is written to the application log**, so a row
that does not work can be diagnosed rather than guessed at — see
[[Troubleshooting]] for where the log lives.

---

## Inbound — what OpsLog listens to

| Service | Sends it | Use |
|---|---|---|
| **WSJT-X / JTDX / MSHV** | those programs, port 2237 | Log their QSOs automatically, follow the DX call being worked, and show their decodes. Multicast is normal here. |
| **ADIF over UDP** | JTAlert, GridTracker, FLDIGI | A text ADIF record per logged QSO. |
| **N1MM Logger+** | N1MM | Its XML contact record. |
| **Remote callsign** | DXHunter and similar | A callsign — and optionally a frequency and mode — to load into the entry form and tune to. |

### Multicast or unicast?

WSJT-X and MSHV normally broadcast to a **multicast group** (usually
`239.255.0.1`) so several programs can hear them at once. Tick *Multicast* and
give the group. A program sending to one address only needs unicast — leave it
unticked.

If you also run **GridTracker**, or anything else that listens to your decoder,
read [[Digital Modes and GridTracker]] first: two programs on one unicast port
work or not depending on which started first, which is the usual cause of
"the decodes arrived yesterday and not today".

A multicast group is an address between `224.0.0.0` and `239.255.255.255`.
`127.0.0.1` is not one — a row ticked *Multicast* with a loopback or LAN
address in the group box listens on unicast instead, and says so in the log.

> **Do not put an inbound row and an outbound row on the same port.** OpsLog
> then receives its own messages, and something it publishes can come back as a
> command. It says so in the log when it spots the arrangement:
> *"X sends on port 2241 and Y listens on it — OpsLog will receive its own
> messages there; give one of the two another port."*

---

## Outbound — what OpsLog sends

| Service | Format | Fires on |
|---|---|---|
| **ADIF message** | a plain ADIF record | each QSO logged |
| **WSJT-X logged QSO** | the same ADIF wrapped in a WSJT-X datagram | each QSO logged |
| **Relay the WSJT-X stream** | every datagram received, byte for byte | as it arrives |
| **PstRotator frequency** | `<PST><FREQUENCY>` | frequency change |
| **N1MM RadioInfo** | N1MM's RadioInfo XML | frequency or mode change |
| **Custom message** | whatever you write | a trigger you pick |

### Relay the WSJT-X stream

WSJT-X, JTDX and MSHV each send to **one address**. Without a relay the choice
is between OpsLog and JTAlert / GridTracker, not both.

This row re-sends every datagram an inbound WSJT-X row receives, **byte for
byte**, to another program — so OpsLog stops being the reason you cannot run the
two together:

```
WSJT-X ──▶ OpsLog (inbound, 2237) ──relay──▶ GridTracker (2238)
```

Point it at the **other** program's port. Pointing it at one of OpsLog's own
listening ports would feed the stream back into itself for ever; the relay
refuses and says so in the log rather than flooding the network.

Nothing is added to the datagrams — no origin header. Some relays in the field
prepend one (`127.0.0.1:2237|`), which is exactly the kind of thing OpsLog has
had to write code to survive on the receiving side; passing it on downstream
would be repeating that mistake.

> If every program involved can do **multicast**, prefer that: each one gets its
> own copy and no relay is needed. See [[Digital Modes and GridTracker]].

### Which one for another logger?

If a logger says it accepts "WSJT-X UDP", it wants the **WSJT-X logged QSO**
row — it listens on the WSJT-X interface and silently discards a bare ADIF
record. Logger32 is the usual case. A logger that documents a plain ADIF
listener wants the **ADIF message** row instead. They are two rows because they
are two different things on the wire; enable the one your logger asks for, not
both, or the QSO arrives twice.

---

## Custom messages

The general case: **you choose when it fires, what it says, and how it leaves.**
This is how a home-made antenna switch, a relay box or a home-automation server
gets told what the station is doing.

### 1. Pick the trigger

| Trigger | Fires when |
|---|---|
| **QSO logged** | a contact is saved |
| **Band change** | the radio changes band — or, on a station with no CAT, the Band selector in the entry strip |
| **Rotator command** | the antenna is told to turn (compass, SP/LP buttons, a spot click) |
| **Lookup done** | a callbook lookup returns |

### 2. Write the message

Anything in `{braces}` is replaced. What is available depends on the trigger:

| Trigger | Placeholders |
|---|---|
| QSO logged | `{call}` `{band}` `{band_m}` `{mode}` `{grid}` `{name}` `{country}` `{rst_s}` `{rst_r}` `{comment}` `{date}` `{time}` `{freq_hz}` `{freq_mhz}` `{dxcc}` |
| Band change | `{band}` `{band_m}` `{mode}` `{freq_hz}` `{freq_mhz}` |
| Rotator command | `{az}` `{el}` `{path}` (`SP`, `LP` or empty) |
| Lookup done | `{call}` `{name}` `{grid}` `{country}` `{qth}` `{state}` `{dxcc}` |

`{band}` is `20m`; `{band_m}` is just `20`, because an antenna switch usually
wants the number and nothing else.

### 3. Choose the transport

- **UDP** — a datagram to an address and port. You choose the line ending.
- **URL** — an HTTP GET. Values are URL-encoded automatically.

### Examples

**Turn an antenna switch on every band change, over HTTP:**

```
Trigger:    Band change
Transport:  URL
URL:        http://192.168.1.50/set?band={band_m}
```
20 m → `http://192.168.1.50/set?band=20`

**Tell a rotator display where the antenna is going:**

```
Trigger:    Rotator command
Transport:  UDP  →  192.168.1.77:8100
Message:    <AZIMUT>{az}</AZIMUT><PATH>{path}</PATH>
```

**Announce each QSO to a shack dashboard:**

```
Trigger:    QSO logged
Transport:  URL
URL:        http://homeassistant.local:8123/api/webhook/qso?call={call}&band={band}&mode={mode}
```

> Credentials in a URL are sent as typed — this is meant for a LAN. Passwords
> are **redacted in the log** so a log file can be shared safely.

### When a band change is a band change

The Band-change trigger follows **the radio**, because an antenna switch should
follow the radio and not what is being typed. Changing band in the entry strip
drives the rig, the rig reports the new band, and the trigger fires from that.

On a station whose rig OpsLog does not control there is nothing to report back,
so the **Band selector itself** counts as the band change. The 🔒 lock on Band
or Frequency suppresses it: a lock means the entry is deliberately decoupled
from the rig, and nothing should move for a contact logged from last year.

---

## Diagnosing a row that does nothing

The log names every message. In order, check:

1. **Is the row enabled?** The list shows it.
2. **`udp: Reload done — N server(s) running`** at startup, and one
   `cfg id=… name=… dir=… service=… port=…` line per row. A row that failed to
   start is listed with its error.
3. **Outbound:** `udp: [NAME] sent N bytes to ADDRESS (service)` for a datagram,
   or the URL for an HTTP row.
4. **A message that renders empty is skipped** and the log says so — usually a
   placeholder that the trigger does not provide.
5. **`a QSO was logged but no outbound "ADIF message" row is enabled`** — the
   answer to "why does my other logger get nothing".

See also: [[Amplifiers and Switches]] for relay boards and their own automatic
control, and [[DX Cluster and Spots]] for spot sources.