GPS Receiver

A Python script that receives real-time GPS and IMU sensor data from an Android phone running SensorStream and displays it in the terminal.

What It Does

• Connects to an Android phone over USB via ADB port forwarding
• Receives a live stream of GPS and IMU JSON packets
• Displays sensor data in a formatted terminal UI, updated in real time
• Auto-reconnects if the phone disconnects
• Provides on_gps() and on_imu() callback hooks for custom processing

Requirements

• Python 3.6+
• No external dependencies (standard library only)
• ADB installed and in your PATH
• SensorStream installed and running on your Android phone

Usage

python3 receiver.py [port]

Default port is 5000.

python3 receiver.py 5000

Press Ctrl+C to stop and clean up the ADB tunnel.

Setup

1. Enable USB Debugging on your Android phone
2. Connect the phone via USB and authorize ADB
3. Grant location permission (first time only):

   adb shell pm grant com.h2x.sensor android.permission.ACCESS_FINE_LOCATION

4. Run the receiver:

   python3 receiver.py

The script automatically:

• Forwards port 5000 from your laptop to the phone (adb forward)
• Starts the SensorService on the phone
• Connects and begins displaying data

Terminal Output

╔══════════════════════════════════╗
║     Phone Sensor Stream          ║
║  2026-03-31 12:34:56             ║
╠══════════════════════════════════╣
║  GPS                             ║
║    Lat:  37.774900               ║
║    Lon: -122.419400              ║
║    Alt:  10.50 m                 ║
║    Acc:  3.20 m   Spd: 0.00 m/s  ║
╠══════════════════════════════════╣
║  IMU                             ║
║    Accel:  0.12  -0.03   9.81   ║
║    Gyro:   0.001  0.002 -0.001  ║
║    Mag:   23.10 -10.40  44.20   ║
╠══════════════════════════════════╣
║  Packets: GPS=142  IMU=7085      ║
╚══════════════════════════════════╝

Custom Integration

Add your own logic in the callback functions at the top of receiver.py:

def on_gps(data):
    # Called for every GPS packet
    # data: {"type":"GPS","lat":...,"lon":...,"alt":...,"acc":...,"spd":...,"brg":...,"ts":...}
    pass

def on_imu(data):
    # Called for every IMU packet
    # data: {"type":"IMU","ax":...,"ay":...,"az":...,"gx":...,"gy":...,"gz":...,"mx":...,"my":...,"mz":...,"ts":...}
    pass

Data Format

Packets arrive as newline-delimited JSON over TCP:

Field	Description
type	"GPS" or "IMU"
lat, lon	Latitude/longitude (degrees)
alt	Altitude (meters)
acc	GPS accuracy radius (meters)
spd	Speed (m/s)
ax/ay/az	Accelerometer (m/s²)
gx/gy/gz	Gyroscope (rad/s)
mx/my/mz	Magnetometer (µT)
ts	Unix timestamp (milliseconds)