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

cd backend
python -m venv venv
venv\Scripts\activate

b. Install dependencies

pip install -r requirements.txt

c. Setup environment variables

copy .env.example .env
# Edit .env file with your settings

d. Initialize database

python manage.py migrate

e. Create admin user (optional)

python manage.py createsuperuser

f. Run the backend server

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

cd frontend
npm install

b. Setup environment variables

copy .env.example .env
# Ensure VITE_API_URL=http://localhost:8000

c. Start development server

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

cd serial_bridge
python -m venv venv
venv\Scripts\activate

b. Install dependencies

pip install -r requirements.txt

c. Setup environment variables

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

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:

# 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:

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)

SECRET_KEY=your-secret-key-here
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1
DATABASE_URL=sqlite:///db.sqlite3

Frontend (frontend/.env)

VITE_API_URL=http://localhost:8000

Serial Bridge (serial_bridge/.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

# 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

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
• React Docs
• PySerial Docs
• Pystray Docs

Support

For issues, check the logs:

• Backend: Django console output
• Frontend: Browser console (F12)
• Serial Bridge: serial_bridge.log file