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.

FREE PLAN · NO CREDIT CARD · WINDOWS / MAC / LINUX / WEB

THE PROBLEM

Desktop, tablet and phone syncing through the cloud to a label printer

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:

TopicPurpose
labelinn/cmd/printPrint a label or a batch
labelinn/cmd/statusList 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.

EXAMPLEJSON
{
  "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.

ServiceCalls
PrintServiceSubmitJob prints a design with data or raw ZPL/TPCL/ESC-Label and returns the result; GetJobStatus reads it back by job id
PrinterFleetServiceListPrinters returns every local printer and whether it is online
VerifyServiceVerifyScan checks a scanned barcode against what was printed
SystemServiceHealthCheck and Ping

03 / MES

Why this is easier than a print server

Typical approachLabelInn edge runtime
Windows print server and a driver per modelNative ZPL, TSPL, TPCL and ESC/Label, no driver
Fire-and-forget raw socket to port 9100A job id per command and a status you can query
Label layout hard-coded in PLC or MES logicDesigns 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.

EXAMPLESHELL
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
ItemBehaviour in the code
SwitchMQTT 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 inlabelinn/cmd/print, labelinn/cmd/status, labelinn/cmd/cancel. Any other action is logged and ignored, with no reply.
Required fieldsprinterId (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 mattercopies must be a JSON number. "copies": "2" fails the cast and returns MQTT print failed: ... instead of printing.
CorrelationPass jobId; if you omit it a UUID is generated. The answer's result carries the job id; there is no other correlation field.
AnswerPublished on labelinn/cmd/response as {"requestTopic": "...", "action": "print", "result": { ... }}. status answers the same way with printers, printerCount and broker state.
SizeA message over 1 MiB is dropped silently.
CancelNot supported yet. labelinn/cmd/cancel is received and logged; it does not stop a job.
Events outlabelinn/print/job_completed, labelinn/print/job_failed, labelinn/printer/online, labelinn/printer/error, labelinn/verify/passed, labelinn/verify/failed.
Payloadszpl 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

ServiceCalls
PrintServiceSubmitJob, GetJobStatus, CancelJob, StreamEvents (stream), SubmitBatch
PrinterFleetServiceListPrinters, GetPrinterHealth, DiscoverPrinters, StreamPrinterStatus (stream)
VerifyServiceVerifyScan, GetVerifyStatus, StreamVerifyEvents (stream)
WorkflowServiceTriggerWorkflow
SystemServiceHealthCheck, 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

  1. No answer at all: MQTT is off, the topic prefix differs from labelinn, the JSON does not parse, the action is not print/status/cancel, or the message is over 1 MiB. All of these are silent.
  2. An answer with success: false: read error. Missing printerId, a missing payloadType, or a cast error from a number sent as text.
  3. 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/error event.

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.

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

Start free →