hgps

Documentation

Overview

hgps -- a resource class for caching Horizon GPS data

Cache your Horizon GPS data in a "smart" GpsCache instance. Cache features:

• (optional) obfuscate location within specified distance from actual loc (note that this works correctly for any location anywhere on the globe)
• (optional) can discover elevation when not specified (i.e., ground level)
• caches GPS fixes -- once a fix is found, coordinates are never again zero

Note that GpsCache instances are also thread safe.

Usage example:

var p *GpsCache = hgps.New()
err := p.SetLocationSourceAndAccuracyInKm(source, gps, accuracy_km)
t := p.SetLocation(lat, lon, -1.0) // Requests elevation discovery
lat, lon, elev := p.GetLocation()
json_str := p.GetAsJSON()

Written by Glen Darling (glendarling@us.ibm.com), Oct. 2016

Index

• Constants
• type GpsCache
  • func New() *GpsCache
  • func (h *GpsCache) EstimateLocation() (lat float64, lon float64, err error)
  • func (h *GpsCache) GetAsJSON() (json_bytes []byte)
  • func (h *GpsCache) GetConfiguration() (config string)
  • func (h *GpsCache) GetLocation() (lat float64, lon float64, elev float64, accuracy_km float64)
  • func (h *GpsCache) GetLocationAsJSON() (json_bytes []byte)
  • func (h *GpsCache) GetLocationSource() (loc_source SourceType)
  • func (h *GpsCache) GetSatellitesAsJSON() (json_bytes []byte)
  • func (h *GpsCache) HasGPS() (has_gps bool)
  • func (h *GpsCache) IsLocationSet() (isSet bool)
  • func (h *GpsCache) SetLocation(lat float64, lon float64, elev float64) (update_time int64)
  • func (h *GpsCache) SetLocationAccuracyInKm(accuracy_km float64)
  • func (h *GpsCache) SetLocationSource(loc_source SourceType)
  • func (h *GpsCache) SetSatellites(report *gpsdc.SKYReport)
• type GpsData
• type IPGPSCoordinates
• type LocationData
• type SatelliteData
• type SatellitesData
• type SourceType

Constants

const DEBUG = 0

DEBUG:

0 : No debug output from this module
1 : Trace all state changes
2 : Also dump full state at each state change
3 : Also show location obfuscation and altitude discovery

const GET_PUBLIC_IP_RETRY_SEC = 10

How long to delay between retries when seeking the public IP address

const LOC_ESTIMATE_RETRY_SEC = 10

How long to delay between retries for location estimate from IP address

Types

type GpsCache

type GpsCache struct {
	// contains filtered or unexported fields
}

The GpsCache "class"

func New

func New() *GpsCache

GpsCache "constructor"

func (*GpsCache) EstimateLocation

func (h *GpsCache) EstimateLocation() (lat float64, lon float64, err error)

Estimate node location using its public IP address for geo-location

func (*GpsCache) GetAsJSON

func (h *GpsCache) GetAsJSON() (json_bytes []byte)

Return the entire Horizon GPS data as a JSON-formatted bytes

func (*GpsCache) GetConfiguration

func (h *GpsCache) GetConfiguration() (config string)

Return the current configuration details

func (*GpsCache) GetLocation

func (h *GpsCache) GetLocation() (lat float64, lon float64, elev float64, accuracy_km float64)

Return cached, and possibly already obfuscated, location (lat, lon, elev)

func (*GpsCache) GetLocationAsJSON

func (h *GpsCache) GetLocationAsJSON() (json_bytes []byte)

Return cached location data as JSON-formatted bytes

func (*GpsCache) GetLocationSource

func (h *GpsCache) GetLocationSource() (loc_source SourceType)

Get the source of the location data (Manual, Estimated, GPS, or Searching)

func (*GpsCache) GetSatellitesAsJSON

func (h *GpsCache) GetSatellitesAsJSON() (json_bytes []byte)

Return cached satellite data as JSON-formatted bytes

func (*GpsCache) HasGPS

func (h *GpsCache) HasGPS() (has_gps bool)

Return whether or not GPS hardware is available

func (*GpsCache) IsLocationSet

func (h *GpsCache) IsLocationSet() (isSet bool)

Return true if lat and lon have been set yet

func (*GpsCache) SetLocation

func (h *GpsCache) SetLocation(lat float64, lon float64, elev float64) (update_time int64)

Set location (latitude, longitude, elevation) NOTE: if location lat, lon, or elev are pure zero, the cache is not updated NOTE: if location provided matches the cached location, the LastUpdate

value is not changed.

NOTE: Location randomization is done only when set, to prevent clients from

receiving many randomizations of a single actual location (enabling
them to estimate the actual location ever more accurately as more
randomizations are received.

NOTE: See also the note above function obfuscate_lat_lon(), below.

func (*GpsCache) SetLocationAccuracyInKm

func (h *GpsCache) SetLocationAccuracyInKm(accuracy_km float64)

Set location source data, accuracy distance, and enforce policy constraints

func (*GpsCache) SetLocationSource

func (h *GpsCache) SetLocationSource(loc_source SourceType)

Set the source of the location data (Manual, Estimated, GPS, or Searching)

func (*GpsCache) SetSatellites

func (h *GpsCache) SetSatellites(report *gpsdc.SKYReport)

Set satellite data

type GpsData

type GpsData struct {
	Location   LocationData    `json:"location" description:"Location"`
	Satellites []SatelliteData `json:"satellites" description:"Data about discovered satellites."`
}

JSON struct for Horizon GPS data

type IPGPSCoordinates

type IPGPSCoordinates struct {
	Latitude  float64 `json:"latitude"`
	Longitude float64 `json:"longitude"`
}

type LocationData

type LocationData struct {
	Latitude   float64    `json:"latitude" description:"Location latitude"`
	Longitude  float64    `json:"longitude" description:"Location longitude"`
	ElevationM float64    `json:"elevation" description:"Location elevation in meters"`
	AccuracyKM float64    `json:"accuracy_km" description:"Location accuracy in kilometers"`
	LocSource  SourceType `json:"loc_source" description:"Location source (one of: Manual, Estimated, GPS, or Searching)"`
	LastUpdate int64      `json:"loc_last_update" description:"Time of most recent location update (UTC)."`
}

JSON struct for location data

type SatelliteData

type SatelliteData struct {
	PRN  float64 `` /* 134-byte string literal not displayed */
	Az   float64 `json:"az"   description:"Azimuth, degrees from true north."`
	El   float64 `json:"el"   description:"Elevation in degrees."`
	Ss   float64 `json:"ss"   description:"Signal strength in dB."`
	Used bool    `` /* 197-byte string literal not displayed */

}

JSON struct for data about a single satellite

type SatellitesData

type SatellitesData struct {
	Satellites []SatelliteData `json:"satellites" description:"Array of data for each of the attached satellites."`
}

JSON struct for satellite data

type SourceType

type SourceType string

const (
	MANUAL    SourceType = "Manual"
	ESTIMATED SourceType = "Estimated"
	SEARCHING SourceType = "Searching"
	GPS       SourceType = "GPS"
)