---
title: DOS MQTT LAB
emoji: 🖥️
colorFrom: green
colorTo: blue
sdk: static
pinned: false
---

# DOS MQTT LAB — DOS programs that really go online

Two **FreeDOS** machines run in the page (v86 x86 emulator). Each has an emulated **NE2000** network card. Inside DOS:

1. the Crynwr **NE2000 packet driver** is loaded,
2. mTCP's **DHCP.EXE** obtains an address (192.168.86.100),
3. **A.EXE** (listener) and **B.EXE** (sender) are real DOS programs, built with Open Watcom against the mTCP TCP/IP stack. They do their own DNS lookup, TCP handshake and speak **MQTT 3.1.1**.

| Program | Behaviour |
|---|---|
| `A.EXE` | Connects, subscribes to the shared topic, and prints each received message. One second later it prints an `echo` line. |
| `B.EXE` | Run once: connects, publishes `Hello from DOS B at HH:MM:SS` (DOS clock), disconnects, exits. |

The page types `A` into machine A once and types `B` into machine B every 5 seconds (DOS has no scheduler). Both DOS screens and an observation log show whether A received what B sent.

## How the packets reach a public broker

Browsers cannot open raw TCP sockets, and Hugging Face static Spaces have no server. v86 terminates the guest's TCP streams; `bridge.js` plays a tiny in-page WISP server that relays every stream the guest opens on **port 1883** to a public broker's **MQTT-over-WebSocket (WSS)** endpoint. MQTT is identical on both transports, so the bytes DOS writes are exactly what the broker receives. DNS goes through DNS-over-HTTPS (Cloudflare) via v86.

So the DOS side is genuine TCP/IP; only the last hop (browser → broker) is a WebSocket.

## Things to know

- **Default broker** is `wss://broker.emqx.io:8084/mqtt`. Public brokers vary: in our tests `broker.hivemq.com` often took ~10 s to answer a CONNECT (or never did), while EMQX and `test.mosquitto.org` answered every time. Pick another from the list if one misbehaves.
- **"Background" A** is a separate DOS machine, because DOS itself is single-tasking.
- The DOS clock is **UTC**.
- Both machines are on isolated virtual networks, so they can both use 192.168.86.100.
- If a B run has not finished when the next 5-second tick arrives, that tick is skipped and logged.
- Copy the topic to another tab or device to see messages travel between separate browsers.
- The page needs a modern browser (WebAssembly, `DecompressionStream`).

## Sources and licenses

See `LICENSE`, `NOTICE.md` and `src/` (DOS program sources, build scripts, boot-disk scripts). GPL-3.0-or-later.

## DOS × Gradio (`gradio.html`)

`G.EXE` is a third DOS program: it sends a question to a public **Gradio Space** (default `tencent/Hy3`) with plain HTTP through the same emulated NE2000/mTCP stack, reads the streamed answer and prints it. The page forwards the plain HTTP as HTTPS, but only to `*.hf.space` paths starting with `/gradio_api/`, and checks that the answer shown on the DOS screen equals the one Gradio returned. Use English (DOS shows ASCII). Open `gradio.html`.

## Developer package

`dev/dosmqtt-dev.zip` holds the sources, build scripts, tests and the developer handover (`dev/HANDOFF.md`). It also contains the mTCP source archive that A.EXE / B.EXE are linked against. Rebuild everything with `tools/build_all.sh`.