Support for UDP Protocol in Networking/Serial Module

[auzcoder]

I am working with Shtrix-M (ШТРИХ-М) scales, which are very popular in CIS countries. These devices primarily communicate over the UDP protocol (default ports: 1111 for receiving and 2000 for sending) using binary/hex payloads.

Currently, QZ Tray provides excellent support for TCP and Serial (COM) ports, but it lacks a direct way to send and receive raw UDP datagrams.

Proposed Solution

It would be highly beneficial if the qz.serial or a new qz.networking module could support UDP communication. Specifically:

1. Ability to open a UDP socket to a specific IP and Port.
2. Ability to send Hex/Base64 encoded binary data via UDP.
3. A callback mechanism to listen for incoming UDP responses (since many scales send a status response immediately after a command).

Example Use Case

• Device: Shtrix-Print Scale
• Protocol: UDP
• Target IP: 192.168.85.208
• Port: 1213
• Payload (Hex): 02 01 13 (Get Status)
• Expected Response (Hex): 02 02 13 00

Additional Context

Adding UDP support would expand QZ Tray's compatibility with a wide range of industrial hardware (scales, sensors, and IoT controllers) that rely on connectionless transport for speed and simplicity.

Thank you for the great tool and constant improvements!

[tresf]

Yeah, I think this can be done rather painlessly by cloning or modifying the SocketIO class to utilize a DatagramSocket.

tray/src/qz/communication/SocketIO.java

Lines 33 to 47 in 4322062

	public SocketIO(String host, int port, Charset encoding, SocketConnection websocket) {
	this.host = host;
	this.port = port;
	this.encoding = encoding;
	this.websocket = websocket;
	}
	public boolean open() throws IOException {
	socket = new Socket(host, port);
	socket.setSoTimeout(NetworkUtilities.SOCKET_TIMEOUT);
	dataOut = new DataOutputStream(socket.getOutputStream());
	dataIn = new DataInputStream(socket.getInputStream());
	return socket.isConnected();
	}

Assigning to @akberenz because I think she can code this particular feature faster than anyone else, but PRs are welcome and if she can't get to it, @Vzor- and myself can whip up a PoC.

I've milestoned it for 2.3.1, but it could land earlier.

[auzcoder]

Thank you for the quick response and for assigning this to the milestone!

I am currently planning a production project that heavily relies on this UDP feature. Could you please provide a rough estimate of when version 2.3.1 (or a beta/pre-release including this fix) might be available for testing?

If it's possible to get a PoC or a nightly build within the next few days, it would be extremely helpful for our project timeline. We are very excited to test this out with our hardware!

[tresf]

If it's possible to get a PoC or a nightly build within the next few days

This timeline is not possible unless you have someone ready to spearhead this feature. Nightly builds are available from our CI if you submit a PR with this feature added.

QZ Tray 2.3.1 would likely land in 3rd quarter of 2026. QZ Tray 2.3.0 is expected a bit sooner.

Note, if you're already a Premium Subscriber, please email support@qz.io so that we can triage it accordingly.

[auzcoder]

QZ Tray UDP Integration Guide (Shtrih-M Scales)

This guide provides technical details for integrating industrial hardware (specifically Shtrikh-M scales) with your web application using the custom UDP-enabled QZ Tray.

1. Quick Start Connection

To establish a connection with the scale over UDP, use the following JavaScript configuration:

var config = {
    host: "192.168.85.208", // Scale IP
    port: 1213,             // Scale listening port (default for Shtrih-M Ethernet)
    options: {
        protocol: "udp",
        localPort: 2000,    // PC source port (Scale expects 2000)
        responseFormat: "HEX" // Critical for binary protocols
    }
};
qz.socket.open(config.host, config.port, config.options)

.then(() => console.log("UDP Socket Connected"))

.catch(err => console.error(err));

<clipboard-copy aria-label="Copy" class="ClipboardButton btn btn-invisible js-clipboard-copy m-2 p-0 d-flex flex-justify-center flex-items-center" data-copy-feedback="Copied!" data-tooltip-direction="w" value="var config = {
host: "192.168.85.208", // Scale IP
port: 1213, // Scale listening port (default for Shtrih-M Ethernet)
options: {
protocol: "udp",
localPort: 2000, // PC source port (Scale expects 2000)
responseFormat: "HEX" // Critical for binary protocols
}
};

qz.socket.open(config.host, config.port, config.options)
.then(() => console.log("UDP Socket Connected"))
.catch(err => console.error(err));" tabindex="0" role="button" style="box-sizing: border-box; padding: 0px !important; font-size: 14px; font-weight: 500; white-space: nowrap; vertical-align: middle; cursor: pointer; user-select: none; appearance: none; border: 0px; border-radius: 6px; line-height: 20px; display: flex !important; position: relative; color: rgb(68, 147, 248); background-color: rgba(0, 0, 0, 0); box-shadow: none; transition: color 80ms cubic-bezier(0.33, 1, 0.68, 1), background-color 80ms cubic-bezier(0.33, 1, 0.68, 1), box-shadow 80ms cubic-bezier(0.33, 1, 0.68, 1), border-color 80ms cubic-bezier(0.33, 1, 0.68, 1); justify-content: center !important; align-items: center !important; margin: 8px !important; width: 28px; height: 28px;">

2. Handling Responses

Since hardware protocols are binary, QZ Tray converts incoming bytes into HEX strings. You must set up an event listener to capture these.

qz.socket.setEventListener(function(event) {

if (event.type === 'RECEIVE') {

processScaleResponse(event.response);

}

});

function processScaleResponse(hex) {

console.log("Raw HEX from Scale:", hex);
<span class="pl-c" style="box-sizing: border-box; color: rgb(145, 152, 161);">// Example: Response 02021300 means Success (00)</span>
<span class="pl-k" style="box-sizing: border-box; color: rgb(255, 123, 114);">if</span> <span class="pl-kos" style="box-sizing: border-box;">(</span><span class="pl-s1" style="box-sizing: border-box;">hex</span><span class="pl-kos" style="box-sizing: border-box;">.</span><span class="pl-en" style="box-sizing: border-box; color: rgb(210, 168, 255);">startsWith</span><span class="pl-kos" style="box-sizing: border-box;">(</span><span class="pl-s" style="box-sizing: border-box; color: rgb(165, 214, 255);">"02"</span><span class="pl-kos" style="box-sizing: border-box;">)</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">&amp;&amp;</span> <span class="pl-s1" style="box-sizing: border-box;">hex</span><span class="pl-kos" style="box-sizing: border-box;">.</span><span class="pl-en" style="box-sizing: border-box; color: rgb(210, 168, 255);">endsWith</span><span class="pl-kos" style="box-sizing: border-box;">(</span><span class="pl-s" style="box-sizing: border-box; color: rgb(165, 214, 255);">"00"</span><span class="pl-kos" style="box-sizing: border-box;">)</span><span class="pl-kos" style="box-sizing: border-box;">)</span> <span class="pl-kos" style="box-sizing: border-box;">{</span>
    <span class="pl-en" style="box-sizing: border-box; color: rgb(210, 168, 255);">alert</span><span class="pl-kos" style="box-sizing: border-box;">(</span><span class="pl-s" style="box-sizing: border-box; color: rgb(165, 214, 255);">"Action Successful!"</span><span class="pl-kos" style="box-sizing: border-box;">)</span><span class="pl-kos" style="box-sizing: border-box;">;</span>
<span class="pl-kos" style="box-sizing: border-box;">}</span>

}

<clipboard-copy aria-label="Copy" class="ClipboardButton btn btn-invisible js-clipboard-copy m-2 p-0 d-flex flex-justify-center flex-items-center" data-copy-feedback="Copied!" data-tooltip-direction="w" value="qz.socket.setEventListener(function(event) {
if (event.type === 'RECEIVE') {
processScaleResponse(event.response);
}
});

function processScaleResponse(hex) {
console.log("Raw HEX from Scale:", hex);

// Example: Response 02021300 means Success (00)
if (hex.startsWith("02") && hex.endsWith("00")) {
    alert("Action Successful!");
}

}" tabindex="0" role="button" style="box-sizing: border-box; padding: 0px !important; font-size: 14px; font-weight: 500; white-space: nowrap; vertical-align: middle; cursor: pointer; user-select: none; appearance: none; border: 0px; border-radius: 6px; line-height: 20px; display: flex !important; position: relative; color: rgb(68, 147, 248); background-color: rgba(0, 0, 0, 0); box-shadow: none; transition: color 80ms cubic-bezier(0.33, 1, 0.68, 1), background-color 80ms cubic-bezier(0.33, 1, 0.68, 1), box-shadow 80ms cubic-bezier(0.33, 1, 0.68, 1), border-color 80ms cubic-bezier(0.33, 1, 0.68, 1); justify-content: center !important; align-items: center !important; margin: 8px !important; width: 28px; height: 28px;">

3. Shtrih-M Protocol Packets

All packets follow this structure: STX (02) | LEN | CMD | DATA | CRC (XOR).

Common Commands:

Command	HEX Packet (Password: 30)	Purpose
Gudok (Beep)	02011312	Chirps the scale to verify connection.
Status	0205111E0000000A	Returns internal flags and state.
Get Weight	0205151E0000000E	Returns current weight in grams.

4. CRC Calculation (JavaScript)

Use this helper to construct packets dynamically:

function sendShtrihPacket(cmd, dataBytes) {

var len = dataBytes.length + 1;

var packet = [len, cmd].concat(dataBytes);

<span class="pl-k" style="box-sizing: border-box; color: rgb(255, 123, 114);">var</span> <span class="pl-s1" style="box-sizing: border-box;">crc</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">=</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">0</span><span class="pl-kos" style="box-sizing: border-box;">;</span>
<span class="pl-k" style="box-sizing: border-box; color: rgb(255, 123, 114);">for</span> <span class="pl-kos" style="box-sizing: border-box;">(</span><span class="pl-k" style="box-sizing: border-box; color: rgb(255, 123, 114);">var</span> <span class="pl-s1" style="box-sizing: border-box;">i</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">=</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">0</span><span class="pl-kos" style="box-sizing: border-box;">;</span> <span class="pl-s1" style="box-sizing: border-box;">i</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">&lt;</span> <span class="pl-s1" style="box-sizing: border-box;">packet</span><span class="pl-kos" style="box-sizing: border-box;">.</span><span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">length</span><span class="pl-kos" style="box-sizing: border-box;">;</span> <span class="pl-s1" style="box-sizing: border-box;">i</span><span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">++</span><span class="pl-kos" style="box-sizing: border-box;">)</span> <span class="pl-kos" style="box-sizing: border-box;">{</span>
    <span class="pl-s1" style="box-sizing: border-box;">crc</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">^=</span> <span class="pl-s1" style="box-sizing: border-box;">packet</span><span class="pl-kos" style="box-sizing: border-box;">[</span><span class="pl-s1" style="box-sizing: border-box;">i</span><span class="pl-kos" style="box-sizing: border-box;">]</span><span class="pl-kos" style="box-sizing: border-box;">;</span>
<span class="pl-kos" style="box-sizing: border-box;">}</span>

<span class="pl-k" style="box-sizing: border-box; color: rgb(255, 123, 114);">var</span> <span class="pl-s1" style="box-sizing: border-box;">fullPacket</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">=</span> <span class="pl-kos" style="box-sizing: border-box;">[</span><span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">0x02</span><span class="pl-kos" style="box-sizing: border-box;">]</span><span class="pl-kos" style="box-sizing: border-box;">.</span><span class="pl-en" style="box-sizing: border-box; color: rgb(210, 168, 255);">concat</span><span class="pl-kos" style="box-sizing: border-box;">(</span><span class="pl-s1" style="box-sizing: border-box;">packet</span><span class="pl-kos" style="box-sizing: border-box;">)</span><span class="pl-kos" style="box-sizing: border-box;">.</span><span class="pl-en" style="box-sizing: border-box; color: rgb(210, 168, 255);">concat</span><span class="pl-kos" style="box-sizing: border-box;">(</span><span class="pl-kos" style="box-sizing: border-box;">[</span><span class="pl-s1" style="box-sizing: border-box;">crc</span><span class="pl-kos" style="box-sizing: border-box;">]</span><span class="pl-kos" style="box-sizing: border-box;">)</span><span class="pl-kos" style="box-sizing: border-box;">;</span>
<span class="pl-k" style="box-sizing: border-box; color: rgb(255, 123, 114);">var</span> <span class="pl-s1" style="box-sizing: border-box;">hexString</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">=</span> <span class="pl-s1" style="box-sizing: border-box;">fullPacket</span><span class="pl-kos" style="box-sizing: border-box;">.</span><span class="pl-en" style="box-sizing: border-box; color: rgb(210, 168, 255);">map</span><span class="pl-kos" style="box-sizing: border-box;">(</span><span class="pl-s1" style="box-sizing: border-box;">b</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">=&gt;</span> <span class="pl-kos" style="box-sizing: border-box;">(</span><span class="pl-s" style="box-sizing: border-box; color: rgb(165, 214, 255);">"0"</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">+</span> <span class="pl-s1" style="box-sizing: border-box;">b</span><span class="pl-kos" style="box-sizing: border-box;">.</span><span class="pl-en" style="box-sizing: border-box; color: rgb(210, 168, 255);">toString</span><span class="pl-kos" style="box-sizing: border-box;">(</span><span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">16</span><span class="pl-kos" style="box-sizing: border-box;">)</span><span class="pl-kos" style="box-sizing: border-box;">)</span><span class="pl-kos" style="box-sizing: border-box;">.</span><span class="pl-en" style="box-sizing: border-box; color: rgb(210, 168, 255);">slice</span><span class="pl-kos" style="box-sizing: border-box;">(</span><span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">-</span><span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">2</span><span class="pl-kos" style="box-sizing: border-box;">)</span><span class="pl-kos" style="box-sizing: border-box;">.</span><span class="pl-en" style="box-sizing: border-box; color: rgb(210, 168, 255);">toUpperCase</span><span class="pl-kos" style="box-sizing: border-box;">(</span><span class="pl-kos" style="box-sizing: border-box;">)</span><span class="pl-kos" style="box-sizing: border-box;">)</span><span class="pl-kos" style="box-sizing: border-box;">.</span><span class="pl-en" style="box-sizing: border-box; color: rgb(210, 168, 255);">join</span><span class="pl-kos" style="box-sizing: border-box;">(</span><span class="pl-s" style="box-sizing: border-box; color: rgb(165, 214, 255);">""</span><span class="pl-kos" style="box-sizing: border-box;">)</span><span class="pl-kos" style="box-sizing: border-box;">;</span>

<span class="pl-k" style="box-sizing: border-box; color: rgb(255, 123, 114);">return</span> <span class="pl-s1" style="box-sizing: border-box;">qz</span><span class="pl-kos" style="box-sizing: border-box;">.</span><span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">socket</span><span class="pl-kos" style="box-sizing: border-box;">.</span><span class="pl-en" style="box-sizing: border-box; color: rgb(210, 168, 255);">sendData</span><span class="pl-kos" style="box-sizing: border-box;">(</span><span class="pl-s1" style="box-sizing: border-box;">host</span><span class="pl-kos" style="box-sizing: border-box;">,</span> <span class="pl-s1" style="box-sizing: border-box;">port</span><span class="pl-kos" style="box-sizing: border-box;">,</span> <span class="pl-kos" style="box-sizing: border-box;">{</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">data</span>: <span class="pl-s1" style="box-sizing: border-box;">hexString</span><span class="pl-kos" style="box-sizing: border-box;">,</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(121, 192, 255);">type</span>: <span class="pl-s" style="box-sizing: border-box; color: rgb(165, 214, 255);">'HEX'</span> <span class="pl-kos" style="box-sizing: border-box;">}</span><span class="pl-kos" style="box-sizing: border-box;">)</span><span class="pl-kos" style="box-sizing: border-box;">;</span>

}

<clipboard-copy aria-label="Copy" class="ClipboardButton btn btn-invisible js-clipboard-copy m-2 p-0 d-flex flex-justify-center flex-items-center" data-copy-feedback="Copied!" data-tooltip-direction="w" value="function sendShtrihPacket(cmd, dataBytes) {
var len = dataBytes.length + 1;
var packet = [len, cmd].concat(dataBytes);

var crc = 0;
for (var i = 0; i < packet.length; i++) {
    crc ^= packet[i];
}

var fullPacket = [0x02].concat(packet).concat([crc]);
var hexString = fullPacket.map(b => ("0" + b.toString(16)).slice(-2).toUpperCase()).join("");

return qz.socket.sendData(host, port, { data: hexString, type: 'HEX' });

}" tabindex="0" role="button" style="box-sizing: border-box; padding: 0px !important; font-size: 14px; font-weight: 500; white-space: nowrap; vertical-align: middle; cursor: pointer; user-select: none; appearance: none; border: 0px; border-radius: 6px; line-height: 20px; display: flex !important; position: relative; color: rgb(68, 147, 248); background-color: rgba(0, 0, 0, 0); box-shadow: none; transition: color 80ms cubic-bezier(0.33, 1, 0.68, 1), background-color 80ms cubic-bezier(0.33, 1, 0.68, 1), box-shadow 80ms cubic-bezier(0.33, 1, 0.68, 1), border-color 80ms cubic-bezier(0.33, 1, 0.68, 1); justify-content: center !important; align-items: center !important; margin: 8px !important; width: 28px; height: 28px;">

5. Troubleshooting

• Address already in use: Ensure no other software (like the Shtrih-M Test Driver) is using Port 2000 or 1213.
• No Response: Verify you are sending the correct 4-byte password. Default is 30 (Hex 1E).
• Firewall: Ensure the Windows Firewall allows UDP traffic on the specified ports.

[tresf]

@auzcoder I've hidden your above message since it's malformatted and redundant with the exact same post here: #1433 (comment). Please cleanup that post and we can crosslink to that as needed.

[auzcoder]

🧾 Feature Request: UDP Support for QZ Tray (Shtrih-M Scale Integration)

📌 Overview

This document describes how to integrate Shtrih-M industrial scales with a web application using a custom UDP-enabled QZ Tray implementation.

Currently, QZ Tray primarily supports TCP/WebSocket-based communication. However, Shtrih-M scales rely on UDP protocol, requiring extended support.

---

🚀 Use Case

Enable web applications to:

• Communicate with Shtrih-M scales over UDP
• Send binary protocol commands
• Receive and parse HEX responses
• Perform real-time weight reading and device control

---

🔌 1. UDP Connection Setup

Example configuration for establishing a UDP connection:

const config = {
    host: "192.168.85.208", // Scale IP
    port: 1213,             // Default Shtrih-M port
    options: {
        protocol: "udp",
        localPort: 2000,    // Required source port
        responseFormat: "HEX" // Required for binary communication
    }
};

qz.socket.open(config.host, config.port, config.options)
    .then(() => console.log("UDP Socket Connected"))
    .catch(err => console.error(err));

---

📡 2. Receiving Data (Event Listener)

Shtrih-M uses binary protocol → QZ Tray returns responses as HEX strings.

qz.socket.setEventListener(function(event) {
    if (event.type === 'RECEIVE') {
        processScaleResponse(event.response);
    }
});

function processScaleResponse(hex) {
    console.log("Raw HEX from Scale:", hex);

    // Example: success response
    if (hex.startsWith("02") && hex.endsWith("00")) {
        alert("Action Successful!");
    }
}

---

📦 3. Protocol Structure

All packets follow this format:

STX (02) | LEN | CMD | DATA | CRC (XOR)

---

⚙️ 4. Common Commands

Command | HEX Packet | Description -- | -- | -- Beep (Gudok) | 02011312 | Test connection Status | 0205111E0000000A | Get device status Get Weight | 0205151E0000000E | Read weight in grams

---

🧮 5. CRC Packet Builder (JS)

Helper function to generate valid packets:

function sendShtrihPacket(cmd, dataBytes) {
    const len = dataBytes.length + 1;
    const packet = [len, cmd, ...dataBytes];

    let crc = 0;
    for (let i = 0; i < packet.length; i++) {
        crc ^= packet[i];
    }

    const fullPacket = [0x02, ...packet, crc];

    const hexString = fullPacket
        .map(b => ("0" + b.toString(16)).slice(-2).toUpperCase())
        .join("");

    return qz.socket.sendData(host, port, {
        data: hexString,
        type: 'HEX'
    });
}

---

⚠️ 6. Known Issues / Limitations

• ❌ Default QZ Tray does not support UDP natively
• ⚠️ Requires custom build or extension
• ⚠️ Binary protocol parsing must be handled manually

---

🛠️ 7. Troubleshooting

❗ Address already in use

• Ensure no other software is using:
  • Port 2000
  • Port 1213

❗ No response from scale

• Verify:
  • Correct password (30 → 0x1E)
  • Correct packet format

❗ Connection blocked

• Check Windows Firewall:
  • Allow UDP traffic on required ports

---

💡 Proposed Enhancement

Add native UDP socket support to QZ Tray with:

• protocol: "udp" option
• configurable localPort
• binary-safe responseFormat
• event-driven receive handler

---

🙏 Why This Matters

Industrial devices (like Shtrih-M scales) often rely on UDP. Supporting this would:

• Expand QZ Tray into industrial environments
• Enable POS + IoT integrations
• Reduce need for native middleware

---

📎 Additional Notes

• Protocol requires strict HEX formatting
• CRC is XOR-based
• Communication is stateless (UDP)