BlueGit

timfa posprint

Files

posprint / docs / HELP.md

HELP.md

feat: include paired Classic Bluetooth SPP printers in discovery
timfa project_84475926_bot_3b4fb417c41b9b24a7422b6452f025d2 · pushed by timfa · 8 weeks ago
8b514b7f History
HELP.md 9.2 KiB Download Raw

posprint Help

Built-in reference for the template editor and POS markup language.

---

Application tabs

TabPurpose
DesignSide-by-side template editor and live preview
HelpThis documentation
SettingsDefault page width for new documents

Toolbar actions

ActionDescription
NewEmpty template with defaults
OpenLoad a .pos file
Save / Save AsWrite .pos file (metadata + body)
InsertImages, barcodes, QR, date/time, parameters, @feed, @cut
PrintEnter parameters, pick a printer, send ESC/POS bytes

While the Print dialog is open, the rest of the UI (including editor autocomplete) is disabled so parameter fields keep focus.

Print-only mode (posprint --print, Explorer Print, or a posprint:// link) shows a live preview on the left and parameters / printer controls on the right. The preview updates as you type parameter values.

Editor assistance

  • Type @ at the start of a line for directive autocomplete (feed, cut, image, barcode, qr, date, time).
  • Use Insert → Barcode / QR code to pick native or raster type before inserting a snippet.

Page settings

SettingDescription
Page width (mm)Paper width — match your physical roll (e.g. 53, 58, 80)
Preview zoomScreen zoom; 100% is calibrated to typical receipt width on screen

Preview width and text use the same calibrated screen scale. Preview font size is bumped to match printed Font A. Blank lines / @feed use the same line spacing as printed text. Heading # uses double width/height like GS ! on the printer; ## uses bold only.

If the document does not end with @cut (ignoring blank lines after it), a red warning appears next to Help.

---

Template language

A template is plain text: paragraphs, headings, lists, checkboxes, ${text} / $[bool] parameters, and directives. There is no inline bold/italic/code markup — asterisks and backticks print literally.

Paragraphs

Consecutive non-empty lines form one paragraph. Multiple spaces in a row are kept (useful for manual column layout), including spaces at the start of a line. Trailing spaces on a line are ignored.

Headings

# Large heading
## Bold heading

Alignment

:left:, :center:, or :right: before a paragraph.

On one line, you can combine markers (e.g. :left: Appel:right: 10). That prints as one row with spaces so the right text sits at the end of the paper width. Writing :right:10:left:Appel is treated the same (left then right). If both sides are too long for the line, they print on separate lines instead.

Bullet lists

- Groceries
  - Milk
  - Eggs
- Wash car

Indent with two spaces (or a tab) per nesting level. Top-level items print as * ; nested items print as - with the same hanging wrap.

* Groceries
  - Milk
  - Eggs
* Wash car

Long items wrap with a hanging indent:

* this is a
  long line
  - nested item that
    wraps too

Parameters

SyntaxEffect
${Name}Text parameter (filled at print time)
$[Name]Checkbox parameter → [ ] or [x]

${Name} and $[Name] must not share the same name.

Checkboxes

Inline checkboxes print as ASCII so they stay in the printer’s CP437 font (Unicode ☐ / √ often become CJK garbage):

SyntaxResult
[] or [ ][ ]
[x] or [X][x]
[] Unchecked
[ ] Also unchecked
[x] Done
$[Paid]

$[Paid] is a parameter: in the Print dialog it is a true/false checkbox; on the receipt it becomes [ ] or [x]. CLI: --set Paid=true.

Horizontal rule

---

Comments

<!-- not printed -->

---

Directives

Directives start with @ at the beginning of a line.

Paper feed / cut

@feed 3
@cut

Blank lines in the editor also feed one line (same as @feed 1).

Date / time

@date
@date DD-MM-YYYY
@time
@time 12h
@time 24h
  • @date with no pattern uses the system regional short date.
  • Custom patterns use tokens such as YYYY, MM, DD.
  • @time defaults to 24-hour; use 12h or 24h.

Image

@image logo.png
@image https://example.com/logo.png width=50%
@image ${LogoPath} width=50% align=center

Local paths resolve relative to the .pos file. http:// and https:// URLs are downloaded when preview or print needs the image (TLS certificate errors are ignored so corporate/self-signed hosts still work).

Barcode

Native (printer draws barcode via ESC/POS):

@barcode CODE128 ${OrderId}
@barcode UPC-A 012345678905
@barcode ITF 12345678 height=80
@barcode CODE128 hallo wereld
@barcode CODE128 ABC show_text=true

Raster (bitmap). Raster barcodes stretch horizontally to full paper width; height follows height.

@barcode RASTER CODE128 ${OrderId}
@barcode RASTER CODE128 hallo wereld
@barcode RASTER CODE93 ABC-1234
Native symbologyNotes
CODE128Alphanumeric
EAN13, EAN8Numeric
CODE39Alphanumeric
UPC-A, UPC-ENumeric
ITFInterleaved 2 of 5; even digit count
CODABARNumeric + A-D start/stop
Raster-onlyUse RASTER prefix
CODE93, CODE11No native ESC/POS in firmware
AttributeDescription
heightHeight in dots (default 64)
alignleft, center, right
show_textNative only: human-readable text under barcode (default off; show_text=true to enable)

Data may contain spaces; tokens after the symbology are joined until the first attribute token (size=…, align=…, etc.). A URL with a query string (https://…?a=1) is still data.

QR code

Native (ESC/POS QR, model 2):

@qr https://example.com/${Id}
@qr ${Url} size=6 ecc=H align=center
@qr hallo wereld size=4

Raster (bitmap; QR versions 1–40):

@qr RASTER https://example.com/${Id}
@qr RASTER ${Url} version=5 scale=4 ecc=M
AttributeNativeRaster
sizeModule dot size 1–16—
scale—Pixels per module (default 4)
version—QR version 1–40 (optional)
eccL, M, Q, HSame
alignleft, center, rightSame

---

Parameters

FormTypePrint dialogCLI
${Name}texttext field--set Name=Value
$[Name]boolcheckbox--set Name=true / false (also 1/0, yes/no)
  • Same name must not appear as both ${…} and $[…].
  • GUI and CLI require every parameter; bools default to unchecked (false) in the dialog.
  • Usable in text; ${…} also in barcode/QR/image paths ($[…] is text-inline only).
# ${StoreName}

$[Paid] Paid in full
[] Pending review

Receipt: ${DocumentNumber}

---

Example receipt

# ${StoreName}
:center:

Receipt: ${DocumentNumber}
@date
@time

@barcode CODE128 ${DocumentNumber}
@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4

@feed 4
@cut

---

GUI printing

1. Print → enter parameters → choose a printer → Print (next to Refresh). Close with the window ✕.

Printers may appear as:

  • USB printer-class devices (direct bulk OUT)
  • Windows spooler queues (Windows)
  • USB-serial ports with a device attached (COMx, /dev/ttyUSB0, /dev/ttyACM0, …)
  • Classic Bluetooth SPP after you pair the printer in the OS (COMx on Windows, often /dev/rfcomm0 on Linux). Listed with a Bluetooth label.

Empty motherboard serial ports (common on Linux as /dev/ttyS*) are hidden. Use Enter port or queue manually if you need one of those.

Bluetooth Low Energy (BLE) printers are not supported. Pair Classic Bluetooth SPP in Windows or your Linux Bluetooth settings first; Posprint does not pair devices itself.

Linux serial / RFCOMM: join the dialout group.

---

CLI

posprint print receipt.pos -p COM3 --set StoreName=Shop
posprint link receipt.pos
posprint cli-help

posprint list prints discovered printers. -p accepts a serial port name (including a paired Bluetooth COM/rfcomm node), USB device label from discovery, or (on Windows) a spooler queue name. See platform CLI help via posprint cli-help.

posprint link prints a posprint:// deep link for the file (see POSPRINT-URL.md).

---

posprint:// links

Websites can open the print dialog with an embedded template:

posprint://print?v=1&d=…

Add &noconfirm=1 to auto-print once a printer is ready (the browser’s protocol prompt is the consent step). Auto-print uses the last printer that printed successfully when that device is still available. Encoding helpers live in lib/. Full guide: POSPRINT-URL.md.

@image may use https://… or http://… (downloaded when preview/print needs the image).

---

.pos file format

JSON with version, metadata, and body (template source). See FILE-FORMAT.md.

Source
1# posprint Help
2
3Built-in reference for the template editor and POS markup language.
4
5---
6
7## Application tabs
8
9| Tab | Purpose |
10|-----|---------|
11| **Design** | Side-by-side template editor and live preview |
12| **Help** | This documentation |
13| **Settings** | Default page width for new documents |
14
15## Toolbar actions
16
17| Action | Description |
18|--------|-------------|
19| **New** | Empty template with defaults |
20| **Open** | Load a `.pos` file |
21| **Save / Save As** | Write `.pos` file (metadata + body) |
22| **Insert** | Images, barcodes, QR, date/time, parameters, `@feed`, `@cut` |
23| **Print** | Enter parameters, pick a printer, send ESC/POS bytes |
24
25While the Print dialog is open, the rest of the UI (including editor autocomplete) is disabled so parameter fields keep focus.
26
27**Print-only mode** (`posprint --print`, Explorer Print, or a `posprint://` link) shows a live preview on the left and parameters / printer controls on the right. The preview updates as you type parameter values.
28
29## Editor assistance
30
31- Type `@` at the start of a line for **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`, `date`, `time`).
32- Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet.
33
34## Page settings
35
36| Setting | Description |
37|---------|-------------|
38| **Page width (mm)** | Paper width — match your physical roll (e.g. `53`, `58`, `80`) |
39| **Preview zoom** | Screen zoom; `100%` is calibrated to typical receipt width on screen |
40
41Preview width and text use the same calibrated screen scale. Preview font size is bumped to match printed Font A. Blank lines / `@feed` use the same line spacing as printed text. Heading `#` uses double width/height like GS `!` on the printer; `##` uses bold only.
42
43If the document does not end with `@cut` (ignoring blank lines after it), a red warning appears next to **Help**.
44
45---
46
47## Template language
48
49A template is plain text: paragraphs, headings, lists, checkboxes, `${text}` / `$[bool]` parameters, and directives. There is **no** inline bold/italic/code markup — asterisks and backticks print literally.
50
51### Paragraphs
52
53Consecutive non-empty lines form one paragraph. Multiple spaces in a row are kept (useful for manual column layout), including spaces at the start of a line. Trailing spaces on a line are ignored.
54
55### Headings
56
57```markdown
58# Large heading
59## Bold heading
60```
61
62### Alignment
63
64`:left:`, `:center:`, or `:right:` before a paragraph.
65
66On **one line**, you can combine markers (e.g. `:left: Appel:right: 10`). That prints as one row with spaces so the right text sits at the end of the paper width. Writing `:right:10:left:Appel` is treated the same (left then right). If both sides are too long for the line, they print on separate lines instead.
67
68### Bullet lists
69
70```markdown
71- Groceries
72 - Milk
73 - Eggs
74- Wash car
75```
76
77Indent with two spaces (or a tab) per nesting level. Top-level items print as `* `; nested items print as `- ` with the same hanging wrap.
78
79```text
80* Groceries
81 - Milk
82 - Eggs
83* Wash car
84```
85
86Long items wrap with a hanging indent:
87
88```text
89* this is a
90 long line
91 - nested item that
92 wraps too
93```
94
95### Parameters
96
97| Syntax | Effect |
98|--------|--------|
99| `${Name}` | Text parameter (filled at print time) |
100| `$[Name]` | Checkbox parameter → `[ ]` or `[x]` |
101
102`${Name}` and `$[Name]` must not share the same name.
103
104### Checkboxes
105
106Inline checkboxes print as ASCII so they stay in the printer’s CP437 font (Unicode ☐ / √ often become CJK garbage):
107
108| Syntax | Result |
109|--------|--------|
110| `[]` or `[ ]` | `[ ]` |
111| `[x]` or `[X]` | `[x]` |
112
113```markdown
114[] Unchecked
115[ ] Also unchecked
116[x] Done
117$[Paid]
118```
119
120`$[Paid]` is a **parameter**: in the Print dialog it is a true/false checkbox; on the receipt it becomes `[ ]` or `[x]`. CLI: `--set Paid=true`.
121
122### Horizontal rule
123
124```markdown
125---
126```
127
128### Comments
129
130```markdown
131<!-- not printed -->
132```
133
134---
135
136## Directives
137
138Directives start with `@` at the beginning of a line.
139
140### Paper feed / cut
141
142```markdown
143@feed 3
144@cut
145```
146
147Blank lines in the editor also feed one line (same as `@feed 1`).
148
149### Date / time
150
151```markdown
152@date
153@date DD-MM-YYYY
154@time
155@time 12h
156@time 24h
157```
158
159- `@date` with no pattern uses the system regional short date.
160- Custom patterns use tokens such as `YYYY`, `MM`, `DD`.
161- `@time` defaults to 24-hour; use `12h` or `24h`.
162
163### Image
164
165```markdown
166@image logo.png
167@image https://example.com/logo.png width=50%
168@image ${LogoPath} width=50% align=center
169```
170
171Local paths resolve relative to the `.pos` file. `http://` and `https://` URLs are downloaded when preview or print needs the image (TLS certificate errors are ignored so corporate/self-signed hosts still work).
172
173### Barcode
174
175**Native** (printer draws barcode via ESC/POS):
176
177```markdown
178@barcode CODE128 ${OrderId}
179@barcode UPC-A 012345678905
180@barcode ITF 12345678 height=80
181@barcode CODE128 hallo wereld
182@barcode CODE128 ABC show_text=true
183```
184
185**Raster** (bitmap). Raster barcodes stretch horizontally to full paper width; height follows `height`.
186
187```markdown
188@barcode RASTER CODE128 ${OrderId}
189@barcode RASTER CODE128 hallo wereld
190@barcode RASTER CODE93 ABC-1234
191```
192
193| Native symbology | Notes |
194|----------------|-------|
195| `CODE128` | Alphanumeric |
196| `EAN13`, `EAN8` | Numeric |
197| `CODE39` | Alphanumeric |
198| `UPC-A`, `UPC-E` | Numeric |
199| `ITF` | Interleaved 2 of 5; even digit count |
200| `CODABAR` | Numeric + A-D start/stop |
201
202| Raster-only | Use `RASTER` prefix |
203|-------------|---------------------|
204| `CODE93`, `CODE11` | No native ESC/POS in firmware |
205
206| Attribute | Description |
207|-----------|-------------|
208| `height` | Height in dots (default `64`) |
209| `align` | `left`, `center`, `right` |
210| `show_text` | Native only: human-readable text under barcode (default off; `show_text=true` to enable) |
211
212Data may contain spaces; tokens after the symbology are joined until the first attribute token (`size=…`, `align=…`, etc.). A URL with a query string (`https://…?a=1`) is still data.
213
214### QR code
215
216**Native** (ESC/POS QR, model 2):
217
218```markdown
219@qr https://example.com/${Id}
220@qr ${Url} size=6 ecc=H align=center
221@qr hallo wereld size=4
222```
223
224**Raster** (bitmap; QR versions 1–40):
225
226```markdown
227@qr RASTER https://example.com/${Id}
228@qr RASTER ${Url} version=5 scale=4 ecc=M
229```
230
231| Attribute | Native | Raster |
232|-----------|--------|--------|
233| `size` | Module dot size 1–16 | — |
234| `scale` | — | Pixels per module (default `4`) |
235| `version` | — | QR version 1–40 (optional) |
236| `ecc` | `L`, `M`, `Q`, `H` | Same |
237| `align` | `left`, `center`, `right` | Same |
238
239---
240
241## Parameters
242
243| Form | Type | Print dialog | CLI |
244|------|------|--------------|-----|
245| `${Name}` | text | text field | `--set Name=Value` |
246| `$[Name]` | bool | checkbox | `--set Name=true` / `false` (also `1`/`0`, `yes`/`no`) |
247
248- Same name must not appear as both `${…}` and `$[…]`.
249- GUI and CLI require **every** parameter; bools default to unchecked (`false`) in the dialog.
250- Usable in text; `${…}` also in barcode/QR/image paths (`$[…]` is text-inline only).
251
252```markdown
253# ${StoreName}
254
255$[Paid] Paid in full
256[] Pending review
257
258Receipt: ${DocumentNumber}
259```
260
261---
262
263## Example receipt
264
265```markdown
266# ${StoreName}
267:center:
268
269Receipt: ${DocumentNumber}
270@date
271@time
272
273@barcode CODE128 ${DocumentNumber}
274@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
275
276@feed 4
277@cut
278```
279
280---
281
282## GUI printing
283
2841. **Print** → enter parameters → choose a printer → **Print** (next to Refresh). Close with the window ✕.
285
286Printers may appear as:
287
288- **USB printer-class** devices (direct bulk OUT)
289- **Windows spooler** queues (Windows)
290- **USB-serial** ports with a device attached (`COMx`, `/dev/ttyUSB0`, `/dev/ttyACM0`, …)
291- **Classic Bluetooth SPP** after you pair the printer in the OS (`COMx` on Windows, often `/dev/rfcomm0` on Linux). Listed with a **Bluetooth** label.
292
293Empty motherboard serial ports (common on Linux as `/dev/ttyS*`) are hidden. Use **Enter port or queue manually** if you need one of those.
294
295Bluetooth Low Energy (BLE) printers are not supported. Pair Classic Bluetooth SPP in Windows or your Linux Bluetooth settings first; Posprint does not pair devices itself.
296
297**Linux serial / RFCOMM:** join the `dialout` group.
298
299---
300
301## CLI
302
303```bash
304posprint print receipt.pos -p COM3 --set StoreName=Shop
305posprint link receipt.pos
306posprint cli-help
307```
308
309`posprint list` prints discovered printers. `-p` accepts a serial port name (including a paired Bluetooth COM/`rfcomm` node), USB device label from discovery, or (on Windows) a spooler queue name. See platform CLI help via `posprint cli-help`.
310
311`posprint link` prints a `posprint://` deep link for the file (see [POSPRINT-URL.md](POSPRINT-URL.md)).
312
313---
314
315## posprint:// links
316
317Websites can open the print dialog with an embedded template:
318
319```
320posprint://print?v=1&d=…
321```
322
323Add `&noconfirm=1` to auto-print once a printer is ready (the browser’s protocol prompt is the consent step). Auto-print uses the last printer that printed successfully when that device is still available. Encoding helpers live in [`lib/`](../lib/). Full guide: [POSPRINT-URL.md](POSPRINT-URL.md).
324
325`@image` may use `https://…` or `http://…` (downloaded when preview/print needs the image).
326
327---
328
329## `.pos` file format
330
331JSON with `version`, `metadata`, and `body` (template source). See [FILE-FORMAT.md](FILE-FORMAT.md).