# Altirra 850 Modem Reference

This reference describes how the host launcher configures Altirra, the emulated
850, and the modem path used by Mutineer. Source of truth:
`tools/run_altirra_850.py`, `tools/run_mutineer_telnet_test.py`, and
`tools/run_mms_hatabs_probe.py`.

## Runtime Path

The intended emulated communications path is:

```text
Atari BASIC/CIO -> MMS HATABS -> R: -> RHND850.COM -> Altirra 850 -> modem device -> host TCP
```

The generated Altirra profile uses an `850` device with `baudex=true` and
`emulevel=1`. In Altirra source and behavior, that mode provides the stub-loader
path while keeping the HLE R: handler available. The modem device is attached
as a child of the 850 bus.

## Profile Generation

`tools/run_altirra_850.py` writes a portable Altirra INI under
`results/altirra-850/`, then copies it to `tools/altirra/4.40/Altirra.ini`.
The portable registry root must be:

```text
User\Software\virtualdub.org\Altirra
```

Altirra ignores portable sections that are not rooted under `User\` or
`Shared\`, so profile sections must keep that prefix.

The profile mounts:

- the selected ATR as `D1:`;
- `third_party/SDX450_maxflash8.car`, unless `MUTINEER_USE_SDX=0`;
- `MUTINEER_EXTRA_DISK`, when set.

## Launch Commands

Launch the current versioned ATR:

```sh
make altirra-850-run
```

Launch a specific ATR:

```sh
MUTINEER_ATR=source/atr/atari-mutineer-v1.1.154.atr make altirra-850-run
```

Connect from the host to the default modem listener:

```sh
telnet 127.0.0.1 6507
```

## Environment Variables

`tools/run_altirra_850.py`:

- `MUTINEER_ATR`: ATR path. Default is the current versioned ATR.
- `MUTINEER_MODEM_PORT`: host modem port. Default `6507`.
- `MUTINEER_CONNECT_RATE`: Altirra modem connection rate. Default `2400`.
- `MUTINEER_TELNET`: enable telnet negotiation in the modem profile.
- `MUTINEER_TELNETLF`: enable Altirra telnet LF handling.
- `MUTINEER_USE_SDX`: mount SDX cartridge when truthy. Default `1`.
- `MUTINEER_CART`: override cartridge image path.
- `MUTINEER_CART_MAPPER`: override cartridge mapper string.
- `MUTINEER_EXTRA_DISK`: mount a second ATR/disk image.
- `MUTINEER_ALTIRRA_DEBUG_LOG`: write Altirra debug output to a chosen path.

Runtime tests also use:

- `MUTINEER_ALTIRRA_DEBUG`: when truthy, write per-run Altirra debug logs.
- `MUTINEER_CONNECT_DELAY`: wait before connecting to the emulated modem.
- `MUTINEER_SEND_DELAY`: delay between scripted telnet sends.
- `MUTINEER_TEST_TIMEOUT`: telnet test timeout.
- `MUTINEER_XMODEM_TIMEOUT`: XMODEM test timeout.

## Baud Settings

The host modem profile defaults to `connect_rate=2400`. MMS defaults its R:
`XIO 36` baud code to `12`, also documented as 2400 in `mms/src/config.inc`.

Atari BASIC can set the MMS baud code used by the next `MMS_MOPEN`:

```basic
MBASE=PEEK(1004)+256*PEEK(1005)
MBAUD=MBASE+90:MBCODE=MBASE+156
R=USR(MBAUD,13):REM 4800 ON NEXT MOPEN
POKE MBCODE,14:REM 9600 ON NEXT MOPEN
```

Keep the Altirra modem `MUTINEER_CONNECT_RATE` and the MMS R: baud code aligned
when testing speed-sensitive behavior.

## Listener And Outbound Modes

The normal BBS test path uses a host listener on `MUTINEER_MODEM_PORT`.
MMS HATABS probe ATRs can also use outbound mode: the Atari-side probe dials
`ATDI <host> <port>`, and the host test accepts the connection.

Probe-specific dial variables:

- `MMS_PROBE_DIAL_HOST`: default `127.0.0.1`.
- `MMS_PROBE_DIAL_PORT`: default `MUTINEER_MODEM_PORT` or `6507`.
- `MMS_HATABS_PROBE_CONNECT_MODE`: default `outbound`.

## Result Files

Manual Altirra launcher profiles are written under `results/altirra-850/`.
Automated test profiles, transcripts, logs, screenshots, and JSON results live
under the relevant `results/` subdirectory documented in
[Testing And Evidence](TESTING_AND_EVIDENCE.md).