View source for Arduinos in Space 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:

 <nowiki>#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();
}
</nowiki>

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 <code>setup()</code> 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 <code>loop()</code> method you regularly call the Arduinos in Space <code>update()</code> 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 <code>sendCommand()</code> 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 <code>Serial</code>, 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 <code>OIS</code>, bind it to the serial connection named <code>Serial</code>, with one data request and no commands being sent:

 ObjectsInSpace OIS(Serial, 1, 0);

Then we begin the <code>setup()</code> 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 <code>begin()</code> 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 <code>HIGH</code> or <code>LOW</code> 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 <code>activate()</code> method:

 OIS.activate();

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

=== Active ===

Once in the active phase, the <code>update()</code> 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 <code>loop()</code> method does nothing else:

  OIS.update();

Whenever the game sends a new EMCON status update, calling <code>update()</code> 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.

[[Category:ArduinosInSpace]]