Multiplayer & serial ports

How-to's

Lists

Audio

Video

Issues

Dev

Misc

Table of index (click to expand)

Introduction
Multiplayer
- Host
- Client
Serial ports
See also

Introduction

Since online multiplayer gaming with DOSBox Staging is heavily dependent on multiplexing serial connections over Enet transport layer we're focusing on both on this page. Enet is a transport layer implemented on top of UDP that is robust and can be used over mobile networks like the LTE while ensuring best effort FIFO.

Networking code in DOS and Windows 3.x games is often based on principle of circuit switched networks like telephone networks that offered high connection quality compared to packet switched networks like the internet we use today. These considerations make Enet almost obligatory for an enjoyable DOS gaming experience over the internet.

Multiplayer

Preconditions for multiplayer gaming:

Realtime communication outside of the game lobby for connection to be established for example through Discord, IRC, SMS, voice or face to face.
One player participating in the game must have port forwarding enabled for a single incoming UDP port to facilitate the game to be hosted if they're behind a firewall. The host must also know their external IP address visible to the internet. The easiest way to figure this out is to search Google for What's my IP.

serialmain

The main program for configuring serial ports on DOSBox Staging is SERIAL.COM.

Host

serialhost1

Lets do a simple null modem based setup. We're running SERIAL.COM with parameters 1 which means COM1 serial port is used, nullmodem means null modem interface is used, port:1250 means we're listening on port 1250 and sock:1 means we're using Enet which is a UDP based transport.

serialhost2

Successful initialisation of Enet and null modem interface can be verified from DOSBox Staging console.

atf1

We're using Jane's ATF: Advanced Tactical Fighters as an example. Usually games indicate null modem interface as serial so we select that. DOS era game multiplayer interfaces have wild variations in user interface and operating principles so its a good idea to refer to game manual for information on how to set it up according to your needs.

atf2

In this final screen before connection is established and players enter the game lobby its usually enough to select the correct serial port in this case COM1 and leave the rest of the settings alone. This avoids potential issues like baud rate mismatch between the UARTs.

Select Answer, wait for connection to be established or view DOSBox Staging console to verify if other players have established Enet transport layer session to your system and are just setting up the game themselves to connect to your host:

serialhost3

Client

serialclient1

Lets do a simple null modem based setup. We're running SERIAL.COM with parameters 1 which means COM1 serial port is used, nullmodem means null modem interface is used, server:<IP address> means we're connecting to a host with designated IP address, port:1250 means we're connecting to the host on port 1250 and sock:1 means we're using Enet which is a UDP based transport.

serialclient2

Successful initialisation of Enet and null modem interface can be verified from DOSBox Staging console. We've also successfully established Enet transport layer session to the host.

atf1

We're using Jane's ATF: Advanced Tactical Fighters as an example. Usually games indicate null modem interface as serial so we select that. DOS era game multiplayer interfaces have wild variations in user interface and operating principles so its a good idea to refer to game manual for information on how to set it up according to your needs.

atf2

In this final screen before connection is established and players enter the game lobby its usually enough to select the correct serial port in this case COM1 and leave the rest of the settings alone. This avoids potential issues like baud rate mismatch between the UARTs. Select Call and wait for connection to be established.

Serial ports

Serial ports can be configured in the config file:

serialX = device [parameter:value]

Or on the DOS command line:

serial X device [parameter:value]

device can be: directserial | modem | nullmodem | mouse |dummy

parameters:

for directserial: irq, realport (required), rxdelay
for modem: irq, listenport, sock (all optional)
for nullmodem: irq, server rxdelay txdelay telnet usedtr transparent port inhsocket sock (all optional)
for mouse: irq, rate (NORMAL or SMOOTH), type (2BTN, 3BTN, WHEEL, MSM, 2BTN+MSM, 3BTN+MSM, or WHEEL+MSM)
for dummy: irq

Defaults

serial1=dummy
serial2=dummy
serial3=disabled
serial4=disabled

Default IRQs (COM1 to COM4): 4, 3, 4, 3

Base memory addresses (COM1 to COM4): 0x3f8, 0x2f8, 0x3e8, 0x2e8

Examples

An example of how to configure an actual serial port for I/O use (Windows):

serial1=directserial realport:com1

Listen on TCP:1250 as server

SERIAL 1 NULLMODEM PORT:1250

Connect to TCP:1250 as client

SERIAL 2 NULLMODEM SERVER:10.0.0.6 PORT:1250

Listen on UDP:5000 as server

SERIAL 3 MODEM LISTENPORT:5000 SOCK:1

Use a physical port on Linux

SERIAL 4 DIRECT REALPORT:ttyUSB0

Mouse Systems mouse:

SERIAL 1 MOUSE TYPE:MSM

Nullmodem options

sock:1

Setting to 1 enables enet on the port, otherwise TCP.

usedtr:1

The nullmodem will

when it is client connect to the server not immediately but as soon as a modem-aware application is started (DTR is switched on).
only receive data when DTR is on.

transparent:1

don't add handshake control.
handshake control: if transparent is 0 or default (and not overridden by another mode), dosbox will include flow control pin changes (DTR and RTS) in the sent nullmodem stream and interpret similar received signals as DSR and CTS pin changes. Also it can include "Line Control Break" signals [todo: when are these used?]

telnet:1

interpret telnet commands.

rxdelay:

How many milliseconds to wait before causing an overflow when the application is unresponsive.
default: rxdelay:50
max value: rxdelay:10000

txdelay:

How many milliseconds to wait before sending data. This reduces network overhead quite a lot.
default: txdelay:12
max value: txdelay:500

port:

port is for both server and client
1 to 65535
default: port:23

inhsocket:1

socket inheritance (client-alike)

Nullmodem escape characters

Information for developers.

DOSBox's nullmodem stream inserts the DTR/CTS pin changes into the stream with a two-byte escape sequence. It does this unless unless transparent:1, or other modes such as telnet are used.

The protocol is not formally described and may change in future, but for developers who wish to connect to the nullmodem stream directly as it is, the escape sequences appear as follows:

First byte: 0xFF
Second byte: 0xFF — for a literal 0xFF
or second byte: 0x00
- +1 for RTS high (sent with CTS pin)
- +2 for DTR high (sent with DSR pin)
- +4 for Line Control Break [todo: when is this used?]