Automation

Overview

Dash Design may be externally automated.

A COM (ActiveX) automation interface is available. See the COM Automation API for interfaces, methods and code examples.

For device selection, refresh the device list and use IsUsbAt(index) to check the actual connection. USB VID/PID properties identify the display model and may also be populated for network displays; they are not a transport test. IsUsbAt is false for network and removable-media devices and does not open or program the device.

For unattended test-setup generation and file conversion, see Command Line Arguments .

Subsections of Automation

Command Line Arguments

Dash Design can generate test setups and convert setup files from the command line without opening a window or prompting for user input. Each command performs one operation, then exits.

Arguments

Argument Operation
--setup-cli-help Show command-line usage.
--list-display-types List the display names accepted by the application.
--generate-test-setup DISPLAY OUTPUT_STEM Generate a rendering test setup for a display, saved as a native setup, XML and raw binary.
--convert-setup FORMAT INPUT OUTPUT Convert a setup file to the specified target format: xml, setup, raw or locked.

Use the executable for your application brand. Display names and native setup extensions follow that application’s supported display types. Quote paths and display names that contain spaces. Output directories must already exist, and existing output files are not overwritten.

Running From PowerShell

The examples below use the GEMS executable, DashDesign.exe. Substitute your application’s executable path as required.

$app = '.DashDesign.exe'
Start-Process $app -ArgumentList '--setup-cli-help' -Wait
Start-Process $app -ArgumentList '--list-display-types' -Wait

Use Start-Process -Wait -PassThru to wait for the application and inspect its exit code in a script. The application is a Windows GUI executable, so launching it directly from a shell may not wait for the command to finish.

Generating A Test Setup

--generate-test-setup DISPLAY OUTPUT_STEM

DISPLAY is a name shown by --list-display-types. OUTPUT_STEM is the output path without an extension. For example, with C:tests already present:

$result = Start-Process $app -ArgumentList '--generate-test-setup CD6 "C:testscd6-rendering"' -Wait -PassThru
$result.ExitCode

For the GEMS application this creates:

File Contents
C:testscd6-rendering.cd6.gdd Editable native setup.
C:testscd6-rendering.xml XML setup, including embedded image and animation data.
C:testscd6-rendering.bin Compiled raw display setup binary.

The native extension depends on the selected display and application brand.

The setup includes a CAN page-select input and four variants of each supported renderable gauge type, arranged over multiple pages. The variants exercise ranges, warning thresholds, numeric formats, text alignment, gradients, transparency, rotation and other gauge-specific properties. Groups contain child gauges. Internal event, logging, hidden and physical LED gauges remain in the normal control-page setup rather than being duplicated as visual gauges.

Depending on display support, channels include signed and unsigned CAN inputs, constant scalar values, maths, logic, bit-string text, image selectors and colour gradients. Test images and animations do not require external asset files.

CAN Inputs

Purpose CAN Input
Page selection Bus 1, standard ID 0x400, unsigned byte 0. Send the one-based page number.
Numeric test value Standard ID 0x401, signed 13-bit Motorola signal at Vector bit offset 3. Uses bus 2 when available, otherwise bus 1.

Sweep the numeric input through negative and positive values, including values below, at and above gauge ranges and warning thresholds. Suggested values are -120, -40, 0, 20, 42, 100, 101, 160, 900 and 1024.

Use current display firmware: the setup may exercise capabilities introduced in newer firmware. Camera and file-browser gauges require the corresponding hardware or media to exercise their live content. Generated setups are test fixtures, not automatic visual pass/fail tests; inspect or compare the rendered results on the simulator or display.

Converting Setup Files

--convert-setup FORMAT INPUT OUTPUT

The target format is specified explicitly; it is not inferred from the output filename.

Format Input Output
xml Native setup XML setup.
setup XML setup Editable native setup.
raw Native setup Compiled raw display setup binary.
locked Native setup Locked setup package.

For example:

Start-Process $app -ArgumentList '--convert-setup xml "C:testssource.cd6.gdd" "C:testssource.xml"' -Wait
Start-Process $app -ArgumentList '--convert-setup setup "C:testssource.xml" "C:testsimported.cd6.gdd"' -Wait
Start-Process $app -ArgumentList '--convert-setup raw "C:testssource.cd6.gdd" "C:testssource.bin"' -Wait
Start-Process $app -ArgumentList '--convert-setup locked "C:testssource.cd6.gdd" "C:testssource.locked"' -Wait

The locked package contains compiled display data, thumbnails, export metadata and source hashes. It does not embed an editable source setup. XML conversion errors fail the command rather than producing a partially imported setup.

Exit Codes

Code Meaning
0 The operation completed successfully.
1 The operation failed.

Progress messages are written to standard output and errors to standard error. Invalid arguments, unknown display types, missing input files, existing output files and conversion or export errors return code 1 without prompting for user input.

Subsections of COM Automation API

Subsections of Classes

Files

Files Documentation

The following files are available:

Subsections of Files

com_gems.idl

Versioned Dash Design automation contracts and unattended upload rules.

Source code: View source

Subsections of Functions

Functions (Alphabetical)

Functions (Alphabetical)

Total functions: 45

Function Owner Description
BindSimuatorCANPort([in] int index, [in] BSTR port_identifier, [in] VARIANT options) GemsDashDesign::IDashApplication Connect a physical CAN port to the simulator.
Cancel(void) GemsDashDesign::IDashJob Cancels the Job.
Click([in] VARIANT options) GemsDashDesign::IDashApplication Simulate a mouse click.
CloseWindow([in] VARIANT options, [out, retval] VARIANT *result) GemsDashDesign::IDashApplication Close a window (if possible).
ConfigureSimulator([in] VARIANT options) GemsDashDesign::IDashApplication Configure the next simulator launch without starting it.
CreateDeviceList([out, retval] IDashDeviceList **retval) GemsDashDesign::IDashApplication Gets a list of the devices that are attached to the system.
CreateOptionsMap([out, retval] IDashOptionsMap **options) GemsDashDesign::IDashApplication Create an instance of IDashOptionsMap that can be used to modify the behaviour of various functions that accept options.
DescriptionAt([in] int index, [out, retval] BSTR *retval) GemsDashDesign::IDashDeviceList Gets the description of the device at the given index.
DownloadSetup([in] BSTR filename, [in, optional] VARIANT options, [out, retval] IDashJob **retval) GemsDashDesign::IDashDevice Start a setup download for this device.
EmbedCdxModel([in] BSTR path) GemsDashDesign::IDashApplication Embed a CDX Model package into the currently open setup (if editable + supported).
EnumerateWindows([in, optional] VARIANT options, [out, retval] BSTR *result) GemsDashDesign::IDashApplication Enumerate Windows in the application.
EraseLog([in, optional] VARIANT options, [out, retval] IDashJob **retval) GemsDashDesign::IDashDevice Start an Erase Log operation for this device.
FocusWindow([in] VARIANT options) GemsDashDesign::IDashApplication Focus & raise a window (if possible).
GenerateHelpInfo([in, optional] VARIANT options, [out, retval] BSTR *result) GemsDashDesign::IDashApplication Generate Help Information as JSON.
Get([in] int index, [out, retval] IDashDevice **retval) GemsDashDesign::IDashDeviceList Gets a representation of the device at the given index.
GetProperties([in] VARIANT options, [out, retval] VARIANT *result) GemsDashDesign::IDashApplication Get all properties from a window / view.
GetProperty([in] VARIANT options, [in] BSTR name, [out, retval] VARIANT *result) GemsDashDesign::IDashApplication Get a single property from a window / view.
GetProperty([in] BSTR name, [out, retval] VARIANT *retval) GemsDashDesign::IDashOptionsMap
IdentifierAt([in] unsigned int index, [out, retval] BSTR *retval) GemsDashDesign::IDashCANPorts Get an identifier for the port at the specified index in the port list.
ImportCanDbc([in] BSTR path, [in] VARIANT options) GemsDashDesign::IDashApplication Import CAN DBC file.
InvokeAction([in] BSTR action_id, [in, optional] VARIANT options) GemsDashDesign::IDashApplication Invokes an action with the specified ID.
IsUsbAt([in] int index, [out, retval] VARIANT_BOOL *retval) GemsDashDesign::IDashDeviceList Tests whether the device uses a physical USB connection.
Keyboard([in] VARIANT options) GemsDashDesign::IDashApplication Simulate a keyboard.
ListCANPorts([out, retval] IDashCANPorts **retval) GemsDashDesign::IDashApplication Obtains an interface for listing CAN adaptors connected to the PC.
NameAt([in] unsigned int index, [out, retval] BSTR *retval) GemsDashDesign::IDashCANPorts Get friendly name of the port at the specified index in the port list.
NameAt([in] int index, [out, retval] BSTR *retval) GemsDashDesign::IDashDeviceList Gets the name of the device at the given index.
NewSetup([in] VARIANT options) GemsDashDesign::IDashApplication Creates a new setup.
OpenSetup([in] BSTR path, [in, optional] VARIANT options) GemsDashDesign::IDashApplication Opens the setup specified by ‘path’.
Refresh() GemsDashDesign::IDashCANPorts Refresh the ports list. Blocks execution until complete.
Refresh(void) GemsDashDesign::IDashDeviceList Rescan the system for the attached devices and update the list.
SaveSetup([in] VARIANT options) GemsDashDesign::IDashApplication Saves the current setup by its current file name.
SaveSetupAs([in] BSTR path, [in] VARIANT options) GemsDashDesign::IDashApplication Saves the current setup by a new file name.
SerialNumberAt([in] int index, [out, retval] BSTR *retval) GemsDashDesign::IDashDeviceList Gets the serial number of the device at the given index.
SetProperties([in] VARIANT options, [in] VARIANT props) GemsDashDesign::IDashApplication Set mutiple properties on a window / view.
SetProperty([in] VARIANT options, [in] BSTR name, [in] VARIANT value) GemsDashDesign::IDashApplication Set a single property on a window / view.
SetProperty([in] BSTR name, [in] VARIANT value) GemsDashDesign::IDashOptionsMap properties are made available by the IDispatch interface (late-binding).
SetSimulationChannel([in] BSTR channel, [in] VARIANT value) GemsDashDesign::IDashApplication Set a simulator channel value.
SupportsCdxModelImageDescriptor([in] LONG descriptorVersion, [out, retval] VARIANT_BOOL *supported) GemsDashDesign::IDashApplication Query implemented CDX Model image descriptor versions without loading a package.
TakeScreenShot([in, optional] VARIANT options, [out, retval] VARIANT *result) GemsDashDesign::IDashApplication Take a screenshot of a window or the whole application.
UploadFirmware([in] BSTR filename, [in, optional] VARIANT options, [out, retval] IDashJob **retval) GemsDashDesign::IDashDevice Start a firmware upload for this device.
UploadSetup([in] BSTR filename, [in, optional] VARIANT options, [out, retval] IDashJob **retval) GemsDashDesign::IDashDevice Start a setup upload for this device (programs opened setup into the device).
UploadSetupUnattended([in] BSTR filename, [in, optional] VARIANT options, [out, retval] IDashJob **retval) GemsDashDesign::IDashDevice Upload a setup without interactive prompts.
UsbPidAt([in] int index, [out, retval] int *retval) GemsDashDesign::IDashDeviceList Gets the USB PID (Product ID) of the device at the given index.
UsbVidAt([in] int index, [out, retval] int *retval) GemsDashDesign::IDashDeviceList Gets the USB VID (Vendor ID) of the device at the given index.
Wait(void) GemsDashDesign::IDashJob Wait for the Job to complete.

Functions by API

Total functions: 45

IDashApplication

Function Description
BindSimuatorCANPort([in] int index, [in] BSTR port_identifier, [in] VARIANT options) Connect a physical CAN port to the simulator.
Click([in] VARIANT options) Simulate a mouse click.
CloseWindow([in] VARIANT options, [out, retval] VARIANT *result) Close a window (if possible).
ConfigureSimulator([in] VARIANT options) Configure the next simulator launch without starting it.
CreateDeviceList([out, retval] IDashDeviceList **retval) Gets a list of the devices that are attached to the system.
CreateOptionsMap([out, retval] IDashOptionsMap **options) Create an instance of IDashOptionsMap that can be used to modify the behaviour of various functions that accept options.
EmbedCdxModel([in] BSTR path) Embed a CDX Model package into the currently open setup (if editable + supported).
EnumerateWindows([in, optional] VARIANT options, [out, retval] BSTR *result) Enumerate Windows in the application.
FocusWindow([in] VARIANT options) Focus & raise a window (if possible).
GenerateHelpInfo([in, optional] VARIANT options, [out, retval] BSTR *result) Generate Help Information as JSON.
GetProperties([in] VARIANT options, [out, retval] VARIANT *result) Get all properties from a window / view.
GetProperty([in] VARIANT options, [in] BSTR name, [out, retval] VARIANT *result) Get a single property from a window / view.
ImportCanDbc([in] BSTR path, [in] VARIANT options) Import CAN DBC file.
InvokeAction([in] BSTR action_id, [in, optional] VARIANT options) Invokes an action with the specified ID.
Keyboard([in] VARIANT options) Simulate a keyboard.
ListCANPorts([out, retval] IDashCANPorts **retval) Obtains an interface for listing CAN adaptors connected to the PC.
NewSetup([in] VARIANT options) Creates a new setup.
OpenSetup([in] BSTR path, [in, optional] VARIANT options) Opens the setup specified by ‘path’.
SaveSetup([in] VARIANT options) Saves the current setup by its current file name.
SaveSetupAs([in] BSTR path, [in] VARIANT options) Saves the current setup by a new file name.
SetProperties([in] VARIANT options, [in] VARIANT props) Set mutiple properties on a window / view.
SetProperty([in] VARIANT options, [in] BSTR name, [in] VARIANT value) Set a single property on a window / view.
SetSimulationChannel([in] BSTR channel, [in] VARIANT value) Set a simulator channel value.
SupportsCdxModelImageDescriptor([in] LONG descriptorVersion, [out, retval] VARIANT_BOOL *supported) Query implemented CDX Model image descriptor versions without loading a package.
TakeScreenShot([in, optional] VARIANT options, [out, retval] VARIANT *result) Take a screenshot of a window or the whole application.

IDashCANPorts

Function Description
IdentifierAt([in] unsigned int index, [out, retval] BSTR *retval) Get an identifier for the port at the specified index in the port list.
NameAt([in] unsigned int index, [out, retval] BSTR *retval) Get friendly name of the port at the specified index in the port list.
Refresh() Refresh the ports list. Blocks execution until complete.

IDashDevice

Function Description
DownloadSetup([in] BSTR filename, [in, optional] VARIANT options, [out, retval] IDashJob **retval) Start a setup download for this device.
EraseLog([in, optional] VARIANT options, [out, retval] IDashJob **retval) Start an Erase Log operation for this device.
UploadFirmware([in] BSTR filename, [in, optional] VARIANT options, [out, retval] IDashJob **retval) Start a firmware upload for this device.
UploadSetup([in] BSTR filename, [in, optional] VARIANT options, [out, retval] IDashJob **retval) Start a setup upload for this device (programs opened setup into the device).
UploadSetupUnattended([in] BSTR filename, [in, optional] VARIANT options, [out, retval] IDashJob **retval) Upload a setup without interactive prompts.

IDashDeviceList

Function Description
DescriptionAt([in] int index, [out, retval] BSTR *retval) Gets the description of the device at the given index.
Get([in] int index, [out, retval] IDashDevice **retval) Gets a representation of the device at the given index.
IsUsbAt([in] int index, [out, retval] VARIANT_BOOL *retval) Tests whether the device uses a physical USB connection.
NameAt([in] int index, [out, retval] BSTR *retval) Gets the name of the device at the given index.
Refresh(void) Rescan the system for the attached devices and update the list.
SerialNumberAt([in] int index, [out, retval] BSTR *retval) Gets the serial number of the device at the given index.
UsbPidAt([in] int index, [out, retval] int *retval) Gets the USB PID (Product ID) of the device at the given index.
UsbVidAt([in] int index, [out, retval] int *retval) Gets the USB VID (Vendor ID) of the device at the given index.

IDashJob

Function Description
Cancel(void) Cancels the Job.
Wait(void) Wait for the Job to complete.

IDashOptionsMap

Function Description
GetProperty([in] BSTR name, [out, retval] VARIANT *retval)
SetProperty([in] BSTR name, [in] VARIANT value) properties are made available by the IDispatch interface (late-binding).

IDashApplication

IDashApplication automation interface.

Instances supporting this interface may be created using the Application coclass.

These examples create an instance and display its window. The application must be installed and its COM server registered on Windows. The C# example uses dynamic COM binding and does not require an imported interop assembly.

The JavaScript examples run with Windows Script Host, not in a browser. Save the chosen JavaScript example as automate.js and place this batch file in the same directory. The batch file works from any current directory and returns the script’s exit code to its caller.

@echo off
cscript.exe //nologo "%~dp0automate.js"
exit /b %errorlevel%
​
// Save as automate.js and run with the batch file above.
var obj = new ActiveXObject("GemsDashDesign.Application");
obj.Visible = true;
WScript.Echo(obj.Version);
using System;
using System.Runtime.InteropServices;

var applicationType = Type.GetTypeFromProgID("GemsDashDesign.Application", throwOnError: true)!;
dynamic app = Activator.CreateInstance(applicationType)!;
try
{
    app.Visible = true;
    Console.WriteLine(app.Version);
}
finally
{
    Marshal.FinalReleaseComObject(app);
}
$ErrorActionPreference = 'Stop'
$app = New-Object -ComObject 'GemsDashDesign.Application'
try {
    $app.Visible = $true
    $app.Version
} finally {
    [void][System.Runtime.InteropServices.Marshal]::FinalReleaseComObject($app)
}
Dim obj
Set obj = CreateObject("GemsDashDesign.Application")
obj.Visible = True
WScript.Echo obj.Version
// Direct COM interface.
::CoInitialize(NULL);
IDashApplication* iface = 0;
HRESULT hr = ::CoCreateInstance(
    CLSID_Application, 
    NULL, 
    CLSCTX_LOCAL_SERVER,
    IID_IDashApplication,
    (LPVOID*)&iface);

if (iface) {
    iface->put_Visible(TRUE);
    iface->Release();
}
::CoUninitialize();
// IDispatch interface.
::CoInitialize(NULL);
HRESULT    hr;
CLSID      clsid;        // CLSID of ActiveX object.
LPUNKNOWN  punk  = NULL; // IUnknown of ActiveX object.
LPDISPATCH pdisp = NULL; // IDispatch of ActiveX object.

// Retrieve CLSID for GemsDashDesign.Application from the registry.
// This is {4CF7EE02-7183-4DF2-B0D9-751AEE62FC25} which could be 
// used directly for better performance.
hr = CLSIDFromProgID(L"GemsDashDesign.Application", &clsid);
if (FAILED(hr)) {
    return hr;
}  
// Create an instance of the ActiveX object.
hr = CoCreateInstance(clsid, NULL, CLSCTX_SERVER, 
                      IID_IUnknown, (void **)&punk);
if (FAILED(hr)) {
    if (punk) punk->Release();
    return hr;
}    
hr = punk->QueryInterface(IID_IDispatch, (void **)&pdisp);
if (FAILED(hr)) {
    punk->Release();
    if (pdisp) pdisp->Release();
    return hr;
}
punk->Release();
// << Use the dispatch interface..
pdisp->Release();    
::CoUninitialize();

Contents

Properties

Property Description
Version Get application version.
ModulePath Get application EXE path.
Visible Displays/hides the Application UI.
FullScreen Makes the window fullscreen (or not).
LastErrorString Provides an error string describing the last method failure that occurred, if possible.
Setup Not yet implemented.
Tabs Not yet implemented.
SelectedDevice Gets the currently selected device (if any).
CurrentTabID Get / Set the current top-level tab ID.
CurrentSubTabID Get / Set the current sub-level tab ID.
SimulatorRunning
SimulatorProcessId Running simulator host PID for native debugger attachment, or zero when stopped.

Public Methods

Function Description
CreateOptionsMap Create an instance of IDashOptionsMap that can be used to modify the behaviour of various functions that accept options.
InvokeAction Invokes an action with the specified ID.
OpenSetup Opens the setup specified by ‘path’.
SaveSetup Saves the current setup by its current file name.
SaveSetupAs Saves the current setup by a new file name.
NewSetup Creates a new setup.
CreateDeviceList Gets a list of the devices that are attached to the system.
GenerateHelpInfo Generate Help Information as JSON.
EnumerateWindows Enumerate Windows in the application.
TakeScreenShot Take a screenshot of a window or the whole application.
CloseWindow Close a window (if possible).
FocusWindow Focus & raise a window (if possible).
SetProperties Set mutiple properties on a window / view.
GetProperties Get all properties from a window / view.
SetProperty Set a single property on a window / view.
GetProperty Get a single property from a window / view.
Click Simulate a mouse click.
SetSimulationChannel Set a simulator channel value.
ImportCanDbc Import CAN DBC file.
Keyboard Simulate a keyboard.
ListCANPorts Obtains an interface for listing CAN adaptors connected to the PC.
BindSimuatorCANPort Connect a physical CAN port to the simulator.
EmbedCdxModel Embed a CDX Model package into the currently open setup (if editable + supported).
ConfigureSimulator Configure the next simulator launch without starting it.
SupportsCdxModelImageDescriptor Query implemented CDX Model image descriptor versions without loading a package.

Properties

Version

Get application version.

BSTR Version

ModulePath

Get application EXE path.

BSTR ModulePath

Visible

Displays/hides the Application UI.

BOOL Visible

The UI will be hidden initially when creating an instance of GemsDashDesign.

FullScreen

Makes the window fullscreen (or not).

BOOL FullScreen

Setting this value to TRUE causes the application window to take up the full screen without title bars etc.

When entering fullscreen mode via the COM Automation Interface, the popup ’toaster’ window giving users a way of exiting fullscreen mode is not displayed.

LastErrorString

Provides an error string describing the last method failure that occurred, if possible.

BSTR LastErrorString

Wehre appropriate, this string is also included in Error exception description strings as a result of IDispatch calls (e.g. when accessed via late binding as with JavaScript).

Setup

Not yet implemented.

IDispatch Setup

In future this will return an interface to the setup object which Offers more setup specific functionality than the Application interface.

Tabs

Not yet implemented.

IDispatch Tabs

In future this will return an interface that gives access/control of the list of tabs, tab groups, views within tabs etc.

SelectedDevice

Gets the currently selected device (if any).

IDashDevice SelectedDevice

May return a NULL device.

CurrentTabID

Get / Set the current top-level tab ID.

BSTR CurrentTabID

CurrentSubTabID

Get / Set the current sub-level tab ID.

BSTR CurrentSubTabID

Some tabs have sub-tabs. This property allows you to get/set the current sub-tab where possible.

SimulatorRunning

BOOL SimulatorRunning

@breif Control the simulator running state.

SimulatorProcessId

Running simulator host PID for native debugger attachment, or zero when stopped.

ULONG SimulatorProcessId

Public Methods

Method: CreateOptionsMap

Create an instance of IDashOptionsMap that can be used to modify the behaviour of various functions that accept options.

HRESULT CreateOptionsMap([out, retval] IDashOptionsMap **options)

It is also possoble to use JavaScript objects for options instead of an options map.

See Also: IDashOptionsMap

Method: InvokeAction

Invokes an action with the specified ID.

HRESULT InvokeAction([in] BSTR action_id, [in, optional] VARIANT options)

If ‘deferred’ is specified and set to ’true’ then the function will defer the action invocation via the event loop and return immediately. In cases where the action would display a modal dialog or message box, using a deferred invocation avoids the caller from blocking. Deferred calls retain the application and snapshot their options until execution finishes.

Method: OpenSetup

Opens the setup specified by ‘path’.

HRESULT OpenSetup([in] BSTR path, [in, optional] VARIANT options)

The user may be prompted to save any modified setup files. See IDashOptionsMap::SaveModifiedDiscard and IDashOptionsMap::SaveModifiedPrompt

Method: SaveSetup

Saves the current setup by its current file name.

HRESULT SaveSetup([in] VARIANT options)

If the setup does not have a file name then the behaviour of this function will depend upon the ‘options’ parameter and may not be saved as a result.

See IDashOptionsMap::SaveModifiedDiscard and IDashOptionsMap::SaveModifiedPrompt

Method: SaveSetupAs

Saves the current setup by a new file name.

HRESULT SaveSetupAs([in] BSTR path, [in] VARIANT options)

If the setup does not have a file name then the behaviour of this function will depend upon the ‘options’ parameter and may not be saved as a result.

See IDashOptionsMap::OverwriteAllow and IDashOptionsMap::OverwriteSilent

If options contains saveCopy = true, writes a copy without changing the open setup’s file name or modified state.

Method: NewSetup

Creates a new setup.

HRESULT NewSetup([in] VARIANT options)

If the setup has been modified then the behaviour of this function will depend upon the ‘options’ parameter and may fail as a result.

Method: CreateDeviceList

Gets a list of the devices that are attached to the system.

HRESULT CreateDeviceList([out, retval] IDashDeviceList **retval)

This will implicitly re-scan the system for the attached devices.

Method: GenerateHelpInfo

Generate Help Information as JSON.

HRESULT GenerateHelpInfo([in, optional] VARIANT options, [out, retval] BSTR *result)

Returns

The information as a JSON string. If outputFile is specified in options then the returned string will be blank.

If the ‘options’ parameter has a property ‘outputFile’ then the JSON will be written to that file instead of returned as a string.

Method: EnumerateWindows

Enumerate Windows in the application.

HRESULT EnumerateWindows([in, optional] VARIANT options, [out, retval] BSTR *result)

Returns

The information as a JSON string.

Method: TakeScreenShot

Take a screenshot of a window or the whole application.

HRESULT TakeScreenShot([in, optional] VARIANT options, [out, retval] VARIANT *result)

Returns

The information as a JSON string.

If the ‘options’ parameter has a property ‘outputFile’ then the screenshot will be output to that path instead of returned.

options can identify the window through one of the following keys:

  • id
  • name
  • label
  • menu: screenshot the active context menu, if any.

If one of these items are not specified then a screenshot of the main window will be taken.

Other options:

  • clipboard: place the screenshot on the Windows clipboard
  • focus: true/false (default true)) - focus the window first.
  • print: Use WM_PRINT to capture the window. This may not work well for all windows (not 100% WYSIWYG), but does mean that occluded window areas are captured.
  • outputFile: Path to save the screenshot to.
  • cursor: Include the mouse cursor in the screenshot (default: false).
  • expand: Expand the screenshot rectangle by the specified number of ‘device’ pixels (depends on Windows display scaling option). expand option does not work with the ‘print’ option.

Method: CloseWindow

Close a window (if possible).

HRESULT CloseWindow([in] VARIANT options, [out, retval] VARIANT *result)

Returns

TRUE if OK, false otherwise. This is a variant for posssilbe future changes.

options: id: Window ID for the window to close. name: ’name’ of window to close. label: ’label’ of window to close. code: result code (e.g. if the window is modal - see e.g. wxID_OK).

Method: FocusWindow

Focus & raise a window (if possible).

HRESULT FocusWindow([in] VARIANT options)

Method: SetProperties

Set mutiple properties on a window / view.

HRESULT SetProperties([in] VARIANT options, [in] VARIANT props)

Method: GetProperties

Get all properties from a window / view.

HRESULT GetProperties([in] VARIANT options, [out, retval] VARIANT *result)

Returns

a JSON string detailing the properties.

Method: SetProperty

Set a single property on a window / view.

HRESULT SetProperty([in] VARIANT options, [in] BSTR name, [in] VARIANT value)

Special Properties:

“selection”: string: json style array [[row,col],…n]. ‘col’ is optional. e.g. “[[5,2],[5,3]]” If a number is specified, the whole row is selected. “text”: For text editors, sets the text.

“expand_sidebar”: Expand the sidebar. “lock_sidebar”: Lock the sidebar.

Method: GetProperty

Get a single property from a window / view.

HRESULT GetProperty([in] VARIANT options, [in] BSTR name, [out, retval] VARIANT *result)

Returns

The property value.

Method: Click

Simulate a mouse click.

HRESULT Click([in] VARIANT options)

Method: SetSimulationChannel

Set a simulator channel value.

HRESULT SetSimulationChannel([in] BSTR channel, [in] VARIANT value)

Method: ImportCanDbc

Import CAN DBC file.

HRESULT ImportCanDbc([in] BSTR path, [in] VARIANT options)

Method: Keyboard

Simulate a keyboard.

HRESULT Keyboard([in] VARIANT options)

Method: ListCANPorts

Obtains an interface for listing CAN adaptors connected to the PC.

HRESULT ListCANPorts([out, retval] IDashCANPorts **retval)

Method: BindSimuatorCANPort

Connect a physical CAN port to the simulator.

HRESULT BindSimuatorCANPort([in] int index, [in] BSTR port_identifier, [in] VARIANT options)

Note: The CAN port will use the bitrate defined in the display setup.

Method: EmbedCdxModel

Embed a CDX Model package into the currently open setup (if editable + supported).

HRESULT EmbedCdxModel([in] BSTR path)

Replaces the current model identity, embedded firmware and Model IPC signal definitions. Takes into account the package’s ‘protected’ setting. The source path is retained for file-change notifications and reloading.

Does not program the display, show ant dialogs, change tabs, or save the setup. Call SaveSetup or SaveSetupAs afterwards to persist the embedded model.

Returns E_INVALIDARG for an empty filename, or a failing HRESULT if no editable CD6 setup is open or package validation/installation fails. For more errors information, see LastErrorString.

​
// Save as automate.js and run with the Windows Script Host batch file
// shown in the application interface examples.
var app = new ActiveXObject("GemsDashDesign.Application");
var options = app.CreateOptionsMap();
options.discardModifiedFiles = true;
options.promptSaveModified = false;
options.allowFileOverwrite = true;
app.OpenSetup("C:\\Setups\\input.cd6.gdd", options);
app.EmbedCdxModel("C:\\Models\\engine.cdxmodel");
app.SaveSetupAs("C:\\Setups\\output.cd6.gdd", options);
using System;
using System.Runtime.InteropServices;

var applicationType = Type.GetTypeFromProgID("GemsDashDesign.Application", throwOnError: true)!;
dynamic app = Activator.CreateInstance(applicationType)!;
try
{
    dynamic options = app.CreateOptionsMap();
    try
    {
        options.discardModifiedFiles = true;
        options.promptSaveModified = false;
        options.allowFileOverwrite = true;
        app.OpenSetup(@"C:\Setups\input.cd6.gdd", options);
        app.EmbedCdxModel(@"C:\Models\engine.cdxmodel");
        app.SaveSetupAs(@"C:\Setups\output.cd6.gdd", options);
    }
    finally
    {
        Marshal.FinalReleaseComObject(options);
    }
}
finally
{
    Marshal.FinalReleaseComObject(app);
}
$ErrorActionPreference = 'Stop'
$app = New-Object -ComObject 'GemsDashDesign.Application'
try {
    $options = $app.CreateOptionsMap()
    try {
        $options.discardModifiedFiles = $true
        $options.promptSaveModified = $false
        $options.allowFileOverwrite = $true
        $app.OpenSetup('C:\Setups\input.cd6.gdd', $options)
        $app.EmbedCdxModel('C:\Models\engine.cdxmodel')
        $app.SaveSetupAs('C:\Setups\output.cd6.gdd', $options)
    } finally {
        [void][System.Runtime.InteropServices.Marshal]::FinalReleaseComObject($options)
    }
} finally {
    [void][System.Runtime.InteropServices.Marshal]::FinalReleaseComObject($app)
}

Method: ConfigureSimulator

Configure the next simulator launch without starting it.

HRESULT ConfigureSimulator([in] VARIANT options)

debugger attach.

Stop the simulator before configuring.

Empty model paths are auto-populated from environment variables CDX_MODEL_DLL

  • CDX_MODEL_IMAGE.

Returns E_INVALIDARG for bad options; E_FAIL for unsupported displays, invalid files, or if the simulator is already running. For more errors information, see LastErrorString.

Start with SimulatorRunning = true, then use SimulatorProcessId to attach Visual Studio or VS Code’s native debugger to SimHost, which loads both DLLs.

Method: SupportsCdxModelImageDescriptor

Query implemented CDX Model image descriptor versions without loading a package.

HRESULT SupportsCdxModelImageDescriptor([in] LONG descriptorVersion, [out, retval] VARIANT_BOOL *supported)

Read-only: requires no open setup, files or connected device, and does not import, save, program or change UI state. S_OK for known and unknown versions; E_POINTER if supported is null. A true result does not bypass validation: schema 2 requires descriptor 1/3, schema 3 requires descriptor 2/4 and valid calibration metadata; all package integrity and identity checks still apply.

Older servers may not implement this appended method. Late-bound clients must handle a missing member as unknown capability, not infer support from the application version. Native clients require an updated server.

IDashCANPorts

Interface for access to PC logging features.

{}

Contents

Properties

Property Description
Count Get the number of items in the list.
IncludePCAN_ISA Property to include ISA PCAN ports in the list (default false).
IncludeKvaserVirtual Property to include Kvaser Virtual CAN ports in the list (default false).

Public Methods

Function Description
Refresh Refresh the ports list. Blocks execution until complete.
NameAt Get friendly name of the port at the specified index in the port list.
IdentifierAt Get an identifier for the port at the specified index in the port list.

Properties

Count

Get the number of items in the list.

int Count

IncludePCAN_ISA

Property to include ISA PCAN ports in the list (default false).

BOOL IncludePCAN_ISA

IncludeKvaserVirtual

Property to include Kvaser Virtual CAN ports in the list (default false).

BOOL IncludeKvaserVirtual

Public Methods

Method: Refresh

Refresh the ports list. Blocks execution until complete.

HRESULT Refresh()

Method: NameAt

Get friendly name of the port at the specified index in the port list.

HRESULT NameAt([in] unsigned int index, [out, retval] BSTR *retval)

Method: IdentifierAt

Get an identifier for the port at the specified index in the port list.

HRESULT IdentifierAt([in] unsigned int index, [out, retval] BSTR *retval)

The identifier is a string that uniquely identifies the CAN port and may be used to open the port by other functions.

IDashDevice

Interface for controlling a device.

Note that this object initially represents a device factory. i.e. it is an object which has the ability to create instances of a real device object internally to GDA for the purpose of executing various commands.

Contents

Properties

Property Description
Name Gets the name of this device.
SerialNumber Gets the device serial number.
Description Gets the device description.
UsbVid Gets the device USB PID.
UsbPid Gets the device USB PID.

Public Methods

Function Description
DownloadSetup Start a setup download for this device.
UploadSetup Start a setup upload for this device (programs opened setup into the device).
UploadFirmware Start a firmware upload for this device.
EraseLog Start an Erase Log operation for this device.
UploadSetupUnattended Upload a setup without interactive prompts.

Properties

Name

Gets the name of this device.

BSTR Name

SerialNumber

Gets the device serial number.

BSTR SerialNumber

Description

Gets the device description.

BSTR Description

UsbVid

Gets the device USB PID.

int UsbVid

UsbPid

Gets the device USB PID.

int UsbPid

Public Methods

Method: DownloadSetup

Start a setup download for this device.

HRESULT DownloadSetup([in] BSTR filename, [in, optional] VARIANT options, [out, retval] IDashJob **retval)

Method: UploadSetup

Start a setup upload for this device (programs opened setup into the device).

HRESULT UploadSetup([in] BSTR filename, [in, optional] VARIANT options, [out, retval] IDashJob **retval)

Method: UploadFirmware

Start a firmware upload for this device.

HRESULT UploadFirmware([in] BSTR filename, [in, optional] VARIANT options, [out, retval] IDashJob **retval)

Method: EraseLog

Start an Erase Log operation for this device.

HRESULT EraseLog([in, optional] VARIANT options, [out, retval] IDashJob **retval)

Method: UploadSetupUnattended

Upload a setup without interactive prompts.

HRESULT UploadSetupUnattended([in] BSTR filename, [in, optional] VARIANT options, [out, retval] IDashJob **retval)

enableSetupDownload (default false).

checkFirmwareUpdate defaults to false. Setting it, acceptFirmwareUpdate, acceptEraseLog or rawSetup to true fails the job before device access. allowDisplayMismatch defaults to false; when true, a mismatch that the interactive uploader permits confirming is accepted with a warning.

Returns

S_OK when the job is created, E_INVALIDARG for an empty filename, E_POINTER for a null output, or a COM error if the setup cannot be opened. An unapproved display-type mismatch, nonempty log or excessive RAM requirement fails without a confirmation dialog.

A rejected job does not erase logs or program the device.

Keep the application and job references until completion or confirmed cancellation. Legacy versions do not expose this method; clients must check its DISPID before use.

IDashDeviceList

Interface for accessing a list of attached devices.

Contents

Properties

Property Description
Count Gets the number of devices in the list.

Public Methods

Function Description
NameAt Gets the name of the device at the given index.
SerialNumberAt Gets the serial number of the device at the given index.
DescriptionAt Gets the description of the device at the given index.
UsbVidAt Gets the USB VID (Vendor ID) of the device at the given index.
UsbPidAt Gets the USB PID (Product ID) of the device at the given index.
Get Gets a representation of the device at the given index.
Refresh Rescan the system for the attached devices and update the list.
IsUsbAt Tests whether the device uses a physical USB connection.

Properties

Count

Gets the number of devices in the list.

int Count

Public Methods

Method: NameAt

Gets the name of the device at the given index.

HRESULT NameAt([in] int index, [out, retval] BSTR *retval)

If the index is invalid, an error will be rasied (E_INVALIDARG).

Method: SerialNumberAt

Gets the serial number of the device at the given index.

HRESULT SerialNumberAt([in] int index, [out, retval] BSTR *retval)

If the index is invalid, an error will be rasied (E_INVALIDARG).

Method: DescriptionAt

Gets the description of the device at the given index.

HRESULT DescriptionAt([in] int index, [out, retval] BSTR *retval)

If the index is invalid, an error will be rasied (E_INVALIDARG).

Method: UsbVidAt

Gets the USB VID (Vendor ID) of the device at the given index.

HRESULT UsbVidAt([in] int index, [out, retval] int *retval)

If the index is invalid, an error will be rasied (E_INVALIDARG).

Method: UsbPidAt

Gets the USB PID (Product ID) of the device at the given index.

HRESULT UsbPidAt([in] int index, [out, retval] int *retval)

If the index is invalid, an error will be rasied (E_INVALIDARG).

Method: Get

Gets a representation of the device at the given index.

HRESULT Get([in] int index, [out, retval] IDashDevice **retval)

If the index is invalid, an error will be rasied (E_INVALIDARG).

Note that this function will always create a new object.

You cannot compare object pointers for equality to identify devices. Use IDashDevice::DevID

Method: Refresh

Rescan the system for the attached devices and update the list.

HRESULT Refresh(void)

Method: IsUsbAt

Tests whether the device uses a physical USB connection.

HRESULT IsUsbAt([in] int index, [out, retval] VARIANT_BOOL *retval)

Returns

S_OK on success, E_INVALIDARG for an invalid index. Refresh the list before querying; this does not open the device.

IDashJob

Interface for controlling and monitoring the progress of asynchronous Jobs/Tasks.

The PowerShell example accepts a job returned by an operation such as IDashDevice::UploadSetup. Pass that object as $job after starting the operation on the intended device. It polls Completed so that the progress display can be updated instead of blocking in Wait. Completed does not imply success: check Failed and Error afterwards. The progress display is cleared even if an error occurs. Stopping the script does not cancel the device operation.

​
function Wait-DashJob {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [object]$Job,
        [string]$Activity = 'Display operation'
    )

    $ErrorActionPreference = 'Stop'

    try {
        while (-not $Job.Completed) {
            $percent = [int][Math]::Floor($Job.Progress * 100)
            Write-Progress -Id 1 -Activity $Activity `
                -Status "$percent% complete" -PercentComplete $percent
            Start-Sleep -Milliseconds 200
        }

        if ($Job.Failed) {
            throw "The job failed: $($Job.Error). Resolve the problem reported in the messages below and retry.`n$($Job.AllMessages)"
        }

        $Job.AllMessages
    } finally {
        Write-Progress -Id 1 -Activity $Activity -Completed
    }
}

Wait-DashJob -Job $job -Activity 'Uploading display setup'
var app = new ActiveXObject("GemsDashDesign.Application");
var device = false;
if (app) {
    device = app.SelectedDevice;
}

if (device !== false) {
    var job = device.UploadSetup(
        "C:\\Folder\\setup.file"
    );
    while (!job.Completed) {
        var prog = (job.Progress * 100) + "%";
        WScript.StdOut.WriteLine(prog);
        WScript.Sleep(500);
    }
    WScript.StdOut.WriteLine("Completed.");
    if (job.Error && job.Error.length) {
        WScript.StdOut.WriteLine("Error: " + job.Error);
    }
}

Contents

Properties

Property Description
Progress Gets the progress of the Job as a value between 0.0 and 1.0 inclusive.
Completed Indicates if the Job has completed.
Failed Indicates if the Job failed.
Error Gets the error status of the Job.
AllMessages Gets a newline-separated string containing all messages generated by the Job.

Public Methods

Function Description
Cancel Cancels the Job.
Wait Wait for the Job to complete.

Properties

Progress

Gets the progress of the Job as a value between 0.0 and 1.0 inclusive.

double Progress

Completed

Indicates if the Job has completed.

BOOL Completed

Check the Error property to determine if there was a failure.

Failed

Indicates if the Job failed.

BOOL Failed

See Also: Error

Error

Gets the error status of the Job.

BSTR Error

This string will be empty of the Job completed without errors.

See Also: Failed

AllMessages

Gets a newline-separated string containing all messages generated by the Job.

BSTR AllMessages

Public Methods

Method: Cancel

Cancels the Job.

HRESULT Cancel(void)

Method: Wait

Wait for the Job to complete.

HRESULT Wait(void)

This will block until the job is completed. Note that this will run the main application event loop from within the wait subroutine - so if the user interface is displayed then the user may still be able to interact with the application.

IDashOptionsMap

Interface for configuring file control options for use with various file-based functions in the COM API.

  • allowFileOverwrite
  • silentFileOverwrite : default true.
  • discardModifiedFiles
  • promptSaveModified : If false then the function will fail unless discardModifiedFiles is true.
  • updateRecentFiles

Contents

Public Methods

Function Description
GetProperty
SetProperty properties are made available by the IDispatch interface (late-binding).

Public Methods

Method: GetProperty

HRESULT GetProperty([in] BSTR name, [out, retval] VARIANT *retval)

Method: SetProperty

properties are made available by the IDispatch interface (late-binding).

HRESULT SetProperty([in] BSTR name, [in] VARIANT value)

Namespaces

Namespaces Documentation

The following namespaces are available:

Subsections of Namespaces

Types

Types

No documented data types were found.