Stibbons at 12:29, 15 August 2018

2018-08-15T12:29:36Z

Stibbons at 12:27, 15 August 2018

2018-08-15T12:27:55Z

Stibbons: Created page, documentation for ObjectsInSpace class.

2018-08-15T12:21:18Z

Created page, documentation for ObjectsInSpace class.

New page

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

← Older revision		Revision as of 12:29, 15 August 2018
Line 218:		Line 218:

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

← Older revision		Revision as of 12:27, 15 August 2018
Line 207:		Line 207:

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

Arduinos in Space API - Revision history

Stibbons at 12:29, 15 August 2018

Stibbons at 12:27, 15 August 2018

Stibbons: Created page, documentation for ObjectsInSpace class.