2018-08-15T12:52:58Z

Stibbons: Created page with "== 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 w..."

Arduinos in Space

2018-08-15T12:52:36Z

Stibbons:

[https://bitbucket.org/pjhardy/arduinosinspace/src/master/ 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.

Arduinos in Space is an open source library, that was neither written nor supported by Flat Earth.

== Arduinos in Space resources ==

* [[Arduinos in Space Getting Started|Getting started]]
* [[Arduinos in Space Hello World|Hello World]]
* [[Arduinos in Space Concepts]]
* [[Arduinos in Space API]]

== 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.

== Going further ==

Objects in Space can send a lot more data to a serial device. It can also accept commands. This is all supported by Arduinos in Space. The library comes with several example sketches (available in the Arduino IDE under File -> Examples -> Arduinos in Space).

[[Arduinos in Space API]] contains a full API reference.

[[Category:ArduinosInSpace]]

Arduinos in Space

2018-08-15T12:41:15Z

Stibbons:

[https://bitbucket.org/pjhardy/arduinosinspace/src/master/ 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.

Arduinos in Space is an open source library, that was neither written nor supported by Flat Earth.

== 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.

# Download the most recent release from the [https://bitbucket.org/pjhardy/arduinosinspace/downloads/ downloads section] of the library repository on Bitbucket.
# Open the Arduino IDE, and navigate to Sketch -> Include Library -> Add .ZIP Library...
# 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:

<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.

== Going further ==

Objects in Space can send a lot more data to a serial device. It can also accept commands. This is all supported by Arduinos in Space. The library comes with several example sketches (available in the Arduino IDE under File -> Examples -> Arduinos in Space).

[[Arduinos in Space API]] contains a full API reference.

[[Category:ArduinosInSpace]]

Arduinos in Space API

2018-08-15T12:29:36Z

Stibbons:

== ObjectsInSpace class ==

This is the main interface for Arduinos In Space. A single ObjectsInSpace object manages all aspects of a serial connection. It provides an interface to send commands to the game, and can poll input pins to trigger those commannds. It also allows to request data from the game, and will pass received data to a specified output pin, or a callback function for more complex requests.

=== Constructors ===

<nowiki>ObjectsInSpace( Stream & serial,
int numRequests,
int numCommandPins
)</nowiki>

Creates an ObjectsInSpace object to manage a serial connection. Note that this constructor will ''not'' attempt to start the serial interface, it must be started separately with eg <tt>Serial.begin()</tt>.

'''Parameters'''
* <tt>serial</tt> The serial instance this object will use to communicate with the game. Usually <tt>Serial</tt>.
* <tt>numRequests</tt> The number of request channels to allocate. This is the maximum number of requests for data this object will support. It does ''not'' include command channels.
* <tt>numCommandPins</tt> The number of ''managed'' input pins to allocate. This is the maximum number of commands channels with managed input pins (created via <tt>registerLatching()</tt> or <tt>registerTrigger()</tt>) the object will support. Commands that will be send directly through <tt>sendCommand()</tt> do not need to be included here.

----

<nowiki>ObjectsInSpace( Stream & serial,
int numRequests
)</nowiki>

Note that this constructor is '''deprecated''', and will be removed in a future release. Identical to the main constructor, but the created object will not be able to support any managed input pins.

=== Member functions ===

==== Handshaking phase ====
===== begin() =====

Initialise the connection, and perform handshaking with the game.

<nowiki>void ObjectsInSpace::begin()</nowiki>

The <tt>begin()</tt> function will periodically send a handshake request packet, and wait for the game to send a successful response. This is a blocking function - it won't return until handshaking is successful and the game has moved to the Synchronisation phase of the connection.

==== Synchronisation phase ====
===== activate() =====

Start active phase

<nowiki>void ObjectsInSpace::activate()</nowiki>

The <tt>activate()</tt> function tells the game that we have completed synchronising commands and requests with the game, and are ready to move in to the active phase of the connection. The game will start sending live data and processing game commands we send.

==== Request channels ====

These functions, executed during the synchronisation phase, set up channels requesting data from the game.

===== registerBool() =====

Register a request for boolean data (true/false, 1/0, on/off).

<nowiki>int ObjectsInSpace::registerBool( OISCommand command,
int pin,
bool invert=false
)</nowiki>

This function will create a channel to receive the requested boolean data from the game. When data on this channel is received, Arduinos in Space will change the status of the given output pin to match the data received. Note that this function also sets the pin mode appropriately, there is no need for a separate <tt>pinMode()</tt> call. The maximum number of request channels that can be created is specified by the numRequests argument to the ObjectsInSpace constructor. Attempts to request more than this limit will silently fail.

'''Parameters'''
* <tt>command</tt> The data command to request.
* <tt>pin</tt> A pin number to control.
* <tt>invert</tt> By default, the output pin will be set high if a boolean true is received on this channel, and low if a boolean false is received. Set the optional invert parameter to true to invert this logic.

'''Returns'''
A unique index of this request in the internal request list.

----

<nowiki>int ObjectsInSpace::registerBool( OISCommand command,
boolCallback callback
)</nowiki>

This function will create a channel to receive the requested boolean data from the game. When data on this channel is received, Arduinos In Space will convert it to a boolean data type (true/false), and then pass it as an argument to the given callback function. The maximum number of request channels that can be created is specified by the numRequests argument to the ObjectsInSpace constructor. Attempts to request more than this limit will silently fail.

'''Parameters'''
* <tt>command</tt> The data command to request.
* <tt>callback</tt> A callback function to handle the received data.

'''Returns'''
A unique index of this request in the internal request list.

===== registerInt() =====

Register a request for numeric data.

<nowiki>int ObjectsInSpace::registerInt( OISCommand command,
intCallback callback
)</nowiki>

This function will create a channel to receive the requested integer data from the game. When data on this channel is received, Arduinos In Space will pass the data in integer format as an argument to the supplied callback function. The maximum number of request channels that can be created is specified by the numRequests argument to the ObjectsInSpace constructor. Attempts to request more than this limit will silently fail.

'''Parameters'''
* <tt>command</tt> The data command to request.
* <tt>callback</tt> A callback function to handle the received data.

'''Return'''
A unique index of this request in the internal request list.

===== registerFloat() =====

Register a request for floating point data.

<nowiki>int ObjectsInSpace::registerFloat( OISCommand command,
floatCallback callback
)</nowiki>

This function will create a channel to receive the requested floating point data from the game. When data on this channel is received, Arduinos In Space will convert it to a floating point type (float), before passing it as an argument to the supplied callback function. The maximum number of request channels that can be created is specified by the numRequests argument to the ObjectsInSpace constructor. Attempts to request more than this limit will silently fail.

'''Parameters'''
* <tt>commannd</tt> The data command to request.
* <tt>callback</tt> A callback function to handle the received data.

==== Command channels ====

These functions, executed during the synchronisation phase, request commands that we want to execute during the active phase.

===== registerCommand() =====

Register a client command.

<nowiki>int ObjectsInSpace::registerCommand( OISCommand command )</nowiki>

Before the game will accept a given command, it must be registered. This function will register the command.

'''Parameters'''
* <tt>command</tt> The command to register.

===== registerLatching() =====

Register two commands bound to an input pin in latching mode.

<nowiki>int ObjectsInSpace::registerLatching ( uint8_t pin,
OISCommand firstCommand,
OISCommand secondCommand,
uint8_t mode=INPUT
)</nowiki>

Arduinos In Space will poll the pin specified by <tt>pin</tt>. The first time it switches from inactive to active the first command will be sent. The second time it switches from inactive to active the second command will be sent, and so on. The maximum number of managed command pins are specified by the numCommandPins argument when constructing an ObjectsInSpace object. Attempts to register more than this limit will silently fail.

'''Parameters'''
* <tt>pin</tt> The pin to monitor. Arduinos in Space will set the mode, do '''not''' call <tt>pinMode()</tt> on this pin.
* <tt>firstCommand</tt> The command to send first active change.
* <tt>secondCommand</tt> The command to send second active change.
* <tt>active</tt> This sets the pin mode, as well as what readings will be considered active. When set to <tt>INPUT</tt>, the pin is active when HIGH. When set to <tt>INPUT_PULLUP</tt>, the pin is active when LOW.

===== registerTrigger() =====

Registers one or two commands bound to a single input pin in trigger mode.

<nowiki>int ObjectsInSpace::registerTrigger ( uint8_t pin,
OISCommand activeCommand,
uint8_t mode = INPUT
)</nowiki>

Arduinos In Space will poll the pin specified by <tt>pin</tt>, and whenever it changes from inactive to active will send the given client command. The maximum number of managed command pins are specified by the numCommandPins argument when constructing an ObjectsInSpace object. Attempts to register more than this limit will silently fail.

'''Parameters''
* <tt>pin</tt> The pin to monitor. Arduinos in Space will set the mode, do '''not''' call <tt>pinMode()</tt> on this pin.
* <tt>activeCommand</tt> The command to send when the pin goes active.
* <tt>mode</tt> This sets the pin mode, as well as what readings will be considered active. When set to <tt>INPUT</tt>, the pin is active when HIGH. When set to <tt>INPUT_PULLUP</tt>, the pin is active when LOW.

----

<nowiki>int ObjectsInSpace::registerTrigger ( uint8_t pin,
OISCommand activeCommand,
OISCommand inactiveCommand,
uint8_t mode = INPUT
)</nowiki>

Arduinos In Space will poll the pin specified by <tt>pin</tt>, sending activeCommand when the pin changes from inactive to active, and inactiveCommand when the pin changes from active to inactive. The maximum number of managed command pins are specified by the numCommandPins argument when constructing an ObjectsInSpace object. Attempts to register more than this limit will silently fail.

'''Parameters''
* <tt>pin</tt> The pin to monitor. Arduinos in Space will set the mode, do '''not''' call <tt>pinMode()</tt> on this pin.
* <tt>activeCommand</tt> The command to send when the pin goes active.
* <tt>inactiveCommand</tt> The command to send when the pin goes inactive.
* <tt>mode</tt> This sets the pin mode, as well as what readings will be considered active. When set to <tt>INPUT</tt>, the pin is active when HIGH. When set to <tt>INPUT_PULLUP</tt>, the pin is active when LOW.

==== Active phase ====

===== update() =====

The main ObjectsInSpace loop.

<nowiki>void ObjectsInSpace::update()</nowiki>

Polls for new serial data, checks managed pin state, keeps the ObjectsInSpace object state consistent. This method should be run fairly frequently, ensure a call to it is in your <tt>loop()</tt> function at least once.

===== sendCommand() =====

Send a command to the game.

<nowiki>void ObjectsInSpace::sendCommand( OISCommand command )</nowiki>

The given command is sent to the game. Commands sent during the active phase should have been registered with <tt>registerCommannd()</tt> during synchronisation. Arduinos in Space does not track registered commands, though, so will send any valid command passed to <tt>sendCommand()</tt>. The game will (should?) ignore commands that were not requested.

'''Parameters'''
* <tt>commannd</tt> The command to send.

===== sendDebug() =====

Send a log message to the game.

<nowiki>void ObjectsInSpace::sendDebug( char * message )</nowiki>

Send a text message to the game. This will be treated as a debug message, and appended to the game log file. Arduinos in Space uses this internally to send a banner message ("Arduinos in Space version x.x.x device successfully connected!") on initial connectionn.

== OISCommand ==

A struct representing a possible Objects in Space channel.

=== Attributes ===

* <pre>int channel</pre> The channel ID. Only used for command channels.
* <pre>char const * name</pre> The full text name of the channel.

This struct contains information necessary to create a request or command channel. Each Arduinos in Space release includes OISCommand constants for all known requests and commands at time of release, with variable names identical to the <tt>name</tt> field. It shouldn't be necessary to create your own.

[[Category:ArduinosInSpace]]

Arduinos in Space API

2018-08-15T12:27:55Z

Stibbons:

2018-07-24T09:09:46Z

Stibbons: Created blank page

Arduinos in Space

2018-07-24T09:07:57Z

Stibbons:

[https://bitbucket.org/pjhardy/arduinosinspace/src/master/ 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 ==

=== Installation ===

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

# Download the most recent release from the [https://bitbucket.org/pjhardy/arduinosinspace/downloads/ downloads section] of the library repository on Bitbucket.
# Open the Arduino IDE, and navigate to Sketch -> Include Library -> Add .ZIP Library...
# 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]].

[[Category:ArduinosInSpace]]

Arduinos in Space

2018-07-24T09:06:56Z

Stibbons:

[https://bitbucket.org/pjhardy/arduinosinspace/src/master/ 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 ==

=== Installation ===

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

# Download the most recent release from the [https://bitbucket.org/pjhardy/arduinosinspace/downloads/ downloads section] of the library repository on Bitbucket.
# Open the Arduino IDE, and navigate to Sketch -> Include Library -> Add .ZIP Library...
# 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]].

[[:Category:ArduinosInSpace]]

Arduinos in Space

2018-07-24T08:22:25Z

Stibbons: Created page with "[https://bitbucket.org/pjhardy/arduinosinspace/src/master/ Arduinos in Space] is an Arduino library to interface with Objects in Space. It aims to provide a high level, Arduin..."

Arduino Librarys

2018-07-24T08:15:04Z

Stibbons: /* Arduino Libraries (WIP) */

== Arduino Libraries (WIP)==

* interface for the serial protocol [https://github.com/Segwegler/OIS_Library OIS Library git]
* [[Arduinos in Space]]. A high-level, Arduino-like interface to Objects in Space.

[[Category:HardwareInterfacing]]

Getting started with hardware

2018-06-29T12:41:00Z

Stibbons: tada!

You want to build an Objects in Space controller? Great! Here's how to get started.

__TOC__

== Configuring the game ==

The hardware interface is not enabled by default. To turn it on, add the following to your [[Configuration file]] (ref: [http://forum.objectsgame.com:88/t/objects-in-space-beta-technical-notes/809 Objects in Space Beta Technical Notes])

<pre>hardware=true</pre>

Windows users may also want to add this option to prevent the game from scanning the hardware COM1 and COM2 ports:

<pre>ignorecom12=true</pre>

== Arduinos ==

Getting started with Arduino is way too big a topic to cover here. The [https://www.arduino.cc/en/Guide/HomePage Arduino Getting Started Guide] and [https://www.arduino.cc/en/Tutorial/HomePage Arduino Tutorial index] are a good jumping-off point. It's recommended, at bare minimum, to familiarise yourself with, and understand how the BlinkWithoutDelay and Debounce example sketches work, and be able to write new sketches that use these techniques. They're very important for driving basic I/O with Objects in Space.

== The serial protocol ==

The [[ExternalProtocol|External Protocol]] documentation includes a description of the serial protocol itself, as well as lists of the commands that are possible and data that can be requested from the game.

== Arduino libraries ==

A number of projects are underway to encapsulate the serial protocol and make writing code to work with the game easier. See [[Arduino Librarys|Arduino Libraries]].

[[Category:HardwareInterfacing]]

Arduino Librarys

2018-06-18T12:19:31Z

Stibbons:

== Arduino Libraries (WIP)==

* interface for the serial protocol [https://github.com/Segwegler/OIS_Library OIS Library git]
* [https://bitbucket.org/pjhardy/arduinosinspace Arduinos In Space]. A high-level, Arduino-like interface to Objects in Space.

[[Category:HardwareInterfacing]]

Serial Requests

2018-06-18T11:52:40Z

Stibbons: Power commands

== Numeric Requests ==

{| class="wikitable"
!colspan="2"|Numeric Requests
|-
!colspan="2"|Power
|-
|<code>POWER_LEVEL</code>
|An '''integer value''' showing available power as a percentage of total capacity. Note that the game currently doesn't fill all batteries to capacity, so this won't report higher than 99.
|-
|<code>POWER_DRAIN</code>
|A '''float value''' indicating net power drain in mw. Values > 0 indicate net power gain, < 0 is a net power loss. For example, the default Ceres starter ship has a 5.00mw reactor, and idles at -1.20mw power draw. <code>POWER_DRAIN</code> usually report 3.80.
|-
|<code>POWER_DRAW_PERCENT</code>
|An '''integer value'''. Usage is unknown. Seems to reflect current power draw as a percentage of total possible draw.
|-
!colspan="2"|Movement
|-
|DESIRED_DIRECTION
|-
|MOTION_ANGLE
|The angle the ship is moving
|-
|DIRECTION
|The angle the ship is facing
|-
|CURRENT_SPEED
|-
|CURRENT_SPEED_PERCENT
|-
!colspan="2"|Nav
|-
|CURRENT_DISTANCE
|-
|ASTEROID_DENSITY
|-
|NEBULA_DENSITY
|-
!colspan="2"|Weapons
|-
|TUBE_SELECTED
|Which weapon tube is selected
|-
|CURRENT_TUBE_SPIN_UP_PERCENT
|-
!colspan="2"|Misc
|-
|PRESSURE_EXTERIOR
|-
|PRESSURE_INTERIOR
|-
|PRESSURE_AIRLOCK
|-
|CURRENT_TEMPERATURE
|-
|AMOUNT_OWED_TO_DOCKED
|-
|AMOUNT_OWED_VIA_COMMS
|-
|AUTO_REPAIR_PERCENT
|-
|ENG_CURRENT_REPAIR_PERCENT
|-
|ENG_CURRENT_SPARE_PARTS
|Might not be in the game
|-
|ENG_MAX_SPARE_PARTS
|Might not be in the game
|-
|JMP_SOLUTION
|-
|MAIN_DRIVE_POWER_LEVEL
|-
|HULL_TEMPERATURE
|-
|UNREAD_EMAILS
|-
|READ_EMAILS
|-
|PLAYER_CREDITS
|-
|SOLAR_RADIATION_PERCENT
|-
|GRAPPLE_ARM_PERCENTAGE
|-
|HACK_PERCENTAGE
|-
|PENDING_EMAILS
|}

== Boolean Requests ==

{| class="wikitable"
!colspan="2"|Boolean Requests
|-
!colspan="2"|Docking
|-
|NOT_DOCKED
|-
|IS_DOCKED_OR_DOCKING
|-
|IS_DOCKED
|-
|IS_DOCKING
|-
|IS_FULLY_DOCKED
|-
|IS_UNDOCKING
|-
|NOT_DOCKING
|-
|NOT_UNDOCKING
|-
|CAN_OPEN_AIRLOCK
|-
|HAS_DOCKING_PERMISSION
|-
|NEEDS_DOCKING_PERMISSION
|-
|HAS_UNDOCKING_PERMISSION
|-
|NEEDS_UNDOCKING_PERMISSION
|-
|NOT_DOCKED_OR_MULTIPLAYER
|-
|NOT_DOCKED_OR_MULTIPLAYER_OR_TUTORIAL
|-
|CAN_GET_UNDOCKING_PERMISSION
|-
|CANNOT_GET_UNDOCKING_PERMISSION
|-
|DOCKED_BUT_CANNOT_UNDOCK
|-
|OWES_MONEY_TO_DOCKED_STATION_AND_CANNOT_PAY
|-
|OWES_MONEY_TO_DOCKED_STATION_AND_CAN_PAY
|-
|IS_DOCKED_WITH_DEPOT
|-
|ANY_AIRLOCK_OPEN
|-
|ALL_AIRLOCKS_SEALED
|-
|AIRLOCKS_CLOSED_BUT_NEEDS_UNDOCK_PERMISSION
|-
|CAN_UNDOCK
|-
|OWES_MONEY_TO_DOCKED_STATION
|-
|IS_DOCKED_WITH_STATION
|-
|IS_DOCKED_WITH_JUMPGATE
|-
|NEED_TO_PAY_FOR_JUMPGATE
|-
|CAN_ACTIVATE_JUMPGATE
|-
|NOT_DOCKED_WITH_STATION
|-
|DOCKED_WITH_JUMPGATE
|-
!colspan="2"|Nav
|-
|CLUSTER_MODE
|-
|NAV_TARGET_SELECTED
|-
|HAS_SELECTED_OBJECT
|-
|HAS_SELECTED_DIRECTION
|True when you are pointing in the direction you are moving (not always correct)
|-
|HAS_COURSE_PLOTTED
|-
|COURSE_PLOTTED_NOT_ENGAGED
|-
|MAP_LOCKED_TO_SHIP
|-
|MAP_IN_SECTOR_MODE
|-
|HAS_SELECTED_DESTINATION
|-
|VALID_TRAVEL_TARGET_SELECTED
|-
|CAN_ADD_WAYPOINT
|-
|IS_IN_FREE_SPACE
| ?
|-
!colspan="2"|Piloting
|-
|CAN_COME_TO_FULL_STOP
|-
|CAN_ROTATE
| ?
|-
|IS_MOVING
|-
|IS_STATIONARY
|-
|MAIN_ENGINE_BURNING
|-
|MAIN_DRIVE_FUNCTIONAL
|-
|AUTO_PILOT_ENGAGED
|-
|AUTO_PILOT_NOT_ENGAGED
|-
|RCS_BURNING
|-
|RCS_BURNING_CW
|-
|RCS_BURNING_CCW
|-
!colspan="2"|Jump Drive
|-
|JMP_CAN_SET_JUMP_DESTINATION
|-
|JMP_CAN_SPIN_UP_JUMP_DRIVE
|-
|JMP_CAN_CALC_JUMP
|-
|JMP_CAN_JUMP
|-
|JMP_CAN_DISCHARGE_JUMP_DRIVE
|-
|JMP_HAS_JUMP_DRIVE
|-
|JMP_IS_SPINNING_UP
|-
|JMP_IS_CALCULATING_JUMP
|-
|JMP_IS_SPUN_UP
|-
|JMP_IS_CALCULATED
|-
|JUMPDRIVE_ACTIVE
|-
!colspan="2"|Alerts
|-
|PWR_LOW_POWER_WARNING
|-
|PCE_ALARM
|-
|STATUS_WARNING
|-
|STATUS_DANGER
|-
|STATUS_NOMINAL
|-
|IN_ASTEROID_FIELD
|-
|IN_NEBULA
|-
!colspan="2"|Weapons
|-
|CM_EXISTS
|-
|CM_CANLAUNCH
|-
|CM_CANNOTLAUNCH
|-
|PDS_EXISTS
|-
|PDS_ACTIVE
|-
|PDS_INACTIVE
|-
|TUBE_HAS_TORPEDO
|-
|TUBE_HAS_MINE
|-
|TUBE_HAS_PROBE
|-
|TUBE_CAN_BE_ARMED”
|-
|TUBE_CAN_POWER_DOWN
|-
|TUBE_CAN_BE_DISABLED
|-
|TUBE_CAN_SPIN_UP
|-
|TUBE_CAN_FIRE
|-
|TUBE_CAN_LAUNCH
|-
|TUBE_LAUNCHED
|-
|TUBE_EMPTY
|-
|TUBE_SPINNING_UP
|-
|TUBE_LINKED
|-
|TUBE_HAS_EXP
|-
|TUBE_HAS_EMP
|-
|TARGET_AND_WEAPON_SELECTED
|-
|TUBE_1_SELECTED
|-
|TUBE_2_SELECTED
|-
|TUBE_3_SELECTED
|-
|TUBE_4_SELECTED
|-
|TUBE_5_SELECTED
|-
|CAN_SET_TARGET
|-
|CAN_CHANGE_TARGET
|-
|CANNOT_SET_OR_CHANGE_TARGET
|-
|PDL_ACTIVE
|-
!colspan="2"|Power
|-
|PWR_IS_DRAINING
|-
|PWR_IS_GENERATING
|-
|IS_TURNED_ON
|-
|IS_TURNED_OFF
|-
|EMCON_MODE
|-
|PWR_CURRENT_MODULE_ON
|-
|PWR_CURRENT_MODULE_OFF
|-
|PWR_CURRENT_MODULE_EMCON_ON
|-
|PWR_CURRENT_MODULE_EMCON_OFF
|-
|PWR_CURRENT_MODULE_CAN_SCRAM
|-
|PWR_REACTOR_ON
|-
|PWR_REACTOR_OFF
|-
!colspan="2"|Comms
|-
|IFF_ACTIVE
|-
|COMMS_AUTOSYNC_ON
|-
|BEING_HAILED
|-
|SELECTED_OBJECT_CAN_COMMUNICATE
|-
|HAS_EMAILS_TO_DOWNLOAD
|-
|SOS_ACTIVE
|-
!colspan="2"|Sensors
|-
|SENSORS_NAV_LINKED
|-
|SENSORS_HISTORY_LOCKED
|-
|SENSORS_AUTO
|-
|LADAR_ACTIVE
|-
|LADAR_FUNCTIONAL
|-
|LADAR_INACTIVE
|-
|LADAR_DETECTED
|-
!colspan="2"|Engineering
|-
|ENG_MODULE_ON
|-
|ENG_MODULE_OFF
|-
|ENG_MODULE_CAN_OPEN
|-
|ENG_MODULE_OPEN
|-
|ENG_NO_MODULE_OPEN
|-
|ENG_CAN_CLOSE_CURRENT_MODULE
|-
|ENG_MODULE_CAN_BE_CONNECTED
|-
|ENG_NO_TRAY_OBJECT_SELECTED
|-
|ENG_CAN_REPAIR_COMPONENT
|-
|ENG_IS_REPAIRING
|-
|AUTO_REPAIR_ENABLED
|-
|AUTO_REPAIR_IDLE
|-
|MODULE_REACTOR_UNDAMAGED
|-
|MODULE_REACTOR_DAMAGED
|-
|MODULE_REACTOR_DESTROYED
|-
|MODULE_REACTOR_CONNECTED
|-
|MODULE_REACTOR_FUNCTIONING
|-
|MODULE_MAINDRIVE_UNDAMAGED
|-
|MODULE_MAINDRIVE_DAMAGED
|-
|MODULE_MAINDRIVE_DESTROYED
|-
|MODULE_MAINDRIVE_CONNECTED
|-
|MODULE_RCS_UNDAMAGED
|-
|MODULE_RCS_DAMAGED
|-
|MODULE_RCS_DESTROYED
|-
|MODULE_RCS_CONNECTED
|-
|MODULE_COMMS_UNDAMAGED
|-
|MODULE_COMMS_DAMAGED
|-
|MODULE_COMMS_DESTROYED
|-
|MODULE_COMMS_CONNECTED
|-
|MODULE_BATT1_UNDAMAGED
|-
|MODULE_BATT1_DAMAGED
|-
|MODULE_BATT1_DESTROYED
|-
|MODULE_BATT1_CONNECTED
|-
|MODULE_BATT2_UNDAMAGED
|-
|MODULE_BATT2_DAMAGED
|-
|MODULE_BATT2_DESTROYED
|-
|MODULE_BATT2_CONNECTED
|-
|MODULE_BATT3_UNDAMAGED
|-
|MODULE_BATT3_DAMAGED
|-
|MODULE_BATT3_DESTROYED
|-
|MODULE_BATT3_CONNECTED
|-
|MODULE_HELM_UNDAMAGED
|-
|MODULE_HELM_DAMAGED
|-
|MODULE_HELM_DESTROYED
|-
|MODULE_HELM_CONNECTED
|-
|MODULE_SENSORS_UNDAMAGED
|-
|MODULE_SENSORS_DAMAGED
|-
|MODULE_SENSORS_DESTROYED
|-
|MODULE_SENSORS_CONNECTED
|-
|MODULE_NAVCOM_UNDAMAGED
|-
|MODULE_NAVCOM_DAMAGED
|-
|MODULE_NAVCOM_DESTROYED
|-
|MODULE_NAVCOM_CONNECTED
|-
|MODULE_WEAP_UNDAMAGED
|-
|MODULE_WEAP_DAMAGED
|-
|MODULE_WEAP_DESTROYED
|-
|MODULE_WEAP_CONNECTED
|-
|MODULE_JUMPDRIVE_UNDAMAGED
|-
|MODULE_JUMPDRIVE_DAMAGED
|-
|MODULE_JUMPDRIVE_DESTROYED
|-
|MODULE_JUMPDRIVE_CONNECTED
|-
|MODULE_BOOTING
|-
|MODULE_DISCONNECTED
|-
!colspan="2"|Misc
|-
|IS_IN_ORBIT
|-
|IS_IN_STANDARD_ORBIT
|-
|IS_IN_HIGH_ORBIT
|-
|IS_IN_POLAR_ORBIT
|-
|NOT_IN_STANDARD_ORBIT
|-
|NOT_IN_HIGH_ORBIT
|-
|NOT_IN_POLAR_ORBIT
|-
|IS_CHANGING_ORBIT
|-
|IS_LEAVING_ORBIT
|-
|IS_ENTERING_ORBIT
|-
|IS_CORRECTING_ORBIT
|-
|IS_IN_STABLE_ORBIT
|-
|SHOW_SPACE_DISC
|-
|DONT_SHOW_SPACE_DISC
|-
|CAN_TELEPORT
|-
|IS_MOORED
|-
|IS_MOORED_TO_DEBRIS
|-
|IS_MOORED_TO_CARGO
|-
|HAS_GRAPPLING_ARM
|-
|GRAPPLING_ARM_IN_USE
|-
|CAN_GRAPPLE_MOORED
|-
|CAN_GRAPPLE_SHIP
|-
|CAN_JETTISON
|-
|CAN_JETTISON_ALL
|-
|CAN_HACK
|-
|CANNOT_HACK
|-
|HAS_HACKING_UNIT
|-
|IS_HACKING
|-
|SHOULD_SHOW_CARGO_SCREEN
|-
|CAN_REPAIR_HULL_AT_DEPOT
|-
|CANNOT_REPAIR_HULL_AT_DEPOT
|-
|CAN_REPAIR_MODULES_AT_DEPOT
|-
|CANNOT_REPAIR_MODULES_AT_DEPOT
|-
|CAN_REARM_AT_DEPOT
|-
|CANNOT_REARM_AT_DEPOT
|-
|CAN_BUY_CM_AT_DEPOT
|-
|CANNOT_BUY_CM_AT_DEPOT
|-
|CAN_JUMP_IN_TUTORIAL
|-
|CAN_DETECT_CASSANDRA
|-
|SUBMENU_OPTIONS
|-
|SUBMENU_INPUT
|-
|SUBMENU_NEWS
|-
|TRADE_HASPURCHASE
|-
|TRADE_VALIDPURCHASE
|-
|TRADE_INVALIDPURCHASE
|-
|TRADE_HASSALE
|-
|TRADE_VALIDSALE
|-
|TRADE_INVALIDSALE
|-
|TRADE_HASPURCHASEORSALE
|-
|COMMERCE_ATMENU
|-
|COMMERCE_NOTATMENU
|-
|COMMERCE_MENUIS
|-
|COMMERCE_CANPURCHASELICENSE
|-
|COMMERCE_CANNOTPURCHASELICENSE
|-
|COMMERCE_LOANGIVERSELECTED
|-
|COMMERCE_LOANGIVERNOTSELECTED
|-
|COMMERCE_REPAYINGLOAN
|-
|COMMERCE_LOANVALID
|-
|COMMERCE_LOANINVALID
|-
|COMMERCE_REPAYMENTVALID
|-
|COMMERCE_REPAYMENTINVALID
|-
|COMMERCE_CANTAKECONTRACT
|-
|COMMERCE_CANNOTTAKECONTRACT
|-
|COMMERCE_CANTAKEPASSENGER
|-
|COMMERCE_CANNOTTAKEPASSENGER
|-
|WIRE_VISIBLE
|-
|MECHANIC_ATMENU
|-
|MECHANIC_AT
|-
|MECHANIC_CAN_REPAIR
|-
|MECHANIC_CANNOT_REPAIR
|-
|MECHANIC_CAN_BUY_POD
|-
|MECHANIC_CANNOT_BUY_POD
|-
|MECHANIC_CAN_SELL_POD
|-
|MECHANIC_CANNOT_SELL_POD
|-
|MECHANIC_CAN_UPGRADE_POD
|-
|MECHANIC_CANNOT_UPGRADE_POD
|-
|MECHANIC_CAN_BUY_MODULE
|-
|MECHANIC_CANNOT_BUY_MODULE
|-
|MECHANIC_CAN_SELL_MODULE
|-
|MECHANIC_CANNOT_SELL_MODULE
|-
|MECHANIC_CAN_BUY_ARMAMENT
|-
|MECHANIC_CANNOT_BUY_ARMAMENT
|-
|MECHANIC_CAN_SELL_ARMAMENT
|-
|MECHANIC_CANNOT_SELL_ARMAMENT
|-
|SHIP_CANBUY
|-
|SHIP_CANNOTBUY
|-
|MOORED_WRECK_HAS_NOT_DOWNLOADED_DATA
|-
|MOORED_WRECK_HAS_DOWNLOADED_DATA
|-
|MOORED_WRECK_HAS_UNCLAMPED_CARGO
|-
|MOORED_WRECK_HAS_NOT_UNCLAMPED_CARGO
|-
|CAN_BOARD_BROKER_SHIP
|-
|CAN_NOT_BOARD_BROKER_SHIP
|-
|IS_VIEWING_SELECTED_SHIP
|-
|IS_NOT_VIEWING_SELECTED_SHIP
|-
|STARTING_NEW_GAME
|-
|CONVERSATION_ACTIVE
|-
|MUSIC_PLAYING
|-
|MUSIC_NOT_PLAYING
|-
|CAN_USE_MUSIC
|-
|SHIP_DISABLED
|-
|COMMERCE_CANTAKEBOUNTY
|-
|COMMERCE_CANNOTTAKEBOUNTY
|-
|}

[[Category:HardwareInterfacing]]