Kerbal Simpit Arduino Library¶

This library manages a serial connection to the Kerbal Simpit plugin for Kerbal Space Program. It handles low-level handshaking and packet sending and receiving, and provides data structures and methods for dealing with messages to and from the plugin.

Quickstart Guide¶

Minimal Arduino sketch¶

A minimal Kerbal Simpit sketch looks like this:

#include <KerbalSimpit.h>

KerbalSimpit mySimpit(Serial);

void setup() {
  Serial.begin(115200);
  while (!mySimpit.init());
}

void loop() {
  mySimpit.update();
}

There are a few parts that are required:

Include the library:
```
#include <KerbalSimpit.h>
```
Create a KerbalSimpit object. The constructor requires one argument, the serial device that we will use. In most cases this is “Serial”:
```
KerbalSimpit mySimpit(Serial);
```
Initialise the serial connection. Kerbal Simpit does not attempt to open the serial device, so the sketch should do so in its setup() function. The speed should match that specified by the plugin in its config file:
```
Serial.begin(115200);
```
Initialise the KerbalSimpit object. The init() function performs a three-way handshake with the Kerbal Simpit plugin. It returns a boolean indicating handshake status, so it’s easiest to just call this in a loop until a successful handshake is performed:
```
while (!mySimpit.init());
```
The update() function is receives new data from the serial connection. It should be called regularly in the sketch loop().

Message channels¶

Every message in to and out of the Kerbal Simpit plugin has a channel ID. Each channel is dedicated to a specific type of information, and the messages this library supports are documented in Kerbal Simpit Message Types.

Sending data¶

The low-level send() function can send arbitrary data to the plugin:

mySimpit.send(messageType, message[], messageSize);

messageType is a byte representing the channel this message is on. The library provides constants for all supported message channels, see Kerbal Simpit Message Types for a full list.
message[] is a byte array representing the message. The library enforces a hard limit on message size, MAX_PAYLOAD_SIZE, which defaults to 32 bytes.
messageSize is a byte representing the size of the message.

The library provides higher-level functions encapsulating most known message channels. For example, both of these lines activate the standard Brakes action group:

mySimpit.send(CAGACTIVATE_MESSAGE, &BRAKES_ACTION, 1);

mySimpit.activateAction(BRAKES_ACTION);

Refer to KerbalSimpit Class Documentation for full documentation.

Receiving data¶

To receive data from the plugin, use the inboundHandler() function to register a callback handler with the library:

mySimpit.inboundHandler(myCallbackHandler);

And define the callback handler:

void myCallbackHandler(byte messageType, byte message[], byte messageSize) {
  switch(messageType) {
  case MESSAGE_TYPE_1:
    // Handle the first type of message.
    break;
  case MESSAGE_TYPE_2:
    // Handle the second type of message.
    break;
  }
}

Most messages from the plugin consist of several pieces of information. The library includes structs and helper functions to assist with working with these. For example, here’s a basic callback handler for dealing with altitude information from the plugin:

void myCallbackHandler(byte messageType, byte mesesage[], byte messageSize) {
  switch(messageType) {
  case ALTITUDE_MESSAGE:
    if (msgSize == sizeof(altitudeMessage)) {
      altitudeMessage myAltitude;
      myAltitude = parseAltitude(msg);
      // further processing of altitude data in myAltitude here
    }
    break;
  }
}

For a full list of available structs and helper functions, refer to Kerbal Simpit Compound Messages.

Going further¶

The examples directory of the library contains several example sketches that demonstrate the different functionality of the library.

KerbalSimpit Class Documentation¶

class KerbalSimpit¶

The KerbalSimpit class manages a serial connection to KSP.

It automates the handshaking process, and provides utility functions to encapsulate most message types in and out of the game.

Public Functions

KerbalSimpit(Stream &serial)¶

Default constructor.

Parameters

serial: The serial instance this instance will use to communicate with the plugin. Usually “Serial”.

bool init()¶

Initialise the serial connection.

Performs handshaking with the plugin. Note that the KSPit library does not* call the begin() method on the serial object. You’ll need to ensure you’ve run Serial.begin(115200) (or similar) before calling this method.

void inboundHandler(void (*messageHandler)(byte messageType, byte msg[], byte msgSize))¶

Specify a callback function to handle messages received from the plugin.

See

messageHandler

Parameters

messageHandler: The callback function.

void registerChannel(byte channelID)¶

Subscribe to a channel of messages coming from the plugin.

This function sends a channel subscription message to the plugin, indicating that this device would like to receive messages send to a given channel.

Parameters

channelID: The ID of the channel to subscribe to.

void deregisterChannel(byte channelID)¶

Unsubscribe from a channel of messages coming from the plugin.

This function sends a channel subscription message to the plugin, indicating that no further messages for the given channel should be sent to this device.

Parameters

channelID: The ID of the channel to unsubscribe from.

template <typename T> void send(byte messageType, T &msg)¶

Send a formatted KSPit packet.

Sends the given message as payload of a KSPit message.

Parameters

messageType: The ID of the message channel.
msg: Any object to be sent. The expected object depends on the message type. No type checking is done by this library.

void send(byte messageType, byte msg[], byte msgSize)¶

Send a formatted KSPit packet.

Sends the given message as payload of a KSPit message.

Parameters

messageType: The ID of the message channel.
msg: A byte array representing the message contents.
msgSize: The size of msg.

void update()¶

Regular library update function.

This function polls the serial device for new data, and performs other tasks that must be done regularly. The function should be called from an Arduino sketch loop() method.

void activateCAG(byte actiongroup)¶

Activate Custom Action Group.

Sends a message to activate the given Custom Action Group.

Parameters

actiongroup: The ID of the Custom Action Group to activate.

void deactivateCAG(byte actiongroup)¶

Deactivate Custom Action Group.

Sends a message to deactivate the given Custom Action Group.

Parameters

actiongroup: The ID of the Custom Action Group to deactivate.

void toggleCAG(byte actiongroup)¶

Toggle Custom Action Group.

Sends a message to toggle the state of the given Custom Action Group.

Parameters

actiongroup: The ID of the Custom Action Group to toggle.

void activateAction(byte action)¶

Activate Action Group.

Sends a message to activate the given standard Action Group(s).

Parameters

action: A bitfield representing one or more Action Groups to activate.

void deactivateAction(byte action)¶

Deactivate Action Group.

Sends a message to deactivate the given standard Action Group(s).

Parameters

action: A bitfield representing one or more Action Groups to deactivate.

void toggleAction(byte action)¶

Toggle Action Group.

Sends a message to toggle the state of the given standard Action Group(s).

Parameters

action: A bitfield representing one or more Action Groups to toggle.

void setSASMode(byte mode)¶

Set SAS mode Send a message to set the desired Autopilot (SAS) mode.

Parameters

mode: The mode to set. Possible modes are listed in the AutopilotMode enum.

This documentation was built using ArduinoDocs.

Kerbal Simpit Message Types¶

Constants for inbound and outbound message IDs.

Enums

enum CommonPackets¶

Common packets.

These packet types are used for both inbound and outbound messages.

Values:

SYNC_MESSAGE = 0¶: Sync message. Used for handshaking.

ECHO_REQ_MESSAGE = 1¶: Echo request. Either end can send this, and an echo response is expected.

ECHO_RESP_MESSAGE = 2¶: Echo response. Sent in reply to an echo request.

enum OutboundPackets¶

Outbound packets.

IDs for packets that go from the game to devices.

Values:

SCENE_CHANGE_MESSAGE = 3¶: Scene change packets are sent by the plugin when entering or leaving the flight scene.

ALTITUDE_MESSAGE = 8¶

Sea level and surface altitude.

Messages on this channel contain an altitudeMessage.

APSIDES_MESSAGE = 9¶

Apoapsis and periapsis.

Messages on this channel contain an apsidesMessage.

LF_MESSAGE = 10¶

Liquid fuel in the vessel.