From d468a256eadfd7b1fba76e039effb50268c7bc5a Mon Sep 17 00:00:00 2001
From: anders <anders@ostsik.no>
Date: Fri, 19 Dec 2025 09:54:32 +0100
Subject: [PATCH] V1

---
 README.md | 193 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 193 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a7a8b00
--- /dev/null
+++ b/README.md
@@ -0,0 +1,193 @@
+# Cisco Switch Port Status Monitor (Telnet)
+
+A Python-based monitoring tool that connects to a **Cisco switch via Telnet**, collects **interface status and PoE information**, and displays **active (connected) ports** in a clean **GUI dashboard**.
+
+This project is designed for **homelab, lab, and operational environments** where SSH may not be available and Telnet is still in use.
+
+---
+
+## ✨ Features
+
+- ✅ Telnet connection using `pexpect`
+- ✅ **Supports login without username**
+- ✅ Handles:
+  - Password-only login
+  - Username + password login
+  - Direct `>` or `#` prompt
+  - Enable (`enable`) password
+- ✅ Automatically disables terminal paging
+- ✅ Collects:
+  - Interface link status
+  - VLAN
+  - Speed (human readable)
+  - Duplex
+  - PoE admin/oper state
+  - PoE power usage (Watts)
+- ✅ GUI table with:
+  - Auto refresh
+  - Manual refresh
+  - Sortable columns
+- ✅ Designed to recover from connection failures gracefully
+
+---
+
+## 🖥️ GUI Overview
+
+The GUI displays **only active (connected) ports** in a sortable table:
+
+| Column | Description |
+|------|------------|
+| Port | Cisco interface converted to Port number |
+| VLAN | Access VLAN |
+| Speed | Human-readable link speed |
+| Duplex | Full / Half |
+| PoE Admin | PoE enabled/disabled |
+| PoE Oper | PoE operational state |
+| Power (W) | Power drawn by the device |
+
+A status bar at the bottom shows:
+- Connection state
+- Errors
+- Last refresh time
+
+---
+
+## 📦 Requirements
+
+### Python
+- Python **3.8+** recommended
+
+### System packages
+Tkinter is required for the GUI.
+
+#### Debian / Ubuntu / Raspberry Pi OS
+```bash
+sudo apt install python3-tk
+```
+
+#### RedHat / Rocky / Alma / CentOS
+```bash
+sudo dnf install python3-tkinter
+```
+
+#### Arch / Manjaro
+```bash
+sudo pacman -S tk
+```
+
+### Python modules
+```bash
+pip install pexpect
+```
+
+---
+
+## ⚙️ Configuration
+
+Edit these variables at the top of `status.py`:
+
+```python
+SWITCH_IP = "10.183.100.11"
+TELNET_PORT = 23
+
+USERNAME = ""            # optional
+PASSWORD = "telnetpass"
+ENABLE_PASSWORD = "enablepass"
+```
+
+### 🔐 Login without username
+If your switch does **not** require a username:
+```python
+USERNAME = ""
+```
+
+This is fully supported.
+
+---
+
+## 🌱 Environment Variables (Recommended)
+
+Instead of hardcoding credentials:
+
+```bash
+export SWITCH_USER=""
+export SWITCH_PASS="telnetpass"
+export SWITCH_ENABLE="enablepass"
+python3 status.py
+```
+
+This keeps secrets out of source code.
+
+---
+
+## 🚀 Running the Program
+
+```bash
+python3 status.py
+```
+
+If running on a **headless server**, ensure:
+- X11 / Wayland forwarding is available, **or**
+- Use a desktop environment
+
+For pure server usage, consider converting this to a **web dashboard**.
+
+---
+
+## 🔁 Refresh Behavior
+
+- Auto refresh every **10 seconds** (configurable in GUI)
+- Manual refresh button
+- Auto refresh can be paused/resumed
+
+The program safely:
+- Reconnects on failure
+- Retries after timeouts
+- Never blocks the GUI
+
+---
+
+## 🛠️ How It Works (Internals)
+
+1. Connects via Telnet using `pexpect`
+2. Detects login prompt type
+3. Enters enable mode if required
+4. Runs:
+   - `show interfaces status`
+   - `show power inline`
+5. Parses CLI output with regex
+6. Merges interface + PoE data
+7. Displays connected ports in GUI
+
+---
+
+## ⚠️ Notes & Limitations
+
+- Telnet must be enabled on the switch
+- Tested primarily on Cisco IOS-style output
+- Parsing may need adjustment for NX-OS / IOS-XE variants
+- GUI requires a graphical environment
+
+---
+
+## 🔮 Possible Extensions
+
+- Web-based dashboard (Flask / FastAPI)
+- Port search & filtering
+- Historical PoE graphs
+- Alerts for power spikes or link changes
+- SSH support
+
+---
+
+## 📜 License
+
+MIT License — use, modify, and share freely.
+
+---
+
+## 👤 Author
+
+Created for homelab and operational monitoring of Cisco switches.
+
+Feel free to extend and adapt.