Geofence on Windows

This section discusses about some Windows OS specific GeoFence information.

# 1. Introduction

Geofence applications are the ones in which you have a background location task running on the phone by which a flag will be raised when you move into or move out of a predefined area. This is useful for maintaining context awareness, social networks, mobile marketing, tracking, etc. BCM47521 has Geofence feature to minimize the power consumption of whole system. BCM47521 computes position with the on-chip processor. This allows the Host CPU to go to sleep for long periods of time, while Geofence areas are still monitored by the chipset BCM47521 wakes up the Host whenever a Geofence area is entered/exited. The Host in turn notifies the Application.

# 2. Geofence Interface

## 2.1 Geofence APIs with Broadcom GPS Library

Broadcom GPS library provides Geofence APIs to add and remove fence information. BCM47521 supports up to 64 Geofence requests simultaneously. Application can add set of a location and a radius to be monitored.

### MakeGeofenceReq

  • Definition ~~~~ .c static GlRequest *MakeGeofenceReq( native_double dLatitude ,native_double dLongitude ,native_double dRadius ,GlReqOnStart cbOnStart ,GlReqOnGeofenceEvent cbOnEvent ,GlOnMemAlloc cbOnMemAlloc = GL_DFLT_MEM_ALLOC ,GlOnMemFree cbOnMemFree = GL_DFLT_MEM_FREE) ~~~~
  • Parameters + dLatitude - Latitude of the fence + dLongitude - Longitude of the fence + dRadius - Radius of the fence + cbOnStart - callback to be invoked when the request starts + cbOnEvent - callback to be invoked when events occur + cbOnMemAlloc - callback to allocate memory + cbOnMemFree - callback to free memory
  • Descriptions + Create request for a Geofence monitoring.

### StartRequest

  • Definition ~~~~ .c bool StartRequest(GlRequest *pReq) ~~~~
  • Parameters + pReq - The request that is created by MakeGeofenceReq
  • Descriptions + Method to start positioning request.

### StopRequest

  • Definition ~~~~ .c bool StopRequest(GlRequest *pReq) ~~~~
  • Parameters + pReq - The request that is created by MakeGeofenceReq
  • Descriptions + Cancel an ongoing request

Broadcom GPS Library also provides a callback function to notify position and fence information when the monitored Geofence area is entered or exited.

### GlReqOnGeofenceEvent

  • Definition ~~~~ .c void (*GlReqOnGeofenceEvent) (GlRequest *pReq, GL_REQ_GEOFENCE_CODE etCode, const GL_FIX_STATUS *pFixStatus) ~~~~
  • Parameters + pReq - The request that is created by MakeGeofenceReq + etCode - GL_REQ_GEOFENCE_ON_ENTRY, GL_REQ_GEOFENCE_ON_EXIT + pFixStatus - GPS position information.
  • Descriptions + Callback function for getting geofence event

## 2.2 Geofence APIs with Windows

## 2.3 Geofence Behavior

Broadcom Geofence runs on the BCM47521 with host consuming very little power, and it does not need the host application processor. Here is the state diagram to understand Geofence Behavior.

State name | Descriptions -----------|------------- Idle | Initial State Prepare Geofence | Download aiding data (Eph, Time, Ref. Pos and LTO) and if possible, try to fix current position. Geofence Mode | BCM47521 is running without Host operation.
Calculating distance between current position and fences.
If fences are too far from current position, BCM47521 goes into Standby Mode to minimize power consumption. Geofence Event Report Mode | Once Geofence area is detected, it wakes up Host and send proper Geofence event to application. House Keeping Mode | Ephemeris is only valid for 10 minutes without correction.
Need to feed updated ephemeris to 47521 10 minutes after last update Periodic Report Mode | It is normal Periodic GPS operation.
Whenever application wants normal GPS operation, the operation mode can be changed to Periodic Report Mode.
If there are both Geofence requests and Periodic Report Mode, application will get current Position Report from Periodic Request and Geofence Event from Geofence Requests.

geofence_3.png

Figure 3 ) Geofence State Diagram

# 3. Host Wake-Up Requirement

BCM47521 enable the Host Application Processor to go to sleep for long periods of time, while Geofences are still monitored. Whenever a Geofence is crossed, or when the chipset needs data from the Host, it will start the wake up process in order to have the Host CPU operations. So there should be a connection to an interrupt on the Host CPU. The Host CPU should wake up and resume the HW flow control in a short time in order to get the serial communication ongoing.

## 3.1 Hardware connection for Geofence

With on-Chip Geofencing of BCM47521, movement across a predefined boundary wakes the Host CPU from a power-saving sleep state. BCM47521 has HOST_WAKE GPIO pin to wake host on Geofence event. Here is a hardware diagram to support Geofence.

geofence_4.png

Figure 4 ) HW Connections for Geofence Whenever BCM47521 needs to wake up the Host, it will take the following actions:

  • Assert HOST_WAKE
  • Send WakeUp packet to Host on UART.
  • Wait for Host communication (with some retry mechanism).
  • De-assert HOST_WAKE

If BCM47521 doesn’t get any communication from the Host, it will have a few retries sending WakeUp packets. After some timeout, it will de-assert the WakeUp GPIO and resume normal processing.

geofence_5.png

Figure 5 ) Host Wake up Sequence

### HOST_WAKE HOST_WAKE is an output from 47521 that is used to wake up the Host AP. Whenever the chipset is powered; HOST_WAKE defaults to high impedance pad (not driven) with internal pull-down. It can be connected directly to an IRQ input on the Host CPU.

When HOST_WAKE set, Kernel detects the rising edge of HOST_WAKE, and the Kernel won’t go sleep mode while HOST_WAKE is set (high).

The HOST_WAKE can be reset with two below conditions.

  1. When ASIC gets a proper message from GLL through serial port.
  2. Even if there is no response, it will be reset (low) after 3 seconds.

Note: GLL doesn’t check the HOST_WAKE GPIO status. Only Kernel checks the GPIO.

geofence_6.png

Figure 6 ) HOST_WAKE Signal

### UART Control

BCM47521 uses HW flow control to prevent data lost while the Host AP is asleep. Whenever the Host CPU goes to sleep, it needs to set the HW flow control lines to prevent data lost. BCM47521 Flow Control is active low and designated as nRTS and nCTS.

  • nRTS should be programmed as an output, driven high (stops BCM47521 from sending data)
  • nCTS should be programmed as an input. Whenever the Host AP wakes up from sleep, it needs to reprogram the UART (HW flow control, baudrate, …). The serial communication will resume at that point.

### Host CPU setup considerations

There are following considerations in terms of setting up Host CPU when we implement Geofence wake up feature.

  • Host Wakeup GPIO (IRQ) setup
  • UART nRTS setup
  • nSTDBY GPIO and external LNA power

#### Host Wakeup GPIO (IRQ) For host wake-up GPIO we need to make sure that this pin can be used as an external interrupt source.

#### UART nRST For UART nRTS, as mentioned above, we need to make sure that nRTS pin must be asserted high before going into sleep and put to low after waking-up from sleep.

#### nSTDBY GPIO and External LNA For nSTDBY GPIO, we need to make sure that it is asserted high even when Host CPU is in sleep state if gpsd is in Geofence mode because without nSTDBY being high ESW cannot run. For external LNA power, we need to make it maintained even during AP sleep, because in Geofence mode, BCM47521 needs RF power for satellite signal acquisition. BCM47521 can enable LNA only when it is needed thru using LNA_EN pin. So the radio of BCM47521 should be on during Host CPU sleep and LNA power should be alive during sleep.

# 4. How to run SDK with Geofence

Geofence can be tested with WinXP executable binary and Triggerfish EVK (that has BCM47521).

### Add Geofence to configuration file At first, configuration file should be changed to add new Geofence job with area information that will be monitored. ~~~~~~~~~{.xml #gpsconfig.xml} <job id="geofence_test"> <task> <req_geofence fencelatitude="33.75" fencelongitude="-84.389" fenceradius="100.0"> <req_geofence fencelatitude="33.75" fencelongitude="-84.3833" fenceradius="100.0"> <req_geofence fencelatitude="33.7454" fencelongitude="-84.389" fenceradius="100.0"> <req_geofence fencelatitude="33.7454" fencelongitude="-84.3833" fenceradius="100.0"> </task> </job> ~~~~~~~~~

  • job id: The name of job id which will be used to execute
  • FenceLatitude, FenceLongitude: Latitude, longitude of Geofence (decimal degrees).
  • FenceRadius: Radius of Geofence (meters).

### Execute executable binary with Geofence job Please follow the below steps to run Geofence job on WinXP. ~~~~~ 1. Open cmd to run 2. cd SDK_TOP_DIRECTORY 3. cd bin 4. dir a. Make sure that you have glgps_win_xp.exe and gpsconfig.xml 5. glgps_win_xp.exe gpsconfig.xml geofence_test a. The job name is case sensitive 6. Observe the T/R LEDs blinking on the evaluation kit. 7. To quit, click on the cmd Window, press "q" on the keyboard. Ctrl-C won't work. 8. Search for PGLOR,2,GFC in the log file under log directory a. The log directory can be changed with LogDirectory in configuration file. ~~~~~

### Check Log file GPS log file contains internal GPS information and NMEA data as well. NMEA data shows Geofence information and event when Geofence is crossed.

$PGLOR,0,GFC - GeoFence Fix

~~~~~ $PGLOR,0,GFC,2,ddmmyy,hhmmss.ms,4.0,37.3,-121.4,400.0,event[,fixes,trials]*CC 1 2 3 4 5 6 7 8 9 10 11* 12*

The fields are:

  • 1 - Sentence version [0]
  • 2 - Sentence identifier "GFC"
  • 3 - request ID
  • 4 - UTC day, month, year
  • 5 - UTC hours, minutes, seconds, 100ths of seconds
  • 6 - Time (seconds) since the request was received
  • 7,8 - Latitude, longitude of geofence (decimal degrees)
  • 9 - Radius of geofence (meters)
  • 10 - Event:
    • IN or OUT from geofence
    • ADD or DELETE geofence
    • YLD
  • 11 - Only for YLD event: number of fixes
  • 12 - Only for YLD event: number of trials
  • CC - checksum ~~~~~

Here are examples of Geofence NMEA. Event | NMEA ------|----- Add Geofence | $PGLOR,1,NEW,GEOFENCE,0*1D
$PGLOR,2,GFC,0,240413,022635.25,1.0,37.2006,127.0732,1000,ADD*72 Delete Geofence | $PGLOR,2,GFC,0,240413,030358.84,2244.6,37.2006,127.0732,1000,DELETE*1B
$PGLOR,2,END,240413,030358.84,2244.6,GEOFENCE,0*1 In from Geofence | $PGLOR,2,GFC,10,240413,022639.32,5.0,37.4980,127.0277,500,IN*3A Out from Geofence | $PGLOR,2,GFC,10,240413,023110.09,277.7,37.4980,127.0277,500,OUT*76 Yield | $PGLOR,1,GFC,0,240413,023003.09,210.8,37.2006,127.0732,1000,YLD,3,3*67

### Check Geofence log with Broadcom NMEA Log Analyzer Broadcom NMEA Log Analyzer can convert GPS log to kmz format, Geofence information can be shown graphically in Google Earth.

At first, convert GPS log file to NMEA file with bar2nmea.bat

~~~~ bar2nmea.bat Broadcom GPS Log file can be dragged to this batch file for conversion. glgps_win_xp.exe for instance can produce some Broadcom GPS Log file. The output will be nmea file. ~~~~

Then, convert the NMEA file to kmz to see in Google Earth.

~~~~ nmea2kmz-g.bat Converts NMEA file to Google Earth KMZ file, with green positions without drawing estimated accuracy circles. (drag and drop of GLL or nmea file to the batch file is possible) ~~~~

In Google Earth, green circle shows a Geofence that is defined in configuration file. And it shows IN/OUT events with time.

  • Green Circle : Geofence defined in configuration file.
  • Blue Dot : True Path
  • Green Dot : Geofence Events.
geofence_8.png
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines