HTTPS SSH

Arduinos In Space!

A library for interacting with Objects in Space via a serial connection.

Protocol support

Arduinos In Space supports all of the known request types and command types documented in the unofficial Objects in Space wiki as of 2018-06-18. Note that at this stage the game is still under rapid development. New requests and commands are being added, and the protocol is likely to get some refinement. Arduinos In Space may lag slightly, or even briefly stop working between releases.

Note also that the library itself is still under development. Breaking changes are planned. But trust me, they're good ones.

Installation

While the library (and the game!) aren't really released yet, it can only be installed manually by following these steps:

  • Download the most recent release from the downloads section of the Bitbucket repository.
  • In the Arduino IDE, navigate to Sketch -> Include Library -> Add .ZIP Library...
  • Select the zip file previously downloaded.

Brief usage

Initialisation and handshaking

First, create an Arduinos In Space object to interface with the game.

ObjectsInSpace OIS(Serial, 5);

The first argument here is the serial interface to use to communicate with the game. This will almost always be Serial, but Arduinos In Space should also work with the Serial2 interface present on Arduino Mega and Leonardo boards, as well as SoftwareSerial interfaces in more esoteric setups.

The second argument is the number of request channels this device will create to request data from the game. This does not include command channels.

Then, inside your setup() function, initialise the serial interface as well as the Arduinos In Space interface.

Serial.begin(9600); // This is the only rate supported by the game.
OIS.begin();

The begin() method handles the initial handshaking stage, and moves to the synchronisation stage, described in more detail below.

Once synchronisation is complete, activate the interface to start sending commands and receiving data.

OIS.activate();

Sending commands

Before we can send a command, we must first register it. This is best done in your setup() function during the synchronisation phase. To register a command, just pass its name (from the wiki page) like this

OIS.registerCommand(FULL_STOP);

Once a command has been registered and synchronisation has been completed, a command can be sent at any time in a similar fashion. For instance, call this in your loop() function to stop your vessel

OIS.sendCommand(FULL_STOP);

Receiving data

Data can be received from the game by writing a callback function to receive and process the data, and then during the synchronisation phase registering the request type and callback. A small callback function that will light an LED when the EMCON system is active might look like this

void emconCallback(int channel, bool data) {
  if (data == 0) {
    digitalWrite(EMCONPin, LOW);
  } else {
    digitalWrite(EMCONPin, HIGH);
  }
}

Then, in your loop() method during synchronisation, this callback can be registered to receive EMCON status updates like this

OIS.registerBool(EMCON_MODE, emconCallback);

OiS sends three data types; bool, int, and float. Each type has a dedicated method to register a callback:

  • registerBool(int channel, boolCallback(int channel, bool data))
  • registerInt(int channel, intCallback(int channel, int data))
  • registerFloat(int channel, floatCallback(int channel, float data))

Each callback takes two arguments. The first is always the channel ID (useful if you want a single callback to handle multiple channels). The second is the data sent.

Note that this library translates data from the game to the appropriate type. This means that each channel type requires a different callback function that accepts different arguments. If you don't want this, then use one of the following methods to register your callback:

  • registerBoolRaw(int channel, rawCallback(int channel, int data))
  • registerIntRaw(int channel, rawCallback(int channel, int data))
  • registerFloatRaw(int channel, rawCallback(int channel, int data))

Note that all register* methods return an integer indicating the request channel ID.

Example sketches

Sketches in the examples/ directory illustrate basic usage for trivial controllers.