# Thermal Printer Wiring Guide for Raspberry Pi 4

## Connection Diagram

```
Thermal Printer (58mm)                    Raspberry Pi 4
┌──────────────────┐                      ┌─────────────────────┐
│                  │                      │                     │
│  Red (VCC/5V)    ├─────────────────────►│ Pin 4 (5V)          │ ⚠️ May need external PSU
│                  │                      │                     │
│  Black (GND)     ├─────────────────────►│ Pin 6 (GND)         │
│                  │                      │                     │
│  Green (RX)      ├─────────────────────►│ Pin 8 (GPIO14/TXD)  │ Pi sends data
│                  │                      │                     │
│  Yellow (TX)     ├─────────────────────►│ Pin 10 (GPIO15/RXD) │ Pi receives (optional)
│                  │                      │                     │
│  Yellow/Green    ├─────────────────────►│ Pin 6 (GND)         │ Shield/extra ground
│                  │                      │                     │
└──────────────────┘                      └─────────────────────┘
```

## Pin Layout (GPIO Header View)

```
Raspberry Pi 4 GPIO Header (looking down at the board)
┌─────────────────────────────────────────┐
│  3V3  [ 1] [ 2]  5V   ← Connect Red here (or use external PSU)
│ GPIO2 [ 3] [ 4]  5V
│ GPIO3 [ 5] [ 6]  GND  ← Connect Black + Yellow/Green here
│ GPIO4 [ 7] [ 8]  GPIO14 (TXD) ← Connect Green here
│   GND [ 9] [10]  GPIO15 (RXD) ← Connect Yellow here
│GPIO17 [11] [12]  GPIO18
│GPIO27 [13] [14]  GND
│GPIO22 [15] [16]  GPIO23
│  3V3  [17] [18]  GPIO24
│GPIO10 [19] [20]  GND
│ GPIO9 [21] [22]  GPIO25
│GPIO11 [23] [24]  GPIO8
│   GND [25] [26]  GPIO7
│   ... (pins 27-40 not shown)
└─────────────────────────────────────────┘
```

## Quick Connection Summary

| Printer Wire | Pi Pin Number | Pi Pin Name | Function |
|-------------|---------------|-------------|----------|
| **Red** | **4** | 5V Power | Power supply (⚠️ high current) |
| **Black** | **6** | Ground | Common ground |
| **Green** | **8** | GPIO 14 (TXD) | Serial transmit (Pi → Printer) |
| **Yellow** | **10** | GPIO 15 (RXD) | Serial receive (Printer → Pi, optional) |
| **Yellow/Green** | **6** | Ground | Shield/secondary ground |

## Testing Steps

### 1. Enable Serial Port on Raspberry Pi

```bash
# Open configuration
sudo raspi-config

# Navigate to:
# 3 Interface Options → I6 Serial Port
# "Login shell over serial?" → No
# "Serial port hardware enabled?" → Yes
# Finish and reboot

sudo reboot
```

### 2. Verify Serial Device

```bash
# Check serial device
ls -l /dev/serial0
ls -l /dev/ttyAMA0

# Both should exist and point to UART
```

### 3. Install Test Tools

```bash
sudo apt update
sudo apt install python3 python3-pip python3-venv

# Create test environment
python3 -m venv test_env
source test_env/bin/activate
pip install python-escpos pyserial
```

### 4. Test Print Script

Create `test_printer.py`:

```python
#!/usr/bin/env python3
from escpos.printer import Serial

# Try different device paths if needed
# Common: /dev/serial0, /dev/ttyAMA0, /dev/ttyS0
try:
    printer = Serial(
        devfile='/dev/serial0',  # or /dev/ttyAMA0
        baudrate=19200,
        timeout=1
    )
    
    print("Printer initialized successfully!")
    printer.text("Hello from Raspberry Pi!\n")
    printer.text("AutoKanban Test Print\n")
    printer.text("=" * 32 + "\n")
    printer.cut()
    print("Print sent successfully!")
    
except Exception as e:
    print(f"Error: {e}")
    print("\nTroubleshooting:")
    print("1. Check wiring connections")
    print("2. Verify serial port is enabled: sudo raspi-config")
    print("3. Check user is in dialout group: groups")
    print("4. Try different baudrates: 9600, 19200, 115200")
    print("5. List available devices: ls -l /dev/tty*")
```

### 5. Run Test

```bash
# Make sure user is in dialout group
sudo usermod -a -G dialout $USER
# Log out and back in, or:
newgrp dialout

# Run test
python3 test_printer.py
```

## ⚠️ Power Considerations

**Important**: Thermal printers can draw 1-2A during printing. The Pi's 5V pins can provide limited current.

**If the printer doesn't work or the Pi reboots during printing:**

1. Use an external 5V power supply (2A or higher):

   ```
   External 5V PSU
   ┌────────────┐
   │  5V   GND  │
   │  │     │   │
   └──┼─────┼───┘
      │     │
      │     └──────────┬─► Pi Pin 6 (GND)
      │                └─► Printer Black wire
      │
      └────────────────────► Printer Red wire
   ```

2. Common ground is critical - connect:
   - External PSU GND → Printer Black
   - External PSU GND → Pi GND (Pin 6)
   - This ensures both devices share the same ground reference

## Troubleshooting

### No output from printer

- Check all connections are secure
- Verify serial port is enabled: `sudo raspi-config`
- Check device path: `ls -l /dev/serial*`
- Try different baudrates: 9600, 19200, 115200
- Check user permissions: `groups` (should include `dialout`)

### Printer prints garbage

- Wrong baudrate - try 9600 or 19200
- Wrong wiring - swap TX/RX if needed

### Pi reboots when printing

- Power supply insufficient - use external 5V PSU for printer

### Permission denied

```bash
sudo usermod -a -G dialout $USER
# Log out and back in
```

## Next Steps

Once the test print works:

1. Note the working device path (`/dev/serial0` or `/dev/ttyAMA0`)
2. Note the working baudrate (likely 19200)
3. Update these in your AutoKanban `app/main.py`
4. Set `DEBUG_PRINT_TO_IMAGE = False` for real printing