Kerbal Sim Pit Protocol

This document describes the current version (version 0) of the Kerbal Sim Pit (KSPit) serial protocol.

Overview

A KSPit packet consists of a 4 byte header, followed by a payload with a hardcoded maximum size of 32 bytes. There is no packet footer.

Header

• Header byte 1
  The first byte of the header is 0xAA (b10101010)
• Header byte 2
  The first nibble of this byte is alternating 0s and 1s. The second nibble of this byte encodes the protocol version. For protocol version 0, this gives a byte value of 0x50.
• Payload size
  This byte gives the size of the payload. The maximum possible payload size is 32 bytes. A payload size larger than 32 bytes is considered invalid, and the packet is discarded.
• Channel
  The packet channel. Channels 0x00 to 0x0F are reserved for internal use by the protocol, other channels are available for in-game providers.

Typical session

At startup, the plugin will open all configured serial ports and start listening for handshaking packets. It is expected that hardware devices will initiate handshaking when they're ready. The device will then perform a three-way handshake with the plugin:

1. Device sends a SYN handshake packet. 1. Plugin responds with a SYNACK handshake packet. 1. Device sends an ACK handshake packet. Handshaking is complete.

Once handshaking is complete, all packets send from the device to the plugin are handled as expected. Unless otherwise noted, the plugin will only send packets to the device if the device has sent a Register Channel packet requesting that channel.

Bidirectional channels

These channels may be used by both the plugin and the device.

0x00: Handshake packets

The first byte of a handshake payload indicates the handshake type:

• 0x00: SYN
• 0x01: SYNACK
• 0x02: ACK

If a device includes any other bytes in a handshake payload, the plugin will consider them ID bytes, and include them in its responses.

0x01: Echo Request

The plugin will respond to an Echo Request packet with an Echo Response packet. If a payload is present in the Echo Request, the plugin will copy it verbatim in to the Echo Response.

0x02: Echo Response

An Echo Response packet should only ever be sent in reply to an Echo Request. Devices do not need to subscribe to this channel to receive packets, they are always sent.

Outbound channels

These channels are only sent from the plugin to connected devices.

0x03: Scene Change

Yet to be implemented.

The plugin sends a Scene Change packet whenever the game switches to a new scene. The payload should consist of a single byte representing the new scene.

0x04: Altitude

Note: This needs to be renumbered

If channel is sent periodically. The payload is 8 bytes, containing sea level and surface altitude.

struct altitudeMessage {
  float sealevel;
  float surface;
}

Inbound channels

These channels are only sent from the plugin to connected devices.

0x03: Register Channel

The device sends a Register Channel packet at any time indicating it wishes to receive packets from the plugin for a given channel.

Each byte of the payload is interpreted as a channel ID to register for. A device can send an array of multiple bytes to register for multiple channels.

0x04: Deregister Channel

The device sends a Deregister Channel packet at any time indicating it no longer wishes to receive packets from the plugin for a given channel. The plugin will no longer send packets for these channels.

Each byte of the payload is intepreted as a channel ID to deregister from. A device can send an array of multiple bytes to deregister from multiple channels.

0x06: Custom Action Group Activate

0x07: Custom Action Group Deactivate

0x08: Custom Action Group Toggle

These channels need to be renumbered

These channels control Custom Action Groups.

• Activate ensures the AG is activated.
• Deactivate ensures the AG is deactivated.
• Toggle flips the state of the AG.

Each byte of the payload is interpreted as a Custom Action Group number. A device can send an array of multiple bytes to act on multiple Custom Action Groups.

The plugin will integrate with the [[http://forum.kerbalspaceprogram.com/index.php?/topic/67235-122dec1016-action-groups-extended-250-action-groups-in-flight-editing-now-kosremotetech/|Action Groups Extended] mod if it's installed. With AGX, the plugin can control all 250 custom action groups. Without AGX, the stock 10 custom action groups are available.

0x09: Action Group Activate

0x0A: Action Group Deactivate

0x0B: Action Group Toggle

These channels need to be renumbered*

These channels control the standard Action Groups.

• Activate ensures the AG is activated.
• Deactivate ensures the AG is deactivated.
• Toggle flips the state of the AG.

The payload should be one byte representing the Action Group to act on. Possible values are:

The plugin can act on multiple Action Groups by adding their values together.