autokanban/WIRING.md

# Thermal Printer Wiring Guide for Raspberry Pi 4

## ⚠️ CRITICAL: Printer RX ↔ Pi TX, Printer TX ↔ Pi RX (CROSSED!)

## Correct Connection Diagram

```
Thermal Printer (58mm)                    Raspberry Pi 4
┌──────────────────┐                      ┌─────────────────────┐
│                  │                      │                     │
│  VCC/5V          ├──X───────────────────│                     │ ❌ DO NOT connect to Pi
│  (Connect to     │  │                   │                     │    (Use external 9V PSU)
│   external PSU)  │  │                   │                     │
│                  │  │                   │                     │
│  GND ────────────┼──┼───────────────────┼─► Pin 6 (GND)       │ Ground to Pi
│  (Black/Blue)    │  │                   │                     │
│                  │  │                   │                     │
│  RX ─────────────┼──┼───────────────────┼─► Pin 8 (GPIO14/TX) │ Printer receives from Pi
│  (Yellow/Green)  │  │                   │                     │
│                  │  │                   │                     │
│  TX ─────────────┼──┼───────────────────┼─► Pin 10 (GPIO15/RX)│ Printer sends to Pi
│  (White/Green)   │  │                   │                     │ (optional)
│                  │  │                   │                     │
└──────────────────┘  │                   └─────────────────────┘
                      │
                      └─► External 9V PSU GND (also connect to Pi GND)


External 9V Power Supply
┌──────────────────┐
│     9V PSU       │
│  (+) ────────────┼─► Printer VCC/5V
│  (-) ────────────┼─► Printer GND + Pi Pin 6 (GND) - COMMON GROUND!
└──────────────────┘
```

## Step-by-Step Wiring Instructions

### 1. Power Connections (External PSU)

```
External 9V PSU (+) ──► Printer VCC/5V pin
External 9V PSU (-) ──► Printer GND pin
                    └─► Raspberry Pi Pin 6 (GND) - MUST share common ground!
```

### 2. Data Connections (Pi ↔ Printer)

```
Raspberry Pi Pin 8 (GPIO14 TX) ──► Printer RX pin
Raspberry Pi Pin 10 (GPIO15 RX) ──► Printer TX pin (optional, can skip)
```

## Raspberry Pi GPIO Pinout (Top View)

```
     ┌─────────────────────────┐
     │  USB  USB      Ethernet │
     │  ┌┐   ┌┐          ┌───┐ │
     └──┘└───┘└──────────┘   └─┘
        
GPIO Header (40 pins)
┌────────────────────────┐
│ 3V3  [●1] [2●]  5V     │ ❌ Don't use for printer power
│      [●3] [4●]  5V     │
│      [●5] [6●]  GND    │ ◄── Connect Printer GND + PSU GND HERE
│      [●7] [8●]  TX     │ ◄── Connect Printer RX HERE (GPIO14)
│ GND  [●9] [10●] RX     │ ◄── Connect Printer TX HERE (GPIO15) - optional
│      [11] [12]         │
│      [13] [14] GND     │
│      [15] [16]         │
│ 3V3  [17] [18]         │
│      [19] [20] GND     │
└────────────────────────┘
```

## Wire Connection Table

| What to Connect | Where It Goes | Pi Pin # | Notes |
|----------------|---------------|----------|-------|
| **Printer GND** | Pi Pin 6 (GND) | **6** | Black/Blue wire |
| **PSU GND (-)** | Pi Pin 6 (GND) | **6** | Share with printer GND |
| **Printer RX** | Pi Pin 8 (TX/GPIO14) | **8** | Yellow/Green wire - DATA OUT |
| **Printer TX** | Pi Pin 10 (RX/GPIO15) | **10** | White/Green wire - optional |
| **Printer VCC** | External PSU (+) | **N/A** | Red wire - NOT to Pi! |
| **PSU (+)** | Printer VCC | **N/A** | 9V power supply positive |

## Visual Reminder: TX ↔ RX Crossover

```
Raspberry Pi          Wire          Thermal Printer
┌──────────┐                       ┌──────────────┐
│          │                       │              │
│   TX ────┼───────────────────────┼──► RX        │  Pi talks → Printer listens
│  (Pin 8) │                       │              │
│          │                       │              │
│   RX ◄───┼───────────────────────┼──── TX       │  Printer talks → Pi listens
│ (Pin 10) │                       │              │  (optional)
│          │                       │              │
│   GND ───┼───────────────────────┼──── GND      │  Common ground
│  (Pin 6) │      └────────────────┼──── PSU (-)  │  All grounds together!
│          │                       │              │
└──────────┘                       └──────────────┘
                                          │
                                          ├──── VCC ◄─── PSU (+)
                                          │
```

## 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