DDS Protocol

This page is a work in progress and may contain incomplete or out of date information.

This page briefly explains the Direct Data Socket "DDS" Protocol whose primary function is the exchange of IEEE 802.3 Ethernet frames between external programs and the XLink Kai client. DDS is intended for use in emulator integration and other utilities not part of the main XLink Kai application suite as a way to exchange Ethernet traffic with remote players as well as physical game consoles on the local LAN.

The protocol is simple text exchange on UDP port 34523

Note: There are several commands intended for internal use only that are not listed here.

Send

connect

connect;locally_unique_identifier;application_name;optional_version_str;optional_version_str2;000000000000000

Sent first at the beginning of a DDS session, connect is used to identify the connecting application to the XLink Kai client.
locally_unique_identifier must be unique locally to this XLink Kai client. If there is a duplicate identifier used any previous connections will be sent a disconnected; response and have their socket closed.
application_name is shown to the user on XLink's "Metrics" display and is also used for loading icons.

The optional version strings are used by kaiEngine itself for specific DDS clients (mostly other Team XLink projects) and are not required.

Response: connected;locally_unique_identifier; on success or disconnected; on failure.

disconnect

disconnect;optional_locally_unique_identifier;optional_padding

Sent to gracefully request a disconnect from DDS.

Response: disconnected;locally_unique_identifier;reason;

discover

discover;

Sent as a UDP broadcast on port 34523 to discover XLink Kai clients. Clients reply with xlink_here; a maximum of once every 2 seconds.

Response: xlink_here;

e

Encapsulated data

e

e;e;raw_ethernet_frame_data

DDS's primary function is the exchange of IEEE 802.3 Ethernet frames. The MAC addresses used in the frames MUST use valid OUI for the appropriate console or XLink will ignore the traffic. (Nintendo emulator traffic should use Nintendo OUI, etc. Contact CrunchBite if you have questions)

Response: None

d

e;d;asmanybytesasyouwant

Send arbitrary bytes to ALL other players in the arena as a broadcast. kaiEngine itself will not action this traffic, it is only used for DDS clients.

Response: None

get

get;key;

Used to request information/state.

username

get;username;

Request the username of the user logged into the connected kaiEngine. Returns an empty string if not logged in.

Response: username;theusername;

essid

get;essid;

Request the ESSID that should be used for PSP adhoc. Returns an empty string if not defined for the Arena or the remote end has not defined it.

Response: essid;theessid;

players

get;players;

Request a list of players in the Arena.

Response: players;player1/player2/player3;

chat

get;chat;

Request state for being sent chat and directmessage types

Response: var;chat;true/false;

ddsonly

get;ddsonly;

Request state of 'ddsonly' mode. In ddsonly mode kaiEngine's normal LAN processing is disabled. If true kaiEngine will ignore local network interfaces completely. If one or more DDS clients set this mode and all of them have disconnected then ethernet processing will be reenabled.

Response: var;ddsonly;true/false;

joinleave

get;joinleave;

Request state of joinleave. Set joinleave to true if your application wants to receive messagea about players joining or leaving the arena.

Response: var;joinleave;true/false;

vars

get;vars;

Request state of all sett-able variables. Currently: ddsonly, joinleave, and chat

Response: var;chat;true/false;

Response: var;ddsonly;true/false;

Response: var;joinleave;true/false;

keepalive

keepalive;

Keep alive messages are sent every 30s and should be immediately replied to with keepalive;. If a keepalive is not answered for 5 minutes the socket will be closed.

Response: None

set

set;key;value;

Used to toggle specific settings.

chat

set;chat;true/false;

Set chat to true if your application wants to receive chat and direct messages. Set to false to disable. Default state is false.

Response: var;chat;true/false;

ddsonly

set;ddsonly;true/false;

Set ddsonly to true if your application requires/works best if kaiEngine's normal LAN processing is disabled. If true kaiEngine will ignore local network interfaces completely. If one or more DDS clients set this mode and all of them have disconnected then ethernet processing will be reenabled.

Response: var;ddsonly;true/false;

joinleave

set;joinleave;true/false;

Set joinleave to true if your application wants to receive messagea about players joining or leaving the arena.

On join: player_join;username;

On leave: player_leave;username;

Response: var;joinleave;true/false;

Deprecated commands

These commands are still present in kaiEngine as of version 7.4.44 but will be removed in the near future. Do not use them.

getplayernames

Deprecated in XLink Kai 7.4.44 Use get instead.

getplayernames;

Sent to request a list of the usernames in the same game arena as the client.

Response: player_names;

getusername

Deprecated in XLink Kai 7.4.44 Use get instead.

getusername;

Sent to request the username of the user logged into the XLink Kai client.

Response: username;

setting

Deprecated in XLink Kai 7.4.44 Use set instead.

setting;chat;true;

Used to toggle specific settings. The only supported setting is 'chat'. Set chat to true if your application wants to receive chat and direct messages.

Response: None

Receive

arena

arena;Arena/Path/Here;

Sent when the local user changes game arena in the XLink Kai client.

connected

connected;identifier;

Acknowledgement of the DDS connection being valid.

disconnected

disconnected;optional_identifier;optional_message;

Sent to indicate the DDS client application has been disconnected. Any messages sent after this is sent will be ignored or replied to with another disconnected message. The optional message may contain a reason for the disconnect.

e

e;e;raw_ethernet_frame_data

Ethernet frame from either a remote player, local console on the LAN, or another DDS client application.

d

e;d;evenmorebytes

Arbitrary bytes broadcast from another player's DDS client.

gameinfo

gameinfo;CONSOLE;Game Name;

Sent when the local user joins a game Arena in the XLink Kai client.

Note: There are additional fields for internal use, they are not explained here.

keepalive

keepalive;

keep alive message sent to check if the DDS client application is still active. These are sent from the XLink Kai client every 30 seconds and if unanswered for 5 minutes (300 seconds) the client will be sent a disconnected; message and dropped.

chat

chat;message_text;

Chat message as received in the XLink Kai client. Only sent to DDS clients if enabled with setting;chat;true;

directmessage

directmessage;message_text;

Direct message as received in the XLink Kai client. Only sent to DDS clients if enabled with setting;chat;true;

message

message;message_text;

Used for messages that should be displayed to the user (if relevant) about the status of the XLink Kai client, the DDS connection to the client, etc.

player_join

player_join;username;

Indicates a player joined the "Arena" the local user is in.

Note: Only sent if set;joinleave;true; was previously sent.

Note: Duplicate player_join; messages will be sent quite frequently as a side effect of how the XLink Kai UI keeps state. Use get;playernames; to get the current list.

player_leave

player_leave;username;

Indicates a player left the "Arena" the local user is in.

Note: Only sent if set;joinleave;true; was previously sent

player_names

player_names;username1/username2/username3;

Response to get;playernames;

username

username;username_here;

Response to get;username;

var

var;key;value;

Response to set;key;value and some get;key; messages.

xlink_here

xlink_here;

Response to discover;

Example session

<< connect;app555532;My Application;1;0;   # Connect to kaiEngine with identifier 'app555532' with application "My Application" version 1.0
>> connected;app555532;                    # Connection acknowledged
<< set;chat;true;                          # Enable chat mode, this is optional
>> chat;This is a public chat message!;    # Example of a chat message
>> keepalive;                              # kaiEngine sent a keepalive to check if the DDS client is still there
<< keepalive;                              # Answer the keepalive
>> e;e;raw_ethernet_frame_data             # kaiEngine sent the client an encapsulated Ethernet frame
<< e;e;raw_ethernet_frame_data             # Client replied with an encapsulated Ethernet frame
<< disconnect;app555532;                   # Client request to gracefully disconnect
>> disconnected;app555532;;                # Disconnect acknowledged

Implementations

Dolphin has support as of build 12233 via pull 8853. For usage see Dolphin Gamecube XLink BBA Tutorial
JPCSP has support as of Nov 21st 2020. For usage see the entry on the JPCSP wiki and the JPCSP PSP Tutorial
XLHA - XLink Handheld Assistant
kaiRemoteDDS
kaiLoopbackBridge

Message availability

The following table shows the messages available in each version of the XLink Kai client.

✔	Available
✗	Unavailable
✗	Deprecated, do not use

Send

	7.4.37	7.4.38	7.4.39	7.4.40	7.4.41	7.4.42	7.4.43	7.4.44	7.4.45
connect;	✔	✔	✔	✔	✔	✔	✔	✔	✔
chat;	✗	✗	✗	✔	✔	✔	✔	✔	✔
disconnect;	✔	✔	✔	✔	✔	✔	✔	✔	✔
discover;	✗	✗	✗	✔	✔	✔	✔	✔	✔
e;e;	✔	✔	✔	✔	✔	✔	✔	✔	✔
get;key;	✗	✗	✗	✗	✗	✗	✗	✔	✔
getessid;	✗	✗	✗	✔	✔	✔	✔	✗	✗
getplayernames;	✗	✗	✗	✔	✔	✔	✔	✗	✗
getusername;	✗	✗	✗	✔	✔	✔	✔	✗	✗
keepalive;	✔	✔	✔	✔	✔	✔	✔	✔	✔
setting;chat;	✔	✔	✔	✔	✔	✔	✔	✗	✗
set;key;value;	✗	✗	✗	✗	✗	✗	✗	✔	✔
	7.4.37	7.4.38	7.4.39	7.4.40	7.4.41	7.4.42	7.4.43	7.4.44	7.4.45

Receive

	7.4.37	7.4.38	7.4.39	7.4.40	7.4.41	7.4.42	7.4.43	7.4.44	7.4.45
arena;	✗	✗	✗	✔	✔	✔	✔	✔	✔
chat;	✔	✔	✔	✔	✔	✔	✔	✔	✔
connected;	✔	✔	✔	✔	✔	✔	✔	✔	✔
directmessage;	✔	✔	✔	✔	✔	✔	✔	✔	✔
disconnected;	✔	✔	✔	✔	✔	✔	✔	✔	✔
e;e;	✔	✔	✔	✔	✔	✔	✔	✔	✔
essid;	✗	✗	✗	✔	✔	✔	✔	✔	✔
gameinfo;	✗	✗	✗	✔	✔	✔	✔	✔	✔
keepalive;	✔	✔	✔	✔	✔	✔	✔	✔	✔
player_join;	✗	✗	✗	✔	✔	✔	✔	✔	✔
player_leave;	✗	✗	✗	✔	✔	✔	✔	✔	✔
player_names;	✗	✗	✗	✔	✔	✔	✔	✔	✔
message;	✔	✔	✔	✔	✔	✔	✔	✔	✔
username;	✗	✗	✗	✔	✔	✔	✔	✔	✔
var;	✗	✗	✗	✗	✗	✗	✗	✔	✔
xlink_here;	✗	✗	✗	✔	✔	✔	✔	✔	✔
	7.4.37	7.4.38	7.4.39	7.4.40	7.4.41	7.4.42	7.4.43	7.4.44	7.4.45

DDS Protocol

Send

connect

disconnect

discover

e

e

d

get

username

essid

players

chat

ddsonly

joinleave

vars

keepalive

set

chat

ddsonly

joinleave

Deprecated commands

getplayernames

getusername

setting

Receive

arena

connected

disconnected

e

e

d

gameinfo

keepalive

chat

directmessage

message

player_join

player_leave

player_names

username

var

xlink_here

Example session

Implementations

Message availability

Send

Receive

Navigation menu

Search