Skip to main content

Device Auto-Tracking: Configuration & Operation

Introduction​

Auto-tracking is a powerful feature of the Bullitt e-BSS platform that enables enterprise customers to receive periodic location updates from satellite-connected devices. This guide explains how to configure auto-tracking for your devices and details how location data is transmitted through the system.

Prerequisites​

Before setting up auto-tracking, ensure you have:

  1. Enterprise Firmware: Your devices must have remote tracking-capable firmware installed. Consumer application firmware does not support remote tracking due to privacy considerations. Contact support@bullitt.com to obtain the appropriate firmware.

  2. Active Device: The device IMSI must be activated and properly provisioned within your enterprise organization in the e-BSS system.

  3. Webhook Configuration: You'll need to set up a webhook endpoint to receive tracking events. This endpoint will receive all uplink messages from your devices, including tracking data.

Important: Auto-tracking functionality is only available when devices are powered on and have an active satellite connection. This feature does not operate over Wi-Fi or cellular networks.

Configuring Auto-Tracking​

Using the API​

You can configure auto-tracking settings for a specific device using the e-BSS API:

Endpoint:

PUT /devices/{imsi}/change-auto-tracking-frequency

Query Parameters:

  • frequency: Interval in minutes between tracking updates
    • Default: -1 (disabled)
    • Minimum: 3 minutes
    • Maximum: 1440 minutes (24 hours)

Example Request:

PUT /devices/123456789012345/change-auto-tracking-frequency?frequency=5

Example Response:

{
  "imsi": "123456789012345",
  "autoTrackingFrequency": 5,
  "updatedAt": "2025-03-21T14:23:45Z"
}

When Activating a Device​

You can also set the auto-tracking frequency when initially activating a device:

Endpoint:

POST /devices/activate

Request Body Example:

{
  "imsi": "123456789012365",
  "autoTrackingFrequency": 5,
  "reason": "for field operations tracking"
}

Response Sample:

{
  "imsi": "123456789012365",
  "iccid": "123456789012345678",
  "productGroup": "HMD",
  "isActivated": true,
  "createdAt": "2025-03-19T23:41:51.433Z",
  "updatedAt": "2025-03-24T15:01:45.256Z",
  "autoTrackingFrequencyInMinutes": 5
}

How Auto-Tracking Works​

The auto-tracking system operates through a series of coordinated steps between the device, satellite network, OTT platform, and e-BSS system:

  1. Connection Establishment: When a device connects to the satellite network, the satellite network provider notifies Bullitt's Over-The-Top (OTT) platform of the connection event.

  2. Configuration Check: The OTT platform queries the e-BSS system to retrieve the device's tracking configuration.

  3. Tracking Initiation: If auto-tracking is enabled for the device, the OTT platform initiates a tracking session by sending a TrackingRequest downlink message to the device through the satellite network. This message contains the configured tracking frequency.

  4. Device Response: Upon receiving the tracking request, the device responds with a StartTracking message and begins sending periodic TrackLocation messages at the configured intervals.

  5. Data Delivery: The OTT platform processes these incoming location messages and forwards them to your configured webhook endpoint via the e-BSS platform.

Auto-Tracking Sequence Diagram

Location Data Format​

When a device sends location data, it will be delivered to your webhook endpoint with the following structure:

{
  "message": {
    "messageType": "TrackLocation",
    "messageId": "0003505dcb762d67d8cde52d0001",
    "timestamp": "2025-03-20T14:32:15Z",
    "payload": {
      "latitude": 51.5074,
      "longitude": -0.1278,
      "altitude": 45,
      "accuracy": 8,
      "speed": 0,
      "bearing": 90,
      "satelliteCount": 7
    }
  },
  "cdr": {
    "cdrId": "cdr_10204",
    "imsi": "123456789012345",
    "eventType": "tracking",
    "direction": "upstream",
    "generatedAt": "2025-03-20T14:32:15Z",
    "dataBytes": 128
  }
}

Best Practices​

  1. Optimize Tracking Frequency:

    • Set an appropriate frequency based on your use case
    • More frequent updates (lower interval) consume more power and data
    • Less frequent updates (higher interval) conserve resources but provide less timely information

  2. Handle Connection Gaps:

    • Remember that tracking only works when satellite connection is active
    • Design your application to gracefully handle gaps in location data

  3. Monitoring Usage:

    • Use the Data Usage Summary API to monitor tracking-related data consumption
    • Track usage patterns to optimize your configuration

  4. Webhook Reliability:

    • Ensure your webhook endpoint is highly available
    • Implement proper error handling and retry logic

Troubleshooting​

Common Issues​

  1. No tracking data received:

    • Verify the device has enterprise firmware installed
    • Confirm the device is activated and auto-tracking is enabled
    • Check if the device has established a satellite connection
    • Verify your webhook is correctly configured and functioning

  2. Inconsistent tracking updates:

    • Check for satellite connectivity issues in the device's operational area
    • Verify the device remains powered on
    • Use the CDR API to check for connection events

  3. Webhook errors:

    • Use the Test Webhook endpoint to verify your webhook configuration
    • Check your server logs for any errors processing incoming webhook requests

Conclusion​

Auto-tracking provides a powerful way to monitor the location of your satellite-connected devices. By understanding how to configure and utilize this feature, you can implement effective tracking solutions for your enterprise needs.

For additional support or questions about auto-tracking, contact enterprise-support@bullitt.com.