CraftWare from SimCraft SDK Support

SUMMARY:  INNER | FIELD | CONSTR | METHOD

CraftwarePC (Win32)

Class Craftware


class Craftware

This class is the base class for the Craftware API (Win32 PC Edition). The constructor and destructor methods for Craftware cannot be called directly and are used internally within the Craftware library only. To utilize this API, any one of the methods designated with the CRAFTWARE_API prefix can be used. Craftware::initialize must be called to start the interface. After a successful init, one of the methods to provide physics through the interface (for craft orientation and acceleration) must be used. Craftware::shutdown() must be called to cleanup the interface. All vectors are based on left-hand coordinates, with Z-up.


Field Summary
struct Craftware_Vars  struct Craftware_Vars
{
   double overallMotionCoefficient;
   double overallIntensityCoefficient;

   double rollAmplitude;
   double pitchAmplitude;
   double yawAmplitude;

   int rollIntensity;
   int pitchIntensity;
   int yawIntensity;
}
 
Constructor Summary
protected  Craftware()
          
protected  virtual ~Craftware()
          
 
Method Summary
 CRAFTWARE_API bool angularAccelerationAndOrientation( float orientation[3], float acceleration[3], float fRadius[3], bool bInDegrees = true )
          
 CRAFTWARE_API bool angularVelocityAndOrientation( float orientation[3], float angular_velocity[3], float fRadius[3], bool bInDegrees = true )
          
 CRAFTWARE_API bool calibratePlatform( bool homeSystem = false, bool bWarnOfMotion = true )
          
 CRAFTWARE_API bool convertLinearAccelToAngularAccel( float* inLinearX, float* inLinearY, float* inLinearZ, float* outAngularX, float* outAngularY, float* outAngularZ )
          
 CRAFTWARE_API bool errorCorrection(UINT axis)
          
 CRAFTWARE_API bool getAxisStatus(UINT axis)
          
 CRAFTWARE_API int getAxisPosition(UINT axis)
          
 CRAFTWARE_API char* getCraftwareVersion()
          
 CRAFTWARE_API int getMaxPosForAxis( UINT axis )
          
 CRAFTWARE_API bool getSettingsUpdates()
          
 CRAFTWARE_API Craftware_Vars getVars()
          
 CRAFTWARE_API bool goHome( bool lockPlatform, bool warnOfMotion = true )
          
 CRAFTWARE_API bool initialize( char* gameModule, bool initControlSystem = true, bool bWarnOfMotion, bool bInitMotion = true )
          
 CRAFTWARE_API bool isShutdownInProgress()
          
 CRAFTWARE_API bool isSystemInitialized()
          
 CRAFTWARE_API bool linearAccelerationAndOrientation( float orientation[3], float acceleration[3], bool bTransformAccelerationVals = true, bool bInDegrees = true )
          
 CRAFTWARE_API bool linearAndAngularAccelerationsAndOrientation( float orientation[3], float linear_accel[3], float angular_accel[3], bool bTransformAccelerationVals = true, bool bInDegrees = true )
          
 CRAFTWARE_API void log( char* logStr, bool overRideOnError = false, bool writeToStdOut = false, bool messageBox = false, UINT iconForMessageBox =-1 )
          
 CRAFTWARE_API void moveAxis(UINT axis, int position)
          
 CRAFTWARE_API bool orientationOnly( float orientation[3], bool bInDegrees = true )
          
 CRAFTWARE_API bool orientationAndGs( float orientation[3], float gs, bool bInDegrees = true )
          
 CRAFTWARE_API void saveHomePos(UINT axis, int position)
          
 CRAFTWARE_API bool setVars(Craftware_Vars)
          
 CRAFTWARE_API bool shutdown(bool bGoHome = true)
          
 CRAFTWARE_API void toggleLogging( bool enableDisable )
          
 

Field Detail

Craftware_Vars

			struct Craftware_Vars();
			
struct Craftware_Vars
{
     double rollAmplitude;       //defines the range of motion for the ROLL axis   ( Range of values: 1 -> 100     Default value: 85 )
     double pitchAmplitude;       //defines the range of motion for the PITCH axis   ( Range of values: 1 -> 100     Default value: 85 )
     double yawAmplitude;       //defines the range of motion for the YAW axis   ( Range of values: 1 -> 100     Default value: 85 )

     int rollIntensity;       //defines the motion intensity for the ROLL axis   ( Range of values: 1 -> 200     Default value: 100 )
     int pitchIntensity;       //defines the motion intensity for the PITCH axis   ( Range of values: 1 -> 200     Default value: 100 )
     int yawIntensity;       //defines the motion intensity for the YAW axis  ( Range of values: 1 -> 200     Default value: 100 )
};


Constructor Detail

Craftware

			protected Craftware();
			
This constructor cannot be called directly. It is used internally only.

~Craftware

			protected virtual ~Craftware();
			
This destructor cannot be called directly. It is used internally only.


Method Detail

angularAccelerationAndOrientation

			public CRAFTWARE_API bool angularAccelerationAndOrientation( float orientation[3],
											  float acceleration[3],
											  float fRadius[3],
											  bool bInDegrees = true );
			
This method is used to provide actual realtime physics and should be called repeatedly at the same frequency as screen painting operations. (or as close as possible) This method allows for the providing of the craft's orientation and angular acceleration vectors. All vectors are based on left-hand coordinates, with Z-up.

Params
orientation[3] (float):
X, Y, Z values for orientation; X = ROLL, Y = PITCH, Z = YAW; can be provided in radians or degrees. Range of values = +/- 180 or +/- 3.14 rad. +X results in ROLL right, +Y results in PITCH up, +Z results in YAW left.

acceleration[3] (float):
X, Y, Z values for angular acceleration; X = ROLL, Y = PITCH, Z = YAW; must be provided in Body Coordinates. Values must be given in either radians per second^2 or degrees per second^2. If provided in radians, bInDegrees must be set to false so the appropriate conversion from radians to degrees can be performed. X represents ROLL (left/right) accel, Y represents PITCH accel (forward/backward), and Z represents YAW accel (twist).

fRadius[3] (float):
Radius values for the X, Y, Z angular acceleration values. The radius for each axis will be used to convert the values provided in acceleration[3] from angular acceleration to linear acceleration.

bInDegrees (boolean) :
Specifies if the values of orientation[3] and acceleration[3] are provided in degrees (true) or radians (false). (default is true)

Return Value (boolean)
True if the command was received and applied without error. A return value of false indicates that an error occurred in the motion control system.

angularVelocityAndOrientation

			public CRAFTWARE_API bool angularVelocityAndOrientation( float orientation[3],
											  float angular_velocity[3],
											  bool bInDegrees = true );
			
This method is used to provide actual realtime physics and should be called repeatedly at the same frequency as screen painting operations. (or as close as possible) This method allows for the providing of the craft's orientation and angular velocity vectors. All vectors are based on left-hand coordinates, with Z-up.

Params
orientation[3] (float):
X, Y, Z values for orientation; X = ROLL, Y = PITCH, Z = YAW; can be provided in radians or degrees. Range of values = +/- 180 or +/- 3.14 rad. +X results in ROLL right, +Y results in PITCH up, +Z results in YAW left.

angular_velocity[3] (float):
X, Y, Z values for angular velocity; X = ROLL, Y = PITCH, Z = YAW; must be provided in Body Coordinates. Values must be given in either radians per second or degrees per second. If provided in radians, bInDegrees must be set to false so the appropriate conversion from radians to degrees can be performed. X represents ROLL (left/right), Y represents PITCH (forward/backward), and Z represents YAW (twist).

bInDegrees (boolean) :
Specifies if the values of orientation[3] are provided in degrees (true) or radians (false). (default is true)

Return Value (boolean)
True if the command was received and applied without error. A return value of false indicates that an error occurred in the motion control system.

calibratePlatform

			public CRAFTWARE_API bool calibratePlatform( bool bHomeSystem = false );
			
Performs a calibration of the motion system. Upon true, the system is in the home position and unlocked. This method is called at initialization, and does not need to be called specifically. Can be used for error correction or outside initialization resets.

Params
bHomeSystem (boolean):
Specifies if each of the actuators will be homed prior to calibration. Homing of the actuators is generally only required for attempts to correct error corrections. (default is false)

Return Value (boolean)
True is returned if the motion simulator was calibrated successfully. A return value of false indicates that either calibration or homing, if specified, failed. Failures could be caused by an unresponsive control system or an error condition within the actuators. A message box will be displayed if any error occurs.

convertLinearAccelToAngularAccel

			public CRAFTWARE_API bool convertLinearAccelToAngularAccel( float* inLinearX, 
float* inLinearY, float* inLinearZ, float* outAngularX, float* outAngularY, float* outAngularZ );
Performs a conversion of linear acceleration to angular acceleration.

In Params
inLinearX (float*):
Linear acceleration X (sway) value as input.

inLinearY (float*):
Linear acceleration Y (surge) value as input.

inLinearZ (float*):
Linear acceleration Z (heave) value as input.

Out Params
outLinearX (float*):
Angular acceleration X (Roll) value as output.

outLinearY (float*):
Angular acceleration Y (Pitch) value as output.

outLinearX (float*):
Angular acceleration Z (Yaw) value as output.

Return Value (void)

errorCorrection

			public CRAFTWARE_API bool errorCorrection();
			
Will attempt to clear each of the installed actuators of any error conditions that have occurred.

Params (void)
NONE

Return Value (boolean)
True is returned when the installed actuators were responsive and all error conditions have been cleared. If false is returned, a message box will be displayed indicated a failure to clear the error condition and SimCraft Support will need to be contacted by the motion simulator user to get the condition corrected.

getAxisStatus

			public CRAFTWARE_API bool getAxisStatus ( UINT axis );
			
Determines the status for the supplied axis.

Params (void)
axis UINT:
Specifies the axis to obtain status information.

Return Value bool
The returned boolean provides a true value for "ready" state and false for "error" state of the supplied axis.

getAxisPosition

			public CRAFTWARE_API int getAxisPosition ( UINT axis );
			
Determines the position for the supplied axis.

Params (void)
axis UINT:
Specifies the axis to obtain position information.

Return Value int
The returned integer is the current position of the supplied axis.

getCraftwareVersion

			public CRAFTWARE_API char* getCraftwareVersion();
			
Determines the current running version of Craftware

Params (void)
NONE

Return Value (char*)
The returned character pointer provides the location of the character array that contains the Craftware version.

getMaxPosForAxis

			public CRAFTWARE_API int getMaxPosForAxis ( UINT axis );
			
Determines and returns the maximum position for the supplied axis.

Params (void)
axis UINT:
Specifies the axis to obtain max position information.

Return Value int
The returned integer is the maximum position of the supplied axis.

getSettingsUpdates

			public CRAFTWARE_API bool getSettingsUpdates();
			
Will refresh the settings in Craftware from the XML based setting file (simSettings.xml).

Params (void)
NONE

Return Value (boolean)
True is returned if the xml file was successfully queried for settings updates. False is returned if the file could not be queried, and is generally caused by insufficient system level permissions.

getVars

			public CRAFTWARE_API Craftware_Vars getVars();
			
Will provide the Craftware_Vars structure which contains motion variables of amplitude and intensity for the PITCH, ROLL, and YAW axes. The values returned are specific to the game module id, which is specified as the first paramater of the initialize() method.

Params (void)
NONE

Return Value (Craftware_Vars)
Returns a copy of the Craftware_Vars struct.

goHome

			public CRAFTWARE_API bool goHome( bool bLockPlatform, bool bWarnOfMotion = true );
			
Returns the motion platform to its default position. [Roll (X) = 0, Pitch (Y) = 0, Yaw (Z) = 0]

Params
bLockPlatform (boolean):
This variable will invoke the automatic locking mechanism in each of the axes of the motion platform. Craftware will automatically check the lock status and unlock the platform before any motion is invoked. There may be times when you want to "goHome" and not lock the platform immediately following the call. In this case, set this variable to false.

bWarnOfMotion (boolean):
If true, the user will receive a message box prompt warning of impending motion of the platform. The user will be given an option to proceed (OK) or to cancel (CANCEL). (default is true)

Return Value (boolean)
If the user is prompted and warned of motion (if bWarnOfMotion is true) and the user cancels the action by selecting "Cancel" in the prompt messagebox, a value of false will be returned. False will also be returned if the home position could not be achieved or if the locking mechanism (bLockPlatform is true) failed to locked the system upon achieving home.

initialize

			public CRAFTWARE_API bool initialize( char* gameModule, bool bInitControlSystem = true, bool bWarnOfMotion );
			
This is a required method to initialize the Craftware API. This method will initialize the internal Craftware variables based on the supplied (unique) gameModule parameter. The gameModule parameter will be used to lookup Craftware variables specific to the gameModule in the Windows registry. (HKEY_LOCAL_MACHINE\SOFTWARE\SimCraft\CraftwarePC\"gameModule" - where "gameModule" is in the form outlined below.)

Params
gameModule (char*):
Specifies the unique id for the game given in the format scGMX where X is the unique game ID (integer) provided by SimCraft. If you need to obtain a unique game ID, please contact SimCraft Support. (support@simcraft.com or 1.877.SimCraft)

bInitControlSystem (boolean):
If true, the motion control system will be initialized. In test and implementation cases where a SimCraft motion device is not present, this value should be false. (default is true)

bWarnOfMotion (boolean):
If true, the motion control system will not be initialized until user accepts a safety warning message box. SimCraft CraftCon will warn user explicitly so it skips the step. Any title embedding Craftware should definately do this and leave true. (default is true)

Return Value (boolean)
If true, the initialization process of the motion control system was successful. If false, the user will be provided a message box indicating the error. For implementation and testing without the presence of a SimCraft motion platform, this method will return false which indicates that the device was not found, but all methods including those intended to provide data to the motion control system can still be called. After a successful initialization, the logging of messages and values will occur to a logs directory contained within the SimCraft control panel installation. If this control panel system is not present on a test or implementation system, logging will still occur but instead to the file "C:\craftwareTestOut.txt".

isShutdownInProgress

			public CRAFTWARE_API bool isShutdownInProgress();
			
Checks Craftware to see if a shutdown sequence has been invoked and is in process.

Params (void)
NONE

Return Value (boolean)
True if a Craftware shutdown sequence is in process, False if not.

isSystemInitialized

			public CRAFTWARE_API bool isSystemInitialized();
			
Checks to see if the motion control system has been initialized successfully.

Params (void)
NONE

Return Value (boolean)
True if the Craftware motion control system has been successfully initialized, False if not.

linearAccelerationAndOrientation

			public CRAFTWARE_API bool linearAccelerationAndOrientation( float orientation[3],
											 float acceleration[3],
											 bool bTransformAccelerationVals = true,
											 bool bInDegrees = true );
			
This method is used to provide actual realtime physics and should be called repeatedly at the same frequency as screen painting operations. (or as close as possible) This method allows for the providing of the craft's orientation and linear acceleration vectors. All vectors are based on left-hand coordinates, with Z-up.

Params
orientation[3] (float):
X, Y, Z values for orientation; X = ROLL, Y = PITCH, Z = YAW; can be provided in radians or degrees. Range of values = +/- 180 or +/- 3.14 rad. +X results in ROLL right, +Y results in PITCH up, +Z results in YAW left.

acceleration[3] (float):
X, Y, Z values for linear acceleration; X = SWAY, Y = SURGE, Z = HEAVE; can be provided in either Body or World Coordinates. Values must be given in meters per second^2. If provided in World Coordinates, bTransformAccelerationVals must be set to true so the appropriate transformation to Body Coordinates can be performed. X represents SWAY (left/right) accel, Y represents SURGE accel (forward/backward), and Z represents HEAVE accel (up/down).

bTransformAccelerationVals (boolean) :
If specified as true, the provided vector as acceleration[3] will be assumed to be provided in World Coordinates and will be transformed to the craft Body Coordinates. If false, no transformation is necessary.

bInDegrees (boolean) :
Specifies if the values of orientation[3] are provided in degrees (true) or radians (false). (default is true)

Return Value (boolean)
True if the command was received and applied without error. A return value of false indicates that an error occurred in the motion control system,

linearAndAngularAccelerationsAndOrientation

			public CRAFTWARE_API bool linearAndAngularAccelerationsAndOrientation( float orientation[3],
											 float linear_accel[3],
											 float angular_accel[3],								 
											 bool bTransformAccelerationVals = true,
											 bool bInDegrees = true );
			
This method is used to provide actual realtime physics and should be called repeatedly at the same frequency as screen painting operations. (or as close as possible) This method allows for the providing of the craft's orientation and both the linear and angular acceleration vectors. All vectors are based on left-hand coordinates, with Z-up.

Params
orientation[3] (float):
X, Y, Z values for orientation; X = ROLL, Y = PITCH, Z = YAW; can be provided in radians or degrees. Range of values = +/- 180 or +/- 3.14 rad. +X results in ROLL right, +Y results in PITCH up, +Z results in YAW left.

linear_accel[3] (float):
X, Y, Z values for linear acceleration; X = SWAY, Y = SURGE, Z = HEAVE; can be provided in either Body or World Coordinates. Values must be given in meters per second^2. If provided in World Coordinates, bTransformAccelerationVals must be set to true so the appropriate transformation to Body Coordinates can be performed. X represents SWAY (left/right) accel, Y represents SURGE accel (forward/backward), and Z represents HEAVE accel (up/down).

angular_accel[3] (float):
X, Y, Z values for angular (rotational) acceleration; X = ROLL, Y = PITCH, Z = YAW; must be provided in Body Coordinates only. Values must be given in degrees per second^2. X represents Roll (left/right) accel, Y represents Pitch accel (forward/backward), and Z represents Yaw accel.

bTransformAccelerationVals (boolean) :
If specified as true, the provided linear accel vector as linear_accel[3] will be assumed to be provided in World Coordinates and will be transformed to the craft Body Coordinates. If false, no transformation is necessary.

bInDegrees (boolean) :
Specifies if the values of orientation[3] are provided in degrees (true) or radians (false). (default is true)

Return Value (boolean)
True if the command was received and applied without error. A return value of false indicates that an error occurred in the motion control system,

log

			public CRAFTWARE_API void log( char* logStr, 
							   bool bOverRideOnError = false, 
							   bool bWriteToStdOut = false, 
							   bool bMessageBox = false, 
							   UINT iconForMessageBox =-1 );
			
This method allows for messages to be logged to the Craftware logging system and/or displayed to the user.

Params
logStr (char*):
Character pointer bOverRideOnError (boolean):
Logging will only log to the file if the log settings "logging enable" is true. If logging enable is false, but an error occurs I can override the log settings by making sure the override error is true. (default is false)

bWriteToStdOut (boolean):
Will write out logStr, assuming logging is enabled, to standard output which is the console window. This value is automatically set as false. This value needs to be true for any messages that would like to be viewed in the game module window. Debugging, etc. (default is false)

bMessageBox (boolean):
If true the log messages will be displayed in a message box. (default is false)

iconForMessageBox (UINT):
Unassigned integer and assigns the icons to the message box. There area 3 values:
   a. INFO: information icon
   b. WARNING: warning exclamation icon
   c. ERR: will show you a red X icon. Error has occurred.

Return Value (void)
NONE

orientationOnly

			public CRAFTWARE_API bool orientationOnly( float orientation[3], bool bInDegrees = true );
			
This method is used to provide actual realtime physics and should be called repeatedly at the same frequency as screen painting operations. (or as close as possible) This method allows for the providing of the craft's orientation vector in local, body coordinates, (X, Y, Z values), for orientation only control of the motion simulator; X = ROLL, Y = PITCH, Z = YAW. Must be provided in craft body coordinates. All vectors are based on left-hand coordinates, with Z-up.

Params
orientation[3] (float):
X, Y, Z values for orientation; X = ROLL, Y = PITCH, Z = YAW; can be provided in radians or degrees. Range of values = +/- 180 or +/- 3.14 rad. +X results in ROLL right, +Y results in PITCH up, +Z results in YAW left.

bInDegrees (boolean):
Specifies if the values of orientation[3] are provided in degrees (true) or radians (false). (default is true)

Return Value (boolean)
True if the command was received and applied without error. A return value of false indicates that an error occurred in the motion control system,

orientationAndGs

			public CRAFTWARE_API bool orientationAndGs( float orientation[3], float gs, bool bInDegrees = true );
			
This method is used to provide actual realtime physics and should be called repeatedly at the same frequency as screen painting operations. (or as close as possible) This method allows for the providing of the craft's orientation vector in local, body coordinates, (X, Y, Z values), for orientation only control of the motion simulator; X = ROLL, Y = PITCH, Z = YAW. Must be provided in craft body coordinates. An additional param for Gs is provided to allow for the specification of Gs experienced by the user. Typically, this value is used in aircraft simulation only. All vectors are based on left-hand coordinates, with Z-up.

Params
orientation[3] (float):
X, Y, Z values for orientation; X = ROLL, Y = PITCH, Z = YAW; can be provided in radians or degrees. Range of values = +/- 180 or +/- 3.14 rad. +X results in ROLL right, +Y results in PITCH up, +Z results in YAW left.

gs (float):
Value representing Gs

bInDegrees (boolean):
Specifies if the values of orientation[3] are provided in degrees (true) or radians (false). (default is true)

Return Value (boolean)
True if the command was received and applied without error. A return value of false indicates that an error occurred in the motion control system,

setVars

			public CRAFTWARE_API bool setVars(Craftware_Vars);
			
Will set the Craftware_Vars stuct which contains motion variables of amplitude and intensity for the PITCH, ROLL, and YAW axes. The values returned are specific to the game module id, which is specified as the first paramater of the initialize() method. All values are stored in the Windows system registry. (HKEY_LOCAL_MACHINE\SOFTWARE\SimCraft\CraftwarePC\"gameModule")

Params
Craftware_Vars struct defined as Craftware_Vars

Return Value (boolean)
Returns true if the setting of the Craftware_Vars struct was successful, false if otherwise.

shutdown

			public CRAFTWARE_API bool shutdown();
			
Homes and locks the motion platform. Cleans up communication ports, close log files, and, assuming all return fine, returns true

Params (void)
NONE

Return Value (boolean)
True if shutdown occurred without error. False if a problem occurred. If an error does occur during shutdown, the user will see a messagebox indicating the problem.

toggleLogging

			public CRAFTWARE_API void toggleLogging( bool enableDisable );
			
Toggles logging on and off.

Params
enableDisable (bool):
If true, logging is enabled. If false, logging is disabled. After a successful initialization, the logging of messages and values will occur to a logs directory contained within the SimCraft control panel installation. If this control panel system is not present on a test or implementation system, logging will still occur but instead to the file "C:\craftwareTestOut.txt".

Return Value (void)
NONE

SUMMARY:  INNER | FIELD | CONSTR | METHOD


Newsletter Signup

Email: