Complete Guide to Integrating Router GPS with VenusOS

Leave a Comment / Projects / By

I wanted to integrate my router’s built-in GPS with my VenusOS system to enhance automations with my Victron Energy equipment and Home Assistant for my camper van. This allows me to track my location, get solar energy predictions in VRM, and create automations within my Home Assistant setup. While I found some helpful tips online, the process was more time-consuming than expected—especially for someone with limited experience using tools like gpsd and socat. This guide aims to provide a clear, step-by-step walkthrough to simplify the setup for others. If you have basic knowledge of how to use the terminal, you should be able to follow this tutorial.

A Note on Adaptability

While these instructions are specific to the GL.iNet GL-X3000 (Spitz AX) router and a VenusOS device (in this case, a Raspberry Pi running VenusOS), the steps should be adaptable to other GPS-enabled routers and VenusOS devices, including the Venus GX. Troubleshooting steps are included along the way, and additional resources are listed at the end if you encounter any challenges. Don’t hesitate to leave a comment if you need further assistance.

If you’re looking for a top-of-the-line router for your van or RV, you can support my work by purchasing the GL-X3000 through my Amazon Affiliate link, letting me know this guide was useful and motivating me to create more (hopefully useful!) content.

Step 1: Enable & Configure GPS on Router

1.1. Login to your router admin panel:

For the GL-X3000, the default IP address is 192.168.8.1, but this may vary by router model. Common default IP addresses include 192.168.1.1, 192.168.10.1, and 192.168.0.1. Enter your router’s IP address into your web browser, then log in with your admin username and password.

If you’re unsure of the IP address or login credentials, check the sticker on the back of your router.

1.2. Enable GPS

From the homepage, you should be able to see an overview of all your internet sources. For your cellular module, click the ‘Modem Management’ icon, which will take you to a page where you can enter and send AT commands, allowing you to configure your modem further than the user interface currently does.

Enter each of these AT commands:

AT+QGPSCFG="autogps",1    # enable auto-start for GPS
AT+QGPS=1    # manually start GPS

This enables GPS autostart on router reboots, and starts the GPS acquisition now. For the GL-X3000, this starts streaming of NEMA sentences (GPS data) to /dev/mhi_LOOPBACK. Other routers may stream to a different location.

1.3. Enable GNSS Constellations

This step is optional, but recommended for increased accuracy and faster position fix.

You can also configure your GPS to use specific global navigation satellite system (GNSS) constellations, such as Glonass, Galileo, or Beidou. To enable all GNSS constellations, use this following command:

AT+QGPSCFG="gnssconfig",1    # Enable all GNSS constellations

This is saved in the modem’s non-volatile memory (NVRAM), so it should persist after reboot.

If you ever decide you’d rather stick to GPS only (no GNSS), you can disable it by running AT+QGPSCFG="gnssconfig",0

1.4. Verify GPS Working

To confirm that GPS data is being streamed from the router, you can use the following command:

cat /dev/mhi_LOOPBACK

This command reads the raw GPS data directly from the device. If GPS is working correctly, you should see a continuous output of NMEA sentences, such as:

  • $GPGGA: Provides essential fix data like latitude, longitude, and altitude.
  • $GPGSA: Indicates the active satellites being used in the GPS fix.
  • $GPGSV: Lists all visible satellites and their signal strengths.
  • $GPRMC: Contains recommended minimum GPS data, including coordinates, speed, and course.

Troubleshooting

  • If there is no output at all from cat /dev/mhi_LOOPBACK:
    • GPS may not be enabled. Double-check that GPS has been enabled on the modem with the appropriate AT commands.
  • NMEA sentences appear from cat /dev/mhi_LOOPBACK but there is no valid GPS data:
    • Wait a few minutes – sometimes it takes a few minutes for the GPS to acquire a fix
    • Try moving the router outside. If this fixes it, you may be in a low service area and/or you may need an external antenna. Being in a van (big metal box) can damper the signal significantly. With fiberglass RVs this is not really an issue.

Step 2: Install and Configure GPS Services on Router

2.1. Install gpsd, gpsd-clients, and socat

  • gpsd is a GPS daemon that shares GPS data with applications across the network.
  • gpsd-clients will allow us to confirm that the GPS data is streaming from gpsd – while not needed, it is useful for troubleshooting
  • socat enables flexible data forwarding, which we’ll use to send GPS data from the router to another device, like a Raspberry Pi running VenusOS

To install gpsd within the router’s admin panel, navigate to Applications → Plug-ins, search for gpsd, and click Install.

Repeat this process with gpsd-clients and socat .

2.2. Configure gpsd

After installation, SSH into your router to configure gpsd

  1. SSH into the Router
    • Open a terminal and connect to the router using its IP address (e.g., 192.168.8.1 for the GL-X3000): 
      ssh root@192.168.8.1    # Replace with your router's IP address
    • When prompted, enter the router’s admin password.
  2. Use the following commands to set the GPS data source, enable global listening, and start the service: 
    uci set gpsd.core.device='/dev/mhi_LOOPBACK'   # Set GPS device location
uci set gpsd.core.listen_globally='1'          # Allow global access to GPS data
uci set gpsd.core.enabled='1'                  # Enable gpsd service

/etc/init.d/gpsd enable                         # Enable gpsd to start on boot
/etc/init.d/gpsd start                          # Start gpsd service now

At this point you should have a gpsd server successfully set up, and it should continue to work after reboot.

2.3. Verify GPS Data Streaming

If you installed gpsd-clients earlier, you can use gpspipe to verify that gpsd is streaming valid NMEA sentences:

gpspipe -r

You should see a continuous stream of NMEA sentences like $GPGGA, $GPGSA, etc., with valid data.

To stop gpspipe streaming, press Ctrl + C.

Troubleshooting

  • No Output from gpspipe -r:If you don’t see any output, double check the GPS data source by running: 
    cat /dev/mhi_LOOPBACK
    • If output appears here: This means the GPS is working, but gpsd is not properly configured to receive data. Check that gpsd is configured to use /dev/mhi_LOOPBACK and restart gpsd.
    • If there is no output at all: GPS may not be enabled. Double-check that GPS has been enabled on the modem with the appropriate AT commands.

Step 3: Set Up socat to Forward GPS Data from Router

To make GPS data accessible from other devices, such as a Raspberry Pi running VenusOS or a Venus GX, we’ll configure socat to forward the GPS data over TCP.

3.1 Configure socat for TCP Forwarding

  1. Choose a Port: Since gpsd typically uses port 2947, select an alternative (e.g., 5555) to avoid potential conflicts.
  2. Run socat: 
    socat TCP-LISTEN:5555,reuseaddr,fork SYSTEM:"gpspipe -r" &
    • Explanation:
      • TCP-LISTEN:5555: Listens on TCP port 5555.
      • reuseaddr: Allows address reuse.
      • fork: Enables multiple connections by forking a process for each.
      • SYSTEM:"gpspipe -r": Pipes GPS data from gpspipe.
      • &: Runs socat in the background.

3.2 Setup socat to run on reboot

To ensure socat starts on router reboot, add the command to /etc/rc.local:

  1. Open /etc/rc.local with vi: 
    vi /etc/rc.local
  2. Edit the File:
    • Press i to enter Insert Mode.
    • Add the socat Command:Insert the following lines above the exit 0 line: 
      # Forward GPS data from Router via TCP
/usr/bin/socat TCP-LISTEN:5555,reuseaddr,fork SYSTEM:"gpspipe -r" &

      Explanation:

      • TCP-LISTEN:5555: Listens on TCP port 5555.
      • reuseaddr: Allows the address to be reused.
      • fork: Handles multiple connections by forking.
      • SYSTEM:"gpspipe -r": Executes gpspipe -r to stream raw GPS data.
      • &: Runs the command in the background.
  3. Save and Exit vi:
    • Press Esc to exit Insert Mode.
    • Type :wq and press Enter to Write and Quit.

3.3 Restart socat:

After editing /etc/rc.local, restart the router or execute the command directly to start socat:

socat TCP-LISTEN:5555,reuseaddr,fork SYSTEM:"gpspipe -r" &

Step 4: Install socat on VenusOS

This step installs socat on your VenusOS device so that you can receive GPS data streamed from your router.

4.1. Enable SSH on VenusOS

To start, enable SSH access on your VenusOS device. This can be done via the Remote Console, which you can access by entering your VenusOS device’s IP address into your web browser.

  1. In the Remote Console, navigate to Settings → General.
  2. Change the Access Level to Superuser (the password for this level is ZZZ).
  3. Set a root password of at least 6 characters.
  4. Toggle SSH on LAN to ON. If you’re using an older version of VenusOS, you may also need to enable Remote Support.

For more details on enabling SSH on VenusOS, refer to Victron’s well-written documentation.

4.2. SSH into your device running VenusOS

After enabling SSH, connect to your VenusOS device from a terminal:

ssh root@192.168.8.2    # Replace with your VenusOS device's IP address

You will be prompted to enter the root password you just set.

4.3. Install socat

Once connected, install socat on VenusOS. socat allows VenusOS to receive GPS data streamed from the router.

opkg update
opkg install socat

4.4. Test the TCP Connection

After socat is installed, test the TCP connection to the router to ensure GPS data is being received correctly:

socat - TCP:192.168.8.1:5555    # Replace with your Router's IP address and port
  • Expected Output: If everything is configured correctly, you should see a continuous stream of NMEA sentences (e.g., $GPGGA, $GPGSA) similar to the output from gpspipe.
  • If Data Streams Successfully: The connection is confirmed, and GPS data is streaming to your VenusOS device.
  • To Stop socat: Press Ctrl + C.

Troubleshooting

Review socat Logs on the Router

  • Check the socat logs on the router for any error messages or connection issues: 
    cat /data/socat.log
    • Look For:
      • Errors: These could point to configuration issues or network connection problems with socat or gpspipe.
      • Connection Success Messages: These logs confirm that socat is successfully forwarding GPS data from the router. Look for lines that indicate successful connections or data forwarding.
  • Ensure your router’s firewall allows traffic on the port you’re using and that no other service is using that port.

Step 5: Configure VenusOS to Receive GPS Data

In this step, we’ll set up VenusOS to receive GPS data forwarded from the router and make it accessible within the Victron system. By creating a virtual serial port and configuring gps_dbus, the GPS data will be visible in Victron’s Remote Console.

5.1. Edit the Startup Script on VenusOS

To ensure GPS data is available every time VenusOS starts, we’ll edit the rc.local startup script to run socat and gps_dbus automatically.

  1. From the VenusOS terminal, edit rc.local: 
    nano /data/rc.local
  2. Add the following lines above the exit 0 line: 
    #!/bin/sh
#
# Forward GPS data from Router via TCP
#
/usr/bin/socat TCP:192.168.10.1:5555 pty,link=/dev/ttyGPS0,raw,nonblock,echo=0,b115200 2>> /data/socat.log &

sleep 2 # this gives socat a little time to start before starting gps_dbus

# Start gps_dbus to publish GPS data to VenusOS
/opt/victronenergy/gps-dbus/gps_dbus -s /dev/ttyGPS0 -b 115200 -t 0 &
  • Explanation:
    • socat Command:
      • Connects to the router’s socat service on TCP port 5555.
      • Creates a virtual serial port at /dev/ttyGPS0 for VenusOS to read GPS data.
      • Redirects any error messages to /data/socat.log for troubleshooting.
    • gps_dbus Command:
      • Starts gps_dbus, which reads GPS data from /dev/ttyGPS0 and publishes it to VenusOS’s D-Bus, making it accessible within the system.
    • Loop to Ensure gps_dbus Runs:
      • Checks if gps_dbus is running; if not, it attempts to start it in a loop. This prevents gps_dbus from failing if it stops unexpectedly.
    • Background Execution (&):
      • Both socat and the loop run in the background, allowing VenusOS to complete its startup process without waiting.

5.2. Make rc.local Executable

To ensure that rc.local runs on startup, make it executable with the following command:

chmod 755 /data/rc.local

5.3. Start gps_dbus Manually

After saving rc.local, you can start gps_dbus manually to immediately check if GPS data is visible in the Victron Remote Console. Run:

/opt/victronenergy/gps-dbus/gps_dbus -s /dev/ttyGPS0 -b 115200 -t 0 &

This starts gps_dbus temporarily, allowing you to verify that GPS data is accessible in the Victron interface without needing to reboot.

5.4. Confirm GPS data appears in VenusOS

In the VenusOS console, Navigate to Settings → GPS

You should now see your GPS “device.” Click on it to view detailed information such as latitude, longitude, altitude, the number of satellites connected, etc.

Screenshot of Victron Console GPS devices menuScreenshot of GPS Device in Victron Console

5.5 Restart VenusOS

After confirming that GPS data is appearing, restart VenusOS to ensure the rc.local configuration works as expected and that both socat and gps_dbus start automatically on boot.

You can reboot VenusOS in one of two ways:

  • From the Terminal: 
    reboot
  • From the Console: Go to Settings → General → Reboot?

Step 6: Add a Watchdog Script to Detect and Restart GPS Service for VenusOS

We’re almost there! Everything is setup, but events like a router reboot can disrupt the GPS data stream. To ensure your GPS service keeps running despite this, we’ll create a watchdog script on VenusOS that checks if GPS data is being received and automatically restarts gps_dbus and/or socat if needed.

6.1. Create the Watchdog Script File:

  1. Run nano to create the file 
    nano /data/gps_watchdog.sh
  2. Add the following content to the file 
    #!/bin/bash

# Path to log file
LOG_FILE="/data/gps_watchdog.log"
MAX_LOG_SIZE=512000  # 500KB

# Function to check and clear log file if it exceeds MAX_LOG_SIZE
check_log_size() {
    if [ -f "$LOG_FILE" ] && [ "$(stat -c%s "$LOG_FILE")" -ge "$MAX_LOG_SIZE" ]; then
        echo "$(date): Log file exceeded $MAX_LOG_SIZE bytes. Clearing log file." > "$LOG_FILE"
    fi
}

check_log_size

# Function to log messages with timestamp
log() {
    echo "$(date): $1" >> "$LOG_FILE"
}

log "GPS Watchdog script triggered"

sleep 5  # Optional: Adjust as needed

# Function to start socat and restart gps_dbus
start_socat() {
    log "Starting socat to create /dev/ttyGPS0"
    # Remove any existing /dev/ttyGPS0 to prevent conflicts
    if [ -e /dev/ttyGPS0 ]; then
        rm -f /dev/ttyGPS0
        log "Removed existing /dev/ttyGPS0"
    fi

    /usr/bin/socat TCP:192.168.10.1:5555 pty,link=/dev/ttyGPS0,raw,nonblock,echo=0,b115200 2>> /data/socat.log &
    socat_pid=$!

    # Sleep for 10 seconds to allow /dev/ttyGPS0 to be created
    sleep 10

    if [ -e /dev/ttyGPS0 ]; then
        log "/dev/ttyGPS0 now exists after starting socat"
    else
        log "Failed to create /dev/ttyGPS0 even after starting socat"
        # Kill socat if it didn't create the device
        kill $socat_pid
        exit 1
    fi

    # After starting socat, restart gps_dbus
    restart_gps_dbus
}

# Function to restart socat and gps_dbus
restart_socat() {
    log "Restarting socat and gps_dbus"
    # Stop gps_dbus to prevent errors when /dev/ttyGPS0 disappears
    pkill gps_dbus
    sleep 2  # Wait for gps_dbus to terminate

    # Kill existing socat process
    pkill socat
    sleep 2  # Wait for socat to terminate

    # Start socat and gps_dbus
    start_socat
}

# Function to check if socat is running
is_socat_running() {
    if pgrep -f "socat TCP:192.168.10.1:5555" > /dev/null 2>&1; then
        return 0  # socat is running
    else
        return 1  # socat is not running
    fi
}

# Function to restart gps_dbus
restart_gps_dbus() {
    log "Restarting gps_dbus service"
    # Stop any existing gps_dbus instances
    pkill gps_dbus
    sleep 2  # Wait for gps_dbus to terminate

    # Start gps_dbus service
    /opt/victronenergy/gps-dbus/gps_dbus -s /dev/ttyGPS0 -b 115200 -t 0 &
    gps_dbus_pid=$!
    log "Started gps_dbus service with PID $gps_dbus_pid"

    # Wait for the service to initialize
    sleep 10
}

# Function to check GPS data using 'read' with a timeout for NMEA sentences
check_gps_data() {
    local line
    local total_timeout=10  # Total time to wait in seconds
    local per_read_timeout=1  # Timeout per read in seconds
    local end_time=$((SECONDS + total_timeout))

    while [ $SECONDS -lt $end_time ]; do
        if IFS= read -r -t $per_read_timeout line < /dev/ttyGPS0; then
            # Remove any carriage return characters
            line="${line%%

    Explanation:

    The main logic of the script first checks if GPS data is being received:

    1. If GPS data is found: It logs that data is being received and exits successfully.
    2. If GPS data is missing: It logs that GPS data was not found, then tries to restart gps_dbus to reinitialize the GPS data flow.
    3. After Restarting gps_dbus: It checks for GPS data again. If data is still missing, it calls start_socat to fully reset both socat and gps_dbus, ensuring a complete reinitialization of the data stream.

    This script ensures that socat and gps_dbus are always running and restarts them if GPS data is interrupted.

6.2. Make the Script Executable:

After saving the file, make the script executable:

chmod +x /data/gps_watchdog.sh

6.3. Schedule the Script to Run Regularly Using cron:

You can automate the checking process by running the script periodically using cron.

  1. Open the crontab editor: 
    crontab -e
  2. Add the following line to run the watchdog script every 5 minutes: 
    */5 * * * * /bin/bash /data/gps_watchdog.sh >> /data/gps_watchdog.log 2>&1

This will ensure that the script checks for GPS data every 5 minutes and restarts the gps_dbus service if GPS data is lost.

Useful Commands

Here are some essential commands for managing and troubleshooting your VenusOS setup and monitoring system performance.

System and Process Monitoring

  • top – Displays real-time system usage, including CPU, memory, and process information.
    • Useful for monitoring overall system health, identifying high-usage processes, and checking system load.
  • ps aux – Shows a detailed list of all running processes, including the user, process ID (PID), CPU and memory usage, and the command that started each process.
    • Use this command to verify if specific processes, like gps_dbus or socat, are running and to monitor their resource usage.
  • pgrep <process_name> – Searches for a running process by name and returns its PID.
    • This command can confirm whether gps_dbus or socat is active by showing the process ID.
  • pkill <process_name> – Stops a process by name.
    • Use this command to stop specific processes if you need to restart them manually.

Network and Connectivity

  • ifconfig – Shows the current network interface configurations, including IP addresses, which can help verify your network connection status.
    • Can help to confirm the device’s IP address and network connectivity
  • ping <IP_address> – Checks connectivity to another device by sending packets and waiting for a response.
    • Use this command to verify if VenusOS can communicate with your router.

Log Management

  • tail -f <log_file> – Displays the last few lines of a log file and updates in real-time as new entries are added.
    • This command is helpful for monitoring live log updates from your watchdog script to see if it’s triggering restarts.
  • less <log_file> – Opens a log file in a viewer that allows scrolling and searching.
    • Use less to inspect log files in detail, helping you review older entries for troubleshooting.

Additional Troubleshooting and Resources

If you’ve followed the guide but run into any issues, don’t worry—there are excellent community resources that can help you troubleshoot and fine-tune your setup. Both the GL.iNet and Victron Energy forums are filled with knowledgeable users and detailed guides. Special thanks to elafargue for their GL-X3000 GPS configuration guide, and to the helpful contributors on the Victron Energy Community forum.

Helpful Links

Need Help?

If you have questions, feel free to comment here or to post on the GL.iNet and Victron Energy forums.

Congratulations!

Congratulations on successfully integrating your router’s GPS with VenusOS! Now that live GPS data is feeding into your Victron system, you’re ready to enhance your smart van or RV setup with location tracking, solar predictions, and custom automations. I hope this guide streamlined the process and made it easy.

If you have suggestions or further questions, feel free to reach out—or share this guide with others who might find it useful. It’s a great way to support future content like this.

Enjoy the open road and your new GPS-enabled setup!

Leave a Comment

Your email address will not be published. Required fields are marked *