Skip to main content

Managing Dynamic Site Location

This guide explains how to dynamically update a site's geographical location using the Avassa system. It's particularly valuable for mobile sites, such as those on vehicles or vessels, that require frequent location updates.

Overview​

A site's initial location is set during site creation. For mobile sites, however, dynamic location updates are essential. The Control Tower now receives location updates every 5 minutes, ensuring that under normal operations, the location displayed in the overview is accurate within this timeframe. In the event of a Control Tower restart, the location displayed in the overview may revert to the position recorded up to one hour ago.

The dynamic location mechanism works as follows:

  • The site regularly updates its location to the Control Tower every 5 minutes.
  • The Control Tower persistently stores these locations every hour, balancing data freshness with system efficiency.
  • Live data can be fetched directly from the site, e.g., when focusing on a site in the UI.

Configuration Settings​

Adjust the frequency of location updates and persistent storage using these parameters:

location-publish-interval​

Determines the interval between location updates sent from a site to the Control Tower. The default value is 5 minutes.

  • Ensures timely updates in the Control Tower overview.
  • Balances frequent updates with minimal network overhead.

location-persist-interval​

Specifies the interval between persistent storage of site locations in the Control Tower. The default is 1 hour.

  • Location updates are persistently stored hourly to maintain data availability after a Control Tower restart.
  • Under normal conditions, the location shown in the overview is at most 5 minutes old. Post-restart, displayed locations could temporarily revert to the last persistently stored value (up to one hour old).

Configuration Example​

To customize the intervals for publishing and persisting location updates, use the following command:

supctl create system settings <<EOF
sites:
  location-publish-interval: 5m
  location-persist-interval: 1h
EOF


## Updating Site Location

Use the local site's `update-location` API action to update its geographical coordinates. Updates are recorded when positional changes exceed approximately:

- **1.11 meters in latitude**
- **0.57 meters in longitude**

### API Request Example

```json
{
  "latitude": 59.336569,
  "longitude": 18.048000
}

Example API Call​

curl -X POST https://api:4646/v1/state/system/update-location \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 59.336569, "longitude": 18.048000}'

Python Script for GPS Device Integration​

Here's a Python script that reads coordinates from a GPS device (via serial communication) and updates the site's location:

import serial
import pynmea2
import avassa_client
import requests

# Serial port configuration for the GPS device
GPS_PORT = '/dev/ttyUSB0'  # Adjust as necessary
GPS_BAUDRATE = 9600

# Avassa API configuration
API_URL = 'https://api.internal:4646/v1/state/system/update-location'
ROLE_ID = '324bc0bf-40c3-4aa5-bb58-360b830405ac'
SECRET_ID = os.environ['APPROLE_SECRET_ID']

def obtain_api_token(role_id, secret_id):
    """
    Authenticate with the Avassa system to obtain an API token.
    """
    client = avassa_client.Client()
    response = client.auth.approle_login(role_id=role_id, secret_id=secret_id)
    return response['auth']['client_token']

def read_gps():
    """
    Read GPS data from the device and parse latitude and longitude.
    """
    with serial.Serial(GPS_PORT, GPS_BAUDRATE, timeout=5) as ser:
        while True:
            line = ser.readline().decode('ascii', errors='replace')
            if line.startswith('$GPGGA'):
                msg = pynmea2.parse(line)
                return msg.latitude, msg.longitude

def update_location(token, latitude, longitude):
    """
    Update the site's location in the Avassa system.
    """
    payload = {'latitude': latitude, 'longitude': longitude}
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    response = requests.post(API_URL, json=payload, headers=headers, verify=False)
    return response.status_code == 200

if __name__ == '__main__':
    # Obtain the API token
    token = obtain_api_token(ROLE_ID, SECRET_ID)
    if token:
        # Read GPS coordinates
        lat, lon = read_gps()
        # Update location in Avassa
        if update_location(token, lat, lon):
            print(f"Location updated to Latitude: {lat}, Longitude: {lon}")
        else:
            print("Failed to update location.")
    else:
        print("Failed to obtain API token.")

Dependencies​

Install required Python packages:

pip install pyserial pynmea2 requests avassa_client

Running the Python Script in a Container​

To run the script inside a container, you need to ensure the GPS device is accessible to the container.

Building the Docker Image​

Create a Dockerfile:

FROM python:3.9

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY gps_location_updater.py .

CMD ["python", "gps_location_updater.py"]

Create a requirements.txt file:

pyserial
pynmea2
requests
avassa_client

Build the container:

docker build -t gps-updater .

Running the Container with GPS Device Access​

Use the Avassa device discovery feature to ensure the container has access to the GPS device. Mount the device inside the container using the devices field in the Avassa application specification.

For more details on how to configure access to serial devices, visit Avassa device discovery tutorial.

Accessing Site Location Data​

Historical site location data is accessible through the system:location Volga topic. Each log entry includes:

  • Latitude and longitude of the site.
  • Timestamp (mtime) of entry creation.
  • Additional metadata (e.g., producer-name, sequence number seqno).

Consuming the system:location Volga Topic​

To read recent location updates:

$ supctl do --site udc1 volga topics system:location consume

Summary​

  • Use the update-location API for dynamic position updates.
  • Frequent location updates (every 5 minutes) ensure accuracy in normal operations.
  • Persistent storage every hour balances freshness with efficiency.
  • Utilize the system:location Volga topic for real-time tracking.
  • The provided Python script allows seamless integration with GPS devices.

Following these guidelines ensures efficient and accurate dynamic location management for mobile sites.