Thermal Notes

The open-source, browser-only visual editor for 58 mm thermal receipt & pocket printers.

---

Overview

Thermal Notes is a lightweight, zero-install web application designed specifically for composing, styling, and printing notes, receipts, to-do lists, and graphics on 58 mm (2-inch) thermal printers.

Everything happens directly inside your browser. There are no accounts, no cloud print servers, no API keys, and no telemetry. When you click Print, Thermal Notes sends pixel-accurate, formatted output directly to your operating system's native print dialog for seamless USB, Bluetooth, Wi-Fi, or AirPrint output.

---

✨ Features

• Live 384-dot Thermal Preview: Calibrated for standard 203 DPI / 58 mm paper rolls (approx. 48 mm printable width).
• Rich Typography: 5 distinct font sizes (XS, S, M, L, XL), bold, italic, underline, inverted styles, and left/center/right alignment.
• Emoji & Multi-language Unicode: Native support using your device's built-in fonts and symbols.
• B&W Image Dithering: Import any image or photo with instant client-side thresholding and Floyd-Steinberg dithering for sharp thermal printing.
• Instant QR Code Generator: Generate crisp, scannable QR codes for URLs, Wi-Fi passwords, crypto addresses, or vouchers.
• Freehand Canvas Drawing: Sketch doodles, signatures, or diagrams with 5 pen widths and an eraser.
• Dynamic Grids & Tables: Create structured checklists, order summaries, price lists, or forms.
• Local Storage File Manager: Save, load, and manage named documents locally on your device.
• Auto-save & Recovery: Protects against accidental tab closures or lost drafts.
• Mobile & Desktop Optimized: Responsive layout with dark and light themes.
• Zero Build Step: 100% static HTML, CSS, and vanilla JavaScript in a single self-contained project.

---

💡 Popular Use Cases

Category	Examples
🛒 Retail & Pop-up Shops	Quick sales slips, order receipts, return tags, custom discount vouchers.
📋 Productivity & Tasks	Daily to-do lists, grocery shopping checklists, Pomodoro logs, scratchpad notes.
🎨 Creative & Journaling	Retro mini-photos, pixel art, scrapbooking stickers, motivational quotes.
📶 Tech & Hospitality	Guest Wi-Fi access tags with QR codes, table reservation slips, lab sample labels.

---

🖨️ Printer & Hardware Compatibility

Thermal Notes works with any thermal printer recognized by your operating system, including:

• Standard 58 mm POS Printers: POS-58, ZJ-58, 5890, EPSON TM-T20 / TM-m30 (configured for 58mm), Star Micronics, Citizen.
• Commercial Desktop Thermal Printers: Munbyn, Xprinter (XP-58 series), Netum, Rongta, Hoin.
• Portable Bluetooth Receipt Printers: Goojprt PT-210, MPT-II, PeriPage, Phomemo, Paperang, Cat printers (via Android/Windows print drivers or RawBT).
• Network / AirPrint Thermal Printers: Any Wi-Fi or Ethernet thermal printer with IPP/AirPrint support.

---

⚙️ Golden Print Settings (Cheat Sheet)

For crisp, edge-to-edge prints without wasted paper, configure your browser print dialog as follows:

Print Setting	Recommended Value	Reason
Destination	Select your 58 mm printer	Uses OS-level print engine
Paper Size	58mm Roll or 58mm x Continuous	Matches actual thermal roll width
Scale	100% (or Actual Size)	Prevents blurriness or unintended shrinking
Margins	None (or Minimum / 0 mm)	Prevents browser margin offsets
Headers & Footers	OFF (Unchecked)	Crucial: Prevents printing URLs and timestamps
Background Graphics	ON (Checked)	Ensures inverted blocks and shades print accurately

💡 Tip: Once you set these once in Chrome, Edge, or Safari, the browser usually remembers them for subsequent prints.

---

🔌 Connection & Setup Guide

🪟 Windows (USB / Bluetooth / Network)

1. Install the manufacturer driver (or generic POS-58 / ZJ-58 driver).
2. Open Windows Settings → Bluetooth & devices → Printers & scanners.
3. Select your printer → Printing preferences.
4. Set the default paper size to 58mm * 210mm (or 58mm Roll).
5. In your browser, press Print in Thermal Notes and select your printer.

🍎 macOS (USB / Network / AirPrint)

1. Connect the printer and open System Settings → Printers & Scanners.
2. Add the printer using its driver or Generic PostScript/ESC-POS driver.
3. In the print dialog, create a Custom Paper Size: 58 mm width with 0 mm margins.

🐧 Linux (CUPS)

1. Open the CUPS web interface (http://localhost:631) or system printer settings.
2. Add the printer using the raw ESC/POS driver or manufacturer PPD.
3. Set the default media size to 58 mm roll.

🤖 Android (Bluetooth / USB / Wi-Fi)

1. Pair your printer via Bluetooth or connect via USB OTG.
2. Install the printer's companion print service plugin or a universal print service app (such as RawBT Print Service or ESC POS Bluetooth Print Service).
3. In Thermal Notes, tap Print, choose the print service from Android's share/print sheet, and tap Print.

📱 iPhone & iPad (iOS / AirPrint)

1. Ensure your thermal printer is AirPrint-enabled or shared via an AirPrint bridge on your local Wi-Fi network.
2. Tap Print in Safari, select the printer, and print directly.

---

🔒 Privacy by Design

Thermal Notes takes privacy seriously:

• 100% Client-Side: Everything runs strictly in your browser's local sandbox.
• Zero Analytics / Telemetry: No tracking pixels, Google Analytics, cookies, or remote logging.
• No Cloud Servers: Your notes and images are never uploaded to any remote server or third party.
• Local Storage Only: Saved notes stay on your local device's localStorage and can be wiped anytime by clearing site data.

---

🚀 Quick Start

Option 1: Use Hosted Web App (No Install)

🚀 Open the Live App: https://mjsasky.github.io/thermal-notes/

Write your note, customize styles or QR codes, and click Print.

Option 2: Run Locally (Zero Setup)

Clone the repository and open index.html in any web browser:

git clone https://github.com/MjSasky/thermal-notes.git
cd thermal-notes

Or start a local lightweight web server:

# Python 3
python -m http.server 8080

# Node.js
npx serve .

Then navigate to http://localhost:8080.

---

📂 Project Structure

thermal-notes/
├── index.html             # Complete standalone app, styles, editor & QR engine
├── assets/
│   ├── saskyco-logo.svg       # Brand header logo (light mode)
│   ├── saskyco-logo-dark.svg  # Brand header logo (dark mode)
│   └── saskyco-icon.svg       # Brand mark / icon
├── favicon.ico            # Favicon
├── favicon-180.png        # Apple touch icon
├── README.md              # Documentation and printer guide
├── LICENSE                # MIT License
├── SECURITY.md            # Security disclosure policy
├── CONTRIBUTING.md        # Contribution guidelines
├── THIRD_PARTY_NOTICES.md # Open-source licenses (QR generator)
└── .gitignore             # Git ignore patterns

---

🤝 Contributing

Contributions, bug reports, and hardware profile documentation are warmly welcome! Please check out CONTRIBUTING.md before submitting a pull request.

---

📄 License & Attribution

Thermal Notes is open-source software licensed under the MIT License.

Developed with ❤️ by SaskyCo.