Skip to main content

Get and Change Device Settings

Device settings can be retrieved and changed remotely, allowing you to replicate our settings on your own app and render using the Spectre GUI on the machine unnecessary. This can be especially helpful in cases where a keyboard and mouse are removed from the machine.

Settings have permissions on them that cannot be changed. Settings with "r" permissions are retrievable via API. Settings with "w" permission are additionally settable via API. This information can be retrieved with the GetSettingInfo command.

<GetSetting>​

GetSetting can be used to retrieve some or all settings. However, functionality is dependent on request type.

Request - All Settings​

Endpoint​

Request all settings from a machine with local IP address 10.1.1.2 set to port 7100.

GET http://10.1.1.2:7100/GetSetting

Desired response format:

Accept: application/xml (DEFAULT)

Response - All Settings​

The Responses/GetSetting/ node contains both a code (where code "0" indicates success) and a /Settings node where the data is present. All settings data begins with /Settings as internally settings are represented by an XML tree.

List is not regularly maintained

Example settings might be out of date. To check what settings are available to you, request GetSettings from your machine.

Cargo Spectre reserves the right to append additional nodes to the paths. Cargo Spectre will not remove or rearrange paths (e.g. /Settings/Device/Name will not disappear, nor will it become /Settings/Info/Name) but some paths may be 'tacked on' (e.g. /Settings/Device/NewNode)

danger

Cargo Spectre highly recommends parsing the full XML or JSON tree instead of looking for a setting at a specific line number or by a specific keyword. Cargo Spectre promises that paths will be unique, but specific node names may not. E.g. 'Name' might be repeated, but /Settings/Device/Name will not.

Furthermore, if an additional node is added further up in the tree, searching for a desired setting on line number 40 will break. Always traverse the tree with an XML or JSON parser instead.

This is a particularly large response
<Responses>
<GetSetting code="0">
<Settings>
<Device>
<Version>3.0.154</Version>
<Name>test-machine</Name>
<Scale>
<Format>Totalcomp Continuous Format</Format>
<Baud>9600</Baud>
<Parity>7 data bits, even parity bit, 1 stop bit</Parity>
<Ntep></Ntep>
</Scale>
</Device>
<Scanner>
<Mode>CARGO</Mode>
<Upload>Never</Upload>
<AutoBarcodeEnabled>false</AutoBarcodeEnabled>
<AutoBarcodeDelay>5</AutoBarcodeDelay>
<AutoSaveEnabled>true</AutoSaveEnabled>
<AutoExportEnabled>false</AutoExportEnabled>
</Scanner>
<Calibration>
<Path>~/.spectre/May-14_10-45-42_2021/</Path>
<Crash>false</Crash>
</Calibration>
<Units>
<Length>inches</Length>
<Volume>cubic feet</Volume>
<Weight>lb</Weight>
</Units>
<Licensing>
<Email>fake@shipper.com</Email>
</Licensing>
<Snapshot>
<Save></Save>
<Images>
<Format>JPG</Format>
</Images>
<Clouds>
<Format>PCD</Format>
</Clouds>
</Snapshot>
<Printing>
<Logo></Logo>
<LogoPlacement>Left</LogoPlacement>
<Pdf>true</Pdf>
<BoxIncluded>true</BoxIncluded>
<Label>true</Label>
<LabelPrinterName></LabelPrinterName>
<BarSymbology>Code 128</BarSymbology>
<ReportPrinterName></ReportPrinterName>
<DimBarcodes>false</DimBarcodes>
<SimplifiedLabel>false</SimplifiedLabel>
<ReportQuantity>1</ReportQuantity>
<LabelQuantity>1</LabelQuantity>
</Printing>
<Network>
<Proxy>false</Proxy>
</Network>
<RemoteApi>
<Port>7100</Port>
</RemoteApi>
<Support>
<Sample>
<Reporting>true</Reporting>
</Sample>
<LoginPrompt>true</LoginPrompt>
</Support>
</Settings>
</GetSetting>
</Responses>

Request - Particular Settings​

Getting particular settings is accomplished by specifying the parameter of Path to the GetSetting command.

Endpoint​

Request a specific setting from a machine with local IP address 10.1.1.2 set to port 7100.

GET http://10.1.1.2:7100/GetSetting?Path=Settings/Printing/Pdf

Or request multiple settings:

GET http://10.1.1.2:7100/GetSetting?Path=Settings/Printing/Pdf+GetSetting?Path=Settings/Printing/Label

Header​

Desired response format:

Accept: application/xml (DEFAULT)

Response - Particular Settings​

The Responses/GetSetting/ node contains both a code (where code "0" indicates success) and a /Settings node where the data is present. All settings data begins with /Settings as internally settings are represented by an XML tree.

<Responses>
<GetSetting code="0">true</GetSetting>
</Responses>

Or request multiple settings:

<Responses>
<GetSetting code="0">true</GetSetting>
<GetSetting code="0">true</GetSetting>
</Responses>

<SetSetting>​

SetSetting can be used to set specific settings.

Specifying a settings path

Settings paths must begin with a /Settings but do not need to end with a /, as in /Settings/Scanner/Mode.

Request​

Endpoint​

Set the PDF Freight-Report setting to false on machine with local IP address 10.1.1.2 set to port 7100.

GET http://10.1.1.2:7100/SetSetting?Path=/Settings/Path/To/MySetting&Value=somevalue

Example: set multiple settings with one command.

GET http://10.1.1.2:7100/SetSetting?Path=/Settings/Printing/Pdf&Value=false+SetSetting?Path=/Settings/Licensing/Email&Value=other.fake@shipper.com

Header​

Desired response format:

Accept: application/xml (DEFAULT)

Response​

This returns a code="0" if the setting was successfully sent.

Settings permissions

As of Spectre version 3.0.154, each setting has permissions attached to it. Only settings with "r" (Read) permissions can be returned by the API, and only settings with "w" (Write) permissions can be edited via API.

Example of response for one setting:

<Responses>
<SetSetting code="0"/>
</Responses>

Example of response for multiple settings:

<Responses>
<SetSetting code="0"/>
<SetSetting code="0"/>
</Responses>

<GetSettingInfo>​

The GetSettingInfo command retrieves many useful attributes about all settings, or one particular one. These attributes include:

  • Permissions: The permissions of the setting. Include read, read-write, etc. (specified as r, rw, etc.). Some permissions are private and are not returned by API, such as the password hash.
  • Category: A generalized type descriptor for the setting. Includes regex for text, select for multi-options, toggle for a more narrow select with only two options (e.g. true/false), etc.
  • Options: Either a regex string or a list of options depending on the category type.
  • Ui: A UI hint for the setting. This is how the Spectre GUI will render settings elements in future versions. Examples include toggle, text, integer, select, etc.
note

Only setting attributes are retrieved by the GetSettingInfo command. For the setting value, use GetSetting.

Request - Info for All Settings​

Endpoint​

Request info for all settings from a machine with local IP address 10.1.1.2 set to port 7100.

GET http://10.1.1.2:7100/GetSettingInfo

Header​

Desired response format:

Accept: application/xml (DEFAULT)

Response - Info for All Settings​

The Responses/GetSettingInfo/ node contains both a "code" (where code 0 indicates success) and a /Settings node where the data is present. All settings data begins with /Settings as internally settings are represented by an XML tree.

Settings permissions

As of Spectre version 3.0.154, each setting has permissions attached to it. Only settings with "r" (Read) permissions can be returned by the API, and only settings with "w" (Write) permissions can be edited via API.

This is a particularly large response
<Responses>
<GetSettingInfo code="0">
<Settings>
<Device>
<Version>
<Permission>r</Permission>
<Ui>text</Ui>
<Category>regex</Category>
<Option>.*</Option>
</Version>
<Name>
<Permission>rw</Permission>
<Ui>text</Ui>
<Category>regex</Category>
<Option>.*</Option>
</Name>
<Scale>
<Format>
<Permission>rw</Permission>
<Ui>select</Ui>
<Category>select</Category>
<Option>Totalcomp Continuous Format</Option>
<Option>FB1100 Continuous Format</Option>
<Option>Rice Lake Continuous Format</Option>
<Option>CI200 Continuous Format</Option>
<Option>Optima OP-900 Continuous Format</Option>
<Option>Mettler Toledo Continuous Format</Option>
<Option>Slimeline Polling Format</Option>
</Format>
<Baud>
<Permission>rw</Permission>
<Ui>select</Ui>
<Category>select</Category>
<Option>9600</Option>
<Option>14400</Option>
<Option>19200</Option>
<Option>28800</Option>
<Option>38400</Option>
<Option>56000</Option>
<Option>57600</Option>
<Option>115200</Option>
</Baud>
<Parity>
<Permission>rw</Permission>
<Ui>select</Ui>
<Category>select</Category>
<Option>7 data bits, even parity bit, 1 stop bit</Option>
<Option>7 data bits, even parity bit, 2 stop bits</Option>
<Option>7 data bits, odd parity bit, 1 stop bit</Option>
<Option>7 data bits, odd parity bit, 2 stop bits</Option>
<Option>8 data bits, no parity bit, 1 stop bit</Option>
</Parity>
<Ntep>
<Permission>rw</Permission>
<Ui>text</Ui>
<Category>regex</Category>
<Option>.*</Option>
</Ntep>
</Scale>
</Device>
<Scanner>
<Mode>
<Permission>rw</Permission>
<Ui>select</Ui>
<Category>select</Category>
<Option>Cargo</Option>
<Option>Black Plastic</Option>
<Option>Parcel</Option>
</Mode>
<Upload>
<Permission>rw</Permission>
<Ui>select</Ui>
<Category>select</Category>
<Option>Never</Option>
<Option>When saving</Option>
</Upload>
<AutoBarcodeEnabled>
<Permission>rw</Permission>
<Ui>toggle</Ui>
<Category>toggle</Category>
<Option>false</Option>
<Option>true</Option>
</AutoBarcodeEnabled>
<AutoBarcodeDelay>
<Permission>rw</Permission>
<Ui>text</Ui>
<Category>regex</Category>
<Option>[0-9]+</Option>
</AutoBarcodeDelay>
<AutoSaveEnabled>
<Permission>rw</Permission>
<Ui>toggle</Ui>
<Category>toggle</Category>
<Option>false</Option>
<Option>true</Option>
</AutoSaveEnabled>
<AutoExportEnabled>
<Permission>rw</Permission>
<Ui>toggle</Ui>
<Category>toggle</Category>
<Option>false</Option>
<Option>true</Option>
</AutoExportEnabled>
</Scanner>
<Calibration>
<Path>
<Permission>rw</Permission>
<Ui>text</Ui>
<Category>regex</Category>
<Option>.*</Option>
</Path>
<Crash>
<Permission>r</Permission>
<Ui>toggle</Ui>
<Category>toggle</Category>
<Option>false</Option>
<Option>true</Option>
</Crash>
</Calibration>
<Units>
<Length>
<Permission>rw</Permission>
<Ui>select</Ui>
<Category>select</Category>
<Option>centimeters</Option>
<Option>feet</Option>
<Option>inches</Option>
<Option>meters</Option>
<Option>millimeters</Option>
</Length>
<Volume>
<Permission>rw</Permission>
<Ui>select</Ui>
<Category>select</Category>
<Option>cubic centimeters</Option>
<Option>cubic feet</Option>
<Option>cubic inches</Option>
<Option>cubic meters</Option>
<Option>cubic millimeters</Option>
</Volume>
<Weight>
<Permission>rw</Permission>
<Ui>select</Ui>
<Category>select</Category>
<Option>g</Option>
<Option>grains</Option>
<Option>grams</Option>
<Option>kg</Option>
<Option>kilograms</Option>
<Option>lb</Option>
<Option>ounces</Option>
<Option>pounds</Option>
<Option>tons</Option>
</Weight>
</Units>
<Licensing>
<Email>
<Permission>rw</Permission>
<Ui>text</Ui>
<Category>regex</Category>
<Option>.*</Option>
</Email>
</Licensing>
<Snapshot>
<Save>
<Permission>rw</Permission>
<Ui>text</Ui>
<Category>regex</Category>
<Option>.*</Option>
</Save>
<Images>
<Format>
<Permission>rw</Permission>
<Ui>select</Ui>
<Category>select</Category>
<Option>JPG</Option>
<Option>PNG</Option>
</Format>
</Images>
<Clouds>
<Format>
<Permission>rw</Permission>
<Ui>select</Ui>
<Category>select</Category>
<Option>PCD</Option>
<Option>PLY</Option>
<Option>NONE</Option>
</Format>
</Clouds>
</Snapshot>
<Printing>
<Logo>
<Permission>rw</Permission>
<Ui>text</Ui>
<Category>regex</Category>
<Option>.*</Option>
</Logo>
<LogoPlacement>
<Permission>rw</Permission>
<Ui>select</Ui>
<Category>select</Category>
<Option>Left</Option>
<Option>Center</Option>
<Option>Right</Option>
</LogoPlacement>
<Pdf>
<Permission>rw</Permission>
<Ui>toggle</Ui>
<Category>toggle</Category>
<Option>false</Option>
<Option>true</Option>
</Pdf>
<BoxIncluded>
<Permission>rw</Permission>
<Ui>toggle</Ui>
<Category>toggle</Category>
<Option>false</Option>
<Option>true</Option>
</BoxIncluded>
<Label>
<Permission>rw</Permission>
<Ui>toggle</Ui>
<Category>toggle</Category>
<Option>false</Option>
<Option>true</Option>
</Label>
<LabelPrinterName>
<Permission>rw</Permission>
<Ui>text</Ui>
<Category>regex</Category>
<Option>.*</Option>
</LabelPrinterName>
<BarSymbology>
<Permission>rw</Permission>
<Ui>select</Ui>
<Category>select</Category>
<Option>Code 128</Option>
<Option>Code 93</Option>
<Option>UPC-A</Option>
<Option>Do not print barcode</Option>
</BarSymbology>
<ReportPrinterName>
<Permission>rw</Permission>
<Ui>text</Ui>
<Category>regex</Category>
<Option>.*</Option>
</ReportPrinterName>
<DimBarcodes>
<Permission>rw</Permission>
<Ui>toggle</Ui>
<Category>toggle</Category>
<Option>false</Option>
<Option>true</Option>
</DimBarcodes>
<SimplifiedLabel>
<Permission>rw</Permission>
<Ui>toggle</Ui>
<Category>toggle</Category>
<Option>false</Option>
<Option>true</Option>
</SimplifiedLabel>
<ReportQuantity>
<Permission>rw</Permission>
<Ui>text</Ui>
<Category>regex</Category>
<Option>[0-9]+</Option>
</ReportQuantity>
<LabelQuantity>
<Permission>rw</Permission>
<Ui>ticker</Ui>
<Category>regex</Category>
<Option>[0-9]+</Option>
</LabelQuantity>
</Printing>
<Network>
<Proxy>
<Permission>rw</Permission>
<Ui>toggle</Ui>
<Category>toggle</Category>
<Option>false</Option>
<Option>true</Option>
</Proxy>
</Network>
<RemoteApi>
<Port>
<Permission>rw</Permission>
<Ui>text</Ui>
<Category>regex</Category>
<Option>[0-9]+</Option>
</Port>
</RemoteApi>
<Support>
<Sample>
<Reporting>
<Permission>rw</Permission>
<Ui>toggle</Ui>
<Category>toggle</Category>
<Option>false</Option>
<Option>true</Option>
</Reporting>
</Sample>
<LoginPrompt>
<Permission>r</Permission>
<Ui>toggle</Ui>
<Category>toggle</Category>
<Option>false</Option>
<Option>true</Option>
</LoginPrompt>
</Support>
</Settings>
</GetSettingInfo>
</Responses>

Request - Info for Specific Setting​

The GetSettingInfo command retrieves many useful attributes about all settings, or one particular one. These attributes include:

  • Permissions: The permissions of the setting. Include read, read-write, write-encrypted, etc. (specified as r, rw, we, etc.). Some permissions are private and are not returned by API, such as the password hash.
  • Category: A generalized type descriptor for the setting. Includes regex for text, select for multi-options, toggle for a more narrow select with only two options (e.g. true/false), etc.
  • Options: Either a regex string or a list of options depending on the category type.
  • Ui: A UI hint for the setting. This is how the Spectre GUI will render settings elements in future versions. Examples include toggle, text, integer, select, etc.

To get the attributes for a particular setting, you must specify a Path optional parameter.

info

As mentioned above, performing a read operation on a setting not set for read permissions is not possible. Such settings are for internal use by the application and are not accessible via API. In such cases, the API will return:

<Responses>
<GetSettingInfo code="0"/>
</Responses>

Endpoint​

Get the attributes for the PDF Freight-Report setting on machine with local IP address 10.1.1.2 set to port 7100.

GET http://10.1.1.2:7100/GetSettingInfo?Path=/Settings/Printing/Pdf

Example: get multiple setting attributes with one command.

GET http://10.1.1.2:7100/GetSettingInfo?Path=/Settings/Printing/Pdf+GetSettingInfo?Path=/Settings/Licensing/Email

Header​

Desired response format:

Accept: application/xml (DEFAULT)

Response - Info for Specific Setting​

The Responses/GetSettingInfo/ node contains both a "code" (where code 0 indicates success) and a /Settings node where the data is present. All settings data begins with /Settings as internally settings are represented by an XML tree.

Settings permissions

As of Spectre version 3.0.154, each setting has permissions attached to it. Only settings with "r" (Read) permissions can be returned by the API, and only settings with "w" (Write) permissions can be edited via API.

Example of response for one setting:

<Responses>
<GetSettingInfo code="0">
<Permission>rw</Permission>
<Ui>toggle</Ui>
<Category>toggle</Category>
<Option>false</Option>
<Option>true</Option>
</GetSettingInfo>
</Responses>

Example of response for multiple settings:

<Responses>
<GetSettingInfo code="0">
<Permission>rw</Permission>
<Ui>toggle</Ui>
<Category>toggle</Category>
<Option>false</Option>
<Option>true</Option>
</GetSettingInfo>
<GetSettingInfo code="0">
<Permission>rw</Permission>
<Ui>text</Ui>
<Category>regex</Category>
<Option>.*</Option>
</GetSettingInfo>
</Responses>

List of All Settings​

List is not regularly maintained

This list is not regularly maintained and may change depending on your version of the Cargo Spectre GUI. To check what settings are available to you, request GetSettings from your machine.

Cargo Spectre reserves the right to append additional nodes to the paths. Cargo Spectre will not remove or rearrange paths (e.g. /Settings/Device/Name will not disappear, nor will it become /Settings/Info/Name) but some paths may be 'tacked on' (e.g. /Settings/Device/NewNode)

danger

Cargo Spectre highly recommends parsing the full XML or JSON tree instead of looking for a setting at a specific line number or by a specific keyword. Cargo Spectre promises that paths will be unique, but specific node names may not. E.g. 'Name' might be repeated, but /Settings/Device/Name will not.

Furthermore, if an additional node is added further up in the tree, searching for a desired setting on line number 40 will break. Always traverse the tree with an XML or JSON parser instead.

PATHS (CASE SENSITIVE)ACCEPTED VALUES(CASE SENSITIVE)
/Settings/Device/Nameany stringHuman-readable name for a particular machine
/Settings/Device/Scale/FormatTotalcomp Continuous Format; FB1100 Continuous Format ; Rice Lake Continuous Format ; CI200 Continuous Format ; Optima OP-900 Continuous Format ; Mettler Toledo Continous Format ; Slimline Polling FormatScale data format
/Settings/Device/Scale/Baud9600 ; 14400 ; 19200 ; 28800 ; 38400 ; 56000 ; 57600 ; 115200Baud rate for an attached scale
/Settings/Device/Scale/Parity8 data bits, no parity bit, 1 stop bit ; 7 data bits, even parity bit, 1 stop bit ; 7 data bits, odd parity bit, 1 stop bit ; 7 data bits, even parity bit, 2 stop bits ; 7 data bits, odd parity bit, 2 stop bitsCommunication information for an attached scale
/Settings/Device/Scale/Ntepany stringThe NTEP certification number for the attached scale
/Settings/Printing/Pdftrue ; falseGenerates a freight report PDF when enabled
/Settings/Printing/Labeltrue ; falseGenerates a freight label PDF when enabled
/Settings/Printing/Logoa string that is a valid file path to an imageA file path for a company logo to be displayed on freight reports
/Settings/RemoteApi/Portany integer in range 1024-49151Port number
/Settings/Scanner/ModeCargo ; ParcelScanning mode. Select β€œcargo” for two camera operation, and β€œparcel” for one camera.
/Settings/Scanner/UploadNever ; When savingUploads scans to cloud storage
/Settings/Snapshot/Images/Formatjpg ; pngThe file format to save images in
/Settings/Units/Lengthmillimeters ; centimeters ; meters ; inches ; feetLength measurement unit for dimensions
/Settings/Units/Volumecubic millimeters ; cubic centimeters ; cubic meters ; cubic inches ; cubic feetVolume measurement unit
/Settings/Units/Weightkilograms ; lbWeight measurement unit