Jump AAR Plugin for TAK Server

A Java-based TAK Server plugin that provides After Action Review (AAR) functionality for jump detection and GPS track analysis. This plugin replaces the existing Python-based AAR system with a robust Java implementation that integrates directly with the TAK Server's PostgreSQL database.

Features

• Direct PostgreSQL Integration: Connects to TAK Server's cot_router table to extract GPS data
• Jump Detection: Implements sophisticated jump detection algorithms for ATOS devices
• REST API: Provides comprehensive REST endpoints for data retrieval and analysis
• Group Analysis: Supports group-based AAR with member aggregation
• Configurable Thresholds: Dynamic jump detection parameters via JSON configuration
• Real-time Data: Pulls live data from TAK Server's CoT message history
• HTML Compatibility: JSON responses compatible with existing CesiumJS visualizations

Prerequisites

• TAK Server 4.x or later
• PostgreSQL database with TAK Server schema
• Java 11 or later
• Maven 3.6 or later

Database Configuration

The plugin connects to the TAK Server's PostgreSQL database using these default settings:

• Host: 127.0.0.1
• Port: 5432
• Database: cot
• Username: martiuser
• Password: TNAkHFxiSOiqCM2R

The plugin reads from the following key tables:

• cot_router: Main CoT message table with GPS coordinates and metadata
• tak_user: User information and group memberships
• groups: Group definitions and permissions

Building the Plugin

Prerequisites

Ensure you have Java 11+ and Maven installed:

java -version
mvn -version

Build Commands

Windows:

build.bat

Linux/Mac:

mvn clean package

The build process will create a single JAR file with all dependencies included.

Deployment

1. Copy the JAR file to the TAK Server plugins directory:

   cp target/jump-aar-plugin-1.0.0.jar /opt/tak/server/plugins/

2. Restart TAK Server to load the plugin:

   sudo systemctl restart takserver

3. Verify installation by checking the TAK Server logs:

   tail -f /opt/tak/server/logs/takserver.log

Look for the message: "Jump AAR Plugin initialized successfully"

REST API Endpoints

The plugin exposes the following REST endpoints under /plugin/jumpaar/:

1. Tags Management

Get Known Tags

GET /plugin/jumpaar/tags

Returns a list of all known tag IDs (EUDs or ATOS tags) with metadata.

Response:

{
  "success": true,
  "tags": [
    {
      "uid": "ATOS-001",
      "callsign": "Alpha-1",
      "organization": "Team Alpha",
      "full_name": "John Doe",
      "device_type": "ATOS",
      "last_seen": "2024-01-01T12:00:00Z"
    }
  ],
  "count": 1
}

2. GPS Track Data

Get Tag GPS Data

GET /plugin/jumpaar/tag_data/{tag_id}?start={ISO8601}&end={ISO8601}

Returns GPS track data for a specific tag within the specified time window.

Parameters:

• tag_id: The tag UID (e.g., "ATOS-001", "android-123456")
• start: Start time in ISO 8601 format (e.g., "2024-01-01T00:00:00Z")
• end: End time in ISO 8601 format (e.g., "2024-01-01T23:59:59Z")

Response:

{
  "success": true,
  "tag_id": "ATOS-001",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-01T23:59:59Z",
  "arr": [
    {
      "timestamp": "2024-01-01T12:00:00Z",
      "latitude": 40.7128,
      "longitude": -74.0060,
      "altitudeFt": 1000.0
    }
  ],
  "jumps": [],
  "track_points_count": 1,
  "jumps_count": 0,
  "device_type": "ATOS"
}

3. Jump Detection

Get Jumps for Tag

GET /plugin/jumpaar/jumps/{tag_id}?start={ISO8601}&end={ISO8601}

Detects and returns jump events for a specific tag within the time window.

Parameters:

• tag_id: The tag UID
• start: Start time in ISO 8601 format
• end: End time in ISO 8601 format

Response:

{
  "success": true,
  "tag_id": "ATOS-001",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-01T23:59:59Z",
  "jumps": [
    {
      "startIdx": 10,
      "endIdx": 25,
      "startTime": "2024-01-01T12:00:00Z",
      "endTime": "2024-01-01T12:05:00Z",
      "dropHeight": 500.0,
      "duration": 300.0,
      "horizontalMovement": 1000.0,
      "startAltitude": 1500.0,
      "endAltitude": 1000.0
    }
  ],
  "track_points_count": 100,
  "jumps_count": 1,
  "device_type": "ATOS"
}

4. Group Management

Get All Groups

GET /plugin/jumpaar/groups

Returns a list of all available groups with member counts.

Response:

{
  "success": true,
  "groups": [
    {
      "id": 1,
      "name": "Team Alpha",
      "bitpos": 1,
      "create_ts": "2024-01-01T00:00:00Z",
      "group_type": "Team",
      "member_count": 5
    }
  ],
  "count": 1
}

5. Group AAR

Get Group AAR

GET /plugin/jumpaar/group_aar/{group_id}?start={ISO8601}&end={ISO8601}

Builds a comprehensive AAR for all members of a group.

Parameters:

• group_id: The group ID or name
• start: Start time in ISO 8601 format
• end: End time in ISO 8601 format

Response:

{
  "success": true,
  "group_id": "1",
  "group_name": "Team Alpha",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-01T23:59:59Z",
  "members": [
    {
      "uid": "ATOS-001",
      "callsign": "Alpha-1",
      "organization": "Team Alpha",
      "full_name": "John Doe",
      "device_type": "ATOS",
      "track_points_count": 100,
      "jumps_count": 2,
      "jumps": [...]
    }
  ],
  "total_members": 5,
  "total_jumps": 8,
  "total_track_points": 500,
  "group_statistics": {
    "device_types": {
      "atos_count": 3,
      "eud_count": 2
    },
    "jumps": {
      "total_jumps": 8,
      "members_with_jumps": 3,
      "average_jumps_per_member": 1.6
    },
    "track_data": {
      "total_track_points": 500,
      "average_track_points_per_member": 100.0
    }
  }
}

6. Group Data (Legacy Compatibility)

Get Group Data

GET /plugin/jumpaar/group_data/{group_id}?start={ISO8601}&end={ISO8601}

Returns aggregated track data and jumps for all group members (compatible with existing HTML visualizations).

7. Threshold Management

Get Current Thresholds

GET /plugin/jumpaar/thresholds

Update Thresholds

PUT /plugin/jumpaar/thresholds
Content-Type: application/json

{
  "landing_stability_threshold": {
    "value": 25,
    "description": "Maximum altitude variance to confirm landing (feet)",
    "min": 5,
    "max": 100,
    "unit": "feet"
  }
}

Reset to Defaults

POST /plugin/jumpaar/thresholds/reset

Jump Detection Algorithm

The plugin implements a sophisticated jump detection algorithm that:

1. Identifies ATOS Devices: Only processes jump detection for devices with UIDs starting with "ATOS"
2. Altitude Analysis: Monitors altitude changes to detect drops
3. Stability Checking: Uses rolling windows to confirm landing stability
4. Horizontal Movement: Validates minimum horizontal displacement
5. Duration Validation: Ensures jumps meet minimum duration requirements
6. Gap Merging: Combines closely spaced jump segments

Configurable Parameters

• landing_stability_threshold: Maximum altitude variance for landing confirmation (feet)
• landing_stability_duration: Time required for stable landing (seconds)
• horizontal_movement: Minimum horizontal distance traveled (feet)
• min_jump_duration: Minimum valid jump duration (seconds)
• jump_merge_window: Maximum gap between jump segments to merge (seconds)

Integration with Existing HTML

The plugin maintains compatibility with existing HTML visualizations by:

1. Preserving JSON Structure: Using the same field names (arr for track points, jumps for events)
2. Maintaining Data Format: Ensuring GPS coordinates and timestamps match expected formats
3. Supporting Existing Endpoints: Keeping legacy endpoints for backward compatibility

URL Updates Required

Update your HTML files to use the new endpoint URLs:

Before (Python Flask):

fetch('/api/db/tag_data?tag_id=1&start=2024-01-01T00:00:00Z&end=2024-01-01T23:59:59Z')

After (Java Plugin):

fetch('/plugin/jumpaar/tag_data/ATOS-001?start=2024-01-01T00:00:00Z&end=2024-01-01T23:59:59Z')

Troubleshooting

Common Issues

1. Database Connection Failed

   • Verify PostgreSQL is running: sudo systemctl status postgresql
   • Check database credentials in the plugin
   • Ensure network connectivity to database

2. No Data Returned

   • Verify tag UIDs exist in the cot_router table
   • Check time range parameters
   • Ensure event_pt column contains valid geometry data

3. Plugin Not Loading

   • Check TAK Server logs for initialization errors
   • Verify JAR file is in the correct plugins directory
   • Ensure Java version compatibility

Logging

The plugin uses SLF4J logging. Check TAK Server logs for detailed information:

tail -f /opt/tak/server/logs/takserver.log | grep "JumpAAR"

Database Queries

To verify data availability, run these queries directly on the PostgreSQL database:

-- Check for ATOS devices
SELECT DISTINCT uid FROM cot_router WHERE uid LIKE 'ATOS%';

-- Check for recent GPS data
SELECT COUNT(*) FROM cot_router 
WHERE event_pt IS NOT NULL 
AND "time" > NOW() - INTERVAL '24 hours';

-- Check group memberships
SELECT g.name, COUNT(tu.id) as member_count
FROM groups g
LEFT JOIN tak_user tu ON tu.groups & (1 << g.bitpos) != 0
GROUP BY g.id, g.name;

Performance Considerations

• Indexing: Ensure proper indexes exist on cot_router.uid, cot_router.time, and cot_router.event_pt
• Time Ranges: Limit query time ranges to reasonable periods (e.g., 24-48 hours)
• Group Size: Large groups may impact performance; consider pagination for groups with 50+ members
• Caching: The plugin doesn't implement caching; consider external caching for frequently accessed data

Security Notes

• The plugin only performs SELECT operations on the database
• No data modification or deletion operations are supported
• All database connections use the configured credentials
• Input validation is performed on all REST parameters

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review TAK Server logs for error messages
3. Verify database connectivity and data availability
4. Test with simple queries to isolate issues

License

This plugin is provided as-is for TAK Server integration. Ensure compliance with your organization's security policies and TAK Server licensing requirements.