Bikun Tracker Live Location

Real-time bus location tracking service for PERUM DAMRI fleet monitoring using WebSocket technology and Redis pub/sub.

🏗️ Architecture

🔐 Environment Variables

Master Service

Variable	Description	Expected Format
REDIS_HOST	Redis server hostname	IP/hostname
REDIS_PORT	Redis server port	Integer (default: 6379)
REDIS_PASSWORD	Redis authentication password	String
MCEASY_API_TOKEN	MCEasy API authentication token	Bearer token

Slave Service

Variable	Description	Expected Format
REDIS_HOST	Redis server hostname	IP/hostname
REDIS_PORT	Redis server port	Integer (default: 6379)
REDIS_PASSWORD	Redis authentication password	String

📁 Project Structure

bikun-location-service/
├── master/              # Vehicle data polling service
│   ├── src/app/
│   │   └── main.py     # Polls MCEasy API and publishes to Redis
│   └── .env
├── slave/              # WebSocket broadcast service
│   ├── src/app/
│   │   └── main.py     # Subscribes to Redis and broadcasts to clients
│   └── .env
└── client/             # Web dashboard
    ├── src/
    │   ├── main.ts
    │   └── index.css
    ├── index.html      # Real-time fleet monitoring dashboard
    └── package.json

🚀 Components

Master Service (master/src/app/main.py)

• Polls MCEasy API for vehicle locations and status
• Implements adaptive polling rate (0.1s - 60.0s) based on data changes
• Publishes updates to Redis channel "bikun"
• Uses bearer token authentication for API access

Slave Service (slave/src/app/main.py)

• FastAPI WebSocket server
• Subscribes to Redis channel "bikun"
• Maintains active WebSocket connections
• Broadcasts vehicle updates to all connected clients
• Implements connection management and error handling

Web Client (client/index.html)

• Real-time fleet monitoring dashboard
• Connects to WebSocket endpoint for live updates
• Features:
  • Connection status indicator
  • Fleet statistics
  • Individual vehicle cards with:
    • Location coordinates
    • Motion status
    • Speed and direction
    • Signal strength
    • Engine status
    • Trip metrics

🔄 Data Flow

🛠️ Setup and Development

1. Configure environment variables in .env files for both master and slave services

2. Start the master service:

cd master
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python src/app/main.py

3. Start the slave service:

cd slave
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn src.app.main:app --reload

4. Start the web client:

cd client
pnpm install
pnpm dev

📡 WebSocket API

/status Endpoint

• URL: ws://localhost:8000/status
• Protocol: WebSocket
• Response Format:

interface VehicleData {
    vehicleId: string;
    licensePlate: string;
    latitude: number;
    longitude: number;
    speed: number;
    direction: number;
    motionStatus: 'P' | 'O' | 'I'; // Parked, Online, Idle
    signalStrength: number;
    engineOn: boolean;
    sumDistance: number;
    sumDrivetimeFormatted: string;
    tripMaxspeed: number;
    lastReceive: string;
    imei: string;
}