# Printer Settings

<p class="doc-lead">Connect a Bluetooth thermal printer from the Field Sale App to print invoices, receipt vouchers, day reports, and customer statements in the field.</p>

<div class="doc-toc">
<p class="doc-toc-title">On this page</p>
<div class="doc-toc-section">
<span class="doc-toc-group-title">Setup</span>
<div class="doc-toc-links">
<a href="#/field-sale-app/printer-settings?id=open-settings">Open Printer Settings</a>
<a href="#/field-sale-app/printer-settings?id=pairing">Pairing the printer</a>
<a href="#/field-sale-app/printer-settings?id=connect">Connect a device</a>
</div>
</div>
<div class="doc-toc-section">
<span class="doc-toc-group-title">Configuration</span>
<div class="doc-toc-links">
<a href="#/field-sale-app/printer-settings?id=paper-width">Paper width</a>
<a href="#/field-sale-app/printer-settings?id=test-print">Test print</a>
<a href="#/field-sale-app/printer-settings?id=permissions">Permissions</a>
</div>
</div>
</div>

<hr class="doc-section-divider">

<h2 id="open-settings">Open Printer Settings</h2>

Open **Printer Settings** from:

- Left drawer menu (hamburger icon → **Printer Settings**), or
- **More** tab → **Printer Settings**

<hr class="doc-section-divider">

<h2 id="pairing">Pairing the printer</h2>

Before connecting in the app, pair the thermal printer with the phone:

**Android**

1. Turn on the printer and enable Bluetooth on the phone.
2. Open phone **Settings → Bluetooth** and pair the printer.
3. Return to the Field Sale App **Printer Settings** screen.
4. Tap **Refresh** to list paired devices.

**iOS**

1. Turn on the printer.
2. Pair the printer in **iPhone Settings → Bluetooth** first.
3. In the app, tap **Refresh** to list paired, connected, and previously used printers.
4. If the printer is not listed, tap **Search nearby** (scans for about 5 seconds).

<hr class="doc-section-divider">

<h2 id="connect">Connect a device</h2>

The **Printer Settings** screen has three sections:

<h3>Connected Device</h3>

Shows the currently connected printer name and Bluetooth address. Displays *No device connected* when none is paired.

<h3>Available Bluetooth Devices</h3>

Lists discovered printers. Tap **Connect** next to a device to set it as the active printer. The connected device is marked *(connected)*.

- **Refresh** — reload paired devices (Android and iOS).
- **Search nearby** — iOS only; scans for nearby BLE printers when the paired list is empty.

<h3>Printer Settings</h3>

Set **Paper Width** before printing. The selection is saved on the device and applies to all subsequent prints.

<hr class="doc-section-divider">

<h2 id="paper-width">Paper width</h2>

Select the width that matches your thermal printer roll:

| Option in app | Line width (characters) | Typical use |
|---------------|---------------------------|-------------|
| **2 inches (24chars)** | 23 characters | Compact 2-inch printers with narrow font |
| **2 inches** | 32 characters | Standard 2-inch (58 mm) printers |
| **3 inches** | 48 characters | Standard 3-inch (80 mm) printers — default |
| **4 inches** | 69 characters | Wide 4-inch (112 mm) printers with barcode column |

After changing paper width, the app shows a confirmation: *Paper width changed to [value]*.

Paper width affects column layout on all print types. See [Print Formats](field-sale-app/print-formats.md) for field layout per width and format.

**Retail** invoice print format is supported on **3-inch** printers only. **Regular** format works on 2, 3, and 4-inch widths.

<hr class="doc-section-divider">

<h2 id="test-print">Test print</h2>

After connecting a printer:

| Button | Action |
|--------|--------|
| **Test Print** | Prints a simple text line (*Print test 1*) to verify connectivity |
| **Test Print Logo** | Prints the configured header image (if set in Field Sale App Settings) |

Use test print to confirm Bluetooth connection and paper width before printing live documents.

<hr class="doc-section-divider">

<h2 id="permissions">Permissions</h2>

The app requests permissions needed for Bluetooth printing:

**Android**

- **Bluetooth Scan** and **Bluetooth Connect** (Android 12+)
- **Location** (Android 9–11) — required by the OS for Bluetooth scanning
- Location services must be enabled for device discovery on Android 9+

**iOS**

- **Bluetooth** permission when first connecting to a printer

If permissions are denied, the app shows an error and printing is blocked until permissions are granted in phone settings.

<hr class="doc-section-divider">

<h2 id="printing-documents">Printing documents</h2>

After setup, print from transaction and report view screens:

| Document | Print button location |
|----------|----------------------|
| Sale Invoice | Draft/Pre-approved actions or footer **Print** on Approved/Closed |
| Credit Note | Draft actions or footer **Print** |
| Sale Order | Draft actions or footer **Print** |
| Sale Quotation | Draft actions or footer **Print** |
| Receipt Voucher | Draft actions or footer **Print** |
| Day Report | Footer **Print** |
| Customer Statement | Print action on report screen |

Print uses the connected printer and saved paper width. Header/footer images from web settings are included when configured.

See [Print Formats](field-sale-app/print-formats.md) for layout details.

<hr class="doc-section-divider">

<h2 id="troubleshooting">Troubleshooting</h2>

| Issue | What to try |
|-------|-------------|
| *Printer not connected* | Open Printer Settings, tap **Refresh**, tap **Connect** |
| *Bluetooth is turned off* | Enable Bluetooth on the phone |
| *Printer is not reachable* | Turn printer off and on; move closer; reconnect |
| *No devices found* | Pair printer in phone Bluetooth settings first, then **Refresh** |
| Print in progress | Wait for the current job to finish before printing again |

<hr class="doc-section-divider">

<h2 id="faq">FAQ</h2>

<p><b>Why does the app say printer not connected?</b><br>
Open Printer Settings, tap Refresh, then Connect on your paired Bluetooth printer. Ensure Bluetooth is enabled on the phone.</p>

<p><b>Do I configure paper width on web or app?</b><br>
Paper width and printer pairing are set in the app under Printer Settings. Custom header/footer text comes from web Field Sale App Settings.</p>

<p><b>Can I print before approving an invoice?</b><br>
Draft and pre-approved documents may offer print from action buttons depending on status. Approved and Closed documents print from the footer Print button.</p>

<p><b>Why is nothing printing despite a connected printer?</b><br>
Confirm paper width matches the printer, wait for any in-progress job to finish, and verify the printer supports ESC/POS Bluetooth used by the app.</p>

<p><b>Are logo images included on prints?</b><br>
Yes when header/footer images are configured in web Field Sale App Settings and the printer supports image rendering.</p>

<hr class="doc-section-divider">

<h2 id="related">Related topics</h2>

- [Print Formats](field-sale-app/print-formats.md)
- [Settings — Print section](field-sale-app/settings.md?id=print-settings)