Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

F Location

F Location is a comprehensive location tracking application built on Frappe framework, designed to track real-time locations of Customers, Employees, and Suppliers with interactive map visualization.

Features

Core Location Tracking

  • Dynamic Reference Support: Track locations for Customers, Employees, or Suppliers using dynamic links
  • Real-time Location Tracking: Enable/disable location tracking per user with checkbox control
  • Current & Target Locations: Store both current position and target destination coordinates
  • Interactive Map View: Web-based map interface powered by Leaflet.js
  • Route Visualization: Display route between current location and target when both are provided
  • User Details on Hover: View summary information by hovering over map markers
  • Flexible Display Names: Custom display names for easy identification
  • Geolocation Support: Built-in browser geolocation integration for easy location updates

Real-time Updates with Redis & WebSocket

  • Socket.IO Integration: Real-time location updates using Frappe's Socket.IO with Redis backend
  • Live Map Updates: Map markers update automatically when locations change
  • Broadcast Updates: Location changes are pushed to all connected clients instantly
  • Background Workers: Scheduled tasks for periodic location broadcasting and stale location checks

Mobile Location Sharing

  • Dedicated Mobile Page: Mobile-optimized page at /share-location for continuous location sharing
  • Configurable Update Interval: Adjust update frequency from 10 seconds to 5 minutes
  • High Accuracy GPS: Toggle high-accuracy mode for better location precision
  • Keep Screen On: Wake Lock API support to prevent screen from sleeping during tracking
  • Battery Efficient: Optimized for mobile devices with configurable update intervals

Location History

  • Historical Tracking: Automatically save all location updates with timestamps
  • Track Movement Paths: View historical routes and movement patterns
  • Detailed Metrics: Store accuracy, altitude, speed, and heading information
  • Data Retention: Configurable cleanup of old location history records

Geofencing

  • Virtual Boundaries: Create circular geofences around specific locations
  • Entry/Exit Detection: Automatic detection when trackers enter or exit geofences
  • Smart Notifications: Email and in-app notifications for geofence events
  • Custom Alerts: Configure separate notifications for entry and exit events
  • Multiple Geofences: Support for multiple geofences per location tracker

Mobile App Integration

  • REST API: Complete RESTful API for mobile app integration
  • Batch Updates: Support for batch location updates to reduce API calls
  • GPS Metadata: Track accuracy, altitude, speed, and heading from GPS devices
  • Nearby Search: Find trackers within a specified radius
  • Quick Tracker Creation: API endpoint for programmatic tracker creation

DocTypes

Location Tracker

The main DocType for tracking user locations:

  • Enable Location Tracking: Checkbox to enable/disable tracking
  • Reference Type: Link to DocType (Customer/Employee/Supplier)
  • Reference Name: Dynamic link to the selected reference type
  • Display Name: Custom name for display purposes
  • Current Latitude/Longitude: Current location coordinates
  • Target Latitude/Longitude: Target destination coordinates (optional)
  • Summary Details: Additional information displayed in map popups

Location History

Automatically tracks historical location data:

  • Location Tracker: Link to Location Tracker
  • Latitude/Longitude: Location coordinates
  • Timestamp: When location was recorded
  • Accuracy: GPS accuracy in meters
  • Altitude: Altitude in meters
  • Speed: Speed in m/s
  • Heading: Direction in degrees
  • Recorded By: User who recorded the location

Geofence

Define virtual boundaries and trigger alerts:

  • Geofence Name: Unique name for the geofence
  • Type: Circular (polygon support coming soon)
  • Location Tracker: Optional link to specific tracker
  • Center Latitude/Longitude: Center point of circular geofence
  • Radius: Radius in meters
  • Notify on Entry/Exit: Toggle notifications
  • Notification Emails: Comma-separated email addresses
  • Notification Users: Comma-separated usernames for in-app alerts

Web Pages

Location Map (/location-map)

Interactive map for viewing all tracked locations:

  • View all tracked users on a single map
  • Select individual users to view their location and route
  • See target routes when destination coordinates are provided
  • Hover over markers to view user summary details
  • Real-time updates via WebSocket (no manual refresh needed)
  • Automatic marker animation when locations update

Share Location (/share-location)

Mobile-optimized page for sharing your location:

  • Select your location tracker
  • Start/stop location sharing with one tap
  • Configure update interval (10s - 5 minutes)
  • Toggle high-accuracy GPS mode
  • Keep screen on during tracking
  • View real-time statistics (coordinates, accuracy, update count)
  • Battery-efficient with configurable intervals

Installation

You can install this app using the bench CLI:

cd $PATH_TO_YOUR_BENCH
bench get-app $URL_OF_THIS_REPO --branch develop
bench install-app f_location

Usage

1. Create Location Trackers

  • Navigate to Location Tracker list
  • Create a new Location Tracker
  • Select Reference Type (Customer, Employee, or Supplier)
  • Select the specific reference (e.g., a specific customer)
  • Enter a Display Name
  • Check "Enable Location Tracking"
  • Use "Get Current Location" button to auto-fill coordinates
  • Optionally add Target Latitude/Longitude for destination
  • Add Summary Details for additional information

2. View on Map

  • Access the map at /location-map or click "View on Map" from any Location Tracker
  • Use the dropdown to select a specific user or view all users
  • Click markers to see popup with user details
  • When target location is set, a route line will be displayed
  • Real-time updates appear automatically (no refresh needed)

3. Share Your Location (Mobile)

  • Visit /share-location on your mobile device
  • Select your tracker from the dropdown
  • Click "Start Sharing Location"
  • Adjust update interval as needed
  • The app will continuously send your GPS location to the server

4. Set Up Geofences

  • Create a new Geofence document
  • Enter a name and select "Circular" type
  • Set center coordinates (latitude/longitude)
  • Define radius in meters
  • Optionally link to specific Location Tracker
  • Enable "Notify on Entry" and/or "Notify on Exit"
  • Add notification emails or usernames
  • When a tracker enters/exits the geofence, alerts will be sent automatically

5. View Location History

  • Open any Location Tracker
  • View linked Location History records
  • Filter by date range to see movement patterns
  • Export historical data for analysis

API Reference

Location Tracker API

get_all_locations()

Returns all enabled location trackers with their current positions.

frappe.call({
    method: 'f_location.f_location.doctype.location_tracker.location_tracker.get_all_locations',
    callback: function(r) {
        console.log(r.message);
    }
});

get_location(tracker_name)

Get detailed location information for a specific tracker.

frappe.call({
    method: 'f_location.f_location.doctype.location_tracker.location_tracker.get_location',
    args: { tracker_name: 'John Doe' },
    callback: function(r) {
        console.log(r.message);
    }
});

update_current_location(tracker_name, latitude, longitude)

Update the current location of a tracker (basic method).

frappe.call({
    method: 'f_location.f_location.doctype.location_tracker.location_tracker.update_current_location',
    args: {
        tracker_name: 'John Doe',
        latitude: 28.6139,
        longitude: 77.2090
    }
});

Mobile API

update_location_from_mobile(location_tracker, latitude, longitude, **kwargs)

Advanced location update with GPS metadata and geofence checking.

frappe.call({
    method: 'f_location.api.update_location_from_mobile',
    args: {
        location_tracker: 'John Doe',
        latitude: 28.6139,
        longitude: 77.2090,
        accuracy: 10.5,
        altitude: 250.0,
        speed: 5.2,
        heading: 180.0
    },
    callback: function(r) {
        if (r.message.success) {
            console.log('Geofences:', r.message.geofences);
        }
    }
});

batch_update_locations(updates)

Update multiple locations in a single API call.

frappe.call({
    method: 'f_location.api.batch_update_locations',
    args: {
        updates: [
            { location_tracker: 'Tracker 1', latitude: 28.6139, longitude: 77.2090 },
            { location_tracker: 'Tracker 2', latitude: 19.0760, longitude: 72.8777 }
        ]
    }
});

get_nearby_trackers(latitude, longitude, radius_km)

Find all trackers within a specified radius.

frappe.call({
    method: 'f_location.api.get_nearby_trackers',
    args: {
        latitude: 28.6139,
        longitude: 77.2090,
        radius_km: 10
    },
    callback: function(r) {
        console.log('Nearby trackers:', r.message);
    }
});

get_tracker_status(location_tracker)

Get detailed status including last update time and GPS metrics.

frappe.call({
    method: 'f_location.api.get_tracker_status',
    args: { location_tracker: 'John Doe' }
});

create_location_tracker_quick(reference_type, reference_name, display_name, auto_enable)

Quickly create a new location tracker programmatically.

frappe.call({
    method: 'f_location.api.create_location_tracker_quick',
    args: {
        reference_type: 'Employee',
        reference_name: 'EMP-001',
        display_name: 'John Doe',
        auto_enable: true
    }
});

Location History API

get_location_history(location_tracker, limit, from_date, to_date)

Retrieve historical location data.

frappe.call({
    method: 'f_location.f_location.doctype.location_history.location_history.get_location_history',
    args: {
        location_tracker: 'John Doe',
        limit: 100,
        from_date: '2025-01-01',
        to_date: '2025-01-31'
    }
});

get_location_path(location_tracker, from_date, to_date)

Get location path coordinates for drawing routes on maps.

frappe.call({
    method: 'f_location.f_location.doctype.location_history.location_history.get_location_path',
    args: { location_tracker: 'John Doe' },
    callback: function(r) {
        // Returns array of [lat, lng] coordinates
        var path = L.polyline(r.message, {color: 'blue'}).addTo(map);
    }
});

Geofence API

get_geofences_for_map()

Get all geofences for map visualization.

frappe.call({
    method: 'f_location.f_location.doctype.geofence.geofence.get_geofences_for_map',
    callback: function(r) {
        r.message.forEach(function(geofence) {
            // Draw geofence circles on map
            L.circle([geofence.center_latitude, geofence.center_longitude], {
                radius: geofence.radius_meters
            }).addTo(map);
        });
    }
});

Real-time Events

The application uses Frappe's Socket.IO with Redis for real-time updates. Subscribe to these events:

location_update

Triggered when any location tracker is updated.

frappe.realtime.on('location_update', function(data) {
    console.log('Location updated:', data.display_name);
    // Update UI with new location
});

geofence_alert

Triggered when a tracker enters or exits a geofence.

frappe.realtime.on('geofence_alert', function(data) {
    console.log('Geofence event:', data.event_type);
    frappe.show_alert({
        message: data.subject,
        indicator: 'orange'
    });
});

Background Tasks

The following scheduled tasks run automatically:

  • Every 5 minutes: Broadcast all current locations to connected clients
  • Hourly: Check for stale location trackers (no update in 2+ hours)
  • Daily: Clean up old location history records (default: 90 days retention)

Configure retention period in System Settings or modify in tasks.py.

Contributing

This app uses pre-commit for code formatting and linting. Please install pre-commit and enable it for this repository:

cd apps/f_location
pre-commit install

Pre-commit is configured to use the following tools for checking and formatting your code:

  • ruff
  • eslint
  • prettier
  • pyupgrade

License

gpl-3.0

F-Location

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages