Advanced Driver Settings (driverConfig)

Last updated

Every driver keeps its protocol settings in the device's driverConfig object. The common ones — ControlLogix slot, S7 rack and slot, FINS transport, node numbers and word order, MELSEC PLC, frame type and data code, Modbus unit ID, byte order, register map and serial settings, OPC-UA security, sign-in and subscriptions, MQTT topics and TLS, MTConnect catch-up, FOCAS macro variables and tool life groups, and the tag maps of EtherNet/IP (Generic), HTTP/REST, Custom JSON and Custom XML — have fields in the Add Device wizard and under Settings → Driver Settings. The rest (HTTP headers and POST body, fixed tag lists, OPC-UA namespace filter…) are set through the REST API. This page shows how, and lists every key each driver reads.

Endpoints

Method	Path	Purpose
GET	/api/devices	List devices, including each driverConfig (credentials masked)
GET	/api/devices/:id	One device
POST	/api/devices	Create a device (admin, editor); accepts driverConfig
PUT	/api/devices/:id	Update fields, including driverConfig (admin, editor)
POST	/api/devices/:id/connect	Connect and subscribe (admin, editor)
POST	/api/devices/:id/disconnect	Disconnect and mark stopped (admin, editor)
GET	/api/devices/:id/info	What the driver reports about the device (model, firmware, configured counts)
DELETE	/api/devices/:id	Delete (admin)
GET	/api/tags/browse/:deviceId	Browse result
GET	/api/devices/status/all	Live connection status of every device

Procedure

1. Find the device ID in the address bar of its detail page, e.g. /devices/7.
2. Sign in and keep the token, read the current config, write the new one, then restart the connection:

APPLIANCE=http://192.168.1.20

# 1. Sign in (jq is optional: without it, copy data.tokens.token by hand)
TOKEN=$(curl -s -X POST "$APPLIANCE/api/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@scada.ink","password":"your-password"}' | jq -r .data.tokens.token)

# 2. Look at the current settings
curl -s "$APPLIANCE/api/devices/7" -H "Authorization: Bearer $TOKEN"

# 3. Replace driverConfig (the whole object is replaced, not merged)
curl -s -X PUT "$APPLIANCE/api/devices/7" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"driverConfig":{"slot":2}}'

# 4. Restart the connection so the driver reads the new settings
curl -s -X POST "$APPLIANCE/api/devices/7/disconnect" -H "Authorization: Bearer $TOKEN"
curl -s -X POST "$APPLIANCE/api/devices/7/connect" -H "Authorization: Bearer $TOKEN"

If two-factor sign-in is on, the login returns a challenge instead; see REST API.

Warning: PUT replaces driverConfig entirely. Always send every key you want to keep. The UI's Save Changes is the exception: it rewrites only the keys it shows — the Driver Settings fields, GE SRTP (ranges), scanners and scales (transport, serial_port, baudrate) — and keeps everything else you set here. Clearing the SRTP range list still removes ranges, which is how you go back to the driver's defaults.

A credential-shaped key (password, token, apiKey, a private key such as tls_private_key, username/password pairs on a camera, a password embedded in a URL, …) is never returned — GET shows "password":"••••••••" instead, for every role, including viewers. Copy the value straight from GET into your PUT body and the stored credential is kept, because the placeholder means "unchanged"; type a real value instead and that becomes the new credential. Leaving the key out entirely still clears it, same as any other key, since the object is replaced rather than merged.

A credential can also be a reference to the Secrets store, written ${secret:NAME} — including inside a URL, as in rtsp://admin:${secret:CAM_PW}@camera/stream. A reference is a name rather than a credential, so GET returns it exactly as you typed it instead of masking it. The appliance looks the value up each time the device connects, so rotating the credential is one edit in Secrets and a reconnect here. A name that matches no secret fails the connection with Secret "NAME" is not in the Secrets store, and nothing is sent to the device.

The server doesn't validate driverConfig; an unknown key is ignored and a wrong type usually shows up as a connection or read error in the driver log.

Keys by driver

Driver	Keys (default)
ControlLogix, CompactLogix	slot (0)
SLC 500, MicroLogix	slot (0); tags — list of address strings shown by Browse
Siemens S7	rack (0), slot (1); tags — list of { "path", "name", "description" } shown by Browse. Symbols imported from TIA Portal are entries with "source": "tia", whose name is the symbol and path its address; Browse lists them by name, and a tag path can be the symbol
Siemens S7 (OPC UA)	The OPC-UA keys, except that security defaults to "auto" (the strongest policy the CPU offers); plus browse_depth (8, 1–16)
Omron FINS	transport ("tcp"; also "udp"), node (1), src_node (10), unit_address (0), word_order ("CDAB"; also "ABCD", "BADC", "DCBA"); tags — list of address strings
Mitsubishi MELSEC	plc_type ("iQ-R"; also "iQ-L", "Q", "L", "QnA", "FX"), frame_type ("3E"; also "4E", "1E"), data_code ("binary"; also "ascii"); tags — list of device strings
AutomationDirect	unit_id (1), byte_order ("ABCD"), registers (a 10-entry DirectLogic preset) — same format as Modbus TCP
GE / Emerson SRTP	tags — list such as ["%R1","%Q12"]; ranges — list of { "type", "start", "end" }
Modbus TCP	unit_id (1, 0–255), byte_order ("ABCD"; also "CDAB", "BADC", "DCBA"); registers — list of { "name", "address", "type": "hr"/"ir"/"coil"/"di", "count", "data_type", "byte_order", "description" }
Modbus RTU	serial_port ("/dev/ttyUSB0"), baudrate (9600), parity ("N"/"E"/"O"), stopbits (1), bytesize (8), slave_id (1), timeout (1.0 s), byte_order ("ABCD"), registers (as Modbus TCP, plus function_code)
OPC-UA	security ("None"; also "Basic256Sha256", "Aes128Sha256RsaOaep", "Aes256Sha256RsaPss", "Basic256", "Basic128Rsa15"), security_mode ("SignAndEncrypt"; also "Sign"), auth_mode ("anonymous", "username", "certificate"), username, password, user_certificate (PEM), user_private_key (PEM), user_key_password, use_subscriptions ("true"), publishing_interval_ms (1000), sampling_interval_ms (the publishing interval), namespace_filter (list of namespace indexes), browse_include_builtin (false)
MQTT	topics (["#"]), qos (0), client_id (scadaink- plus the device ID), username, password, tls ("false"), tls_verify ("true"), tls_ca_cert, tls_client_cert, tls_private_key (PEM text), tls_key_password
EtherNet/IP (Generic)	tags — list of { "name", "assembly", "offset", "cip_type", "bit" } (assembly) or { "name", "class_code", "instance", "attribute", "cip_type", "data_type", "service", "write_service", "writeable", "description" } (attribute)
MTConnect	device (empty), sample_catchup ("true"), sample_count (1000)
Fanuc FOCAS	macro_variables (list of numbers or ranges), macro_write ("false"), tool_life_groups (list), status_style ("auto"; also "30i", "legacy")
SECS/GEM	session_id (1), mode ("active"/"passive"), svids, ceids, t3 (45), t5 (10), t6 (5), t7 (10)
HTTP / REST API, Custom JSON	base_url ("http://IP:port"), method ("GET"/"POST"), headers, body, tags — list of { "path", "name", "url", "endpoint", "json_path", "data_type" } (json_path: dot path or JSONPath)
Custom XML	base_url, method, headers, tags — list of { "path", "url", "endpoint", "xml_path", "attr", "data_type" } (xml_path: dot path or XPath with predicates)
Raw TCP	encoding ("ascii"/"hex"), delimiter ("\n"), connect_timeout (10), read_timeout (5), tags — list of { "path", "request", "response_offset", "response_length", "data_type", "byte_order", "write_request" }
Barcode / QR Scanner	transport ("tcp"/"serial"), serial_port, baudrate, delimiter ("\n"), tx_delimiter ("\r\n"), encoding ("utf-8"), connect_timeout (10), read_timeout (1), strip_prefix, strip_suffix
Weigh Scale	as scanner, plus weight_regex, unit ("kg"), stable_token ("ST"), unstable_token ("US")
Universal Robots	read_timeout (5)
KUKA (KUKAVARPROXY)	variables — list of { "path", "krl", "data_type", "writeable" }; read_timeout (5)
FANUC Robot	tags — list of { "name", "class_code", "instance", "attribute", "data_type", "service" }
Machine Vision	Managed by the Vision page — see Vision.

The driver guides in this category show worked examples for each.

See also

• Device Detail Page
• REST API Reference
• Adding Modbus Devices (TCP and RTU)
• Adding Allen-Bradley PLCs (Logix, SLC, MicroLogix)
• Scripting API Reference