Application Notes¶
This is a collection of application notes that describe how to solve common scenarios using different integration methods.
The intended audience are system integrators and developers familiar with programming and network communication. It is assumed that the JSON-RPC API documentation is well known, and that the Tutorial has been completed.
AN-Activate Profile¶
Profiles are used for storing named groups of Settings. When a profile is activated, all the settings in the profile are applied. This can be useful for adapting the system behavior for different product types.
The special variable __profile__ can be used to activate a profile from a job.
For a selected hardware input event, you can activate one of three profiles, named
profile1, profile2, or profile3.
See also
Activate profile from JSON-RPC: settings.profile.activate
Including the special variable __profile__ activates the specified profile.
^XA
^LH0,0
^LL200
^PW400
^FX{"_custom_job_id": "job_abc1", "__profile__": "profile1"}
^FO50,20
^FDTest with job variables^FS
^XZ
This example sets the job id to job_abc1 and activates the profile profile1.
See also
AN-Code Matching¶
Code Matching confirms that the correct label is applied on the correct product.
Include Code Matching Data in Job¶
The special variable _code_matching is used for specifying the data, and
optional match conditions within a job.
ZPL Example where two barcodes are expected to be read and matched exactly.
^XA
^BY10
^FO020,55^BIN,100,Y,N^FD12345^FS
^FO40,230^BQN,2,10^FDLA,1234567890123456789012345678901234567890^FS
^FX Exact Match Data for label verification ^FS
^FX{"_code_matching":{"expected":[["1234567890123456789012345678901234567890","12345"]]}}^FS
^XZ
See also
AN-Dynamic Variables¶
Dynamic variables are typically used in weight labelling where the same layout can be reused for many products, and only the weight varies.
This makes it possible for a host system to activate a layout, and a weigher can send the weight in a small JSON-RPC message for each weighed product.
Example request:
{
"jsonrpc": "2.0",
"id": 42,
"method": "jobs.put",
"params": {
"pages": [
{
"copies": 1,
"layout": {
"fields": [
{
"halign": "left",
"spans": [
{
"font": "Liberation Sans Bold 12",
"text": "{{ product_name }}",
"template": true
}
],
"type": "text",
"valign": "baseline",
"x": 20,
"y": 100,
"width": 1000,
"height": 500
},
{
"halign": "left",
"spans": [
{
"font": "Liberation Sans 10",
"text": "Weight: {{ \"%.3f kg\" | format( (weight_g | float)/1000) }}",
"template": true
}
],
"type": "text",
"valign": "baseline",
"x": 20,
"y": 150,
"width": 1000,
"height": 500
},
{
"type": "barcode",
"symbology": "CODE-128",
"gs1": true,
"x": 300,
"y": 200,
"height": 100,
"halign": "center",
"module_width": 5,
"message": "{{ '(3103)%06d' | format(weight_g | int) }}",
"human_readable": true,
"template": true
}
],
"height": 400,
"layout_version": "2.0",
"required_variables": ["weight_g"],
"width": 600
}
}
],
"product_count": -1,
"variables": {
"product_name": "ACME Products"
}
}
}
Note
The use of "required_variables" ensures that each product will only use those variables one
time only, and that a label cannot be printed before those variables are available.
The weigher can then send for each product:
{
"method": "variables.dynamic.put",
"params": {
"variables": {"weight_g": "1230"}
},
"jsonrpc": "2.0",
"id": 1
}
AN-Motorized Stand¶
Motorized Stands are often used in conjunction with pallet marking, or other applications where labels are applied on varying heights.
Include Stand Position In Job¶
The special variable __stand1-position-mm is used for setting the stand1 position from a job.
From JSON-RPC it is possible to control many aspects of the motorized stands.
- stand namespace - Full API documentation.
- Setting Position In Job - This example includes a stand position in the job metadata, so the system will move the printer to the specified position, before activating the job.
From Modbus TCP it is possible to:
- WR_STAND1_GOTO_MM - Go to a specified stand position.
- WR_STAND1_GOTO_STORED_POS - Go to a stored position.
ZPL example where the stand position is set to 800 mm:
^XA
^LH0,0
^LL200
^PW400
^FX{"_custom_job_id": "job_abc1", "__stand1-position_mm": 800}
^FO50,20
^FDTest at stand position 800^FS
^XZ
See also
AN-Partial Pallets¶
A Motorized Stand with a Partial Pallet Sensor allows applying labels on partially filled pallets at a fallback position.
Set Fallback Position¶
The special variable __partial_pallets-fallback_position_mm is used for setting the fallback position from a job.
Example request:
{
"method": "settings.set",
"params": {"setting": "partial_pallets-fallback_position_mm", "value": 250},
"jsonrpc": "2.0",
"id": 0
}
Expected response:
{"result": null, "id": 0, "jsonrpc": "2.0"}
Note that it is also possible to include the setting as a “special” job variable by prepending it with double underscores similar to Setting Position in Job
Example where fallback position is set to 250 mm.
^XA
^FX Set fallback position to 250 mm ^FS
^FX{"_custom_job_id": "job_ppfp", "__partial_pallets-fallback_position_mm": 250}
^LH0,0
^LL200
^PW400
^BY10
^FO020,55^BIN,100,Y,N^FD12345^FS
^FO40,230^BQN,2,10^FDLA,1234567890123456789012345678901234567890^FS
^XZ
See also
AN-UTF-8¶
The printer support UTF-8 characters encoding which can be used to print characters outside of the A-Z range. E.g. Chinese, Korean, Arabic and Western non A-Z (e.g. ÅÄÖÜ߀). The font used must contain the requested characters.
Example request:
{
"method": "jobs.put",
"params": {
"pages": [
{
"layout": {
"fields": [
{
"y": 50,
"x": 100,
"type": "text",
"spans": [
{
"text": "Korean: 서울",
"font": "FreeSans 10"
}
]
}
],
"layout_version": "2.0",
"required_variables": [],
"width": 500,
"height": 200
},
"copies": 1
}
],
"variables": {"_custom_job_id": "my-print-job"}
},
"id": 0,
"jsonrpc": "2.0"
}
Expected response:
{"jsonrpc": "2.0", "id": 0, "result": {"replace_current": false, "usage_count": 0, "product_matching": false, "variables": {"_custom_job_id": "my-print-job"}, "required_variables": [], "pages": [{"layout": {"required_variables": [], "layout_version": "2.0", "width": 500, "height": 200, "fields": [{"y": 50, "spans": [{"font": "FreeSans 10", "text": "Korean: \uc11c\uc6b8"}], "x": 100, "type": "text"}]}, "copies": 1}], "reprintable": true, "product_count": -1, "created": "2022-12-28T16:16:52.329802+01:00", "extendable": false}}
Use the ZPL ^CI28 (Change International Font/Encoding) command to select UTF-8 encoding.
^XA
^LH0,0
^LL200
^PW400
^CI28
^FO10,10
^A@N,24,24
^FDKorean: 서울^FS
^XZ