Skip to main content

Device Location Data

Overview​

Golain's IoT platform provides a specialized mechanism for handling device location data. This feature allows for efficient tracking and management of device geographical information, which is crucial for many IoT applications such as fleet management, asset tracking, and location-based services.

Topic Structure​

Location data is transmitted and received using a dedicated MQTT topic format:

/<slug>/<device-name>/device-data/location

Where:

  • <slug> is your project or organization identifier (Find this under device details on the platform.)
  • <device-name> is the unique identifier for the device

Data Format​

Location data is structured using Protocol Buffers (protobuf), which offers efficient serialization and deserialization. The proto3 syntax is used for defining the message structure.

Proto3 Definition​

syntax = "proto3";

option go_package = "github.com/golain-io/protos/wkt";

message location {
    double latitude = 1;
    double longitude = 2;
    float altitude = 3;
    float speed = 4;
    float heading = 5;
    float accuracy = 6;
    string timestamp = 7;
    int32 timeEpoch = 8;
}

Field Descriptions​

  1. latitude (double): The latitude coordinate in degrees
  2. longitude (double): The longitude coordinate in degrees
  3. altitude (float): The altitude in meters above sea level (optional)
  4. speed (float): The speed of the device in meters per second (optional)
  5. heading (float): The heading or direction of movement in degrees (0-360, where 0 is North) (optional)
  6. accuracy (float): The accuracy of the location data in meters (optional)
  7. timestamp (string): A human-readable timestamp of when the location was recorded (optional)
  8. timeEpoch (int32): The Unix epoch time (in seconds) when the location was recorded (optional)
info

You only need to send timestamp or timeEpoch when there is a mis-match between time of recording the data and time of sending. Golain uses the time of insertion as the timestamp of the data if none of these values are provided.

Usage​

Sending Location Data​

Devices should publish their location data to the specified topic using the protobuf-encoded message format. Ensure that your device is capable of encoding the location data according to the provided proto definition.

Best Practices​

  1. Update Frequency: Choose an appropriate update frequency based on your application needs and device capabilities. High-frequency updates provide more accurate tracking but consume more power and bandwidth.

  2. Data Accuracy: Use the accuracy field to filter out potentially unreliable location data in your applications.

  3. Time Synchronization: Ensure that devices have accurate time synchronization to provide meaningful timestamp and timeEpoch values.

  4. Power Management: For battery-powered devices, optimize location update frequency to balance between accuracy and power consumption.

  5. Data Retention: Implement appropriate data retention policies for historical location data, considering both storage constraints and potential analytical needs.

Integration with Golain Features​

Location data can be leveraged across various Golain platform features:

  • Dashboards: Create geospatial visualizations using the Geo Map panel type.
  • Rule Engine: Trigger actions based on device location (e.g., geofencing alerts).
  • Analytics: Perform spatial analysis on historical location data.

By utilizing this standardized approach to location data, you can easily implement location-aware features in your IoT solutions, ensuring consistency and interoperability across your devices and applications.