Add install_everything.sh, update README.md, WIKI.md

This commit is contained in:
2026-03-13 16:03:04 +08:00
parent e72a3ab85c
commit 99f1b3e095
3 changed files with 506 additions and 3 deletions

View File

@@ -49,6 +49,64 @@ From a nondeveloper perspective:
- Lucide is a library of clean, modern icons (like arrows, hearts, or search magnifying glasses). Its the visual garnish that makes apps feel intuitive. - Lucide is a library of clean, modern icons (like arrows, hearts, or search magnifying glasses). Its 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://<your-server>:3000/tck/tck_rtu/install_everything.sh`
## Getting Started ## Getting Started
--- ---
### Prerequisites ### Prerequisites
@@ -108,8 +166,9 @@ The app detects display mode by port:
| Port | Mode | Resolution | | Port | Mode | Resolution |
|------|------|------------| |------|------|------------|
| 8080 | Kiosk | 1024x600 (fixed) | | 8888 | Kiosk | 1024x600 (fixed, for 7" touchscreen) |
| 9090 | Remote | Full HD (responsive) | | 9090 | Remote | Full HD (responsive, for PC access) |
| 5173 | Dev | Development server |
## Bundle Size ## Bundle Size

276
WIKI.md
View File

@@ -1,5 +1,63 @@
# TCK RTU - Technical Documentation # 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 ## 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. 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 | | BatteryStatus | `BatteryStatus.tsx` | Battery voltage with status indicator |
| LoginIndicator | `LoginIndicator.tsx` | Login status display | | 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 ### Data Flow
1. **Sensor Data Collection** 1. **Sensor Data Collection**
@@ -108,12 +193,13 @@ When the API is unavailable, mock data is automatically generated with realistic
## Display Modes ## Display Modes
### Kiosk Mode (Port 8080) ### Kiosk Mode (Port 8888)
- Fixed resolution: 1024x600 - Fixed resolution: 1024x600
- Optimized for 7" touchscreen - Optimized for 7" touchscreen
- Compact layouts with 44px+ touch targets - Compact layouts with 44px+ touch targets
- No scrollbars - navigation buttons instead - No scrollbars - navigation buttons instead
- **Primary mode for local touchscreen display**
### Remote Mode (Port 9090) ### Remote Mode (Port 9090)
@@ -121,6 +207,7 @@ When the API is unavailable, mock data is automatically generated with realistic
- Full HD optimized - Full HD optimized
- Expanded information display - Expanded information display
- Standard scrollbars - Standard scrollbars
- **For remote access via network**
## Navigation ## Navigation
@@ -146,6 +233,19 @@ When the API is unavailable, mock data is automatically generated with realistic
└── LOGIN └── 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 ## State Management
### Zustand Store Structure ### Zustand Store Structure
@@ -267,6 +367,176 @@ python -m http.server 8080
npx serve dist 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://<server-ip>: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 ## Future Phases
### Phase 2: Settings Framework ### Phase 2: Settings Framework
@@ -297,6 +567,10 @@ npx serve dist
- Check backend is running - Check backend is running
- Verify CORS settings - 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 ### Development Tools
- React DevTools - React DevTools

170
install_everything.sh Executable file
View File

@@ -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