Arduinos in Space

Arduinos in Space is an Arduino library to interface with Objects in Space. It aims to provide a high level, Arduino-like interface while still being powerful and flexible.

Getting started

Requirements

Any Arduino-compatible board should work. The Hello World sketch below needs a board with a built-in LED. All genuine Arduino/Genuino boards have one, as well as most Arduino-compatible boards.

Installation

The library is not (yet) available through the Arduino Library Manager, so must be installed manually.

1. Download the most recent release from the downloads section of the library repository on Bitbucket.
2. Open the Arduino IDE, and navigate to Sketch -> Include Library -> Add .ZIP Library...
3. Select the zip file previously downloaded.

Hello World

First, ensure Objects in Space is configured to talk to hardware, following the directions in Getting started with hardware.

Open the Arduino IDE, create a new sketch (File -> New), and enter the following code:

#include "ArduinosInSpace.h:

ObjectsInSpace OIS(Serial, 1, 0);

void setup() {
  Serial.begin(9600);
  OIS.begin();

  OIS.registerBool(EMCON_MODE, LED_BUILTIN);

  OIS.activate();
}

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

Save this (call it something like "HelloWorld", then build and upload to your board. With the board still connected, ensure the Arduino serial monitor is not running, and launch Objects in Space. All going well, the game will open a connection to your board, and the built-in LED on your board will turn on to indicate when EMCON mode is active.

Understanding Arduinos in Space

Using Arduinos in Space is fairly straightforward. In the setup() method of your sketch you start by setting up a serial connection with the game, and creating an Arduinos in Space object that will manage the connection. Then you use methods on that object to progress through the different connection phases. Once the connection has been fully established, in the loop() method you regularly call the Arduinos in Space update() method to check for new input and send commands. Finally, you ensure that callback functions are defined to handle data from the game, and send commands to the game using the sendCommand() function or built in input handlers.

Breaking down HelloWorld

Let's examine the different phases by looking at the above HelloWorld sketch line-by-line.

Initial setup

First, we need to include the Arduinos in Space library:

#include <ArduinosInSpace.h>

Then we create an Arduinos in Space object. We'll use this object for all of our interactions with the game.

The object constructor takes three arguments. The first is the serial object we'll use. In most instances, this will just be Serial, but SoftwareSerial and extended serial interfaces are also supported. The second argument is the number of ``request channels`` we'll be creating - these are requests for data from the game. The third argument is the number of ``managed input pins`` that will send commands to the game. We'll learn what these are later.

For HelloWorld we create an object named OIS, bind it to the serial connection named Serial, with one data request and no commands being sent:

ObjectsInSpace OIS(Serial, 1, 0);

Then we begin the setup() function and move through connection phases with the game.

Connection phases

A connection between Objects in Space (the server) and an Arduino (the client) has three separate phases:

• Handshaking: the server is listening for an initial request from the client.
• Syncing: the client sends commands to the server defining expected inputs and outputs.
• Active: the server is able to send game data to the client, and the client is able to send commands to the server.