SpaceControl DLL  Version 2.8.9
API documentation for the SpaceControl 3D input devices
Functions
Functions for accessing SpaceControl devices

These functions are used to handle with a device in a more general way as in the other sections. More...

Functions

ScStatus scGetDevNum (int *devNumP, int *usedDevNumP, int *maxDevIdxP)
 Retrieves the number devNum of SpaceControl devices actually connected to the computer, the number usedDevNum of SpaceControl devices actually used by the driver and the maximal device index maxDevIdx a device may be addressed with at the moment. More...
 
ScStatus scGetDevInfo (int devIdx, ScDevInfo *diP)
 Retrieves some information data about the device with the given index. More...
 
ScStatus scGetDefDevPars (int devIdx, ScDevPars *dpP)
 Retrieves the default values of the device parameters. More...
 
ScStatus scGetDevPars (int devIdx, ScDevPars *dpP)
 Retrieves the actual device parameters as listed in the *.cfg files. More...
 
ScStatus scSetDevPars (int devIdx, ScDevPars *dpP)
 Sets and retrieves the actual device parameters as listed in the device's configuration file. More...
 
ScStatus scSetDevParsToDefaults (int devIdx, ScDevPars *dpP)
 Sets the actual device parameters to the defaults and retrieves the new parameters. More...
 
ScStatus scFetchStdData (int devIdx, short *xP, short *yP, short *zP, short *aP, short *bP, short *cP, int *traLmhP, int *rotLmhP, int *eventP, long *tvSecP, long *tvUsecP)
 Fetches the standard data set. More...
 
ScStatus scTransferCallbackFunction (int devIdx, stdDataCallbackP cbP)
 This function hands over a callback function pointer to the API. More...
 
ScStatus scGetRawData (int devIdx, unsigned char buf[RAW_DATA_LEN])
 The opto-electronical sensor integrated into the cap consists of six LEDs illuminating six position sensitive devices (PSD) producing data between 0 and 1023. More...
 
ScStatus scGetCfgFilename (int devIdx, char *filename)
 Retrieves the name and path of the device's actual configuration file. More...
 
ScStatus scSaveDevPars (int devIdx, char *filePath)
 Saves the actual parameters of the device with index devIdx to the configuration file given in filePath. More...
 
ScStatus scLoadDevPars (int devIdx, char *filePath, ScDevPars *dpP)
 Loads the parameters in the configuration file given in filePath into the device with index devIdx. More...
 
ScStatus scPressKey (int devIdx, int key)
 Triggers the same action as is done when a key of the device is pressed, i. More...
 
ScStatus scRelKey (int devIdx, int key)
 Triggers the same action as is done when a key of the device is released. More...
 
ScStatus scTriggerFunction (int devIdx, int funcIdx)
 Triggers the function with index funcIdx. More...
 
ScStatus scGetFmwUpdtState (int devIdx, int *mcuIdP, int *progressP)
 Retrieves the state of a firmware update in progress. More...
 
ScStatus scExecCmd (int devIdx, char *cmd)
 Executes a special command. More...
 

Detailed Description

These functions are used to handle with a device in a more general way as in the other sections.

Function Documentation

◆ scExecCmd()

ScStatus scExecCmd ( int  devIdx,
char *  cmd 
)

Executes a special command.

To avoid an extensive growing of API functions this function can be used to execute different commands. It is made for SpaceControl's internal use rather than for the common audience. A special syntax is needed for the command buffer:
The first character is the command identifier. The content of the others depends on the first one. For the time being the following command is defined only:

  • First character: '3': Causes all blue LEDs to blink with the period given in the following four characters. The string should be 0 terminated.
    Example: "30150\0": The LEDs will be 150 ms on and 150 ms off and so on.
    Example: "30000\0": Blinking is shut off.
    Example: "3-001\0": Values less than 0 mean, the period is retrieved from the parameter "blinkPeriod" in file "SpaceController/daemon.ini" in the user's home directory.
    Example:
    int devIdx = 0;
    char cmd[MAX_FILENAME_LEN] = "30500";
    ScStatus status = scExecCmd(devIdx, cmd);
    if (status == SC_OK)
    printf("ok\n");
    else
    printf("error\n");
    Parameters
    devIdxthe index of the device (if needed, -1 in other cases)
    cmdthe command with optional parameters
    Returns
    SC_OK, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX, SC_EXEC_CMD_ERROR

References SC_COMMUNICATION_ERROR.

◆ scFetchStdData()

ScStatus scFetchStdData ( int  devIdx,
short *  xP,
short *  yP,
short *  zP,
short *  aP,
short *  bP,
short *  cP,
int *  traLmhP,
int *  rotLmhP,
int *  eventP,
long *  tvSecP,
long *  tvUsecP 
)

Fetches the standard data set.

The device sends the standard data without request. These data can be fetched with this command. scFetchStdData() will wait 30 ms (this can be changed with the parameter mSendDelay of structure ScAdvancedSettings) if no data is delivered and then return with ScStatus SC_COMMUNICATION_ERROR. This is no real error in that case. Since the data is not actively requested you will get SC_COMMUNICATION_ERROR also in case of a wrong device index > 0; a device index < 0 will result in SC_WRONG_DEVICE_INDEX
The standard data consist out of:

  • The three translational coordinates (x, y, z) and the three rotational data (a [rotation around the x-axis], b [rotation around the y-axis] and c [rotation around the z-axis]).
  • The two flags traLmh and rotLmh. These are binary masks indicating how strong the cap is elongated regarding the advanced settings mTraLmBnd, mTraMhBnd, mRotLmBnd and mRotMhBnd. These four values give bounderies defining what is a low, mid or high elongation for the cap.
    Example: mTraLmBnd may be set to 80, mTraMhBnd may be set to 150. This means a translational elongation less then 80 is defined to be a "low" elongation, between 80 and 150 is a "mid" elongation and one greater than 150 is a "high" elongation (these definitions are used to trigger macro functions if configured in the GUI's function to key assignment dialog). The daemon evaluates this and tells it with the binary flags, so the application programmer does not need to do the calculation again.
    The bits of traLmh are set in this way:
    • Bit 0 is set if x < 0 and x >= -mTraLmBnd
    • Bit 1 is set if x < -mTraLmBnd and x >= -mTraMhBnd
    • Bit 2 is set if x < -mTraMhBnd
    • Bit 3 is set if x > 0 and x <= mTraLmBnd
    • Bit 4 is set if x > mTraLmBnd and x <= mTraMhBnd
    • Bit 5 is set if x > mTraMhBnd
    • Bit 6 is set if y < 0 and y >= -mTraLmBnd
    • Bit 7 is set if y < -mTraLmBnd and y >= -mTraMhBnd
    • Bit 8 is set if y < -mTraMhBnd
    • Bit 9 is set if y > 0 and y <= mTraLmBnd
    • Bit 10 is set if y > mTraLmBnd and y <= mTraMhBnd
    • Bit 11 is set if y > mTraMhBnd
    • Bit 12 is set if z < 0 and z >= -mTraLmBnd
    • Bit 13 is set if z < -mTraLmBnd and z >= -mTraMhBnd
    • Bit 14 is set if z < -mTraMhBnd
    • Bit 15 is set if z > 0 and z <= mTraLmBnd
    • Bit 16 is set if z > mTraLmBnd and z <= mTraMhBnd
    • Bit 17 is set if z > mTraMhBnd
      The bits of rotLmh are handled in the same way, but the rotational coordinates a, b and c are used.
  • The event code. With this parameter the daemon informs the application about some events the application might react on. These are the following (see enumeration EventType in event_type.h):
    • event has the value NOTHING_CHANGED: As the value says there is no event transmitted with this message.
    • event is less then BSC_SETTINGS_CHANGED: The value is a bitmask storing the device keys actually pressed. The meaning of the bits is as follows:
      • Bit 0 is set: key 1 is pressed.
      • Bit 1 is set: key 2 is pressed.
      • Bit 2 is set: key 3 is pressed.
      • Bit 3 is set: key 4 is pressed.
      • Bit 4 is set: key 5 is pressed.
      • Bit 5 is set: key 6 is pressed.
      • Bit 6 is set: ctrl key is pressed.
      • Bit 7 is set: alt key is pressed.
      • Bit 8 is set: shift key is pressed.
      • Bit 9 is set: esc key is pressed.
      • Bit 10 is set: front key is pressed.
      • Bit 11 is set: right key is pressed.
      • Bit 12 is set: top key is pressed.
      • Bit 13 is set: fit key is pressed.
      • Bit 14 is set: 2D/3D key is pressed.
      • Bit 15 is set: panel key is pressed.
      • Bit 16 is set: menu key is pressed.
    • event is BSC_SETTINGS_CHANGED: Basic settings are changed, the application should retrieve the basic settings parameters from the daemon again (if it is interested in the parameters).
    • event is ADV_SETTINGS_CHANGED: Advanced settings are changed, the application should retrieve the advanced settings parameters from the daemon again (if it is interested in the parameters).
    • event is DEV_PARS_CHANGED: Any parameters are changed, the application should retrieve all settings parameters from the daemon again (if it is interested in the parameters).
    • event is DEV_ERR_UNKNOWN_COMMAND, DEV_ERR_INVALID_VALUE, DEV_ERR_PARSE_ERROR, DEV_ERR_INTERNAL_ERROR, DEV_ERR_INVALID_ID or DEV_ERR_BUF_OVERFLOW: These signal error states in the device's firmware. The firmware is error free of course and they will not occur :-).
    • event is DEV_FRONT, DEV_RIGHT, DEV_TOP or DEV_FIT. The user has triggered one of the commands which are normally located at the Front-, Right-, Top- or Fit-Buttons. Be aware: The user may have reconfigured his keys, therefore getting the DEV_FRONT event e. g. does not mean necessarily that the user has pressed the Front key. May be he laid this command on another one.
      The application can trigger some appropriate action when getting one of these events.
    • event is equal or greater than APPL_FUNC_START. The user has pressed a key configured with a menu function of a "supported application". This is of interest only if one wants to write a SpaceControl plug-in. See the plug-in specification document for details.
    • Hint: If a device key is pressed the daemon always sends a key bitmask event (value less than BSC_SETTINGS_CHANGED). If the key is configured by the user to some further action the daemon will send a second event specifying the action, e. g. a DEV_FRONT event additionally! In these events all cap coordinates are set to 0.
  • The time the driver has generated the message. It is given as the number of seconds elapsed since jan 01 1970 UTC (in parameter tvSec) and the number of additional microseconds (in parameter tvUsec). These are the same as the components in the well known C struct timeval.

Example:

int devIdx = 0;
short x, y, z, a, b, c;
int traLmh, rotLmh, event;
long tvSec, tvUsec;
ScStatus status;
status = scFetchStdData(devIdx, &x, &y, &z, &a, &b, &c, &traLmh, &rotLmh, &event, &tvSec, &tvUsec);
if (status == SC_OK)
printf("x: %d\n", x);
else
printf("error\n");
Parameters
devIdxthe index of the device to be requested
Return values
xPpointer to the x coordinate
yPpointer to the y coordinate
zPpointer to the z coordinate
aPpointer to the rotation around the x-axis
bPpointer to the rotation around the y-axis
cPpointer to the rotation around the z-axis
traLmhPpointer to the low-, mid- and high-flags of translation
rotLmhPpointer to the low-, mid- and high-flags of rotation
eventPpointer to an event no.; events may be signaled at any time
tvSecPpointer to the time the message was generated by the driver: seconds elapsed since jan 01 1970 UTC
tvUsecPpointer to the time the message was generated by the driver: additional microseconds since *tvSecP
Returns
SC_OK, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX

References SC_OK, and SC_WRONG_DEVICE_INDEX.

◆ scGetCfgFilename()

ScStatus scGetCfgFilename ( int  devIdx,
char *  filename 
)

Retrieves the name and path of the device's actual configuration file.

The configuration file is located in the user's home directory in the folder 'SpaceController'. The folder SpaceController contains a set of folders whose names are constructed out of the serial numbers of all the devices connected to the computer in the past. Each of these folders contain a set of configuration files which are loaded alternatively dependent on the application controlled by the device.
Example:

int devIdx = 0;
char filename[MAX_FILENAME_LEN];
ScStatus status = scGetCfgFilename(devIdx, filename);
if (status == SC_OK)
printf("%sfilename: \n", filename);
else
printf("error\n");
Parameters
devIdxthe index of the device to be requested
Return values
filenamefile name, e.g. /home/fs/spacecontrol/[serialNo]/last.cfg
Returns
SC_OK, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX

References MAX_FILENAME_LEN, SC_COMMUNICATION_ERROR, SC_OK, and SC_WRONG_DEVICE_INDEX.

◆ scGetDefDevPars()

ScStatus scGetDefDevPars ( int  devIdx,
ScDevPars *  dpP 
)

Retrieves the default values of the device parameters.

Example:

int devIdx = 0;
ScDevPars dp;
ScStatus status = scGetDefDevPars(devIdx, &dp);
if (status == SC_OK)
printf("the default threshold is %d\n", dp.mBs.mNullRadius);
else
printf("error\n");
Parameters
devIdxindex of the device the parameters are requested
Return values
dpPpointer to the device parameters to be retrieved
Returns
SC_OK, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX

References SC_COMMUNICATION_ERROR, SC_OK, and SC_WRONG_DEVICE_INDEX.

◆ scGetDevInfo()

ScStatus scGetDevInfo ( int  devIdx,
ScDevInfo *  diP 
)

Retrieves some information data about the device with the given index.


Example:

int devIdx = 0;
ScDevInfo di;
ScStatus status = scGetDevInfo(devIdx, &di);
if (status == SC_OK)
printf("devices firmware version: %s\n", di.mDescrptn);
else
printf("error\n");
Parameters
devIdxindex of the device the infos are requested
Return values
diPpointer to the retrieved device info
Returns
SC_OK, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX

References SC_COMMUNICATION_ERROR, SC_OK, SC_WRONG_DEVICE_INDEX, ScDevInfo::setDescrptn(), ScDevInfo::setId(), and ScDevInfo::setSerialNo().

◆ scGetDevNum()

ScStatus scGetDevNum ( int *  devNumP,
int *  usedDevNumP,
int *  maxDevIdxP 
)

Retrieves the number devNum of SpaceControl devices actually connected to the computer, the number usedDevNum of SpaceControl devices actually used by the driver and the maximal device index maxDevIdx a device may be addressed with at the moment.


All devices are stored in an array; to address a device all DLL functions need the index in this array, and the indices are in the range 0..maxDevIdx. If a device is disconnected from the computer the array element is set to NULL but not removed out of the array (this behaviour ensures that an index does not change if another device is disconnected from the computer). Therefore maxDevIdx may be greater than devNum-1.
After getting maxDevIdx one can use function scGetDevInfo() to get the description or serial number of a device to identify it for further calls.
You can plug in more than one device into your computer. But, the driver is able to receive data from more than one device only if there is a "Master" device connected. Therefore there might be a difference between the values devNum and usedDevNum: devNum is the number of devices plugged in actually, usedDevNum is the number of devices actually used. These values are the same only if there is at least one master device connected, if not usedDevNum has the value 1 or 0.
Update: From driver version 2.4.0 on a master device is not necessary any longer to use more than one device. All hints concerning master devices in this document are obsolet therefore. Example:

int devNum, usedDevNum;
int maxDevIdx;
ScStatus status = scGetDevNum(&devNum, &usedDevNum, &maxDevIdx);
if (status == SC_OK)
{
printf("number of devices: %d\n", devNum);
for (int i = 0; i <= maxDevIdx; i++)
{
ScDevInfo di;
status = scGetDevInfo(i, &di);
if (status == SC_OK)
printf("device with index %d has serial no. %s\n", i, di.mSerialNo);
}
}
else
printf("error\n");
Return values
devNumPnumber of devices connected to the computer
usedDevNumPnumber of devices used by the driver (equals devNum only if there is a master device, is 0 or 1 otherwise)
maxDevIdxPbiggest index of a device connected to the computer
Returns
SC_OK, SC_COMMUNICATION_ERROR

References SC_COMMUNICATION_ERROR, and SC_OK.

◆ scGetDevPars()

ScStatus scGetDevPars ( int  devIdx,
ScDevPars *  dpP 
)

Retrieves the actual device parameters as listed in the *.cfg files.

Example:

int devIdx = 0;
ScDevPars dp;
ScStatus status = scGetDevPars(devIdx, &dp);
if (status == SC_OK)
printf("the threshold is %d\n", dp.mBs.mNullRadius);
else
printf("error\n");
Parameters
devIdxindex of the device the parameters are requested
Return values
dpPpointer to the device parameters to be retrieved
Returns
SC_OK, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX

References SC_COMMUNICATION_ERROR, SC_OK, and SC_WRONG_DEVICE_INDEX.

◆ scGetFmwUpdtState()

ScStatus scGetFmwUpdtState ( int  devIdx,
int *  mcuIdP,
int *  progressP 
)

Retrieves the state of a firmware update in progress.


The SpaceController contains three micro controllers (MCU):

  • The main micro controller (#1).
  • The micro controller for the Display (#2).
  • The micro controller of the sensor to measure the cap deflection (#4).

A firmware file is a zipped file with the extension "fmw" that contains the three files KMM.hex, KSM.hex and KDM.hex. If the user initiates a firmware update via the GUI the firmware file is unzipped, and the three hex files are written into the controllers' flash memory. The actual state can be retrieved with this command. If mcuId is < 0 an error has occured. Example:

int devIdx = 0;
int mcuId, progress;
ScStatus status = scGetFmwUpdtState(devIdx, &mcuId, &progress);
if (status == SC_OK)
{
printf("Micro controller: %d\n", mcuId);
printf(" progress/%: %d\n", progress);
}
else
printf("error\n");
Parameters
devIdxthe index of the device to be requested
Return values
mcuIdPthe ID of the micro controller just updating ( 0: no update in progress, 1: mainboard microcontroller is updating, 2: display microcontroller is updating, 4: sensor microcontroller is updating, -1: error while updating mainboard MCU, -2: error while updating display MCU, -4: error while updating sensor MCU)
progressPthe update sequence's progress of one of the three micro controllers in percent (-1..100, -1 means error)
Returns
SC_OK, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX

References SC_COMMUNICATION_ERROR, SC_OK, and SC_WRONG_DEVICE_INDEX.

◆ scGetRawData()

ScStatus scGetRawData ( int  devIdx,
unsigned char  buf[RAW_DATA_LEN] 
)

The opto-electronical sensor integrated into the cap consists of six LEDs illuminating six position sensitive devices (PSD) producing data between 0 and 1023.

These raw data can be requested here. Using this function is not recommended, use scFetchStdData() instead. The function returns a buffer of 28 unsigned characters with the following content:

  • buf[ 0]: PSD1, high Byte
  • buf[ 1]: PSD1, low Byte
  • buf[ 2]: PSD2, high Byte
  • buf[ 3]: PSD2, low Byte
  • buf[ 4]: PSD3, high Byte
  • buf[ 5]: PSD3, low Byte
  • buf[ 6]: PSD4, high Byte
  • buf[ 7]: PSD4, low Byte
  • buf[ 8]: PSD5, high Byte
  • buf[ 9]: PSD5, low Byte
  • buf[10]: PSD6, high Byte
  • buf[11]: PSD6, low Byte
  • buf[12]: PSD7, high Byte (this is pseudo data for intnernal use only)
  • buf[13]: PSD7, low Byte (this is pseudo data for intnernal use only)
  • buf[14]: LED1, high Byte
  • buf[15]: LED1, low Byte
  • buf[16]: LED2, high Byte
  • buf[17]: LED2, low Byte
  • buf[18]: LED3, high Byte
  • buf[19]: LED3, low Byte
  • buf[20]: LED4, high Byte
  • buf[21]: LED4, low Byte
  • buf[22]: LED5, high Byte
  • buf[23]: LED5, low Byte
  • buf[24]: LED6, high Byte
  • buf[25]: LED6, low Byte
  • buf[26]: LED7, high Byte (this is pseudo data for intnernal use only)
  • buf[27]: LED7, low Byte (this is pseudo data for intnernal use only) Attention: Only seven bits per byte are used. To get a value use the following formula: value = highByte*128 + lowByte. Example:
    int devIdx = 0;
    unsigned char buf[RAW_DATA_LEN];
    ScStatus status = scGetRawData(devIdx, buf);
    if (status == SC_OK)
    printf("PSD1: %d\n", buf[0]*128 + buf[1]);
    else
    printf("error\n");
    Parameters
    devIdxthe index of the device to be requested
    Return values
    bufdata buffer containing the result
    Returns
    SC_OK, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX

References RAW_DATA_LEN, SC_COMMUNICATION_ERROR, SC_OK, and SC_WRONG_DEVICE_INDEX.

◆ scLoadDevPars()

ScStatus scLoadDevPars ( int  devIdx,
char *  filePath,
ScDevPars *  dpP 
)

Loads the parameters in the configuration file given in filePath into the device with index devIdx.


Example:

int devIdx = 0;
char filename[MAX_FILENAME_LEN] = "/home/fs/test.cfg";
ScStatus status = scLoadDevPars(devIdx, filename, dpP);
if (status == SC_OK)
printf("ok\n");
else
printf("error\n");
Parameters
devIdxthe index of the device
filePathfile name, e.g. /home/fs/my.cfg
Return values
dpPpointer to the device parameter structure
Returns
SC_OK, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX

References SC_COMMUNICATION_ERROR, SC_OK, and SC_WRONG_DEVICE_INDEX.

◆ scPressKey()

ScStatus scPressKey ( int  devIdx,
int  key 
)

Triggers the same action as is done when a key of the device is pressed, i.

e. a macro assigned to the key is executed.
Example:

int devIdx = 0;
int key = 5;
ScStatus status = scPressKey(devIdx, key);
if (status != SC_OK)
printf("error\n");
Parameters
devIdxindex of the device the key seems to be pressed
keythe key's index (0..16)
Returns
SC_OK, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX, SC_PARAMETER_OUT_OF_RANGE, SC_KEYSTROKE_ERROR

References MAX_KEY_IDX, SC_COMMUNICATION_ERROR, SC_KEYSTROKE_ERROR, SC_OK, SC_PARAMETER_OUT_OF_RANGE, and SC_WRONG_DEVICE_INDEX.

◆ scRelKey()

ScStatus scRelKey ( int  devIdx,
int  key 
)

Triggers the same action as is done when a key of the device is released.


Example:

int devIdx = 0;
int key = 5;
ScStatus status = scRelKey(devIdx, key);
if (status != SC_OK)
printf("error\n");
Parameters
devIdxindex of the device the key seems to be released
keythe key's index (0..16)
Returns
SC_OK, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX, SC_PARAMETER_OUT_OF_RANGE, SC_KEYSTROKE_ERROR

References MAX_KEY_IDX, SC_COMMUNICATION_ERROR, SC_KEYSTROKE_ERROR, SC_OK, SC_PARAMETER_OUT_OF_RANGE, and SC_WRONG_DEVICE_INDEX.

◆ scSaveDevPars()

ScStatus scSaveDevPars ( int  devIdx,
char *  filePath 
)

Saves the actual parameters of the device with index devIdx to the configuration file given in filePath.


Example:

int devIdx = 0;
char filename[MAX_FILENAME_LEN] = "/home/fs/test.cfg";
ScStatus status = scSaveDevPars(devIdx, filename);
if (status == SC_OK)
printf("ok\n");
else
printf("error\n");
Parameters
devIdxthe index of the device
Return values
filePathfile name, e.g. /home/fs/spacecontroller/[serialNo]/last.cfg
Returns
SC_OK, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX, SC_FILE_IO_ERROR

References SC_COMMUNICATION_ERROR.

◆ scSetDevPars()

ScStatus scSetDevPars ( int  devIdx,
ScDevPars *  dpP 
)

Sets and retrieves the actual device parameters as listed in the device's configuration file.

Example:

int devIdx = 0;
ScDevPars dp;
ScStatus status = scGetDevPars(devIdx, &dp); // get the actual values
if (status == SC_OK)
printf("the threshold is %d\n", dp.mBs.mNullRadius);
else
printf("error\n");
dp.mBs.mNullRadius = 10; // change one value
status = scSetDevPars(devIdx, &dp); // write the values back
if (status == SC_OK)
printf("the threshold is now %d\n", dp.mBs.mNullRadius);
else
printf("error\n");
Parameters
devIdxindex of the device the parameters are requested
Return values
dpPpointer to the device parameters to be retrieved
Returns
SC_OK, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX, SC_PARAMETER_OUT_OF_RANGE

References SC_COMMUNICATION_ERROR, SC_OK, SC_PARAMETER_OUT_OF_RANGE, and SC_WRONG_DEVICE_INDEX.

◆ scSetDevParsToDefaults()

ScStatus scSetDevParsToDefaults ( int  devIdx,
ScDevPars *  dpP 
)

Sets the actual device parameters to the defaults and retrieves the new parameters.

Example:

int devIdx = 0;
ScDevPars dp;
ScStatus status = scSetDevParsToDefaults(devIdx, &dp);
if (status == SC_OK)
printf("the threshold is now %d\n", dp.mBs.mNullRadius);
else
printf("error\n");
Parameters
devIdxindex of the device the parameters are to be set
Return values
dpPpointer to the device parameters to be retrieved
Returns
SC_OK, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX, SC_PARAMETER_OUT_OF_RANGE

References SC_COMMUNICATION_ERROR, SC_OK, SC_PARAMETER_OUT_OF_RANGE, and SC_WRONG_DEVICE_INDEX.

◆ scTransferCallbackFunction()

ScStatus scTransferCallbackFunction ( int  devIdx,
stdDataCallbackP  cbP 
)

This function hands over a callback function pointer to the API.

The callback function is called automatically as soon as a new data packet is available and gets the data packet into its parameters.
Since scFetchStdData() waits for 30 ms if no data is present you may observe a significant slow down in your application when calling it in a loop (as is necessary in most applications). This must be avoided by executing this loop in a separate thread.
If you are not used to handling threads scTransferCallbackFunction() may be an alternative: It creates two threads for you; the first one reads the data packets from the device [using scFetchStdData()] in a loop, the second one looks for new data packets and calls your callback function as soon as new data is available. This design avoids time lags even if your callback function needs more time to execute than the time between two data packets. If one or more data packets arrive before your callback function returns only the last data packet is transmitted in the next call, the other packets are ignored in this case.
Your callback function must have the following signature:

int cbFunction(short x, short y, short z, // translational data
short a, short b, short c, // rotational data
int traLmh, int rotLmh, int event, // flags and events
long tvSec, long tvUsec) // time the packet is generated

I. e. it is nearly the same as in scFetchStdData() (see documentation there), only the first parameter, the device index, is omitted. This is because you will need your own callback function for each device (if more than one is connected), and you have to assign your callback to the device explicitly by handing over the device index together with your callback function when registrating it with scTransferCallbackFunction(). In most cases you have only one device connected, and devIdx is 0.
Example:

int myCallbackFunction(short x, short y, short z,
short a, short b, short c,
int traLmh, int rotLmh, int event,
long tvSec, long tvUsec)
{
printf("x: %d, y: %d, z: %d\n", x, y, z);
return 0; // all other return values are logged as an error if logging is on
}
ScStatus status = scTransferCallbackFunction(0, &myCallbackFunction);
if (status == SC_OK)
printf("Callback function hooked.\n");
else
printf("error\n");

To stop the created threads call scTransferCallbackFunction() again with the same devIdx but with NULL as function pointer.
Calling scDisconnect() will also stop the Threads.
A complete minimal sample application is shown in section 2.2 Threads.

Parameters
devIdxthe index of the device the callback function gets data from
cbPyour callback function; it is called each time new data is received from the device with index devIdx; if NULL is handed over a former transfered callback function is removed
Returns
SC_OK, SC_PARAMETER_OUT_OF_RANGE, SC_COMMUNICATION_ERROR, SC_THREAD_ERROR

◆ scTriggerFunction()

ScStatus scTriggerFunction ( int  devIdx,
int  funcIdx 
)

Triggers the function with index funcIdx.

The functions are listed in the function tree in the SpaceControl Panel's "Function Assignment" dialog, and in the configuration file for the foreground application (e. g. "C:\Users\SpaceController\Devices\<SerialNo>\common.cfg") in section [FUNCTIONS]. They start with index 0.
Example:

int devIdx = 0;
int funcIdx = 9; // = function "ToggleRotation" (driver version 2.2.0)
ScStatus status = scTriggerFunction(devIdx, funcIdx);
if (status != SC_OK)
printf("error\n");
Parameters
devIdxindex of the device (has its own configuration file, therefore has its own list of functions)
funcIdxthe function index
Returns
SC_OK, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX, SC_PARAMETER_OUT_OF_RANGE

References SC_COMMUNICATION_ERROR, SC_OK, SC_PARAMETER_OUT_OF_RANGE, and SC_WRONG_DEVICE_INDEX.

SC DLL
SpaceControl Copyright (c) SpaceControl GmbH & Co. KG, Am Technologiepark 10, D-82229 Seefeld
Generated by Doxygen