# FleetTracker360 / Traccar — GPS Tracking Platform

Traccar open-source GPS tracking server deployed as a Docker container. Tracks phones (iOS Traccar Client) and OBD2 dongles. HERE Maps API for traffic-aware ETAs.

## Architecture

```
iPhone (Traccar Client)  →  Traccar Server (Docker)  →  HERE Maps API (traffic)
OBD2 dongles             →                              →  Sho'Nuff (ETAs, alerts)
Garrison's iPhone        →                              →  Live Dashboard (ops portal)
```

## Traccar Docker Deployment

```bash
# Run Traccar with bundled H2 database (no external DB needed)
docker run -d --restart unless-stopped \
  --name traccar \
  -p 8082:8082 \
  -p 5055:5055 \
  -p 5055:5055/udp \
  -v /opt/traccar/logs:/opt/traccar/logs \
  traccar/traccar:latest
```

| Port | Protocol | Purpose |
|------|----------|---------|
| 8082 | TCP | Web UI + REST API |
| 5055 | TCP/UDP | Device communication (GPS protocols) |

## Traccar REST API

| Endpoint | Method | Returns |
|----------|--------|---------|
| `/api/session` | POST | Login (username, password) |
| `/api/devices` | GET | All registered devices |
| `/api/positions` | GET | Latest positions per device |
| `/api/positions?deviceId=X` | GET | Position history for device |
| `/api/geofence` | GET | Defined geofence zones |
| `/api/notifications` | GET | Push notification rules |
| `/api/reports/route` | POST | Trip history between dates |
| `/api/server` | GET | Server info and settings |

Default credentials: `admin` / `admin`.

## HERE Maps API Integration

HERE API signup: https://developer.here.com/

| Feature | Free Tier | Endpoint |
|---------|-----------|----------|
| Geocoding | 250k/mo | `GET https://geocode.search.hereapi.com/v1/geocode` |
| Routing with traffic | 250k/mo | `GET https://router.hereapi.com/v8/routes` |
| Reverse geocode | 250k/mo | `GET https://revgeocode.search.hereapi.com/v1/revgeocode` |

### ETA Calculation Flow

```python
# 1. Get current position from Traccar
# GET /api/positions?deviceId=1 → {latitude, longitude}

# 2. Reverse geocode to address (optional)
# GET https://revgeocode.search.hereapi.com/v1/revgeocode?at={lat},{lng}&apikey={key}

# 3. Route to destination with traffic
# GET https://router.hereapi.com/v8/routes?origin={lat},{lng}&destination={address}&transportMode=car&traffic=enabled&apikey={key}
# → Returns travelTime (with traffic) and travelTimeWithoutTraffic
```

### ETA Query from Sho'Nuff

```python
# When Master asks "how long to home?"
position = traccar_api.get_latest_position("Germaine's iPhone")
home = geocode("Savannah, GA")
route = here_api.route(position, home, traffic=True)
# → "34 min via I-95 S (traffic normal). Without traffic: 28 min."
```

## iOS Traccar Client Setup

1. Install "Traccar Client" from App Store
2. Server URL: `http://fleettracker360.com:5055` (or whatever the deployed domain/port is)
3. Device identifier: any name (e.g., "Germaine's iPhone")
4. Enable background location updates
5. Client sends periodic GPS pings to the Traccar server

## OBD2 Dongle Pairing

Traccar supports 200+ GPS protocols. Most OBD2 dongles speak one of:
- TK103
- GPS103
- GL200
- GT06
- Oscium

Configure in Traccar: add a new device, select the protocol matching the dongle, enter the IMEI/serial.

## Dashboard Concept

The FleetTracker360 live dashboard at `ops.itpropartner.com/fleettracker360.html` shows:
- Hero location card (current position, speed, heading)
- ETA grid to saved locations (Home, Office, School, Gym)
- Vehicle telemetry (speed, RPM, fuel, battery, engine codes)
- Daily trip stats (miles, steps, time)
- Alert feed (arrivals, departures, geofence crossings)
- Mini map with breadcrumb trail
- Device status row (phones, vehicles)

## Subscription Selling Model

Multi-user Traccar instance with per-vehicle pricing. Use HERE Maps free tier (250k/mo) for initial deployments. Upgrade to paid HERE plan only when fleet exceeds traffic limits.

Project folder: `/root/projects/fleettracker/`
Domain: `fleettracker360.com` (Cloudflare proxied)