Text Line protocol
The Text Line protocol lets a device that can send text over TCP select what the printer prints. For each line of text it receives, the printer runs one or more configured actions. Each action selects a label by name, or looks up the text as a key in a table.
The most common client is a network barcode scanner: a scanned product code selects the matching label. Any other client that can open a TCP connection and send text works just as well, such as a PLC, a weighing scale or a script.
The protocol only goes one way. The printer never sends anything back. If a client needs replies, or needs to do more than select print jobs, use the Aurora API instead.
In the web UI, the protocol is listed as Text Line / Barcode.
Before v5.4, the protocol was called Line. Existing configurations are converted when the printer is upgraded.
At a glance
| Item | Value |
|---|---|
| Transport | TCP. The printer is the server. |
| Port | Chosen when the protocol is added, 11000 by default. See Printer setup. |
| Direction | Client to printer only. No response is sent. |
| Framing | One message per line, terminated by LF, CR or CR+LF. |
| Encoding | UTF-8 |
| Maximum line | 8192 bytes, including the line terminator |
| Clients | Up to 50 at the same time. Further connections are closed immediately. |
The printer listens on all of its network interfaces, for both IPv4 and IPv6. It has no idle timeout between lines, so a client can keep one connection open and send any number of lines on it, or open a new connection for each line.
Wire format
Each line is a message. A line ends with LF (hex 0A) or CR (hex
0D) v6.0.1, so CR+LF also works, as it ends a line followed by
an empty line, which is ignored.
Before v6.0.1, a line ends only with LF, and a CR directly before the LF is removed. Many barcode scanners send only CR after each code by default. With those versions, configure the scanner to send LF or CR+LF, or nothing will be printed.
The printer also:
- ignores empty lines,
- removes a UTF-8 byte order mark at the start of the first line,
- discards text after the last line terminator when the connection is closed, so the last line must be terminated too,
- closes the connection if a line is longer than 8192 bytes,
- closes the connection if no data arrives for the Read timeout, 1 second by default, while a line is incomplete, so that a partial line, for example from a scanner that lost its connection mid-code, is not joined with the next one v6.1. See Settings.
How a line is handled
For each received line, the printer:
- Removes leading and trailing whitespace, if Trim whitespace is on.
- Ignores the line if it equals the Error Value,
ERRORby default. A warning is logged. Use this for the text a scanner sends when it fails to read a code. - Runs each action in order, with the line as its value. See Actions.
Every line runs every action, including a line with the same text as the previous one. If an action fails, for example because the label does not exist, the error is logged on the printer, and the next action still runs. The client is not told about the error.
Where to start
- Setting up the printer? Read Printer setup.
- Looking for a worked example? See Examples.