labelpi/docs/ANLEITUNG.en.md

LabelPi – User guide

1. Basics

Top bar: printer (only shown if several are connected) · roll · length (continuous rolls only) · rotated · copies · dithering · auto-cut (models with a cutter only) · cut mark · Print.

• The roll selected here must match the roll that is loaded. LabelPi asks if you change the roll compared with the last print.
• rotated: On continuous rolls the length is shown horizontally and the label is rotated by 90° when printing, so you read it like on screen.
• Dithering: Only useful for photos/greys. Keep it off for text, QR codes and barcodes.
• Cut mark (continuous rolls without a cutter): prints a dashed line at the end of the label so you cut in the right place by hand (e.g. QL-500).

Working in the designer

• View: By default only the most important functions are shown. Advanced view (bar at the top right) adds rotate, dithering, auto-cut, cut mark, series, grid and zoom. More elements (PDF, shapes, symbols) are in the ＋ More … menu, saving/export under File ▾.
• Add elements from the toolbar, tap = select, drag = move, bottom-right corner = resize.
• The properties are in the bar at the bottom, which always stays visible. It also has buttons to align the element to the label.
• Elements snap to the edge, centre and other elements while moving (pink guide lines).
• ↶ / ↷ undo and redo (last 25 steps).

2. Elements

Element	Notes
Text	Multi-line. Auto size fills the box with the largest possible font (set the box height).
Symbol	Warning, hazard, recycling signs etc. – they are text in a symbol font, so freely scalable.
QR code	Any text or link; placeholders allowed. The QR assistant builds Wi-Fi, vCard, email … for you.
Barcode	Choose a type (see below). With invalid content a red warning appears and nothing is printed.
Image	Photo/logo from your device. Switch dithering on for photos.
PDF	The page size selects the matching roll. Multi-page PDFs can be printed as a series (one page per label).
Shapes	Circle, line, arrow, triangle – filled or outline, rotatable in 45° steps (properties → Rotation).
Table	See section 3.

Barcode types

Type	Input
Code 128	Any characters
EAN-13	12 digits (check digit is added)
EAN-8	7 digits
Code 39	Capital letters, digits, - . $ / + % and space
GS1-128	With brackets, e.g. (01)09501101530003(17)271231(10)AB12
Data Matrix	Any text, square

3. Tables

• Tap a cell = select it (blue). Double-click or double-tap = type directly into the cell. Enter accepts, Tab jumps to the next cell, Esc cancels.
• In the properties: add/remove rows and columns, font, line width, first row bold.
• Table border: all lines · outside only · row lines · none.
• Border of a single cell: select the cell and tick top / bottom / left / right. This is in addition to the table border – with “none (cell borders only)” just the marked cells get lines (e.g. a single underline).
• Texts that are too long shrink automatically to fit the cell.
• You can also edit the content as text: one line per table row, columns separated by ;.

4. Placeholders

Placeholders work in text, QR codes, barcodes and table cells. The names are German; English short forms exist.

Placeholder	Meaning	Example
{n}	Counter within the series	1, 2, 3 …
{n:5}	Counter, 5 digits with leading zeros	00001
{gesamt} / {total}	Number of labels in the series	{n}/{gesamt} → 3/10
{lfd}, {lfd:5}	Running counter that remembers (stored on the Pi, survives restarts and device changes)	1001, 1002 …
{lfd.invoice}	Named counter, as many as you like	independent of {lfd}
{datum} / {date}	Today's date	24.10.2026
{datum:JJJJ-MM-TT}	Date with a custom format (JJJJ/YYYY, JJ/YY, MM, TT/DD)	2026-10-24
{datum+30}	Date plus 30 days (also -7; units d days, w weeks, m months, j/y years)	23.11.2026 · {datum+6m:MM/JJJJ} → 04/2027
{zeit}, {zeit:HH:MM:SS}	Time	14:35
{jahr} {monat} {tag}	Single date parts (also with offset, e.g. {jahr+1j})	2026 · 10 · 24
{kw} / {cw}	ISO calendar week (e.g. {kw+2w} = week in two weeks)	43
{wochentag} {monatname}	Name in the interface language	Saturday
{zufall:8} / {random:8}	Random code (8 characters, without easily confused ones like 0/O and 1/I); every label of a series gets a different one	K7HT3QWZ
{uuid}	Random UUID	3f2a9c1e-…
{ColumnName}	Value from the CSV column (CSV series only)	{Name}

English short forms: {date} {time} {year} {month} {day} {weekday} {cw} {random} {total} {seq}.

Filters (append with |, combinable): {Name|gross} UPPERCASE · {Name|klein} lowercase · {Name|titel} Title Case (English: |upper |lower |title) · {n:8|luhn} appends a Luhn check digit · {n:12|gtin} appends the EAN/GTIN check digit.

Notes

• Date and time come from the device you print from. Unknown placeholders are left unchanged.
• {lfd} reserves the numbers when printing. If printing fails the counter is reset (no gaps). You see the next value in the preview and under Settings → Counter, where you can also change it.
• Examples: SN-{jahr}-{lfd:4} → SN-2026-0001 · Best before {datum+30} · CW {kw}/{jahr} · {n:11|gtin} as EAN content.

5. Series (“Series…”)

• Counter: set start, step and count. Example: start 100, step 5, count 10 → 100, 105, …, 145.
• CSV file: first row = column names, then one label per row. Separator ; or ,, UTF-8.

  Name;Item;Number
  Miller;Screw M4;1001
  Smith;Nut M4;1002
  

  Use {Name}, {Item}, {Number} in the designer.
• PDF pages: created when you import a multi-page PDF.
• Copies apply per label of the series. Printing happens in blocks; the history only shows the first label of the series.
• The preview first shows label 1; use ‹ › next to “Series…” to page through all labels.

6. Grid (“Grid…”)

Continuous rolls only. Several labels side by side and below each other on one strip:

1. Set the label width in mm (e.g. 28 mm on a 62 mm roll for two columns).
2. Set columns × rows and gap.
3. When printing, consecutive labels (copies or series) fill the grid. If the grid does not fit the roll an error appears.

7. Templates, history, export, backup

• Templates: save with “Save as template”, sort into folders, edit (name/folder) and export.
• History: every print and every “Save” ends up here. Print again, Edit, or use Select to delete/export several.
• Export/import: labels and templates as a JSON file, e.g. to share. ⬇ PNG/PDF exports the current label as an image or PDF.
• Backup: Settings → Save database stores everything (including printers and password), Restore backup puts it back.

8. Printers and security

• USB printers are detected automatically. Several identical models are told apart by their USB port.
• Network printers (LAN/Wi-Fi): Settings → Add network printer (name, IP, model).
• Password protection: Settings → Password protection. Without it anyone on the network can print – use it only in trusted networks.

9. Form mode, QR assistant

• Form mode: every template has an Form button. It shows only a small form with one field per custom placeholder (e.g. {Name}, {Room}), a preview and the number of copies – no designer. Ideal for colleagues who only need to print.
• QR assistant: select the QR code and click QR assistant… in the properties. Types: link, Wi-Fi access, contact (vCard), email, phone, SMS, location, free text. You fill in the fields and the content is built correctly. Placeholders are allowed here too.

9a. Keyboard shortcuts

Key	Action
Del	Delete the selected element
Ctrl+Z	Undo
Ctrl+Y or Ctrl+Shift+Z	Redo
Enter / Tab / Esc	In a table cell: accept / next cell / cancel

10. Common problems

Problem	Solution
Label cut off or misplaced	Is the roll in the app the same as the loaded one? Check “rotated”.
Barcode is not printed	Check the input (e.g. EAN-13 needs 12 digits).
Text looks different on paper	Dithering off; font not too small (below about 6 pt).
Page not reachable	Pi and device on the same network? Use the IP instead of labelpi.local.
More help	docs/INSTALL.md (installation, troubleshooting)

11. Languages

The interface is available in German and English. Choose the language in the bar at the top right; it is remembered per device (the browser language is used on first start).

Adding a new language

1. Settings → Languages → Download template for a new language (neue-sprache.json).
2. Open the file: the German text on the left must not be changed, enter your translation on the right. {} are placeholders for numbers/names and must stay in the same number and order. Empty entries are shown in German.
3. Set "_name" at the top to the name of the language, e.g. "Français".
4. Save the file as languagecode.json, e.g. fr.json.
5. Add language file (.json) – or put the file into the lang/ folder on the Pi. Custom files survive updates and take precedence over built-in ones.

Translating this guide (optional): put it into the lang/ folder (or docs/) as ANLEITUNG.fr.md – it is then shown under Help when that language is active. Without a translation the German guide is shown.

Placeholders such as {datum} keep their names; English short forms exist ({date} …). Dates, weekdays and month names appear in the selected language. If you would like to share your translation, the project welcomes a pull request.