MANUFACTURING / MQTT / GRPC / ON-PREM
Print Labels When the Line Says So: MQTT and gRPC for PLCs, MES and Robots
Publish a JSON command to labelinn/cmd/print on your MQTT broker (or call PrintService.SubmitJob over gRPC on port 6633) and the PC next to the printer prints it and answers with the job result. Send your own jobId: it is the only value that ties the answer back to your command.
{
"printerId": "<printer id>",
"payloadType": "design",
"designId": "<design id>",
"designDataRows": [
{ "sku": "A-1042", "lot": "L2610", "qty": "24" }
],
"copies": 1
}THE PROBLEM

On a production line the controller already knows the moment a carton is full, a pallet is wrapped or a part has passed inspection. What usually happens next is an operator walking to a PC to print the label. That walk is where labels end up on the wrong box.
LabelInn's edge runtime sits on a PC on your network and listens for print commands over MQTT, the messaging protocol most SCADA systems, gateways and Node-RED flows already speak, and over gRPC for MES software and robot cells that prefer typed calls. It renders the label and sends native printer commands. No print server, no Windows driver per printer model.
Labels triggered by the line, not by a walk to the PC. Publish a message, a label prints. Talk to us about your line →
01 / MQTT
How it works
Connect LabelInn to your existing broker, such as Mosquitto, EMQX or HiveMQ, or switch on its built-in broker. TLS, username and password, and QoS 0, 1 and 2 are supported. LabelInn subscribes to these command topics:
| Topic | Purpose |
|---|---|
labelinn/cmd/print | Print a label or a batch |
labelinn/cmd/status | List local printers and broker state |
A print command names the printer and says what to print: a saved LabelInn design filled with your data, or raw ZPL, TPCL or ESC/Label if your system already generates printer language.
{
"printerId": "<printer id>",
"payloadType": "design",
"designId": "<design id>",
"designDataRows": [
{ "sku": "A-1042", "lot": "L2610", "qty": "24" }
],
"copies": 1
}Every command is answered on labelinn/cmd/response with the job result and its id, so the controller can confirm the label before the carton moves on.
02 / GRPC
gRPC: typed calls for MES and robot cells
The same runtime runs a gRPC server on your LAN (port 6633 by default, with an automatic fallback if it is taken). Switch it on in LabelInn's gRPC settings and it starts with the app.
| Service | Calls |
|---|---|
| PrintService | SubmitJob prints a design with data or raw ZPL/TPCL/ESC-Label and returns the result; GetJobStatus reads it back by job id |
| PrinterFleetService | ListPrinters returns every local printer and whether it is online |
| VerifyService | VerifyScan checks a scanned barcode against what was printed |
| SystemService | HealthCheck and Ping |
03 / MES
Why this is easier than a print server
| Typical approach | LabelInn edge runtime |
|---|---|
| Windows print server and a driver per model | Native ZPL, TSPL, TPCL and ESC/Label, no driver |
| Fire-and-forget raw socket to port 9100 | A job id per command and a status you can query |
| Label layout hard-coded in PLC or MES logic | Designs edited visually in LabelInn, referenced by id |
04 / INDUSTRIAL AUTOMATION
Connecting your line
- From the PLC side, anything that publishes MQTT or calls gRPC works: an MQTT-capable controller, a SCADA system, Node-RED, an MES, or a protocol gateway in front of the PLC.
- On the floor, a PC near the printers runs LabelInn and drives them over USB or the network.
- Prefer plain HTTP? The same runtime takes jobs on
POST /local/v1/print/jobs. See printing from a web app.
THE MQTT CONTRACT
Fields, types and answers, exactly
Read from edge_mqtt_service.dart, edge_mqtt_command_bridge.dart and edge_print_job_request.dart. This was not run against a PLC; treat it as the code's contract and test one command on your broker.
mosquitto_pub -h 192.168.1.20 -t labelinn/cmd/print -m '{
"printerId": "<printer id>",
"payloadType": "design",
"designId": "<design id>",
"designDataRows": [ { "sku": "A-1042", "lot": "L2610", "qty": "24" } ],
"copies": 1,
"jobId": "carton-000123"
}'
# the answer arrives on labelinn/cmd/response| Item | Behaviour in the code |
|---|---|
| Switch | MQTT is off by default. Turn it on in the app's MQTT settings (port 1883, or 8883 with TLS, prefix labelinn), or use the built-in broker. |
| Topics in | labelinn/cmd/print, labelinn/cmd/status, labelinn/cmd/cancel. Any other action is logged and ignored, with no reply. |
| Required fields | printerId (non-empty) and payloadType: zpl, escLabel, tpcl or design (the values the command bridge names in its error). A missing one returns {"success": false, "error": "printerId is required"}. |
| Types matter | copies must be a JSON number. "copies": "2" fails the cast and returns MQTT print failed: ... instead of printing. |
| Correlation | Pass jobId; if you omit it a UUID is generated. The answer's result carries the job id; there is no other correlation field. |
| Answer | Published on labelinn/cmd/response as {"requestTopic": "...", "action": "print", "result": { ... }}. status answers the same way with printers, printerCount and broker state. |
| Size | A message over 1 MiB is dropped silently. |
| Cancel | Not supported yet. labelinn/cmd/cancel is received and logged; it does not stop a job. |
| Events out | labelinn/print/job_completed, labelinn/print/job_failed, labelinn/printer/online, labelinn/printer/error, labelinn/verify/passed, labelinn/verify/failed. |
| Payloads | zpl takes the ZPL text in payloadData; escLabel and tpcl take base64 bytes; design takes designId and designDataRows. printPlan, serialStart and serialStep are also read. |
THE gRPC CONTRACT
Services and calls in the schema
| Service | Calls |
|---|---|
PrintService | SubmitJob, GetJobStatus, CancelJob, StreamEvents (stream), SubmitBatch |
PrinterFleetService | ListPrinters, GetPrinterHealth, DiscoverPrinters, StreamPrinterStatus (stream) |
VerifyService | VerifyScan, GetVerifyStatus, StreamVerifyEvents (stream) |
WorkflowService | TriggerWorkflow |
SystemService | HealthCheck, GetMetrics, Ping |
The default port is 6633 (HTTP is 6631, WebSocket 6632). Unlike MQTT, the gRPC schema declares CancelJob and SubmitBatch; check on your build that the call you need returns a result before you rely on it.
FIRST-LINE FAULTS
Nothing printed: where to look
- No answer at all: MQTT is off, the topic prefix differs from
labelinn, the JSON does not parse, the action is notprint/status/cancel, or the message is over 1 MiB. All of these are silent. - An answer with
success: false: readerror. MissingprinterId, a missingpayloadType, or a cast error from a number sent as text. - An answer with a job id but no label: the job is queued for a printer that is off or unreachable; see the printer's status or the
labelinn/printer/errorevent.
QUESTIONS / FAQ
Frequently asked questions
Can a PLC print a label with LabelInn?
Yes. Anything that publishes an MQTT message or makes a gRPC call can print: an MQTT-capable controller, SCADA, Node-RED, an MES or a protocol gateway in front of the PLC.
Which MQTT brokers does LabelInn work with?
Standard MQTT brokers such as Mosquitto, EMQX and HiveMQ, with TLS, username and password, and QoS 0 to 2. LabelInn can also run its own built-in broker.
How does the line know the label printed?
Each MQTT command is answered on labelinn/cmd/response with the job result. Over gRPC, SubmitJob returns the result directly and GetJobStatus reads it back by job id.
Can I send raw ZPL instead of a LabelInn design?
Yes. A print command can carry a saved design plus data, or raw ZPL, TPCL or ESC/Label.
How does my PLC match the response to its print command?
Send a jobId in the command. The reply on labelinn/cmd/response contains the job in result, so you can match on that id. Without your own jobId the app generates one and you can only match on arrival order.
Can I cancel a label over MQTT?
Not currently: the cancel topic is accepted and logged but does not stop the job. Over gRPC the schema has a CancelJob call.
Why does my command return "MQTT print failed"?
A field has the wrong JSON type, most often copies sent as text instead of a number.
KEEP GOING
Related
NEXT STEP / LABELINN
Let the line trigger its own labels
Run LabelInn next to your printers and connect it to the systems that already run the line. · MQTT commands and gRPC services · A result for every job · Native printer languages, no drivers