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.

Viewing Configured vs Dynamic Location​

Note — supctl show output depends on --config:

  • supctl show --config system sites <site> displays the configured (static) location from the site’s configuration.
  • supctl show system sites <site> (without --config) displays the dynamic (runtime) location as reported by the site.

Example (configured location):

supctl show --config system sites udc1
name: udc1
type: edge
when-disconnected: treat-as-normal
location:
  latitude: 59.411986
  longitude: 17.981929
quarantined: false
allow-local-unseal: false
topology:
  parent-site: topdc
ingress-allocation-method: dhcp
management-ipv4-access-list:
  - 192.168.100.1
hosts:
...

Example (dynamic location):

supctl show system sites udc1
name: udc1
type: edge
when-disconnected: treat-as-normal
location:
  latitude: 5.22
  longitude: 5.565
creation-time: 2025-08-18T14:11:37.810Z
domain: udc1.site.test
labels:
  system/type: edge
  system/name: udc1
quarantined: false
allow-local-unseal: false
topology:
  parent-site: topdc
ingress-allocation-method: dhcp
management-ipv4-access-list:
  - 192.168.100.1
connection-state:
  connected: true
  last-connect: 2025-08-18T14:12:15.478Z
  last-disconnect: 2025-08-18T14:12:06.342Z
call-home-state:
  all-hosts:
    called-home: 3
    total: 3
  controller-hosts:
    called-home: 3
    total: 3
  cluster-established: true
...

The runtime view (without --config) may include additional live fields such as connection-state and call-home-state, which are not part of the stored configuration.

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​

{
  "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}'

After a successful update, supctl show system sites <site> (without --config) will reflect the new dynamic coordinates. The configured location (visible with --config) remains unchanged unless you update the site configuration.

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 os
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.
  • Use supctl show --config to see the configured (static) location; omit --config to see the dynamic (runtime) location.
  • 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.