BGB 1.4 link protocol

This is the bgb 1.4 link protocol. Used in bgb versions 1.4.x and 1.5.x and possibly in later versions.

It is the intention that this protocol keeps being used, with negotiation for new features as necessary, to maintain back and forward compatibility with older BGB versions (>= 1.4) and 3rd party implementations. If this is no longer possible, the protocol version will be changed, and compatibility broken.

bgb game link works over TCP/IP. one side listens, the other side connects. When the initial handshake is complete, until the connection is broken, a plugged in link cable is emulated.

The TCP_NODELAY setting should be set on the socket to avoid extra delays in the OS. Also, keep in mind that due to the nature of TCP, packet boundaries are not guaranteed: multiple commands may be in a single TCP packet, and a command may be split over multiple TCP packets.

When individual bits are referred to, bit 0 is the lowest bit. Literal values are decimal, or $ prefixed hexadecimal.

All communication is in the form of 8 byte packets.

structure of packets

Note that while the i1 field would typically be used for a timestamp, its actual usage depends on an individual command's description of fields.

ofs	size	description
0	1	b1, command
1	1	b2
2	1	b3
3	1	b4
4	4	i1, timestamp (little endian)

initial handshake

When the link is established, both sides send a "version" packet, and verify the received packet. If the received values don't match, the connection is dropped.

timestamp

Both sides maintain a "timestamp", which is in 2 MiHz clocks (2^21 cycles per second). Each side sends its own local timestamp in packets, and maintains the difference between its own timestamp, and the received timestamp. Timestamps only contain the lowest 31 bits, the highest bit is always 0. Timestamps can wrap over. Timestamps are used so each side can, at the right times, wait for the remote side, for synchronization.

commands

The number in each header is the command number (value of b1)

1 - version

The protocol version. A change of these fields indicates a different (incompatible) protocol used.

b2=1
b3=4
b4=0
i1=0

101 - joypad

Joypad change, for remote control of an emulator. The receiving end can choose to ignore joypad changes, or update its button state accordingly.

Any bits and fields other than the ones used for a purpose MUST be 0 when sending, and MUST be ignored when receiving.

b2=joypad change
	bit 0-2: button number
	bit 3: 1 if button is pressed, 0 if button is released
	bit 4-7: 0 (due to a bug in previous bgb versions, these bits can't be used in the future and must remain 0)
b3=0
b4=0
i1=0

104 - sync1

Send a byte as master. The control value is mostly the SC register, except the addition of the double speed bit.

b2=data value.
b3=control value.
	bit 0: 1
	bit 1: high speed
	bit 2: double speed
	bit 3-6: 0
	bit 7: 1
b4=0
i1=timestamp

105 - sync2

Send a byte as slave. This command is sent in response to receiving a sync1, if a passive transfer was started.

b2=data value
b3=control value, $80
b4=0
i1=0

106 - sync3

This packet can have two meanings.

Sent in response to a received active transfer when not doing a passive transfer:

b2=1
b3=deprecated
b4=deprecated
i1=0

A synchronization (sending timestamp) that is not a transfer:

b2=0
b3=deprecated
b4=deprecated
i1=timestamp

108 - status

Used to communicate various status values about this emulator. if the other side is not running, or paused, this side can change its behavior accordingly. Any bits and fields other than the ones used for a purpose MUST be 0 when sending, and MUST be ignored when receiving. They may be used in the future. The status packet should be sent in response to version (for initial handshake), and whenever the status changes. it MUST NOT be sent in response to receiving a status packet.

b2=flags
	bit 0 ($01): statusflag_running: is running
	bit 1 ($02): statusflag_paused: is paused
	bit 2 ($04): statusflag_supportreconnect: support automatic reconnect and "wantdisconnect" (new in BGB 1.5.2)
b3=0
b4=0
i1=0

109 - wantdisconnect

(new in BGB 1.5.2)

Used to indicate to not automatically reconnect after the connection is broken, for user initiated disconnect. All fields must be 0 on sending, and must be ignored on receiving

Usage of this command depends on having seen statusflag_supportreconnect set in a "status" message in this session:

If YES: On a user initiated disconnect, one SHOULD send the "wantdisconnect" message. If the link was broken without having seen a "wantdisconnect" message, one MAY automatically reconnect. If the link is broken and the message was seen, one MUST NOT automatically reconnect.

If NO: One MUST NOT send the "wantdisconnect" message. If the link is broken, one SHOULD NOT automatically reconnect.