Primary "front-facing" class for the SetListArduino library. More...

#include <SetListArduino.h>

Classes
struct	SerialCommandCallback
	Data `struct` containing a map between serial commands and SetList callback functions. More...

Public Member Functions
	SetListArduino (int triggerChannel)
	Constructor function. More...

template<typename Device >
void	registerDevice (Device &device, int channel)
	Registers an Arduino-controlled device with SetListArduino, indicating it should expect to receive SetList commands from the computer. More...

template<typename Callback >
void	registerCommand (const char *command, int channel, Callback function)
	Registers a callback command with SetListArduino, associated with a particular device channel. More...

void	clearSetList ()
	Clears the currently programmed setlist by resetting SetListArduino::_setlistLength counter. More...

int	getTriggerChannel ()
	Returns SetListArduino::_triggerChannel. More...

void	triggerUpdate ()
	Forces update on all devices to next SetList line. More...

void	readSerial ()
	Listens to the serial stream for new commands from the computer. More...

void	clearSerialBuffer ()
	Resets the serial buffer after encountering a line termination character. More...

Private Attributes
volatile int	_line
	State variable tracking active SetList line. More...

int	_setlistLength
	Member data containing the length of the programmed SetList. More...

int	_triggerChannel
	Binding for `attachInterrupt()` ISR routine. More...

SerialCommandCallback *	_commandList
	Dynamically allocated list of registered commands. More...

char	_serialTerm
	Serial stream line terminator. More...

char	_buffer [SERIALCOMMAND_BUFFER+1]
	Serial command buffer. More...

int	_bufPos
	Current position in the serial buffer. More...

char	_delim [2]
	Text delimiter to use for strtok_r in readSerial(). More...

char *	_last
	State variable used by strtok_r in readSerial(). More...

int	_commandCount
	Holds total number of registered commands. More...

int	_activeDevice
	Variable tracking the channel of "active" device. More...

int	_deviceCount
	Tracks number of registered devices. More...

SetListBase *	_deviceList [MAX_DEVICE_NUMBER]
	List of pointers to the registered devices. More...

bool	_errorFlag
	Boolean flag indicating whether an error has occurred. More...

Static Private Attributes
static const char	_activateDeviceCmd = '@'
	Special short command to activate a particular device. More...

static const char	_initRunCmd = '$'
	Special short command to initialize a run. More...

static const char	_echoSetListCmd = '?'
	Special short command to echo each device's SetList back to the serial terminal. More...

static const char	_executeSingleLine = '#'
	Special short command to execute a single setlist line on a particular channel. More...

Detailed Description

Primary "front-facing" class for the SetListArduino library.

Summary

SetListArduino orchestrates the whole show. If you simply want to implement computer control for a new Arduino-controlled device, this is the only class you'll need to deal with.

In an Arduino sketch, you will want to use the pre-declared singleton instance, SetListImage. This ensures the Arduino handles trigger interrupts properly.

For specific information about implementing an Arduino sketch, look to the README.

Constructor & Destructor Documentation

SetListArduino::SetListArduino ( int triggerChannel )

Constructor function.

Creates what (should be) a singleton instance of SetListArduino.

Parameters

triggerChannel Integer specifying where attachInterrupt() should bind. For Arduino Due, this will be the trigger channel pin number. For other Arduino boards, this might be the index of an ISR which operates on a particular (pre-defined) pin. Check out the Arduino Documentation for details on what you should pass here.

Member Function Documentation

void SetListArduino::clearSerialBuffer ( )

Resets the serial buffer after encountering a line termination character.

void SetListArduino::clearSetList ( )

Clears the currently programmed setlist by resetting SetListArduino::_setlistLength counter.

int SetListArduino::getTriggerChannel ( )

Returns SetListArduino::_triggerChannel.

See also: SetListArduino()

void SetListArduino::readSerial ( )

Listens to the serial stream for new commands from the computer.

This should be called repeatedly in the void loop(){...} portion of your Arduino sketch. For more information, look at the README.

template<typename Callback >

void SetListArduino::registerCommand	(	const char *	command,
		int	channel,
		Callback	function
	)

inline

Registers a callback command with SetListArduino, associated with a particular device channel.

This is how you set up a "connection table" between particular serial commands and the correct callback functions to control the state of a connected device. During LoadHardwareImage, LabView SetList will write a sequence of "short commands" and parameters to the serial terminal. SetListArduino listens for these, and depending on which device is being written to, associates those commands with a particular callback function and inserts the resulting callback into that device's setlist using SetListDevice::insertToSetList().

Information about how to implement this in an Arduino sketch can be found in the README.

Parameters

command	"Short command" SetListArduino will listen for on the serial terminal. This should match up with the short-command set up in the LabView device.
channel	Integer specifying the device channel to register the command with. See details in SetListArduino::registerDevice().
function	Callback function to be executed.

template<typename Device >

void SetListArduino::registerDevice	(	Device &	device,
		int	channel
	)

inline

Registers an Arduino-controlled device with SetListArduino, indicating it should expect to receive SetList commands from the computer.

If #SETLIST_DEBUG is set, this will print debug information back to the serial terminal.

Be sure to read the channel details below!!** You'll be glad you did when you avoid a segfault.

Parameters

device Device, passed in by reference, which will be added to SetListArduino::_deviceList and enabled for computer control.

channel Integer, starting with zero, corresponding to the index at which the device will be placed in the array SetListArduino::_deviceList. It is important that you define channels sequentially, beginning with 0, because SetListArduino will loop through _deviceList[0] ... _deviceList[n] where n is the number of registered devices. If it tries to execute SetList commands on a device that has not been registered, you risk a segfault. Ultimately this should be protected against, but for now just take note! Number your channels from 0...n and you'll be fine.

For specific information on how this should be used in an Arduino sketch, look to the README.

See also: registerCommand(), SetListDevice

void SetListArduino::triggerUpdate ( )

Forces update on all devices to next SetList line.

This function loops through the registered devices, and calls SetListDevice::executeSetList() on the active line.

The active setlist line is kept track of by SetListArduino::_line.

Make sure you have read the warning in SetListArduino::registerDevice(), because there is a risk of segfault if SetListArduino tries to execute callbacks for non-existant devices.

See also: registerDevice(), SetListDevice::executeSetList()

Member Data Documentation

const char SetListArduino::_activateDeviceCmd = '@'

staticprivate

Special short command to activate a particular device.

Sending "@ 0" to the serial terminal will activate the device on channel 0. This short command expects a single parameter; any additional parameters will be ignored.

See also: SetListArduino::_activeDevice, readSerial()

int SetListArduino::_activeDevice

private

Variable tracking the channel of "active" device.

Here, "active" means SetList commands written to the serial terminal will be added to that device's SetList. Devices are activated with the special short command given in SetListArduino::_activateDeviceCmd.

char SetListArduino::_buffer[SERIALCOMMAND_BUFFER+1]

private

Serial command buffer.

readSerial() stores characters here while looking for serial termination character.

int SetListArduino::_bufPos

private

Current position in the serial buffer.

int SetListArduino::_commandCount

private

Holds total number of registered commands.

SerialCommandCallback* SetListArduino::_commandList

private

Dynamically allocated list of registered commands.

List of SetListArduino::SerialCommandCallback structs, which SetListArduino::readSerial() uses to lookup incoming serial commands when programming a new SetList.

See also: readSerial(), SerialCommandCallback

char SetListArduino::_delim[2]

private

Text delimiter to use for strtok_r in readSerial().

int SetListArduino::_deviceCount

private

Tracks number of registered devices.

Variable keeping count of how many Arduino-controlled devices are registered with SetListArduino for computer control.

During the execution of a SetList, SetListArduino will loop through each device in SetListArduino::_deviceList, up to the index given by _deviceCount. See the warning in registerDevice() about avoiding segfaults.

See also: SetListArduino::_deviceList, registerDevice()

SetListBase* SetListArduino::_deviceList[MAX_DEVICE_NUMBER]

private

List of pointers to the registered devices.

This is a list of pointers to devices you have registered using registerDevice(). Be sure to look at the warning in registerDevice() to avoid segfaults, because the channel you register with a given device is just the index in _deviceList.

I concede this could be handled better, perhaps in a future release.

const char SetListArduino::_echoSetListCmd = '?'

staticprivate

Special short command to echo each device's SetList back to the serial terminal.

Sending "?" to the serial terminal will cause the Arduino to write each device's setlist to the serial terminal, including information about how many SetList triggers that device expects.

See also: readSerial()

bool SetListArduino::_errorFlag

private

Boolean flag indicating whether an error has occurred.

During readSerial(), if SetListArduino encounters an error such as an out-of-bound index, non-rectangular setlist, or invalid command, it will set _errorFlag = true and report back to LabView on the serial stream.

This feature can be enabled/disabled by setting SETLIST_ERROR_CHECK

const char SetListArduino::_executeSingleLine = '#'

staticprivate

Special short command to execute a single setlist line on a particular channel.

Sending "# (channel) (line)" will cause the Arduino to execute the SpecificSetListCallback function on the given line and channel.

For example, "# 0 5" would execute the SetList command line 5 for device 0.

See also: readSerial()

const char SetListArduino::_initRunCmd = '$'

staticprivate

Special short command to initialize a run.

Sending "$" to the serial terminal will place the Arduino in a state where it is ready to receive triggers on SetListArduino::_triggerChannel.

See also: readSerial()

char* SetListArduino::_last

private

State variable used by strtok_r in readSerial().

volatile int SetListArduino::_line

private

State variable tracking active SetList line.

char SetListArduino::_serialTerm

private

Serial stream line terminator.

Set to "\n" in SetListArduino()

int SetListArduino::_setlistLength

private

Member data containing the length of the programmed SetList.

Behavior of SetListArduino relies on the SetLists programmed from LabView be of equal length. Specifically, SetListArduino::_setlistLength is reset each time LabView activates a new device from the serial terminal, and is incremented for each new SetList line passed for that device. There is rudimentary error checking done to ensure each SetListDevice has a setlist of the expected length. Setting SETLIST_ERROR_CHECK will cause SetListArduino to print back to the serial terminal indicating either the command was OK or whether there is an error.

int SetListArduino::_triggerChannel

private

Binding for attachInterrupt() ISR routine.

For Arduino Due, this is the pin where you have attached the trigger channel. For other Arduinos, this is the ISR to use, which works on a pre-defined pin.

Interrupts are handled in the static class SetListISR.

See also: SetListISR, SetListArduino()

The documentation for this class was generated from the following files:

/Users/npisenti/git_master/libraries/SetListArduino/SetListArduino.h
/Users/npisenti/git_master/libraries/SetListArduino/SetListArduino.cpp

Classes

Public Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Summary

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation