Class to use u-blox AssistNow to get a faster GPS fix. More...

#include <UbloxGPS.h>

Public Member Functions
	UbloxAssistNow ()
	Constructor. You typically instantiate one of these as a global variable if you want to use AssistNow. More...

virtual	~UbloxAssistNow ()
	Destructor.

UbloxAssistNow &	withAssistNowKey (const char *assistNowKey)
	Required! Pass your AssistNow API key in this function. More...

UbloxAssistNow &	withDisableLocation ()
	Runs AssistNow without location hinting. More...

void	setup ()
	Call from main application setup. Required!

void	loop ()
	Call from main application loop. Required! More...

Static Public Member Functions
static UbloxAssistNow *	getInstance ()
	Gets the singleton instance of this class,. More...

Protected Member Functions
void	stateWaitConnected ()
	State machine handler for waiting for a Particle cloud connection (internal) More...

void	stateWaitLocation ()
	State machine handler for waiting for location data (internal) More...

void	stateSendRequest ()
	State machine handler for sending a request (internal) More...

void	stateReadResponse ()
	State machine handler for reading the response from the u-blox server (internal) More...

void	stateSendToGPS ()
	State machine handler for sending data to the GPS (internal) More...

void	stateDone ()
	State machine handler used when done (internal) More...

void	subscriptionHandler (const char event, const char data)
	Particle event subscription handler (internal) More...

Protected Attributes
std::function< void(UbloxAssistNow *)>	stateHandler = &UbloxAssistNow::stateWaitConnected
	State handler function.

unsigned long	stateTime = 0
	Time used for state transition timeouts. The millis() value at the start of the wait.

AssistNowDownload *	download = 0
	State data for downloading including the buffer. This is only allocated when we are downloading to save RAM.

unsigned long	packetDelay = 1
	Delay in milliseconds between messages sent to the GPS during stateSendToGPS.

bool	disableLocation = false
	Set to true to disable getting location data. This causes slower time to first sync and larger downloads.

unsigned long	waitLocationTimeoutMs = 10000
	Amount of time in milliseconds to wait for the location and elevation data to arrive.

String	assistNowKey
	Assist now API token/key. Required.

String	assistNowServer = "online-live1.services.u-blox.com"
	Server to contact for u-blox aiding data.

Static Protected Attributes
static UbloxAssistNow *	instance = 0
	Singleton instance of this class.

Detailed Description

Class to use u-blox AssistNow to get a faster GPS fix.

Using this feature requires several things, described in greater detail in the documentation:

u-blox access token (you can get this at no charge)
Google API token (you can probably use the free tier)
Particle Google Maps Integration to map cell tower ID to location
Particle Integration with Google Elevation API to get elevation from location

As the data will be downloaded by cellular, this will increase your cellular data usage while decreasing the time to first fix. For more details, see the AssistNow.md file in the Github repository for more details.

You typically instantiate this object as a global variable in your main application file. You'll need to call the withAssistNowKey(), setup(), and loop() methods.

You don't need to explicitly start AssistNow. It will automatically start when the cloud connects and will check the GPS to see if can see satellites. If it can see fewer than 3 satellites it will

Constructor & Destructor Documentation

◆ UbloxAssistNow()

UbloxAssistNow::UbloxAssistNow ( )

Constructor. You typically instantiate one of these as a global variable if you want to use AssistNow.

This object has minimal storage requirements so it's OK to allocate it all of the time. It will determine if the GPS needs aiding data and request it automatically. The download temporary buffers are allocated only when needed and freed when done.

Member Function Documentation

◆ getInstance()

static UbloxAssistNow* UbloxAssistNow::getInstance ( )

inlinestatic

Gets the singleton instance of this class,.

This class is normally instantiated once in the main application code.

◆ loop()

void UbloxAssistNow::loop ( )

Call from main application loop. Required!

It returns quickly when not doing assist now so you can just call it all the time.

◆ stateDone()

void UbloxAssistNow::stateDone ( )

protected

State machine handler used when done (internal)

The done state will delete the AssistNowDownload object if allocated, otherwise it does nothing. This state is entered if:

AssistNow is not needed (GPS has a fix)
The u-blox AssistNow API key has not been set
An error occurs (can't get geolocation, elevation, can't contact u-blox aiding server)

◆ stateReadResponse()

void UbloxAssistNow::stateReadResponse ( )

protected

State machine handler for reading the response from the u-blox server (internal)

If all of the data is read successfully, goes to stateSendToGPS. Otherwise, goes to stateWaitDone. There is no retry on failure, as if there is a cellular connection probably it's probably just better to let the GPS get its data from satellite.

Next state: stateSendToGPS or stateWaitDone.

◆ stateSendRequest()

void UbloxAssistNow::stateSendRequest ( )

protected

State machine handler for sending a request (internal)

This state prepares the request to the u-blox aiding data server and makes the connection. If an error occurs, goes to stateDone, otherwise goes to stateReadResponse.

Next state: stateReadResponse or stateWaitDone.

◆ stateSendToGPS()

void UbloxAssistNow::stateSendToGPS ( )

protected

State machine handler for sending data to the GPS (internal)

The stateReadResponse method buffers all of the GPS aiding data before sending it to the GPS. The data is generally under 3K, and buffering the whole data helps make sure it's valid and allows it to be sent out in more controlled bursts to the GPS.

◆ stateWaitConnected()

void UbloxAssistNow::stateWaitConnected ( )

protected

State machine handler for waiting for a Particle cloud connection (internal)

In order to use the webhooks there must be a cloud connection. While in disableLocation mode technically we could start after cellular ready, the difference in time is not sufficient to warrant that special-case.

This state will either:

Find that there are enough satellites visible (3 or more) and aiding won't likely help much now and go to the stateDone.
Get cell tower (or Wi-Fi) information and start a Google maps geolocation.

Next state: stateWaitLocation or stateWaitDone

◆ stateWaitLocation()

void UbloxAssistNow::stateWaitLocation ( )

protected

State machine handler for waiting for location data (internal)

Waits for location and elevation data. The subscriptionHandler will move to stateSendRequest if we get location and elevation.

If a timeout occurs (no location information for tower, or webhooks missing) then it will go to stateWaitDone.

Next state: stateSendRequest or stateWaitDone.

◆ subscriptionHandler()

void UbloxAssistNow::subscriptionHandler	(	const char *	event,
		const char *	data
	)

protected

Particle event subscription handler (internal)

This is only activated if there is a need to do AssistNow. If the GPS already has a fix the subscription handler is not registered.

◆ withAssistNowKey()

UbloxAssistNow& UbloxAssistNow::withAssistNowKey ( const char * assistNowKey )

inline

Required! Pass your AssistNow API key in this function.

Parameters

assistNowKey The access token you received from u-blox for using the AssistNow service.

The key looks like "c4Pufq9Wp1WnjXo1aNIN5g" as is not the same as any u-blox username or password you may have.

◆ withDisableLocation()

UbloxAssistNow& UbloxAssistNow::withDisableLocation ( )

inline

Runs AssistNow without location hinting.

This mode does not require the Google Maps integration or the Elevation integration, however it does not improve the time to first fix as much, and also increases the data usage. With location hinting, the GPS can get a fix much more quickly, and the aiding data download is smaller because it can skip the satellite ephemeris data for satellites that won't be in view of your location.

Whenever possible you should use location hinting (set up the webhooks and don't call this function).

The documentation for this class was generated from the following files:

src/UbloxGPS.h
src/UbloxGPS.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ UbloxAssistNow()

Member Function Documentation

◆ getInstance()

◆ loop()

◆ stateDone()

◆ stateReadResponse()

◆ stateSendRequest()

◆ stateSendToGPS()

◆ stateWaitConnected()

◆ stateWaitLocation()

◆ subscriptionHandler()

◆ withAssistNowKey()

◆ withDisableLocation()