diff --git a/.doc_for_ai/TASMOTA_WEBUI_CODING_GUIDE.md b/.doc_for_ai/TASMOTA_WEBUI_CODING_GUIDE.md new file mode 100644 index 000000000..943cb047d --- /dev/null +++ b/.doc_for_ai/TASMOTA_WEBUI_CODING_GUIDE.md @@ -0,0 +1,947 @@ +# Tasmota WebUI Coding Guide + +This guide provides comprehensive instructions for coding WebUI interfaces for Tasmota, based on analysis of the actual Tasmota web interface source code and screenshots. + +## Overview + +Tasmota's WebUI is a lightweight, embedded web interface designed for ESP8266/ESP32 microcontrollers with severe memory constraints. The interface follows a minimalist design philosophy while providing comprehensive device control and configuration capabilities. + +### Visual Design Analysis + +Based on the actual Tasmota WebUI screenshots, the interface features: + +1. **Main Control Page**: + - Large status display showing device state ("OFF") + - Color control sliders with visual gradients (hue, saturation, brightness) + - Toggle buttons for device control + - Clean button layout with consistent spacing + +2. **Configuration Pages**: + - Nested fieldsets for logical grouping + - Form elements with proper labels and placeholders + - Consistent button styling with color coding (blue for navigation, green for save, red for dangerous actions) + - Mobile-optimized layout with full-width buttons + +3. **Navigation Structure**: + - Hierarchical menu system + - Clear visual separation between sections + - Consistent header with device name and Tasmota branding + +## Core Design Principles + +### 1. Memory Efficiency +- Minimal HTML/CSS/JavaScript footprint +- Inline styles and scripts to reduce HTTP requests +- Compressed and minified code +- CSS variables for theming without duplication + +### 2. Responsive Design +- Mobile-first approach with `viewport` meta tag +- Flexible layouts that work on small screens +- Touch-friendly button sizes and spacing +- Minimal external dependencies + +### 3. Dark Theme by Default +- Professional dark color scheme +- High contrast for readability +- Consistent color variables throughout + +### 4. Progressive Enhancement +- Core functionality works without JavaScript +- JavaScript enhances user experience +- Graceful degradation for older browsers + +## HTML Structure Pattern + +### Basic Page Template + +```html + + + + + + + Tasmota Configuration + + + + +
+ +
+ + +``` + +### Key HTML Structure Elements + +1. **Container Div**: Main wrapper with consistent styling +2. **Header Section**: Device name and page title +3. **Content Area**: Forms, buttons, and configuration options +4. **Footer**: Version information and links + +## CSS Design System + +### Color Variables + +Tasmota uses CSS custom properties for consistent theming: + +```css +:root { + --c_bg: #252525; /* Background color */ + --c_frm: #4f4f4f; /* Form/fieldset background */ + --c_ttl: #eaeaea; /* Title text color */ + --c_txt: #eaeaea; /* Regular text color */ + --c_txtwrn: #ff5661; /* Warning text color */ + --c_txtscc: #008000; /* Success text color */ + --c_btn: #1fa3ec; /* Primary button color */ + --c_btnoff: #08405e; /* Disabled button color */ + --c_btntxt: #faffff; /* Button text color */ + --c_btnhvr: #0e70a4; /* Button hover color */ + --c_btnrst: #d43535; /* Reset/danger button color */ + --c_btnrsthvr: #931f1f; /* Reset button hover */ + --c_btnsv: #47c266; /* Save button color */ + --c_btnsvhvr: #5aaf6f; /* Save button hover */ + --c_in: #dddddd; /* Input background */ + --c_intxt: #000000; /* Input text color */ + --c_csl: #1f1f1f; /* Console background */ + --c_csltxt: #65c115; /* Console text color */ + --c_tab: #999999; /* Tab color */ + --c_tabtxt: #faffff; /* Tab text color */ +} +``` + +### Typography and Layout + +```css +body { + text-align: center; + font-family: verdana, sans-serif; + background: var(--c_bg); +} + +div, fieldset, input, select { + padding: 5px; + font-size: 1em; +} + +fieldset { + background: var(--c_frm); +} + +p { + margin: 0.5em 0; +} +``` + +### Input Styling + +```css +input { + width: 100%; + box-sizing: border-box; + -webkit-box-sizing: border-box; + -moz-box-sizing: border-box; + background: var(--c_in); + color: var(--c_intxt); +} + +input[type=checkbox], input[type=radio] { + width: 1em; + margin-right: 6px; + vertical-align: -1px; +} + +input[type=range] { + width: 99%; +} + +select { + width: 100%; + background: var(--c_in); + color: var(--c_intxt); +} +``` + +### Button System + +```css +button { + border: 0; + border-radius: 0.3rem; + background: var(--c_btn); + color: var(--c_btntxt); + line-height: 2.4rem; + font-size: 1.2rem; + width: 100%; + -webkit-transition-duration: 0.4s; + transition-duration: 0.4s; + cursor: pointer; +} + +button:hover { + background: var(--c_btnhvr); +} + +.bred { + background: var(--c_btnrst); +} + +.bred:hover { + background: var(--c_btnrsthvr); +} + +.bgrn { + background: var(--c_btnsv); +} + +.bgrn:hover { + background: var(--c_btnsvhvr); +} +``` + +## JavaScript Patterns + +### Core Utility Functions + +```javascript +// Element selection shortcuts +var eb = s => document.getElementById(s); +var qs = s => document.querySelector(s); + +// Password visibility toggle +var sp = i => eb(i).type = (eb(i).type === 'text' ? 'password' : 'text'); + +// Window load event handler +var wl = f => window.addEventListener('load', f); + +// Auto-assign names to form elements +function jd() { + var t = 0, i = document.querySelectorAll('input,button,textarea,select'); + while (i.length >= t) { + if (i[t]) { + i[t]['name'] = (i[t].hasAttribute('id') && (!i[t].hasAttribute('name'))) + ? i[t]['id'] : i[t]['name']; + } + t++; + } +} + +// Show/hide elements with class 'hf' +function sf(s) { + var t = 0, i = document.querySelectorAll('.hf'); + while (i.length >= t) { + if (i[t]) { + i[t].style.display = s ? 'block' : 'none'; + } + t++; + } +} + +wl(jd); // Auto-assign names on load +``` + +### AJAX Communication + +```javascript +var x = null, lt, to, tp, pc = ''; + +// Load data with AJAX +function la(p) { + a = p || ''; + clearTimeout(ft); + clearTimeout(lt); + if (x != null) { x.abort(); } + + x = new XMLHttpRequest(); + x.onreadystatechange = () => { + if (x.readyState == 4 && x.status == 200) { + var s = x.responseText + .replace(/{t}/g, "") + .replace(/{s}/g, ""); + eb('l1').innerHTML = s; + clearTimeout(ft); + clearTimeout(lt); + lt = setTimeout(la, 400); // Auto-refresh every 400ms + } + }; + x.open('GET', '.?m=1' + a, true); + x.send(); + ft = setTimeout(la, 2e4); // Fallback timeout 20 seconds +} + +// Control function for sliders and buttons +function lc(v, i, p) { + if (eb('s')) { + if (v == 'h' || v == 'd') { + var sl = eb('sl4').value; + eb('s').style.background = 'linear-gradient(to right,rgb(' + sl + '%,' + sl + '%,' + sl + '%),hsl(' + eb('sl2').value + ',100%,50%))'; + } + } + la('&' + v + i + '=' + p); +} +``` + +### Form Handling + +```javascript +// Submit form with UI feedback +function su(t) { + eb('f3').style.display = 'none'; + eb('f2').style.display = 'block'; + t.form.submit(); +} + +// File upload with validation +function upl(t) { + var sl = t.form['u2'].files[0].slice(0, 1); + var rd = new FileReader(); + rd.onload = () => { + var bb = new Uint8Array(rd.result); + if (bb.length == 1 && bb[0] == 0xE9) { + fct(t); // Factory reset check + } else { + t.form.submit(); + } + }; + rd.readAsArrayBuffer(sl); + return false; +} + +// Factory reset confirmation +function fct(t) { + var x = new XMLHttpRequest(); + x.open('GET', '/u4?u4=fct&api=', true); + x.onreadystatechange = () => { + if (x.readyState == 4 && x.status == 200) { + var s = x.responseText; + if (s == 'false') setTimeout(() => { fct(t); }, 6000); + if (s == 'true') setTimeout(() => { su(t); }, 1000); + } else if (x.readyState == 4 && x.status == 0) { + setTimeout(() => { fct(t); }, 2000); + } + }; + x.send(); +} +``` + +## Page Layout Patterns + +### Configuration Menu Layout + +Based on the Tasmota configuration menu, here's the standard layout pattern: + +```html +
+ +
+ +

ESP32-DevKit

+

Tasmota

+
+ + +
+

Configuration

+
+ + +

+
+ + + +

+
+ + + + + + +
+
+ + Tasmota 15.0.1.4 (tasmota) by Theo Arends + +
+
+``` + +### Configuration Form Layout + +For configuration pages with forms: + +```html +
+  Other parameters  +
+ + +
+  Template  +

+ +

+

+ +

+
+ + +
+ +
+ + + +

+ + + +

+ +
+ + + +
+  Emulation  +

+ +
+ +

+
+ + +
+ + +
+``` + +### Main Page with Controls + +The main control page features a prominent status display and interactive controls. Based on the screenshot analysis: + +```html + +
+ + +
") + .replace(/{m}/g, "") + .replace(/{e}/g, "
+ + + +
+ +
+ + + + + + + + + + + + + + + + + + +
+
+ +
+
+
+ +
+
+ + +
+ +
+
+ + +
+ OFF +
+ + + +``` + +## Advanced UI Components + +### Status Display + +The main page features a large, prominent status display: + +```css +.status-display { + text-align: center; + font-size: 4em; + font-weight: bold; + color: var(--c_txt); + padding: 20px; + margin: 10px 0; +} +``` + +```html +
OFF
+``` + +### Color Control Sliders + +The interface includes sophisticated color control with visual feedback: + +```html + +
+ +
+ + +
+ +
+ + +
+ +
+``` + +### Button Layout Patterns + +Based on the screenshots, buttons follow specific layout patterns: + +```css +/* Full-width buttons with consistent spacing */ +.btn-full { + width: 100%; + margin: 2px 0; + padding: 12px; + border-radius: 4px; +} + +/* Button color variations */ +.btn-primary { background: var(--c_btn); } /* Blue - Navigation */ +.btn-success { background: var(--c_btnsv); } /* Green - Save */ +.btn-danger { background: var(--c_btnrst); } /* Red - Reset/Restart */ +.btn-secondary { background: var(--c_btnoff); } /* Gray - Disabled */ +``` + +## Advanced UI Components + +### Range Sliders with Visual Feedback + +```css +.r { + border-radius: 0.3em; + padding: 2px; + margin: 4px 2px; +} +``` + +### Textarea for Console/Logs + +```css +textarea { + resize: vertical; + width: 98%; + height: 318px; + padding: 5px; + overflow: auto; + background: var(--c_bg); + color: var(--c_csltxt); +} +``` + +### Hidden Elements + +```css +.hf { + display: none; +} +``` + +### Utility Classes + +```css +.p { + float: left; + text-align: left; +} + +.q { + float: right; + text-align: right; +} + +a { + color: var(--c_btn); + text-decoration: none; +} + +td { + padding: 0px; +} +``` + +## Best Practices + +### 1. Memory Optimization +- Use inline styles for unique elements +- Minimize JavaScript object creation +- Reuse DOM elements where possible +- Use CSS variables for consistent theming + +### 2. User Experience +- Provide immediate visual feedback for actions +- Use consistent button sizing and spacing +- Implement proper form validation +- Show loading states during operations + +### 3. Accessibility +- Use semantic HTML elements +- Provide proper labels for form controls +- Ensure sufficient color contrast +- Support keyboard navigation + +### 4. Performance +- Minimize HTTP requests +- Use efficient DOM manipulation +- Implement proper error handling +- Cache frequently accessed elements + +### 5. Responsive Design +- Use flexible layouts +- Test on various screen sizes +- Ensure touch-friendly interface +- Provide appropriate viewport settings + +## Integration with Tasmota Backend + +### Command Execution Pattern + +```javascript +// Execute Tasmota command via AJAX +function executeCommand(cmd, params) { + var url = '/?m=1&' + cmd; + if (params) url += '=' + encodeURIComponent(params); + + var xhr = new XMLHttpRequest(); + xhr.open('GET', url, true); + xhr.onreadystatechange = function() { + if (xhr.readyState === 4 && xhr.status === 200) { + // Handle response + updateUI(xhr.responseText); + } + }; + xhr.send(); +} +``` + +### Status Updates + +```javascript +// Auto-refresh status every 400ms +function refreshStatus() { + la(); // Calls the main load function +} + +setInterval(refreshStatus, 400); +``` + +### Form Submission + +```javascript +// Handle form submission with confirmation +function submitForm(formId, confirmMsg) { + if (confirmMsg && !confirm(confirmMsg)) { + return false; + } + document.getElementById(formId).submit(); + return true; +} +``` + +## Visual Design Specifications + +### Layout Dimensions + +Based on the screenshots, the interface uses these key dimensions: + +- **Minimum width**: 340px (as specified in CSS) +- **Button height**: Approximately 48px for touch-friendly interaction +- **Spacing**: 2-4px between elements, larger gaps between sections +- **Border radius**: 4px for buttons and form elements + +### Typography Hierarchy + +```css +/* Device name header */ +h3 { + font-size: 1.2em; + color: var(--c_ttl); + margin: 10px 0; +} + +/* Main title */ +h2 { + font-size: 1.8em; + color: var(--c_ttl); + margin: 5px 0; +} + +/* Status display */ +.status { + font-size: 4em; + font-weight: bold; + text-align: center; +} + +/* Section headers */ +legend { + font-weight: bold; + padding: 0 10px; +} +``` + +### Form Element Styling + +The screenshots show consistent form styling: + +```css +/* Text inputs with proper spacing */ +input[type="text"], input[type="password"] { + padding: 8px; + margin: 4px 0; + border: 1px solid #666; + border-radius: 4px; + background: var(--c_in); + color: var(--c_intxt); +} + +/* Checkboxes with labels */ +input[type="checkbox"] { + margin-right: 8px; + transform: scale(1.2); +} + +/* Radio buttons in groups */ +input[type="radio"] { + margin-right: 8px; + margin-left: 0; +} +``` + +### Matter Protocol Integration + +The screenshots show Matter protocol support with a distinctive icon: + +```html + +``` + +## Common UI Patterns + +### 1. Toggle Buttons +```html + + +``` + +### 2. Configuration Sections +```html +
+  Section Title  + +
+``` + +### 3. Input with Label +```html + +
+ +``` + +### 4. Checkbox with Label +```html + +``` + +### 5. Radio Button Group +```html +
+  Emulation  +

+ +
+ +

+
+``` + +### 6. Password Field with Toggle +```html + +
+ +``` + +### 7. Template Configuration +```html +
+  Template  +

+ +

+

+ +

+
+``` + +### 8. Status Display with Dynamic Updates +```html +
+ OFF +
+ + +``` + +### 9. Color Picker Sliders +```html + + + + + + + + + + + + + + + + + +
+
+ +
+
+
+ +
+
+ + +
+ +
+
+``` + +## Mobile Optimization + +Based on the screenshots, the interface is optimized for mobile devices: + +### Touch-Friendly Design +- **Button height**: Minimum 44px for easy touch interaction +- **Slider handles**: Large enough for finger control +- **Spacing**: Adequate gaps between interactive elements +- **Text size**: Readable on small screens + +### Responsive Layout +```css +@media (max-width: 480px) { + .container { + min-width: 320px; + padding: 10px; + } + + button { + min-height: 44px; + font-size: 16px; /* Prevents zoom on iOS */ + } + + input[type="range"] { + height: 44px; + } +} +``` + +This guide provides the foundation for creating Tasmota-compatible WebUI interfaces that are efficient, user-friendly, and consistent with the existing design system. The visual specifications are based on actual Tasmota WebUI screenshots showing the main control page, configuration forms, and navigation menus. \ No newline at end of file diff --git a/.doc_for_ai/Tasmota configuration menu.png b/.doc_for_ai/Tasmota configuration menu.png new file mode 100644 index 000000000..c2bd7674e Binary files /dev/null and b/.doc_for_ai/Tasmota configuration menu.png differ diff --git a/.doc_for_ai/Tasmota configuration other.png b/.doc_for_ai/Tasmota configuration other.png new file mode 100644 index 000000000..abe707e6f Binary files /dev/null and b/.doc_for_ai/Tasmota configuration other.png differ diff --git a/.doc_for_ai/Tasmota main page.png b/.doc_for_ai/Tasmota main page.png new file mode 100644 index 000000000..b3a185b5b Binary files /dev/null and b/.doc_for_ai/Tasmota main page.png differ