scalesApp/SETUP.md

# ScalesApp - Complete Setup & Installation Guide

A three-tier application for reading serial COM port data, storing it in a Django backend, and displaying it in a React frontend.

## Project Structure

```
ScalesApp/
├── frontend/                 # React web application
│   ├── src/
│   ├── public/
│   ├── package.json
│   └── .env.example
├── backend/                  # Django REST API
│   ├── api/                 # Main API app
│   ├── manage.py
│   ├── settings.py
│   ├── requirements.txt
│   └── .env.example
├── serial_bridge/           # Python serial reader (system tray)
│   ├── app.py
│   ├── serial_reader.py
│   ├── tray_icon.py
│   ├── requirements.txt
│   ├── serial_bridge.spec
│   └── .env.example
└── README.md
```

## Prerequisites

- **Python 3.8+** (for Django and Serial Bridge)
- **Node.js 16+** (for React)
- **Windows OS** (Serial Bridge uses Windows-specific system tray)
- A COM port device (scales or serial reader)

## Step-by-Step Installation

### 1. Backend (Django) Setup

#### a. Create virtual environment
```bash
cd backend
python -m venv venv
venv\Scripts\activate
```

#### b. Install dependencies
```bash
pip install -r requirements.txt
```

#### c. Setup environment variables
```bash
copy .env.example .env
# Edit .env file with your settings
```

#### d. Initialize database
```bash
python manage.py migrate
```

#### e. Create admin user (optional)
```bash
python manage.py createsuperuser
```

#### f. Run the backend server
```bash
python manage.py runserver
```

The API will be available at `http://localhost:8000`

**Available API Endpoints:**
- `GET /api/readings/` - List all readings
- `POST /api/readings/` - Create a new reading
- `GET /api/readings/latest/` - Get the latest reading
- `GET /api/readings/by_port/?port=COM1` - Get readings from specific port

### 2. Frontend (React) Setup

#### a. Install dependencies
```bash
cd frontend
npm install
```

#### b. Setup environment variables
```bash
copy .env.example .env
# Ensure VITE_API_URL=http://localhost:8000
```

#### c. Start development server
```bash
npm start
```

The frontend will open at `http://localhost:3000`

**Features:**
- Real-time data display from COM ports
- Port selector for filtering
- Recent readings table
- Auto-refresh every 2 seconds

### 3. Serial Bridge (Python) Setup

#### a. Create virtual environment
```bash
cd serial_bridge
python -m venv venv
venv\Scripts\activate
```

#### b. Install dependencies
```bash
pip install -r requirements.txt
```

#### c. Setup environment variables
```bash
copy .env.example .env
# Edit .env with your COM port and backend URL
```

Key settings:
- `COM_PORT=COM1` (change to your port)
- `BAUD_RATE=9600` (adjust based on your device)
- `BACKEND_URL=http://localhost:8000`

#### d. Run the application
```bash
python app.py
```

The app will:
- Appear in system tray
- Start reading from COM port
- Automatically post data to Django backend
- Retry failed posts
- Log to `serial_bridge.log`

### 4. Running All Services (Development)

Open 3 terminal windows and run:

```bash
# Terminal 1: Backend
cd backend
venv\Scripts\activate
python manage.py runserver

# Terminal 2: Frontend
cd frontend
npm start

# Terminal 3: Serial Bridge
cd serial_bridge
venv\Scripts\activate
python app.py
```

## Building Serial Bridge as EXE

To create a standalone Windows executable that runs in the system tray:

```bash
cd serial_bridge

# Install PyInstaller
pip install pyinstaller

# Build the executable
pyinstaller serial_bridge.spec
```

The executable will be created at `serial_bridge\dist\ScalesApp\ScalesApp.exe`

You can:
- Run it directly
- Add it to Startup folder (`C:\Users\<User>\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup`)
- Create a Windows Task Scheduler entry to run at startup

## Data Flow

```
┌──────────────────┐
│  Physical Device │
│  (Scales/COM)    │
└────────┬─────────┘
         │
         │ Serial data
         ▼
┌──────────────────────────────┐
│  Serial Bridge (Python)      │
│  - Reads COM port            │
│  - System tray app           │
│  - Retry logic               │
└────────┬─────────────────────┘
         │
         │ HTTP POST /api/readings/
         ▼
┌──────────────────────────────┐
│  Django Backend              │
│  - REST API                  │
│  - Database storage          │
│  - CORS enabled              │
└────────┬─────────────────────┘
         │
         │ REST API GET /api/readings/
         ▼
┌──────────────────────────────┐
│  React Frontend              │
│  - Real-time display         │
│  - Port selector             │
│  - Auto-refresh              │
└──────────────────────────────┘
```

## Configuration Files

### Backend (backend/.env)
```env
SECRET_KEY=your-secret-key-here
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1
DATABASE_URL=sqlite:///db.sqlite3
```

### Frontend (frontend/.env)
```env
VITE_API_URL=http://localhost:8000
```

### Serial Bridge (serial_bridge/.env)
```env
COM_PORT=COM1
BAUD_RATE=9600
BACKEND_URL=http://localhost:8000
AUTO_CONNECT=True
DEBUG=False
```

## Troubleshooting

### Backend Issues
- **Port already in use**: Change port: `python manage.py runserver 8001`
- **CORS errors**: Check `ALLOWED_HOSTS` and `CORS_ALLOWED_ORIGINS` in settings.py
- **Database errors**: Run migrations: `python manage.py migrate`

### Frontend Issues
- **Cannot connect to backend**: Ensure Django is running and `VITE_API_URL` is correct
- **Port 3000 in use**: Kill process: `netstat -ano | findstr :3000`

### Serial Bridge Issues
- **COM port not found**: List available ports with: `python -m serial.tools.list_ports`
- **Backend not reachable**: Check `BACKEND_URL` and ensure Django server is running
- **No tray icon**: Run as administrator, check Windows system tray settings
- **Data not posting**: Check `serial_bridge.log` for errors

## Production Deployment

### Backend
```bash
# Use production settings
export DJANGO_SETTINGS_MODULE=scalesapp.settings
python manage.py collectstatic
# Use Gunicorn
pip install gunicorn
gunicorn scalesapp.wsgi -b 0.0.0.0:8000
```

### Frontend
```bash
npm run build
# Serve dist folder with nginx or similar
```

### Serial Bridge
Create Windows Service or Scheduled Task to run the EXE at startup.

## Next Steps

1. ✅ Test all three components locally
2. ✅ Verify data flow from COM → Backend → Frontend
3. ✅ Customize React components if needed
4. ✅ Build Serial Bridge as EXE
5. ✅ Deploy to production servers
6. ✅ Setup monitoring and logging

## Additional Resources

- [Django REST Framework Docs](https://www.django-rest-framework.org/)
- [React Docs](https://react.dev/)
- [PySerial Docs](https://pyserial.readthedocs.io/)
- [Pystray Docs](https://github.com/moses-palmer/pystray)

## Support

For issues, check the logs:
- Backend: Django console output
- Frontend: Browser console (F12)
- Serial Bridge: `serial_bridge.log` file