# Installing tkinter on macOS

## Problem

`ModuleNotFoundError: No module named '_tkinter'`

This error occurs because tkinter is not included with the default Python installation on macOS.

## Solution: Install via Homebrew (Recommended)

Homebrew is the simplest and most reliable way to get tkinter on macOS.

### Step 1: Install Homebrew (if not already installed)

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

### Step 2: Install Python with tkinter

Find your Python version:

```bash
python3 --version
# Output: Python 3.11.x, 3.12.x, 3.13.x, 3.14.x, etc.
```

Then install Tcl/Tk plus the corresponding python-tk package:

```bash
brew install tcl-tk
```

```bash
# For Python 3.10
brew install python@3.10 python-tk@3.10

# For Python 3.11
brew install python@3.11 python-tk@3.11

# For Python 3.12
brew install python@3.12 python-tk@3.12

# For Python 3.13
brew install python@3.13 python-tk@3.13

# For Python 3.14
brew install python@3.14 python-tk@3.14

# Or use the generic package (recommended if unsure)
brew install python
```

### Step 3: Create a Fresh Virtual Environment

After installing tkinter, create a new virtual environment to ensure proper integration:

```bash
# Create virtual environment
python3 -m venv .venv

# Activate it
source .venv/bin/activate

# Verify tkinter is available
python3 -m tkinter

# If a small window appears, tkinter is installed correctly!
```

### Step 4: Install Application Dependencies

```bash
python -m pip install -U pip setuptools wheel
python -m pip install matplotlib pyserial numpy pandas psutil
```

### Step 5: Run the GUI

```bash
temp-logger-gui
```

---

## 🎯 Quick Fix (Recommended Path)

If you just want to get running quickly:

```bash
# 1. Install Homebrew (if needed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Install Tcl/Tk + Python + tkinter
brew install tcl-tk
brew install python@3.11 python-tk@3.11

# 3. Create fresh virtual environment
python3.11 -m venv .venv
source .venv/bin/activate

# 4. Install dependencies
python -m pip install -U pip setuptools wheel
python -m pip install matplotlib pyserial numpy pandas psutil

# 5. Run the GUI
cd /path/to/Temp_Logger
python -m pip install -e .
temp-logger-gui
```

---

## Verification

Check if tkinter is available:

```bash
python3 -m tkinter
```

A small window with a quit button should appear. If it does, tkinter is installed!

Programmatic verification:

```python
python3 << EOF
try:
    import tkinter
    print("✓ tkinter is installed and working")
    print(f"✓ tkinter version: {tkinter.TkVersion}")
except ImportError as e:
    print(f"✗ tkinter is NOT installed: {e}")
EOF
```

## GUI Options

### Option 1: Full tkinter GUI (Recommended if available)

```bash
temp-logger-gui
```

Features:

- Professional dark theme
- Full configuration panel
- File browser
- Terminal-style output
- Best user experience
- Tunable parameters (AVG level, update interval, buffer size)

---

## Command-Line Alternative (No GUI)

## Troubleshooting

### Still getting tkinter error after installation?

1. **Verify Python path:**

   ```bash
   which python3
   python3 --version
   ```

2. **Test tkinter module directly:**

   ```bash
   python3 -c "import _tkinter; print('OK')"
   ```

3. **Test via GUI:**

   ```bash
   python3 -m tkinter
   ```

4. **Check if Homebrew installation is in PATH:**

   ```bash
   which python3.11  # or your version
   ls -la /usr/local/bin/python*
   ls -la /opt/homebrew/bin/python*
   ```

5. **Reinstall with fresh environment:**

   ```bash
   # Uninstall old packages
   brew uninstall tcl-tk python@3.11 python-tk@3.11

   # Reinstall fresh
   brew install tcl-tk python@3.11 python-tk@3.11

   # Create new virtual environment
   rm -rf .venv
   python3.11 -m venv .venv
   source .venv/bin/activate
   python -m pip install -U pip setuptools wheel
   python -m pip install matplotlib pyserial numpy pandas psutil
   ```

### Error: "Multiple Python installations found"

If you have multiple Python versions installed:

```bash
# Find all Python installations
ls /usr/local/bin/python*
ls /usr/bin/python*

# Use the specific version from Homebrew
/usr/local/bin/python3.11 -m tkinter
/opt/homebrew/bin/python3.11 -m tkinter
```

### macOS-Specific Notes

**Intel Macs (x86_64):**

- Homebrew installs to `/usr/local/bin/`
- Standard installation process

**Apple Silicon Macs (M1/M2/M3):**

- Homebrew installs to `/opt/homebrew/bin/`
- Make sure your Homebrew is for ARM64 architecture
- Check: `file /opt/homebrew/bin/brew` (should show "Mach-O 64-bit")

```bash
# For Apple Silicon, verify architecture
python3 -c "import sys; print(f'Architecture: {sys.platform}, {sys.maxsize}')"

# Should show: arm64 for Apple Silicon
uname -m  # Shows "arm64" for Apple Silicon
```

### Permission Issues

If you get permission errors:

```bash
# Check if Homebrew directory is writable
ls -la /usr/local/bin/ | head

# Fix permissions if needed
sudo chown -R $(whoami) /usr/local/bin
```

---

## Alternative Solutions

### If Homebrew Installation Fails

#### Option 1: Use Official Python Installer

1. Download Python from [python.org](https://www.python.org/downloads/)
2. Run the installer (includes tkinter)
3. Use the installed Python:

   ```bash
   /usr/local/bin/python3 -m venv venv
   source venv/bin/activate
   python -m pip install -U pip setuptools wheel
   python -m pip install matplotlib pyserial numpy pandas psutil
   temp-logger-gui
   ```

#### Option 2: Use MacPorts (Alternative Package Manager)

```bash
# Install MacPorts from https://www.macports.org/install.php
sudo port install python311 py311-tkinter py311-matplotlib py311-pyserial

# Create virtual environment with MacPorts Python
python3.11 -m venv venv
source venv/bin/activate
python -m pip install -U pip setuptools wheel
python -m pip install matplotlib pyserial numpy pandas psutil
```

#### Option 3: Use Command-Line Logger (No GUI)

If GUI installation is problematic, the command-line logger works perfectly:

```bash
temp-logger --no-plot
```

Produces identical CSV output files, just without the graphical interface.

---

## Complete Setup Checklist

- [ ] Homebrew installed: `brew --version`
- [ ] Python and tkinter installed: `python3 -m tkinter` (opens window)
- [ ] Virtual environment created: `source venv/bin/activate`
- [ ] Dependencies installed: `pip list | grep -E "matplotlib|pyserial|numpy"`
- [ ] GUI starts: `temp-logger-gui`
- [ ] Connection works: Click "Start" button, see data in info panel

---

## Performance Tips

For best performance on macOS:

1. **Use native Python installation** (from Homebrew or python.org)
2. **Create virtual environment** to isolate dependencies
3. **Use SSD for data logging** (faster CSV writes)
4. **Enable matplotlib backend**: `export MPLBACKEND=TkAgg`
5. **Adjust plot interval** in GUI (250-500ms for older Macs)

---

## Summary

1. ✅ Install Homebrew (if not installed)
2. ✅ Install Python and tkinter via Homebrew
3. ✅ Create fresh virtual environment
4. ✅ Install application dependencies
5. ✅ Run `temp-logger-gui`
6. ✅ Click "Start" button and begin logging!

All done! Your Temperature Logger GUI is ready to use.

(c) 2024-26 Prof. Flavio ABREU ARAUJO. All rights reserved.
