Arduinos in Space API

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

ObjectsInSpace( Stream & serial,
                     int numRequests,
                     int numCommandPins
              )

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 Serial.begin().

Parameters

• serial The serial instance this object will use to communicate with the game. Usually Serial.
• numRequests 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.
• numCommandPins The number of managed input pins to allocate. This is the maximum number of commands channels with managed input pins (created via registerLatching() or registerTrigger()) the object will support. Commands that will be send directly through sendCommand() do not need to be included here.

---

ObjectsInSpace( Stream & serial,
                     int numRequests
              )

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.

void ObjectsInSpace::begin()

The begin() 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

void ObjectsInSpace::activate()

The activate() 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).

int ObjectsInSpace::registerBool( OISCommand command,
                                         int pin,
                                        bool invert=false
                                )

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 pinMode() 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

• command The data command to request.
• pin A pin number to control.
• invert 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.

---

int ObjectsInSpace::registerBool(   OISCommand command,
                                  boolCallback callback
                                )

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

• command The data command to request.
• callback 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.

int ObjectsInSpace::registerInt(  OISCommand command,
                                 intCallback callback
                               )

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

• command The data command to request.
• callback 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.

int ObjectsInSpace::registerFloat(    OISCommand command,
                                   floatCallback callback
                                 )

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

• commannd The data command to request.
• callback 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.

int ObjectsInSpace::registerCommand( OISCommand command )

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

Parameters

• command The command to register.

registerLatching()

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

int ObjectsInSpace::registerLatching (    uint8_t pin,
                                       OISCommand firstCommand,
                                       OISCommand secondCommand,
                                          uint8_t mode=INPUT
                                     )

Arduinos In Space will poll the pin specified by pin. 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

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

registerTrigger()

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

int ObjectsInSpace::registerTrigger (    uint8_t pin,
                                      OISCommand activeCommand,
                                         uint8_t mode = INPUT
                                    )

Arduinos In Space will poll the pin specified by pin, 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

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

---

int ObjectsInSpace::registerTrigger ( uint8_t pin, OISCommand activeCommand, OISCommand inactiveCommand, uint8_t mode = INPUT )

Arduinos In Space will poll the pin specified by pin, 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

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

Active phase

update()

The main ObjectsInSpace loop.

void ObjectsInSpace::update()

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 loop() function at least once.

sendCommand()

Send a command to the game.

void ObjectsInSpace::sendCommand( OISCommand command )

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

Parameters

• commannd The command to send.

sendDebug()

Send a log message to the game.

void ObjectsInSpace::sendDebug( char * message )

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

• int channel

  The channel ID. Only used for command channels.

• char const * name

  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 name field. It shouldn't be necessary to create your own.