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.
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.
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:
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.
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.
COM Automation API
Overview
Start with the generated Overview page for the top-level API introduction and examples.
GEMS Dash Design supports automation via a COM interface.
There is a dual interface; GEMS Dash Design can be automated by both an IDispatch style interface which supports late-binding languages such as Javascript and additionally via direct v-table style interfaces.
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.
varobj=newActiveXObject("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);
}
Dim obj
Set obj = CreateObject("GemsDashDesign.Application")
obj.Visible =TrueWScript.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();
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.
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.
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.
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).
“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.
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.
varapp=newActiveXObject("GemsDashDesign.Application");
varoptions=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);
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.
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.
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.
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'
varapp=newActiveXObject("GemsDashDesign.Application");
vardevice=false;
if (app) {
device=app.SelectedDevice;
}
if (device!==false) {
varjob=device.UploadSetup(
"C:\\Folder\\setup.file" );
while (!job.Completed) {
varprog= (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);
}
}
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.