반응형
개요
python-escpos는 ESC/POS 명령어를 이용해 영수증용 열전사(thermal) 프린터를 파이썬에서 제어하는 라이브러리입니다. 텍스트 출력, 이미지/바코드/QR 코드 전송, 페이퍼 커팅, 프린터 리셋 등 하드웨어 기능을 파이썬 코드로 다룰 수 있어 POS 시스템, 키친 프린팅, 라벨 출력 자동화에 유용합니다.
기본 문법 / 주요 파라미터
| 파라미터 | 설명 | 예시 / 기본값 |
|---|---|---|
| vendor_id | USB 장치의 Vendor ID (lsusb로 확인) | 0x04b8 (Epson) |
| product_id | USB 장치의 Product ID (lsusb로 확인) | 0x0202 |
| interface | USB 인터페이스 번호 (lsusb -vvv로 확인) | 0 (기본) |
| in_ep / out_ep | USB 입력/출력 엔드포인트 주소 | 0x81 / 0x01 (기본 예시) |
| ip | 네트워크 프린터의 IP 주소 | "192.168.1.99" |
| port | 네트워크 포트 (메이저 프린터는 보통 9100) | 9100 |
| device | 시리얼 프린터의 포트 경로 | "/dev/ttyUSB0" |
| baudrate / parity / stopbits / bytesize | 시리얼 통신 설정 | 9600, N, 1, 8 (기본값 예시) |
| profile | 프린터 모델 프로파일 (자동 설정 보완용) | "TM-T88III" |
기본 사용 예시
가장 간단한 USB 프린터 예제입니다. 먼저 lsusb로 vendor/product를 확인한 뒤 인스턴스를 생성하고 텍스트를 보냅니다.
from escpos.printer import Usb
# Vendor ID, Product ID는 lsusb로 확인
p = Usb(0x04b8, 0x0202)
p.text("Hello World\n")
p.cut()
실전 활용 예시
아래 예제들은 실제 서비스에 자주 쓰이는 패턴들입니다.
1) 네트워크 프린터에 이미지와 바코드 함께 출력하기
from escpos.printer import Network
kitchen = Network("192.168.1.100", port=9100, profile="TM-T88III")
kitchen.text("주문번호: 12345\n")
kitchen.image("/path/to/logo.png")
kitchen.barcode('4006381333931', 'EAN13', 64, 2)
kitchen.cut()
2) USB 프린터에 로고와 QR코드 출력 (Pillow, qrcode 필요)
from escpos.printer import Usb
import qrcode
p = Usb(0x04b8, 0x0202, profile="TM-T88III")
# QR 코드 만들기
qr = qrcode.make('https://example.com/order/12345')
qr.save('/tmp/qr.png')
p.image('/path/to/logo.png')
p.text('상품명: 키보드\n')
p.image('/tmp/qr.png')
p.cut()
3) 시리얼(Serial) 프린터 설정 예시
from escpos.printer import Serial
s = Serial(devfile='/dev/ttyUSB0', baudrate=9600, bytesize=8, parity='N', stopbits=1, timeout=1)
s.text('라벨 출력 테스트\n')
s.cut()
주의사항 / 자주 하는 실수
- lsusb로 Vendor ID/Product ID, 인터페이스와 엔드포인트를 정확히 확인하세요. 잘못된 값은 출력 실패 원인입니다.
- USB 권한 문제: 일반 계정에서 접근하려면 udev 규칙을 추가하거나 루트 권한이 필요합니다. (권한 에러가 흔함)
- 의존성 설치: pyusb, Pillow, qrcode, pyserial, python-barcode 등이 필요합니다. 이미지 출력이나 QR/바코드 생성은 해당 라이브러리가 설치되어 있어야 합니다.
- 이미지 크기/흑백 변환: 프린터 폭에 맞게 이미지를 리사이즈하고 흑백 변환해야 깨끗하게 나옵니다. Pillow로 사전 처리하세요.
- 엔코딩/줄바꿈: 텍스트 엔코딩(특히 한글)과 줄바꿈 문자(\n) 처리를 확인하세요. 폰트/프로파일에 따라 한글 출력이 안 될 수 있습니다.
- 커팅 지원 여부: 모든 프린터가 자동 커팅을 지원하지 않습니다. p.cut()이 동작하지 않으면 문서나 모델 사양을 확인하세요.
- 네트워크 프린터 IP/포트: DHCP 환경에서는 IP가 바뀔 수 있으니 고정 IP 또는 DNS/예약을 사용하세요.
마무리
python-escpos는 열전사 프린터 자동화를 빠르게 구현할 수 있는 실용적인 툴입니다. 장치 정보(lsusb) 확인, 권한/의존성 설치, 이미지 전처리만 신경 쓰면 POS나 키친 프린팅 같은 자동화 작업을 안정적으로 만들 수 있습니다.
참고 자료
반응형