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

Objects in Space connections

Before getting in to how Arduinos in Space, let's talk about how the game communicates with devices. 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.

Arduinos in Space overview

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.

Handshaking

Before doing anything else, we need to begin the serial connection from the client side. Note that the game only supports communication at 9600 baud.

Serial.begin(9600);

Now the game is in the Handshaking phase, just waiting for us to send a handshaking request. Arduinos in Space will handle the handshaking, we just have to call the begin() method.

OIS.begin();

This will send the commands required to complete handshaking, and move in to the sync phase.

Syncing

In the sync phase, the game is expecting us to send commands specifying what data we would like to receive, and what commands we would like to send, when the connection is active. Arduinos in Space has numerous methods available to register commands and request data. But for HelloWorld we just use one.

Here, we're requesting Boolean (either on or off) information about EMCON state - we're asking the game to tell us if EMCON is on or off. When we request data like this, we need to tell Arduinos in Space what to do with it. For HelloWorld we tell the library to directly manage the LED_BUILTIN pin - this is an alias for the pin connected to the Arduino's built-in LED. When requested in this way, Arduinos in Space will monitor the data sent from the game, and automatically set the pin HIGH or LOW depending on EMCON status.

OIS.requestBool(EMCON_MODE, LED_BUILTIN);

Once we've requested all of the inputs and outputs we'd like, we move to the active phase. Arduinos in Space does this by calling the activate() method:

OIS.activate();

That's all that's needed in the setup() method, and we move to the active phase and the Arduino loop() method.

Active

Once in the active phase, the update() method is the workhorse of Arduinos in Space. This method reads incoming serial data from the game, parses it, processes the commands and data it contains. It also updates the status of managed input pins, sending commands back to the game if required.

All this means that it needs to be called frequently. For HelloWorld, the loop() method does nothing else:

 OIS.update();

Whenever the game sends a new EMCON status update, calling update() will cause Arduinos in Space to read the data, and if EMCON is on it will turn on the LED_BUILTIN LED. If EMCON is off, LED_BUILTIN will be turned off.