POS System

English

Español

English

Español

Appearance

Hardware Setup ​

The POS Terminal integrates with thermal receipt printers, cash drawers, and barcode scanners. This guide covers the configuration and testing for each device type.

Thermal Receipt Printer ​

The system supports ESC/POS compatible thermal printers connected via USB or network (TCP/IP). Most popular models from Epson, Star Micronics, and Bixolon are compatible.

USB Printer Setup:

  1. Connect the printer to the POS terminal via USB.
  2. On Linux, ensure the current user has permission to access USB devices. Add the user to the lp group: sudo usermod -aG lp $USER and log out/in.
  3. Identify the device path (e.g., /dev/usb/lp0) or use lsusb to find the vendor and product IDs.
  4. In the store server .env file, set: PRINTER_TYPE=usb and PRINTER_DEVICE=/dev/usb/lp0.

Network Printer Setup:

  1. Connect the printer to the store's local network and assign a static IP address through the printer's configuration menu.
  2. Verify connectivity: ping <printer-ip> and nc -z <printer-ip> 9100 (port 9100 is the standard raw printing port).
  3. In the store server .env file, set: PRINTER_TYPE=network, PRINTER_HOST=192.168.1.100, and PRINTER_PORT=9100.

Cash Drawer ​

Cash drawers are typically connected to the receipt printer via an RJ-11 cable (the "kick" connector on the back of the printer). When the system sends a receipt to print, it also sends the cash drawer open command. No separate driver or configuration is needed -- the drawer opens automatically when the printer receives the ESC/POS drawer kick command.

If your cash drawer connects directly to the terminal via USB, set CASH_DRAWER_TYPE=usb and CASH_DRAWER_DEVICE=/dev/usb/drawer0 in the .env file. Most configurations use the printer-connected approach.

Barcode Scanner ​

USB barcode scanners that operate in keyboard emulation mode (HID) work out of the box with no configuration. The scanner types characters into whatever input field has focus, just like a keyboard. The POS Terminal is designed to accept this input on the main sale screen.

For best results:

  1. Configure the scanner to add a newline (Enter) suffix after each scan. This triggers the product lookup automatically.
  2. Set the scanner to keyboard emulation mode if it is not already (consult the scanner's manual for the mode-switching barcodes).
  3. Avoid scanners that require proprietary drivers, as they may not work on Linux.

Testing Hardware ​

The store server includes a hardware test utility. Run:

bash
cd apps/store-server
cargo run -- test-hardware

This command tests each configured device: it sends a test page to the printer, triggers the cash drawer, and waits for a barcode scan. Follow the on-screen prompts to verify each device is functioning correctly. If any test fails, check the connection and configuration settings described above.