cd_control_module Class Reference [ControlDeck framework]

The class from which all user code will be derived. More...

#include <cd_control_module.h>

List of all members.

Public Member Functions
	cd_control_module (const char *mod_name)
	Constructor.
virtual	~cd_control_module ()
	Destructor.
virtual void	initialize_data ()
	Create any necessary data points; do not attempt to request data points yet.
virtual void	initialize_data_requests ()
	Aggregate data requests here.
virtual void	setup_data (const char *command, const char *value)
	Get variable setup data from the setup file.
virtual void	initialize ()
	Perform any other necessary initialization.
void	request_timer (double period, int code)
	Request that a timer be called at a specific interval for periodic tasks.
void	remove_timer (int code)
	Stop receiving timer notifications for a specific timer.
virtual void	run_timer (int code)
void	start_background_task (void *data, int code)
	Start a background task that will process data and then return a result asynchronously.
virtual void	run_background_task (void *data, int code)
	Process a specific background task.
virtual void	handle_intermediate_data (void *data, int code)
	Process intermediate results from a background task.
virtual void	complete_background_task (void *data, int code)
	Process a completed background task.
void	return_intermediate_data (void *data, int code)
	Return an intermediate result from a background task.
void	request_event_notification (const char *group, const char *event_name, int code)
	Request notification whenever an event occurs (most modules will want notification of at least sim updates)
void	trigger_event (const char *group, const char *event_name)
	Trigger an event so that other modules are notified of its occurrence.
virtual void	handle_event (int code)
	Handle the occurrence of an event.
CD_DATA_REF	create_data (const char *group, const char *path, int type, const char *units, const char *description, void *initial_value=NULL)
	Create a ControlDeck variable that is available to other modules.
CD_DATA_REF	request_data (const char *group, const char *path, int type, bool required=false, const char *units=NULL, const char *description=NULL)
	Get access to a ControlDeck variable from another module or from the DSim simulation.
void	mark_telemetry (CD_DATA_REF data)
	Mark a ControlDeck variable as being telemetry to be provided to VisualCommander.
void	mark_command (CD_DATA_REF data, const char *human_name=NULL)
	Mark a ControlDeck variable as being commandable from VisualCommander.
void	mark_command_and_telemetry (CD_DATA_REF data, const char *human_name=NULL)
	Mark a ControlDeck variable as being telemetry and being commandable from VisualCommander.
void	mark_telemetry_and_command (CD_DATA_REF data, const char *human_name=NULL)
	Mark a ControlDeck variable as being telemetry and being commandable from VisualCommander.
void	add_attribute (CD_DATA_REF data, const char *attribute, const char *value)
	Add an attribute to a ControlDeck variable.
bool	value_as_type (CD_DATA_REF data, int type, void *destination)
	Get the current value of a ControlDeck variable.
void	set_value_as_type (CD_DATA_REF data, int type, void *source, const char *msg=NULL)
	Set the current value of a ControlDeck variable.
void	add_setup (const char *command, const char *value)
void	execute_setups (void)
void	plog (const char *format,...)
	Log an informational message.
void	error (const char *file, int line, const char *format,...)
	Throw an error, halting execution of the entire control deck and printing an error message.
ds_date	current_time ()
	Get the current time for the control system.
unsigned int	get_variables_count () const
	Used by the manifest builder to access created variables - supplies a copy of the array.
virtual void	describe_setup ()
	Provide the command suite along with a description for each.
void	describe_setup_command (const char *command, const char *description)
	Used only in describe_setup to add a command and description.
void	set_x (void *v)
	Internal use only.

---

Detailed Description

The class from which all user code will be derived.

All user code in ControlDeck is derived from the cd_control_module class. The virtual functions (initialize_data(), initialize(), run_timer(), run_background_task(), handle_intermediate_data(), complete_background_task() and handle_event()) are overridden as required. The derived user code is then installed into a control system within a control deck.

---

Constructor & Destructor Documentation

cd_control_module::cd_control_module

(

const char *

mod_name )

Constructor.

Control Module constructor. Code in this function should be minimal, as no system/deck connection yet exists. Do not call any cd_control_module functions from your constructor.

Parameters:

mod_name

The module name (which must be unique within its control system). Your constructor must pass the name it is given to the cd_control_module constructor.

---

Member Function Documentation

void cd_control_module::add_attribute	(	CD_DATA_REF	data,
		const char *	attribute,
		const char *	value
	)

Add an attribute to a ControlDeck variable.

Add an attribute to a variable which will subsequently be provided to VisualCommander. This function must be called during initialize() to have any effect.

Parameters:

data	The CD_DATA_REF for the variable to which the attribute should be added.
attribute	The attribute to add.
value	The value to give the attribute.

Referenced by mark_command(), mark_command_and_telemetry(), and mark_telemetry_and_command().

void cd_control_module::add_setup	(	const char *	command,
		const char *	value
	)

Store a setup command read from a setup file (internal use only).

Parameters:

command	The command to issue.
value	The command value.

void cd_control_module::complete_background_task	(	void *	data,
		int	code
	)		[virtual]

Process a completed background task.

This function should handle the completion of a background task.

Parameters:

data	The data object originally provided to start_background_task(). This function should take care to delete this object (after casting it to the appropriate data structure).
code	The code provided when start_background_task was called.

CD_DATA_REF cd_control_module::create_data	(	const char *	group,
		const char *	path,
		int	type,
		const char *	units,
		const char *	description,
		void *	initial_value = NULL
	)

Create a ControlDeck variable that is available to other modules.

Create a new ControlDeck variable. This is analogous to DSim's publish_variable, except that the variable is stored by the system rather than referring to a local module variable.

Parameters:

group	The group this variable should exist within. If this is NULL, the group defaults to the system that this module is located within.
path	The path to this variable within the group. This path is not constrained to follow regular DSim path requirements, but it should do so if the variable will be used as telemetry
type	The type of this variable (typically sd_type_double,sd_type_matrix or the like).
units	A string giving the units for this variable
description	A string giving a human description for this variable
initial_value	A pointer to a variable giving the initial value for this variable. This pointer must be either NULL (no initial value) or must refer to a variable of a type appropriate for the new variable- no conversion is performed!

Returns:

A CD_DATA_REF that can subsequently be used to get or set the value of this variable. On failure, the return value will be equal to NULL.

References plog().

void cd_control_module::describe_setup

(

)

[virtual]

Provide the command suite along with a description for each.

By overriding describe_setup(), modules are able to self-document the setup commands that they accept. This is necessary for users to properly set up objects of this model with the Control Deck GUI application, as only described setup commands can be used from that application. Modules that do not accept custom setup commands do not need to provide an implementation of this function, but modules that override parse_setup() should also override describe_setup().

Within the describe_setup() implementation, describe_setup_command() should be called once for each setup command that this model accepts.

Always call your module's superclass's implementation of describe_setup() first.

References describe_setup_command().

void cd_control_module::describe_setup_command	(	const char *	command,
		const char *	description
	)

Used only in describe_setup to add a command and description.

Documents a single setup command accepted by this model.

Parameters:

command	A command accepted by this model, which should match one of the strings handled by this model's implementation of parse_setup().
description	A human-readable description of this command. This description will be displayed to users who are setting up objects of this model to allow them to properly use the custom setup commands.

Referenced by describe_setup().

void cd_control_module::error	(	const char *	file,
		int	line,
		const char *	format,
			...
	)

Throw an error, halting execution of the entire control deck and printing an error message.

Print an error message and halt the entire control deck. This function also takes a file and line number, and should be called as ERROR(format,...) (which will fill in the file and line info automatically) rather than directly. This function will print the error message and then halt execution of the deck, and should be used only for fatal errors.

Parameters:

file	The file in which the error occurred.
line	The line at which the error occurred.
format	The format string.

void cd_control_module::execute_setups

(

void

)

Execute the setup commands provided in the setup file (internal use only). Calls setup_data() for each setup command.

References setup_data().

Referenced by cd_control_system::initialize_data().

void cd_control_module::handle_event

(

int

code )

[virtual]

Handle the occurrence of an event.

Overload this function to handle events. When an event occurs for which the module has requested notification with request_event_notification, this function will be called.

Parameters:

code	The code provided during the request_event_notification() call.

void cd_control_module::handle_intermediate_data	(	void *	data,
		int	code
	)		[virtual]

Process intermediate results from a background task.

This function should handle intermediate data that has been returned by a running background task.

Parameters:

data	The data object provided as intermediate data. This function should take care to delete this object (after casting it to the appropriate data structure).
code	The code provided by the task returning the data.

Referenced by return_intermediate_data().

void cd_control_module::initialize

(

)

[virtual]

Perform any other necessary initialization.

This function is called after initialize_data() to allow the module to complete any necessary initialization, including the setup of events. All cd_control_module functions are fully available at this time. Also, at this time variables have been set with values from any Set lines in the ControlDeck setup file.

Referenced by cd_control_system::initialize().

void cd_control_module::initialize_data

(

)

[virtual]

Create any necessary data points; do not attempt to request data points yet.

This function is called to allow the module an opportunity to create data points as necessary using create_data(). Do not request any data points yet, as the order of initialization is non-deterministic. Also, no variables have yet been set from the ControlDeck setup file.

Referenced by cd_control_system::initialize_data().

void cd_control_module::initialize_data_requests

(

)

[virtual]

Aggregate data requests here.

This function is called to allow the module an opportunity to request data points as necessary. Called after initialize_data(); Also include the mark_telemetry() and mark_command() calls in this method.

References request_data().

Referenced by cd_control_system::initialize().

void cd_control_module::mark_command	(	CD_DATA_REF	data,
		const char *	human_name = NULL
	)

Mark a ControlDeck variable as being commandable from VisualCommander.

Mark a variable as a command so that it can be set by VisualCommander. This function must be called during initialize() to have any effect.

Parameters:

data	The CD_DATA_REF for the variable to mark.
human_name	An optional parameter giving the command a more human-readable name

References add_attribute().

void cd_control_module::mark_command_and_telemetry	(	CD_DATA_REF	data,
		const char *	human_name = NULL
	)

Mark a ControlDeck variable as being telemetry and being commandable from VisualCommander.

Mark a variable as a command and telemetry so that it can be set by VisualCommander. This function must be called during initialize() to have any effect.

Parameters:

data	The CD_DATA_REF for the variable to mark.
human_name	An optional parameter giving the command a more human-readable name

References add_attribute().

void cd_control_module::mark_telemetry

(

CD_DATA_REF

data )

Mark a ControlDeck variable as being telemetry to be provided to VisualCommander.

Mark a variable as telemetry so that it is provided to VisualCommander. This function must be called during initialize() to have any effect.

Parameters:

data	The CD_DATA_REF for the variable to mark.

void cd_control_module::mark_telemetry_and_command	(	CD_DATA_REF	data,
		const char *	human_name = NULL
	)

Mark a ControlDeck variable as being telemetry and being commandable from VisualCommander.

Mark a variable as a command and telemetry so that it can be set by VisualCommander. This function must be called during initialize() to have any effect.

Parameters:

data	The CD_DATA_REF for the variable to mark.
human_name	An optional parameter giving the command a more human-readable name

References add_attribute().

void cd_control_module::plog	(	const char *	format,
			...
	)

Log an informational message.

Print an informative log message. Use this function in the same way that printf would be used.

Parameters:

format

The format string.

Referenced by create_data(), and set_value_as_type().

void cd_control_module::remove_timer

(

int

code )

Stop receiving timer notifications for a specific timer.

Remove a timer so it is no longer called.

Parameters:

code	The code with which the timer was registered.

CD_DATA_REF cd_control_module::request_data	(	const char *	group,
		const char *	path,
		int	type,
		bool	required = false,
		const char *	units = NULL,
		const char *	description = NULL
	)

Get access to a ControlDeck variable from another module or from the DSim simulation.

Get access to a ControlDeck variable from another module or from the DSim simulation. Must be called from within initialize_data_requests();

Get a reference to a ControlDeck variable (which may be a DSim published variable that has been mapped into the ControlDeck). This reference can subsequently be used to get or set the value of the variable. This is somewhat analagous to DSim's subscribe functionality.

Parameters:

group	The group that the variable of interest is located within. If this is NULL, the group defaults to this module's group.
path	The path to the variable of interest.
type	The expected type of the variable to be looked up. If the type does not match, NULL will be returned.
required	The presence of this variable is required or optional.
units	The expected units of the varlable to be looked up. If the units does not match, NULL will be returned.
description	Text comment visible in the ControlDeckManager GUI.

Returns:

A CD_DATA_REF that can subsequently be used to get or set the value of this variable. On failure, the return value will be equal to NULL.

Referenced by initialize_data_requests().

void cd_control_module::request_event_notification	(	const char *	group,
		const char *	event_name,
		int	code
	)

Request notification whenever an event occurs (most modules will want notification of at least sim updates)

Request that the system notify this module any time the system or any other module triggers an event with the given group and event name. Be aware that event names can be duplicated as long as the groups are different. To receive notification of simulation updates, use the constant CD_SYSTEM_GROUP for the group and CD_SIMULATION_STEP_EVENT for event_name.

Parameters:

group	The group for the triggered event of interest. If this is NULL, the group will default to the system that this module is in.
event_name	The event name for the triggered event of interest.
code	The code that the system should provide when notifying you of this event.

void cd_control_module::request_timer	(	double	period,
		int	code
	)

Request that a timer be called at a specific interval for periodic tasks.

Request that run_timer() be called every period seconds with the provided code.

Parameters:

period	The timer period
code	The user-defined code for this timer.

void cd_control_module::return_intermediate_data	(	void *	data,
		int	code
	)

Return an intermediate result from a background task.

Return a set of data to the main thread (which will be handled by handle_intermediate_data()). This is the only acceptable way to communicate back to the main thread from a task (other than task completion).

Parameters:

data	The data object. This object should be allocated with new, and will be deleted by the handle_intermedaite_data() function.
code	The code to return with the data object.

References handle_intermediate_data().

void cd_control_module::run_background_task	(	void *	data,
		int	code
	)		[virtual]

Process a specific background task.

This function should handle actually running a background task based on the provided code. It is critically important that this function *not* touch any data other than that passed in via the data variable, and the only method of communication back to the main thread should be with the return_intermediate_data function. (Other communication is possible, if absolutely necessary, but data synchronization is then up to the user and is strongly discouraged).

Parameters:

data	The data object provided when start_background_task was called.
code	The code provided when start_background_task was called.

void cd_control_module::run_timer

(

int

code )

[virtual]

Overload this function to handle a timer whenever it fires

Parameters:

code	The code of the timer that fired

void cd_control_module::set_value_as_type	(	CD_DATA_REF	data,
		int	type,
		void *	source,
		const char *	msg = NULL
	)

Set the current value of a ControlDeck variable.

Store a value from the provided source into a ControlDeck variable. Currently, the provided type must match the ControlDeck variable's type to avoid failure.

Parameters:

data	The CD_DATA_REF to the variable of interest.
type	The type for the variable from which the value should be copied (typically one of sd_type_double,sd_type_matrix,etc).
source	A pointer from which the data should be copied.
msg	A string that is appended to the error message when the CD_DATA_REF is null.

Returns:

true if the storage was successful; false if it failed (due to a failed type conversion).

References plog().

void cd_control_module::setup_data	(	const char *	command,
		const char *	value
	)		[virtual]

Get variable setup data from the setup file.

This function is called to allow the control system setup file to provide configuration to the module as to where it should request data from. It will be called once for each data-configuration element in the setup file for this module, and will be called after initialize_data_requests() but before initialize() via execute_setups().

Referenced by execute_setups().

void cd_control_module::start_background_task	(	void *	data,
		int	code
	)

Start a background task that will process data and then return a result asynchronously.

Spawn a new thread to run a background task, and pass to it a data object and a code.

Parameters:

data	The data object. This object should be allocated with new, and will be deleted when the task is complete.
code	The code for this task. This code will be provided to the user-overloaded run_background_task function, to allow for multiple types of background tasks. It will also be provided when the task ends, and whenever the task provides intermediate data.

void cd_control_module::trigger_event	(	const char *	group,
		const char *	event_name
	)

Trigger an event so that other modules are notified of its occurrence.

Trigger the system to notify other modules that a specific event has occurred.

Parameters:

group	The group to trigger the event in. If this is NULL (the usual value), the group will default to the system that this module is in.
event_name	The event name to trigger.

bool cd_control_module::value_as_type	(	CD_DATA_REF	data,
		int	type,
		void *	destination
	)

Get the current value of a ControlDeck variable.

Retrieve the value of a ControlDeck variable by storing it in the provided destination. Currently, the provided type must match the ControlDeck variable's type to avoid failure.

Parameters:

data	The CD_DATA_REF to the variable of interest.
type	The type for the variable into which the value should be stored (typically one of sd_type_double,sd_type_matrix,etc).
destination	A pointer into which the data should be stored.

Returns:

true if the storage was successful; false if it failed (due to a failed type conversion).

---

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

• cd_control_module.h
• cd_control_module.cc