From 99f1b3e09514c94f1b1f538687c72e75a4e80389 Mon Sep 17 00:00:00 2001 From: admin Date: Fri, 13 Mar 2026 16:03:04 +0800 Subject: [PATCH] Add install_everything.sh, update README.md, WIKI.md --- README.md | 63 +++++++++- WIKI.md | 276 +++++++++++++++++++++++++++++++++++++++++- install_everything.sh | 170 ++++++++++++++++++++++++++ 3 files changed, 506 insertions(+), 3 deletions(-) create mode 100755 install_everything.sh diff --git a/README.md b/README.md index 51d136a8d..733eb8b02 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,64 @@ From a non‑developer perspective: - Lucide is a library of clean, modern icons (like arrows, hearts, or search magnifying glasses). It’s the visual garnish that makes apps feel intuitive. +## Quick Start (One-Line Install) + +### From Web (on Raspberry Pi with network access) + +```bash +# Option 1: Direct clone and run +git clone https://github.com/your-repo/tck_rtu.git /opt/tck_rtu +cd /opt/tck_rtu +./install_everything.sh + +# Option 2: From custom web server +# Place install_everything.sh on your web server at: +# http://tckrtuiyo:3000/tck/tck_rtu/install_everything.sh +# Then run: +curl -sL http://tckrtuiyo:3000/tck/tck_rtu/install_everything.sh | bash + +# Option 3: From GitHub raw (replace with actual repo URL) +curl -sL https://raw.githubusercontent.com/your-repo/main/install_everything.sh | bash +``` + +### Manual Install + +```bash +# 1. Clone repository +git clone https://github.com/your-repo/tck_rtu.git /opt/tck_rtu +cd /opt/tck_rtu + +# 2. Install Node.js (if not installed) +curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash - +sudo apt-get install -y nodejs + +# 3. Install dependencies +cd sample_interface +npm install + +# 4. Run +cd .. +./start.sh +``` + +### Web Server Setup (for Option 2) + +If you want to serve the install script from a local web server: + +```bash +# Place the script in your web root +sudo cp install_everything.sh /var/www/html/tck/tck_rtu/ + +# Start nginx +sudo systemctl start nginx + +# Or use Python +cd /var/www/html/tck/tck_rtu +python3 -m http.server 3000 +``` + +Then access via: `http://:3000/tck/tck_rtu/install_everything.sh` + ## Getting Started --- ### Prerequisites @@ -108,8 +166,9 @@ The app detects display mode by port: | Port | Mode | Resolution | |------|------|------------| -| 8080 | Kiosk | 1024x600 (fixed) | -| 9090 | Remote | Full HD (responsive) | +| 8888 | Kiosk | 1024x600 (fixed, for 7" touchscreen) | +| 9090 | Remote | Full HD (responsive, for PC access) | +| 5173 | Dev | Development server | ## Bundle Size diff --git a/WIKI.md b/WIKI.md index 1a5064858..7394482bf 100644 --- a/WIKI.md +++ b/WIKI.md @@ -1,5 +1,63 @@ # TCK RTU - Technical Documentation +## Table of Contents + +- [Overview](#overview) +- [System Architecture](#system-architecture) + - [Hardware Requirements](#hardware-requirements) + - [Software Architecture](#software-architecture) +- [Components](#components) + - [Dashboard Components](#dashboard-components) + - [View Components](#view-components) + - [Data Flow](#data-flow) +- [API Client](#api-client) + - [Endpoint](#endpoint) + - [Response Format](#response-format) + - [Mock Data](#mock-data) +- [Display Modes](#display-modes) + - [Kiosk Mode (Port 8888)](#kiosk-mode-port-8888) + - [Remote Mode (Port 9090)](#remote-mode-port-9090) +- [Navigation](#navigation) + - [Menu Structure](#menu-structure) + - [View Components List](#view-components-list) +- [State Management](#state-management) + - [Zustand Store Structure](#zustand-store-structure) + - [Usage](#usage) +- [Testing](#testing) + - [Test Infrastructure](#test-infrastructure) + - [Running Tests](#running-tests) + - [Test Structure](#test-structure) +- [Performance](#performance) + - [Bundle Size Targets](#bundle-size-targets) + - [Optimizations](#optimizations) + - [Performance Tips](#performance-tips) +- [Deployment](#deployment) + - [Build](#build) + - [Output](#output) + - [Production Server](#production-server) +- [Start Script](#start-script) + - [Usage](#start-script-usage) + - [Options](#start-script-options) +- [Installation Script](#installation-script) + - [Quick Install](#quick-install) + - [Web Server Setup](#web-server-setup) + - [Manual Install](#manual-install) +- [UI Design Decisions](#ui-design-decisions) + - [Layout Principles](#layout-principles) + - [Touch Targets](#touch-targets) + - [Color Scheme](#color-scheme) +- [User Flow](#user-flow) + - [Kiosk Mode Flow](#kiosk-mode-flow) + - [Navigation Buttons](#navigation-buttons) +- [Future Phases](#future-phases) + - [Phase 2: Settings Framework](#phase-2-settings-framework) + - [Phase 3: Data Management & Network Stack](#phase-3-data-management--network-stack) +- [Troubleshooting](#troubleshooting) + - [Common Issues](#common-issues) + - [Development Tools](#development-tools) + +--- + ## Overview TCKRTUIYO is a web-based interface for Base Station/Real-Time Unit (RTU) monitoring rainfall and related sensors. The system is designed to run on Raspberry Pi Zero 2 W with a 7" capacitive touchscreen display. @@ -46,6 +104,33 @@ TCKRTUIYO is a web-based interface for Base Station/Real-Time Unit (RTU) monitor | BatteryStatus | `BatteryStatus.tsx` | Battery voltage with status indicator | | LoginIndicator | `LoginIndicator.tsx` | Login status display | +### View Components + +| View | File | Description | +|------|------|-------------| +| Dashboard | `DashboardView.tsx` | Main rainfall monitoring display | +| Graph | `GraphView.tsx` | Data visualization with charts | +| Utility | `UtilityView.tsx` | Additional utility functions | +| Calibration | `CalibrationView.tsx` | Sensor calibration interface | +| FlashMemory | `FlashMemoryView.tsx` | Data storage management | +| Setting | `SettingView.tsx` | Main settings hub | +| Login | `LoginView.tsx` | Authentication interface | + +### Settings Sub-Views + +| Setting | File | Description | +|---------|------|-------------| +| Station Info | `StationInfoView.tsx` | Station ID, version info | +| Date/Time | `DateTimeSettingView.tsx` | Date, time, timezone configuration | +| Mobile | `MobileSettingView.tsx` | Mobile network (SIM) settings | +| ADC | `ADCSettingView.tsx` | ADC calibration | +| Rainfall | `RainfallSettingView.tsx` | Rainfall sensor settings | +| EVAP | `EVAPSettingView.tsx` | Evaporation sensor settings | +| GPRS | `GPRSSettingView.tsx` | GPRS configuration | +| Level | `LevelSettingView.tsx` | Water level sensor settings | +| Siren | `SirenSettingView.tsx` | Alarm/siren configuration | +| Network | `NetworkSettingView.tsx` | WiFi/Ethernet settings | + ### Data Flow 1. **Sensor Data Collection** @@ -108,12 +193,13 @@ When the API is unavailable, mock data is automatically generated with realistic ## Display Modes -### Kiosk Mode (Port 8080) +### Kiosk Mode (Port 8888) - Fixed resolution: 1024x600 - Optimized for 7" touchscreen - Compact layouts with 44px+ touch targets - No scrollbars - navigation buttons instead +- **Primary mode for local touchscreen display** ### Remote Mode (Port 9090) @@ -121,6 +207,7 @@ When the API is unavailable, mock data is automatically generated with realistic - Full HD optimized - Expanded information display - Standard scrollbars +- **For remote access via network** ## Navigation @@ -146,6 +233,19 @@ When the API is unavailable, mock data is automatically generated with realistic └── LOGIN ``` +### View Components List + +All views are located in `sample_interface/src/app/components/views/`: + +- `DashboardView.tsx` - Main rainfall dashboard +- `GraphView.tsx` - Data visualization with chart +- `UtilityView.tsx` - Utility functions hub +- `CalibrationView.tsx` - Sensor calibration +- `FlashMemoryView.tsx` - File management +- `SettingView.tsx` - Settings hub (side-by-side Display & System settings) +- `LoginView.tsx` - Login interface +- Settings sub-views (StationInfo, DateTime, Mobile, ADC, Rainfall, EVAP, GPRS, Level, Siren, Network) + ## State Management ### Zustand Store Structure @@ -267,6 +367,176 @@ python -m http.server 8080 npx serve dist ``` +## Start Script + +The `start.sh` script provides an interactive menu for common development commands. + +### Usage + +```bash +./start.sh [option] +``` + +### Options + +| Option | Description | +|--------|-------------| +| `1` or `dev` | Start dev server (port 5173) | +| `2` or `dev:8888` | Start dev server on port 8888 (kiosk mode) | +| `3` or `dev:9090` | Start dev server on port 9090 (remote mode) | +| `4` or `test` | Run tests | +| `5` or `test:watch` | Run tests in watch mode | +| `6` or `build` | Build for production | +| `7` or `preview` | Preview production (port 4173) | +| `8` or `lint` | Run linter | +| `9` or `clean` | Clean build artifacts | +| `10` or `install` | Install dependencies | +| `p` or `port` | Change default ports | +| `0` or `exit` | Exit | + +**Note**: Port 8888 is recommended for kiosk mode (7" touchscreen), port 9090 for remote access. + +## Installation Script + +The `install_everything.sh` script automates the entire installation process including: +- Installing system dependencies (curl, git, nginx) +- Installing Node.js 20.x +- Cloning the repository +- Installing npm dependencies +- Starting the application + +### Quick Install + +```bash +# Option 1: Clone and run locally +git clone https://github.com/your-repo/tck_rtu.git /opt/tck_rtu +cd /opt/tck_rtu +./install_everything.sh + +# Option 2: From web server (see below) +curl -sL http://tckrtuiyo:3000/tck/tck_rtu/install_everything.sh | bash + +# Option 3: From GitHub raw +curl -sL https://raw.githubusercontent.com/your-repo/main/install_everything.sh | bash +``` + +### Web Server Setup + +To serve the install script from a local web server for Option 2: + +```bash +# Method 1: Using Python (simple) +sudo mkdir -p /var/www/html/tck/tck_rtu +sudo cp install_everything.sh /var/www/html/tck/tck_rtu/ +cd /var/www/html/tck/tck_rtu +sudo python3 -m http.server 3000 + +# Method 2: Using nginx +sudo cp install_everything.sh /var/www/html/tck/tck_rtu/ +sudo systemctl start nginx + +# Access via: +# http://:3000/tck/tck_rtu/install_everything.sh +# or +# http://tckrtuiyo:80/tck/tck_rtu/install_everything.sh +``` + +### Manual Install + +If you prefer to install manually: + +```bash +# 1. Install system dependencies (as root) +sudo apt-get update +sudo apt-get install -y curl git nginx + +# 2. Install Node.js 20.x +curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash - +sudo apt-get install -y nodejs + +# 3. Clone repository +sudo mkdir -p /opt +sudo git clone https://github.com/your-repo/tck_rtu.git /opt/tck_rtu + +# 4. Install dependencies +cd /opt/tck_rtu/sample_interface +sudo npm install + +# 5. Run +cd /opt/tck_rtu +sudo ./start.sh +``` + +## UI Design Decisions + +### Layout Principles + +1. **Vertical Stacking**: Information flows top-to-bottom +2. **Controls at Bottom**: Interactive elements (buttons, inputs) placed at bottom for easy thumb access +3. **Summary at Top**: Key metrics and visualizations at top +4. **No Scrolling**: All content fits within 1024x600 viewport + +### Touch Targets + +- Minimum touch target: 44x44px +- Spacing between targets: 8px minimum +- Navigation buttons placed next to titles (not just in header) + +### Color Scheme + +- **Background**: Dark gray (#1a1a2e, #16213e) +- **Cards**: Slightly lighter gray (#0f3460, #1f4068) +- **Primary Accent**: Blue (#4d96ff, #3a86ff) +- **Text**: White/light gray for contrast +- **Status Colors**: + - Green: Good/normal + - Yellow/Orange: Warning + - Red: Critical/alert + +## User Flow + +### Kiosk Mode Flow + +1. **Boot**: System starts, Chromium launches in kiosk mode +2. **Load**: App loads at http://localhost:8888 +3. **Dashboard**: Shows rainfall data, clock, battery, signal +4. **Navigate**: Use side buttons to switch views +5. **Interact**: Touch screen for settings/siren tests + +### Navigation Buttons + +- **Horizontal placement**: Next to view titles (not just in header) +- **Clear labeling**: Icon + text for clarity +- **Consistent position**: Same location across all views + +**Graph View Layout** (example): +``` +┌─────────────────────────────────────┐ +│ [Icon] Graph View [↑] [↓] │ <- Header with nav buttons +├─────────────────────────────────────┤ +│ Time Range | Data Pts | Avg Value │ <- Summary at top +├─────────────────────────────────────┤ +│ │ +│ Data Visualization │ <- Chart at bottom +│ │ +└─────────────────────────────────────┘ +``` + +**Settings View Layout** (example): +``` +┌─────────────────────────────────────┐ +│ [Icon] Setting [←] [→] │ +├─────────────────────────────────────┤ +│ Display Settings │ System Settings│ <- Side-by-side +├─────────────────────────────────────┤ +│ Date │ Time │ Timezone │ <- Horizontal +├─────────────────────────────────────┤ +│ Phone Number │ APN │ <- Horizontal (Mobile) +├─────────────────────────────────────┤ +│ Enable EVAP │ Pan Coef │ Interval │ <- Horizontal (EVAP) +└─────────────────────────────────────┘ +``` + ## Future Phases ### Phase 2: Settings Framework @@ -297,6 +567,10 @@ npx serve dist - Check backend is running - Verify CORS settings +4. **Dev server wrong port** + - Use `--port` flag: `npm run dev -- --port 8888` + - Not `VITE_PORT=8888` (doesn't work with npm) + ### Development Tools - React DevTools diff --git a/install_everything.sh b/install_everything.sh new file mode 100755 index 000000000..07a00ef4d --- /dev/null +++ b/install_everything.sh @@ -0,0 +1,170 @@ +#!/bin/bash + +# TCK RTU - Install Everything Script +# This script installs all prerequisites and starts the application +# Usage: bash <(curl -sL https://raw.githubusercontent.com/REPO_URL/main/install_everything.sh) +# Or: ./install_everything.sh + +set -e + +# Colors +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +CYAN='\033[0;36m' +NC='\033[0m' +BOLD='\033[1m' + +echo -e "${CYAN}${BOLD}" +echo "╔══════════════════════════════════════════════════════╗" +echo "║ TCK RTU - Automated Installation Script ║" +echo "╚══════════════════════════════════════════════════════╝" +echo -e "${NC}" + +# Configuration +APP_DIR="/opt/tck_rtu" +REPO_URL="${REPO_URL:-https://github.com/your-repo/tck_rtu.git}" + +# Detect if running as root +if [ "$EUID" -eq 0 ]; then + IS_ROOT=true +else + IS_ROOT=false +fi + +# Function to install system dependencies +install_system_deps() { + echo -e "${BLUE}[1/5] Installing system dependencies...${NC}" + + if command -v apt-get &> /dev/null; then + # Debian/Ubuntu + if [ "$IS_ROOT" = true ]; then + apt-get update + apt-get install -y curl git nginx + else + echo -e "${YELLOW}Not running as root. System deps must be installed manually:${NC}" + echo " sudo apt-get update" + echo " sudo apt-get install -y curl git nginx" + fi + elif command -v yum &> /dev/null; then + # RHEL/CentOS + if [ "$IS_ROOT" = true ]; then + yum install -y curl git nginx + else + echo -e "${YELLOW}Not running as root. Run manually: sudo yum install -y curl git nginx${NC}" + fi + elif command -v pacman &> /dev/null; then + # Arch + if [ "$IS_ROOT" = true ]; then + pacman -S --noconfirm curl git nginx + else + echo -e "${YELLOW}Not running as root. Run manually: sudo pacman -S --noconfirm curl git nginx${NC}" + fi + fi + + echo -e "${GREEN}System dependencies check complete.${NC}" +} + +# Function to install Node.js +install_node() { + echo -e "${BLUE}[2/5] Installing Node.js...${NC}" + + if command -v node &> /dev/null; then + NODE_VERSION=$(node -v) + echo -e "${GREEN}Node.js already installed: $NODE_VERSION${NC}" + return + fi + + if [ "$IS_ROOT" = true ]; then + curl -fsSL https://deb.nodesource.com/setup_20.x | bash - + apt-get install -y nodejs + else + echo -e "${YELLOW}Node.js not found. Please install manually:${NC}" + echo " curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -" + echo " sudo apt-get install -y nodejs" + fi + + echo -e "${GREEN}Node.js installation complete.${NC}" +} + +# Function to clone or update repository +setup_repo() { + echo -e "${BLUE}[3/5] Setting up repository...${NC}" + + if [ -d "$APP_DIR" ]; then + echo -e "${YELLOW}Directory $APP_DIR already exists. Updating...${NC}" + cd "$APP_DIR" + git pull origin main 2>/dev/null || git pull + else + echo -e "Cloning repository to $APP_DIR..." + if [ "$IS_ROOT" = true ]; then + mkdir -p "$APP_DIR" + git clone "$REPO_URL" "$APP_DIR" + else + echo -e "${YELLOW}Cannot create $APP_DIR without root. Using current directory.${NC}" + if [ ! -d "sample_interface" ]; then + echo "Please ensure the repository is cloned first." + exit 1 + fi + APP_DIR=$(pwd) + fi + fi + + cd "$APP_DIR" + echo -e "${GREEN}Repository setup complete.${NC}" +} + +# Function to install npm dependencies +install_npm_deps() { + echo -e "${BLUE}[4/5] Installing npm dependencies...${NC}" + + if [ ! -d "$APP_DIR/sample_interface" ]; then + echo -e "${RED}Error: sample_interface not found in $APP_DIR${NC}" + exit 1 + fi + + cd "$APP_DIR/sample_interface" + + if [ -d "node_modules" ]; then + echo -e "${YELLOW}node_modules exists. Updating...${NC}" + npm update + else + npm install + fi + + echo -e "${GREEN}NPM dependencies installed.${NC}" +} + +# Function to start the application +start_app() { + echo -e "${BLUE}[5/5] Starting application...${NC}" + echo "" + + cd "$APP_DIR" + + # Make start.sh executable + chmod +x start.sh + + echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" + echo -e "${GREEN}Installation complete!${NC}" + echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" + echo "" + echo -e "Starting TCK RTU menu..." + echo "" + + # Run start.sh + ./start.sh +} + +# Main execution +main() { + install_system_deps + install_node + setup_repo + install_npm_deps + start_app +} + +# Run main +main