Update readme.md

ctsdownloads · web-flow · commit bfa528c8466c · 2025-07-05T00:09:02.000-07:00
## Framework Enhanced Diagnostic Tool aka "combined.sh"

This intelligent diagnostic script collects and analyzes system logs from your Framework laptop, automatically detecting hardware issues and providing actionable recommendations in plain English. It's specifically designed for Framework laptops with model-aware analysis and Framework-specific troubleshooting guidance.
diff --git a/log-helper/readme.md b/log-helper/readme.md
@@ -1,129 +1,249 @@
+## Framework Enhanced Diagnostic Tool aka "combined.sh"
+
+This intelligent diagnostic script collects and analyzes system logs from your Framework laptop, automatically detecting hardware issues and providing actionable recommendations in plain English. It's specifically designed for Framework laptops with model-aware analysis and Framework-specific troubleshooting guidance.
+
+## Table of Contents
+
+- [TL;DR - Quick Start](#tldr---quick-start)
+- [Key Features](#key-features)
+- [Which distros does this work on?](#which-distros-does-this-work-on)
+- [How to use this tool?](#how-to-use-this-tool)
+  - [Prerequisites](#prerequisites)
+  - [Quick Start](#quick-start)
+- [Diagnostic Options](#diagnostic-options)
+  - [1. Last X Minutes](#1-last-x-minutes-)
+  - [2. Last 24 Hours](#2-last-24-hours-)
+  - [3. Specific Time Range](#3-specific-time-range-)
+  - [4. Filter Previously Created Log File](#4-filter-previously-created-log-file-)
+- [Understanding the Results](#understanding-the-results)
+  - [System Information](#-system-information)
+  - [Intelligent Recommendations](#-intelligent-recommendations)
+  - [Pattern Analysis](#-pattern-analysis)
+  - [Framework-Specific Features](#-framework-specific-features)
+- [Example Output](#example-output)
+- [When to Contact Support](#when-to-contact-support)
+- [Quick Commands](#quick-commands)
+- [Framework Resources](#framework-resources)
+- [Advanced Information](#advanced-information)
+
+### TL;DR - Quick Start
+
+**Download and run immediately:**
+```bash
+curl -s https://raw.githubusercontent.com/FrameworkComputer/linux-docs/main/log-helper/combined.sh -o combined.sh && chmod +x combined.sh && bash combined.sh
+```
 
-## Framework Log Helper aka "combined.sh"
+Choose option 1 or 2, check the "INTELLIGENT RECOMMENDATIONS" section in the output for actionable solutions.
 
-This script collects and analyzes system logs from your computer, helping Framework support to identify potential issues or errors. 
-It can also gather logs from specific time ranges or filter existing logs for keywords, providing summaries of potential problems related to graphics, networking, and critical sytem errors.
+---
 
-### Which distros does this work on?
+### Key Features
 
-**This is tested to work with the following Linux distros.**
+- **🔍 Intelligent Issue Detection**: Automatically identifies GPU hangs, thermal problems, WiFi issues, USB connection problems, and more
+- **🖥️ Framework-Specific Analysis**: Detects your exact Framework model and provides model-specific recommendations
+- **📋 Plain English Recommendations**: Translates technical errors into clear, actionable advice
+- **🌡️ Real-Time Hardware Monitoring**: Shows current temperatures, power status, and connectivity
+- **⚡ Smart Noise Filtering**: Focuses on actual problems, ignoring routine system operations
+- **🔧 Comprehensive Hardware Detection**: Identifies your GPU, WiFi card, storage, RAM, and expansion cards
 
-- Ubuntu
-- Fedora
-- Bazzite/Project Bluefin (curl is installed already)
-- (This "should work" on anything using curl with sane paths to dmesg and journalctl)
+### Which distros does this work on?
 
-### How to use this tool?
+**This tool works with all major Linux distributions and automatically installs required packages:**
 
-####
-- [Deep dive into how it works](https://github.com/FrameworkComputer/linux-docs/blob/main/log-helper/how-it-works.md#how-it-works).
-- [Troubleshooting common issues](https://github.com/FrameworkComputer/linux-docs/blob/main/log-helper/how-it-works.md#troubleshooting).
+- **Ubuntu/Debian/Linux Mint** (officially supported by Framework)
+- **Fedora** (officially supported by Framework) 
+- **Bazzite/Project Bluefin** (officially supported by Framework)
+- **Arch Linux/Manjaro/EndeavourOS** (community supported)
+- **openSUSE Tumbleweed/Leap** (community supported)
+- **NixOS** (community supported)
+- **Pop!_OS** (community supported)
 
-**For customer self-support, this is useful in that you can grab your logs from any of the three options:**
+### How to use this tool?
 
-### Install Curl
+#### Prerequisites
 
-Curl should already be installed, but just in case:
+Most systems already have curl installed. If needed:
 
-#### Fedora
-```
+**Fedora:**
+```bash
 sudo dnf install curl -y
 ```
 
-or
+**Ubuntu/Debian:**
+```bash
+sudo apt install curl -y
+```
+
+**Bazzite/Bluefin:** Already included, no installation needed.
 
-#### Ubuntu
+#### Quick Start
+
+**Download and run the diagnostic tool:**
+```bash
+curl -s https://raw.githubusercontent.com/FrameworkComputer/linux-docs/main/log-helper/combined.sh -o combined.sh && chmod +x combined.sh && bash combined.sh
 ```
-sudo apt install curl -y
+
+**For future runs:**
+```bash
+./combined.sh
 ```
 
-or
+### Diagnostic Options
 
-#### Bazzite or Bluefin
+#### 1. Last X Minutes ⏰
+**Best for recent issues**
 
-Simply goto the next step below to run it, nothing else needs to be added.
+- Select option `1`
+- Enter the number of minutes (e.g., `30` for issues that happened 30 minutes ago)
+- The tool will analyze logs from that timeframe and provide recommendations
 
-#### (Either distro) Then run:
+![Last X Minutes](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/log-helper/images/1.png "Last X Minutes")
 
-```
-curl -s https://raw.githubusercontent.com/FrameworkComputer/linux-docs/main/log-helper/combined.sh -o combined.sh && clear && bash combined.sh
-```
+![Finshed scan](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/log-helper/images/2.png "Finshed scan")
 
-<br />
+**Example use cases:**
+- Graphics crashed while gaming
+- WiFi suddenly disconnected
+- System became unresponsive
+- Thermal throttling during heavy workload
 
-#### Running the script in the future
+#### 2. Last 24 Hours 📅
+**Best for ongoing or intermittent issues**
 
->After the install, you can run going forward with the following in the HOME directory. So merely opening a terminal and running this will work if the original script has not been moved.<br />
+- Select option `2`
+- Analyzes the full day of system logs
+- Identifies patterns like recurring WiFi drops or thermal cycling
 
-```
-bash combined.sh
-```
-<br /><br />
+**Example use cases:**
+- Random system freezes throughout the day
+- Intermittent USB connection issues
+- Gradual performance degradation
+- Battery or charging problems
+
+#### 3. Specific Time Range 🎯
+**Best when you know exactly when the issue occurred**
+
+- Select option `3`
+- Enter start time: `YYYY-MM-DD HH:MM` (24-hour format)
+- Enter end time: `YYYY-MM-DD HH:MM`
 
-----------------------------------------------------------
+**Example:**
+- Start: `2025-01-15 14:30` (Jan 15, 2:30 PM)
+- End: `2025-01-15 15:00` (Jan 15, 3:00 PM)
 
-#### Last X Minutes (How many minutes ago do you wish to gather logs from)
+#### 4. Filter Previously Created Log File 🔍
+**For advanced analysis of existing logs**
 
-- Paste in the code mentioned previously, press enter, type in option 1.
+- Run after creating a log file with options 1-3
+- Search for specific keywords or phrases
+- Creates `filtered_log.txt` with matching entries
 
-- Type in the Enter the number of minutes you wish to gather logs from. 
->For example, if the issue happened about 15 minutes ago, you might choose to type in 25 to gather logs from 25 minutes ago. This gives you a buffer of time in case you're not sure.
+### Understanding the Results
 
-- Once the minutes are typed into the terminal as shown below (using your number keys), press enter. Enter your sudo password when prompted.
+The diagnostic tool creates `combined_log.txt` with several sections:
 
-- First progress bar will run, then the second one. Once completed, the log file combined_log.txt will appear in your home directory.
-<br />
+#### 🔧 System Information
+- Framework model detection
+- Hardware specifications (GPU, WiFi, RAM, storage)
+- Current temperatures and power status
+- Linux distribution compatibility status
 
- ![Last X Minutes](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/main/log-helper/images/1.gif "Last X Minutes")
+#### ⚡ Intelligent Recommendations
+**Color-coded by severity:**
 
-<br /><br />
+- **🔴 IMMEDIATE**: Stop using immediately (dangerous temperatures, hardware faults)
+- **🟠 URGENT**: Address soon (GPU crashes, memory issues, storage problems)
+- **🟡 IMPORTANT**: Should fix (USB issues, WiFi problems, audio issues)
+- **🔵 INFORMATIONAL**: Status updates (distro compatibility, normal thermal behavior)
+- **🟢 PREVENTIVE**: Proactive suggestions (elevated temperatures, minor issues)
 
-----------------------------------------------------------
+#### 📊 Pattern Analysis
+- WiFi stability (tracks disconnection frequency)
+- USB connection reliability
+- GPU stability monitoring
+- Thermal management effectiveness
 
-#### Last 24 hours (As it says, 24 hours from this moment of logs)
+#### 🎯 Framework-Specific Features
 
-- Paste in the code mentioned previously, press enter, type in option 2.
->This will run a bit slower, depending on your log(s) size.
+**Model-Aware Recommendations:**
+- Framework Laptop 13: 60W charger verification
+- Framework Laptop 16: 180W charger verification + GPU module checks
+- Framework Desktop: Power supply diagnostics
+- Expansion card troubleshooting
 
-- First progress bar will run, then the second one. Once completed, the log file combined_log.txt will appear in your home directory.
+**Thermal Management:**
+- Modern AMD (7040+ series): Higher temperature tolerance (95°C normal)
+- Intel processors: Conservative thresholds (80°C watch point)
+- Model-specific cooling guidance
 
-<br /><br />
-----------------------------------------------------------
+**Hardware Detection:**
+- MediaTek WiFi cards (MT7921/MT7925)
+- Intel WiFi cards (iwlwifi)
+- AMD GPUs (RDNA 2/3)
+- Intel integrated graphics
+- Framework expansion cards
 
-#### Specific time range
+### Example Output
 
-- Paste in the code mentioned previously, press enter, type in option 3.
+![Details](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/log-helper/images/4.png "Details")
 
-- You will be asked for a START TIME. This is the beginning period you wish to gather logs from. Enter in the date and time in this format: YYYY-MM-DD HH:MM and then press enter.
->You do not need to add minutes (MM) if you do not want to - this works fine with YYYY-MM-DD HH instead. Time must be military time. So for 2pm for example, that would be 14:00. 
 
-**For all of the above examples, your log will be sent to combined_log.txt in your home directory.**
+```
+🖥️  Framework Laptop 16 - checking GPU module and enhanced thermal envelope
+🌡️  Current CPU: 67°C via Tctl (Modern AMD: runs hot by design - watch at 90°C, throttles at 95°C, critical at 100°C, emergency at 105°C)
+✅ No issues detected
+
+🔵 INFORMATIONAL Status:
+• [DISTRO_COMPATIBILITY] ✅ Your Linux distribution (fedora 42) is officially supported and tested by Framework for your Framework Laptop 16 → You should have the best experience and full hardware support
+```
 
+### When to Contact Support
 
-**Note, each time you collect logs, you will be overwriting the previous combined_log.txt file.**
+![Intelligent recommendations](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/log-helper/images/3.png "Intelligent recommendations")
 
-![Specific Time Range](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/main/log-helper/images/2.gif "Specific Time Range")
+**Contact Framework Support if you see:**
+- Multiple 🔴 IMMEDIATE or 🟠 URGENT recommendations
+- Repeated GPU crashes or system freezes
+- Hardware fault messages (Machine Check, MCE errors)
+- Persistent thermal issues despite cleaning
 
-<br /><br />
-----------------------------------------------------------
+**Include these files with your support ticket:**
+- `combined_log.txt` (the full diagnostic report)
+- Screenshots of any error messages
+- Description of when the issue occurs
 
-#### Filter previously created log file
+### Quick Commands
 
->This is an option used by support and those who know what they're look for. Looking at your logs, you are going to see a ton of verbose messages. 99.9% of the "errors" or warnings you see are fine. This is normal. Even some of the items that appear in "Focused Summary of Potential Issues" and "General Summary of Potential Issues (excluding gnome-shell errors)" are fine. We simply want to gather everything that logs collect. And while the summaries are verbose, they are not an automatic indication that anything is wrong. For newer users, we recommend leaving option 4 to Framework Support staff.
+After running the diagnostic:
 
-- Collect logs using one of the methods indicated above. Note, each time you collect logs, you will be overwriting the previous combined_log.txt file. 
+```bash
+# View full report
+cat combined_log.txt
 
-- Paste in the code mentioned previously, press enter, type in option 4.
+# View only recommendations
+grep -A 20 "INTELLIGENT RECOMMENDATIONS" combined_log.txt
+
+# Monitor temperatures in real-time
+watch -n 2 sensors
+
+# Check current system status
+sensors
+```
 
-- You will be asked two questions; do you wish to grep for a keyword or a key phrase.
-> Make your selection if you are familiar with Linux. If you are not, this is an ideal time to stop, open a support ticket. When support replies, send them the combined_log.txt file in your home directory.
+### Framework Resources
 
-- If you selected Grep for a key phrase, type in the phrase without any quotes. Press enter.
+**Support & Documentation:**
+- **Support Center**: https://frame.work/support
+- **Linux Guides**: https://frame.work/linux
+- **Community Forum**: https://community.frame.work/
+- **Knowledge Base**: https://knowledgebase.frame.work/categories/linux-S1IUEcFbkx
+- **Linux Tools and Scripts**: https://knowledgebase.frame.work/linux-on-framework-tools-and-scripts-rymax1Jdyg
+- **Framework Guides**: https://guides.frame.work/
+-  **Enhanced WiFi Analyzer**: https://github.com/FrameworkComputer/linux-docs/tree/main/Enhanced-WiFi-Analyzer
 
-- If you selected Grep for a keyword, type in the keyword without. Press enter.
+### Advanced Information
 
-- Your filtered_log.txt located in your home directory file will contain your query.
-- 
-![Filter Previously Created Log File](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/main/log-helper/images/3.gif "Filter Previously Created Log File")
+- [Deep dive into how it works](https://github.com/FrameworkComputer/linux-docs/blob/main/log-helper/how-it-works.md#how-it-works)
+- [Troubleshooting common issues](https://github.com/FrameworkComputer/linux-docs/blob/main/log-helper/how-it-works.md#troubleshooting)
 
-<br /><br />
+**Note:** Each diagnostic run overwrites the previous `combined_log.txt` file. Save important reports before running again.
