TCP / UDP

For equipment that has no industrial protocol at all: bench scales, barcode and RFID readers, weather stations, laboratory instruments, serial devices behind an Ethernet gateway, and in-house protocols. QUBIQ opens the socket, splits the byte stream into messages, and lets you map fields to tags.

Configuration

Field	Description
Name	Connection identifier.
Host	Device IP or hostname (for client role).
Port	Device port, or the port to listen on in server role.
Transport	tcp or udp.
Role	client — QUBIQ connects out. server — QUBIQ listens and the device connects in.
Frame mode	How the byte stream is split into messages. See below.
Delimiter	For delimiter framing: the terminator, e.g. \r\n, \n, \x03.
Frame size	For fixed-length framing: bytes per message.
Max message bytes	Hard cap; a message larger than this is discarded rather than buffered indefinitely.
Field delimiter	Splits a message into fields, e.g. , for CSV, \t, ;.
Field count	Expected number of fields. A message with a different count turns its tags Bad.
Writeable	Allows tags on this connection to send data to the device.
Connect timeout (ms)	Socket connect timeout.
Inactivity timeout (ms)	Reconnect if nothing is received for this long.

Framing

A TCP stream has no message boundaries — framing is how you recover them. Getting this wrong is the usual cause of "half a reading" or "two readings stuck together".

Frame mode	Use when	Notes
Delimiter	The device terminates each message (\r\n, \n, ETX)	The most common case.
Fixed length	Every message is exactly N bytes	Binary protocols with a fixed record.
None	UDP, where each datagram is already a message	Do not use for TCP.

UDP preserves datagram boundaries, so framing is usually unnecessary — but UDP also loses datagrams silently and may reorder them. Do not use it for anything you must not miss.

Field mapping

Every connection gets a fixed set of generated tags, and a binding's address picks one of them by name:

Generated tag	Holds
message	The whole message, as text.
messageBytes	The whole message, as hexadecimal.
lastReceiveTime	When the message arrived.
field0 … fieldN	One per field, counted from 0, when a field delimiter and field count are set.
writeable, writeableBytes	Write-only: what a write sends to the device. TCP with Writeable on only.

Message:  "ST,GS,+  12.345,kg\r\n"
Fields:   field0="ST"  field1="GS"  field2="+  12.345"  field3="kg"

Tag  Scale/Status  → field0
Tag  Scale/Weight  → field2   (data type float)
Tag  Scale/Unit    → field3

Field count is a cheap integrity check: a truncated or concatenated message has the wrong number of fields. It is not parsed into wrong tags: every tag of that message goes Bad, with the counts in the status (field count 3 does not match expected 4).

Binding tags

Field	Notes
Tag	One of the generated tags, chosen from a list. The field tags appear once the connection has a field count.
Data type	Set it — text "12.345" becomes a number only if the tag says float.

There is no poll rate: every message the device sends updates the tags.

Writing to the device

With writeable enabled on a TCP connection, writing a tag bound to writeable (text) or writeableBytes (hexadecimal) transmits its value on the socket. The framing configuration is applied on the way out: the delimiter is appended, or the payload is padded to the fixed length.

Use this for command protocols — tare a scale, trigger a reader, request a measurement.

Quality and liveness

A raw socket gives no quality information, so QUBIQ infers it:

Condition	Quality
Message parsed, field present	Good
Socket down or reconnecting	Bad
Field count does not match	Bad on every tag of the message, with the counts
Message over Max message bytes	Not published; the stream stops
Nothing received within Inactivity timeout	Connection reported disconnected: link open but silent

A tag's stale after is not enforced in this release. Set the connection's Inactivity timeout instead, so a device that holds its socket open and goes silent is reported rather than looking like a quiet one.

Security

Raw TCP/UDP has no authentication and no encryption. Anyone who can reach the port can send data that QUBIQ will parse into tags.

• Keep these devices on an isolated segment.
• In server role, bind to a specific interface and firewall the port.
• Never expose a server-role TCP/UDP connection to an untrusted network.
• Treat values from it as untrusted input: validate ranges on the tag, not just in the display.

Troubleshooting

Symptom	Check
Values are truncated or concatenated	Wrong frame mode or delimiter. Capture the raw stream and look at the actual terminator.
Some messages ignored	Field count mismatch — the device emits a status message with a different shape.
Data stops after a while	Device closed the socket; set inactivity timeout so QUBIQ reconnects.
Nothing at all, client role	The device may be a server-only device expecting QUBIQ to listen — switch roles.
Numbers arrive as strings	Set the tag's data type; leading spaces and + signs are handled on conversion.
Works then breaks after a firmware update	Vendors change delimiters and field order between versions. Re-capture.

Next

→ SQL databases