LocationFusionRK Class Reference

#include <LocationFusionRK.h>

Data Structures
struct	CmdHandler
	This class is used internally for registerCommand. More...

Public Types
enum class	PublishFrequency { manual , once , periodic }
	How often to publish location. More...
enum class	Status : int {   idle = 0 , publishing = 1 , publishSuccess = 2 , publishFail = 3 ,   locEnhancedWait = 4 , locEnhancedSuccess = 5 , locEnhancedFail = 6 }
	Current status of this library. More...

Public Member Functions
void	setup ()
	Perform setup operations; call this from global application setup()
LocationFusionRK &	withPublishManual ()
	Set the publish frequency to manual. Call requestPublish() to do so. This is the default.
LocationFusionRK &	withPublishOnce ()
	Set the publish frequency to publish once after connecting to the cloud.
LocationFusionRK &	withPublishPeriodic (std::chrono::milliseconds ms)
	Set the publish frequency to publish periodically when cloud connected.
PublishFrequency	getPublishFrequency () const
	Get the current publish frequency. Default is manual.
LocationFusionRK &	withAddWiFi (bool enable=true)
	Add Wi-Fi access points nearby to the loc event. Default is false.
LocationFusionRK &	withAddTower (bool enable=true)
	Add serving cellular tower information to the loc event. Default is false.
LocationFusionRK &	withAddToEventHandler (std::function< void(Variant &eventData, Variant &locVariant)> handler)
	Add an "add to event" handler.
LocationFusionRK &	withCmdHandler (const char *cmd, std::function< void(const Variant &data)> handler)
	Adds a handler when the Particle function "cmd" is received.
LocationFusionRK &	withEnableCmdFunction (bool enable)
	Enables or disables the "cmd" function handler. Default is enabled.
LocationFusionRK &	withLocEnhancedHandler (std::function< void(const Variant &data)> handler)
	Adds a handler when loc-enhanced data is calculated by the cloud.
LocationFusionRK &	withStatusHandler (const char *cmd, std::function< void(Status)> handler)
	Adds a handler when the status has changed. Added in version 0.0.3.
LocationFusionRK &	withThreadStackSize (size_t size)
	Sets the worker thread stack size. Must be set before setup()
void	requestPublish ()
	Request a publish now.
Status	getStatus () const
	Get the current status of the library (idle, publishing, etc.)
void	lock ()
	Locks the mutex that protects shared resources.
bool	tryLock ()
	Attempts to lock the mutex that protects shared resources.
void	unlock ()
	Unlocks the mutex that protects shared resources.

Static Public Member Functions
static LocationFusionRK &	instance ()
	Gets the singleton instance of this class, allocating it if necessary.

Protected Member Functions
	LocationFusionRK ()
	The constructor is protected because the class is a singleton.
virtual	~LocationFusionRK ()
	The destructor is protected because the class is a singleton and cannot be deleted.
	LocationFusionRK (const LocationFusionRK &)=delete
LocationFusionRK &	operator= (const LocationFusionRK &)=delete
void	updateStatus (Status status)
	Update the status and call the status handlers. Used internally. Added in 0.0.3.
os_thread_return_t	threadFunction (void)
	Worker thread function.
void	stateIdle ()
	Internal state handler for idle and not connected to the cloud.
void	stateConnected ()
	Internal state handler for connected to the cloud.
void	stateBuildPublish ()
	Internal state handler for building a publish.
void	statePublishWait ()
	Internal state handler for waiting for the publish to complete.
void	stateLocEnhancedWait ()
	Internal state handler for waiting for the loc-enhanced to be received.
int	functionHandler (const Variant &eventData)
	Called from the Particle.function handler for "cmd".
void	locEnhanced (const Variant &eventData)
	Called when a "loc-enhanced" cmd function is received.

Static Protected Member Functions
static int	functionHandlerStatic (String cmd)
	Called from the Particle.function handler for "cmd".
static void	locEnhancedStatic (const Variant &eventData)
	Called when a "loc-enhanced" cmd function is received.

Protected Attributes
os_mutex_t	mutex = 0
	Mutex to protect shared resources.
Thread *	thread = 0
	Worker thread instance class.
size_t	threadStackSize = 6144
	Size of the work thread stack. Must set before setup()
PublishFrequency	publishFrequency = PublishFrequency::manual
	How often to publish (manual, once, periodic)
std::chrono::milliseconds	publishPeriod = 5min
	If publishing periodic, how often to publish.
std::chrono::milliseconds	publishFailureRetry = 1min
	If publish fails, how long to wait before trying again. The location will be built again.
std::chrono::milliseconds	locEnhancedTimeout = 1min
	Amount of time to wait for loc-enhanced.
bool	locEnhancedReceived = false
	Used to handle loc-enhanced state changes.
unsigned long	stateTime = 0
	Used for calculating the locEnhancedTimeout.
std::function< void(LocationFusionRK &)	stateHandler ) = &LocationFusionRK::stateIdle
	State handler. Run from the worker thread.
bool	addWiFi = false
	When building a location publish, add Wi-Fi access point information.
bool	addTower = false
	When building a location publish, add serving tower information.
std::vector< std::function< void(Variant &eventData, Variant &locVariant)>	addToEventHandlers )
	Vector of handlers to add more information to the location event.
bool	enableCmdFunction = true
	Add a function handler for "cmd".
std::vector< CmdHandler >	commandHandlers
	Handler functions to call when a cmd Particle.function is received.
std::vector< std::function< void(const Variant &eventData)>	locEnhancedHandlers )
	Handler functions to call when loc-enhanced is received on-device.
bool	manualPublishRequested = false
	true when a manual publish has been requested
int	publishCount = 0
	Number of successful publishes. THis is used to handle once mode.
CloudEvent	event
	Event being built or sent.
Variant	eventData
	The data payload being build for the loc event.
uint64_t	nextPublishMs = 0
	When to publish next in periodic mode. Compare to System.millis().
int	locRequestId = 1
	loc events contain a request ID, this is the next one to use
Status	status = Status::idle
	Current status pof the library.
std::vector< std::function< void(Status)> >	statusHandlers
	Handlers to call when the status changes.

Static Protected Attributes
static LocationFusionRK *	_instance
	Singleton instance of this class.

Detailed Description

This class is a singleton; you do not create one as a global, on the stack, or with new.

From global application setup you must call: LocationFusionRK::instance().setup();

Member Enumeration Documentation

PublishFrequency

enum class LocationFusionRK::PublishFrequency

strong

How often to publish location.

Enumerator
manual	Only when requested.
once	Once after connecting to the cloud.
periodic	Periodically (period is configurable)

Status

enum class LocationFusionRK::Status : int

strong

Current status of this library.

Note that the publishSuccess and publishFailed status codes are only useful when using the handler callback. Almost immediately after that notification, the status goes to idle, so it would be hard to catch this status by polling.

The locEnhancedSuccess and locEnhancedFail also require the callback to be useful. Note the locEnhanced status events are only used if you have enabled a loc-enhanced callback to receive the events on-device. If you do not do this, the loc-enhanced will only exist in the cloud and not be sent back to the device.

If you are implementing sleep control, you can go go sleep if the status is idle.

Enumerator
idle	is idle (cloud connected or not)
publishing	publishing a loc event (includes building the event)
publishSuccess	publish succeeded
publishFail	publish failed
locEnhancedWait	waiting for a loc-enhanced reply
locEnhancedSuccess	loc-enhanced reply received
locEnhancedFail	loc-enhanced reply timed out

Constructor & Destructor Documentation

LocationFusionRK() [1/2]

LocationFusionRK::LocationFusionRK ( )

protected

The constructor is protected because the class is a singleton.

Use LocationFusionRK::instance() to instantiate the singleton.

LocationFusionRK() [2/2]

LocationFusionRK::LocationFusionRK ( const LocationFusionRK & )

protecteddelete

This class is a singleton and cannot be copied

Member Function Documentation

functionHandler()

int LocationFusionRK::functionHandler ( const Variant & eventData )

protected

Called from the Particle.function handler for "cmd".

Parameters

eventData

Returns

int

Calls commandHandlers, added with withCmdHandler.

functionHandlerStatic()

int LocationFusionRK::functionHandlerStatic ( String cmd )

staticprotected

Called from the Particle.function handler for "cmd".

Parameters

cmd

Returns

int

Parses cmd as JSON and the calls the non-static functionHandler.

getPublishFrequency()

PublishFrequency LocationFusionRK::getPublishFrequency ( ) const

inline

Get the current publish frequency. Default is manual.

Returns

PublishFrequency

getStatus()

Status LocationFusionRK::getStatus ( ) const

inline

Get the current status of the library (idle, publishing, etc.)

Returns

Status

This method is used for polling. The be called when the status changes, see withStatusHandler.

instance()

LocationFusionRK & LocationFusionRK::instance ( )

static

Gets the singleton instance of this class, allocating it if necessary.

Use LocationFusionRK::instance() to instantiate the singleton.

locEnhanced()

void LocationFusionRK::locEnhanced ( const Variant & eventData )

protected

Called when a "loc-enhanced" cmd function is received.

Parameters

eventData

Calls locEnhancedHandlers.

locEnhancedStatic()

void LocationFusionRK::locEnhancedStatic ( const Variant & eventData )

staticprotected

Called when a "loc-enhanced" cmd function is received.

Parameters

eventData

This just calls the non-static method with the singleton instance.

lock()

void LocationFusionRK::lock ( )

inline

Locks the mutex that protects shared resources.

This is compatible with WITH_LOCK(*this).

The mutex is not recursive so do not lock it within a locked section.

operator=()

LocationFusionRK & LocationFusionRK::operator= ( const LocationFusionRK & )

protecteddelete

This class is a singleton and cannot be copied

requestPublish()

void LocationFusionRK::requestPublish ( )

inline

Request a publish now.

Works in all modes (manual, once, and periodic). Can be called when offline; it will only be calculated when connected to the cloud (breathing cyan).

setup()

void LocationFusionRK::setup

(

)

Perform setup operations; call this from global application setup()

You typically use LocationFusionRK::instance().setup();

Typically you use all of the withXXX() functions before setup.

stateBuildPublish()

void LocationFusionRK::stateBuildPublish ( )

protected

Internal state handler for building a publish.

May be in this state for a while, but the state handlers are run from a worker thread so it won't affect operation of the rest of the system typically.

Exit conditions:

• When publish begins -> statePublishWait

stateConnected()

void LocationFusionRK::stateConnected ( )

protected

Internal state handler for connected to the cloud.

Exit conditions:

• Particle.connected() return false -> stateIdle
• It's time to publish a location -> stateBuildPublish

stateIdle()

void LocationFusionRK::stateIdle ( )

protected

Internal state handler for idle and not connected to the cloud.

Exit conditions:

• Particle.connected() return true -> stateConnected

stateLocEnhancedWait()

void LocationFusionRK::stateLocEnhancedWait ( )

protected

Internal state handler for waiting for the loc-enhanced to be received.

Exit conditions:

• When loc-enhanced is received or times out -> stateConnected

statePublishWait()

void LocationFusionRK::statePublishWait ( )

protected

Internal state handler for waiting for the publish to complete.

Exit conditions:

• When publish completes -> stateConnected if not receiving loc-enhanced on-device -> stateLocEnhancedWait if receiving loc-enhanced on-device

May set

• manualPublishRequested (set to false on success)
• publishCount (increments on success)
• nextPublishMs increased by either publishPeriod or publishFailureRetry

threadFunction()

os_thread_return_t LocationFusionRK::threadFunction ( void )

protected

Worker thread function.

This method is called to perform operations in the worker thread.

You generally will not return from this method.

tryLock()

bool LocationFusionRK::tryLock ( )

inline

Attempts to lock the mutex that protects shared resources.

Returns

true if the mutex was locked or false if it was busy already.

updateStatus()

void LocationFusionRK::updateStatus ( Status status )

protected

Update the status and call the status handlers. Used internally. Added in 0.0.3.

Parameters

status

This only calls the status handlers if the status changes.

withAddToEventHandler()

LocationFusionRK & LocationFusionRK::withAddToEventHandler ( std::function< void(Variant &eventData, Variant &locVariant)> handler )

inline

Add an "add to event" handler.

Parameters

handler

Returns

LocationFusionRK&

The "add to event" handler allows you to add data to the loc event. You might do this if you want to support a cellular modem that has built-in GNSS, or use an external GNSS receiver.

The handler can be a C function or C++11 lambda and has the following prototype:

void handler(Variant &eventData, Variant &locVariant)

• eventData is the whole loc event
• locVariant is the Variant for the inner loc object

withAddTower()

LocationFusionRK & LocationFusionRK::withAddTower ( bool enable = true )

inline

Add serving cellular tower information to the loc event. Default is false.

Parameters

enable

Returns

LocationFusionRK&

This can be called on devices without cellular (P2, for example) and it will be ignored.

withAddWiFi()

LocationFusionRK & LocationFusionRK::withAddWiFi ( bool enable = true )

inline

Add Wi-Fi access points nearby to the loc event. Default is false.

Parameters

enable

Returns

LocationFusionRK&

This can be called on devices without Wi-Fi (B-SoM, for example) and it will be ignored.

withCmdHandler()

LocationFusionRK & LocationFusionRK::withCmdHandler	(	const char *	cmd,
		std::function< void(const Variant &data)>	handler )

Adds a handler when the Particle function "cmd" is received.

Parameters

cmd
handler

Returns

LocationFusionRK&

Your handler is called when the "cmd" field within the function JSON matches.

The handler can be a C function or C++11 lambda. The prototype is:

withEnableCmdFunction()

LocationFusionRK & LocationFusionRK::withEnableCmdFunction ( bool enable )

inline

Enables or disables the "cmd" function handler. Default is enabled.

Parameters

enable

Returns

LocationFusionRK&

Must be called before setup()!

If disabled, withCmdHandler() and withLocEnhancedHandler() will not function because they require the cmd handler.

If you need to additional custom cmd handlers instead of disabling support, use withCmdHandler() to hook your code into this library instead of the other direction.

withLocEnhancedHandler()

LocationFusionRK & LocationFusionRK::withLocEnhancedHandler ( std::function< void(const Variant &data)> handler )

inline

Adds a handler when loc-enhanced data is calculated by the cloud.

Parameters

handler

Returns

LocationFusionRK&

The handler prototype is:

void handler(const Variant &data);

Fields typically in data in the handler:

• h_acc horizontal accuracy (meters)
• lat latitude
• lon longitude

If you do not add a handler, the loc-enhanced data is not sent to the device. Handling loc-enhanced data locally on device adds one data operation.

withPublishManual()

LocationFusionRK & LocationFusionRK::withPublishManual ( )

inline

Set the publish frequency to manual. Call requestPublish() to do so. This is the default.

Returns

LocationFusionRK&

withPublishOnce()

LocationFusionRK & LocationFusionRK::withPublishOnce ( )

inline

Set the publish frequency to publish once after connecting to the cloud.

Returns

LocationFusionRK&

withPublishPeriodic()

LocationFusionRK & LocationFusionRK::withPublishPeriodic ( std::chrono::milliseconds ms )

inline

Set the publish frequency to publish periodically when cloud connected.

Parameters

ms

Returns

LocationFusionRK&

Even though the parameter is in milliseconds, you probably shouldn't publish more often than every few minutes.

If you are using location fusion on a non-Tracker device it costs 50 data operations per fusion request, so doing location fusion frequently on the free plan may cause your account to be paused due to running out of data operations.

withStatusHandler()

LocationFusionRK & LocationFusionRK::withStatusHandler ( const char * cmd, std::function< void(Status)> handler )

inline

Adds a handler when the status has changed. Added in version 0.0.3.

Parameters

cmd
handler

Returns

LocationFusionRK&

Your handler is called when the "cmd" field within the function JSON matches.

The handler can be a C function or C++11 lambda. The prototype is:

void handler(Status status)

• status The new status value

This method uses a callback to be notified when the status changes. It is called from the library's worker thread so you should not do anything that will block in your callback.

withThreadStackSize()

LocationFusionRK & LocationFusionRK::withThreadStackSize ( size_t size )

inline

Sets the worker thread stack size. Must be set before setup()

Parameters

size	in bytes. The default if you do not call this is 6144

Returns

LocationFusionRK&

Prior to version 0.0.4 the stack was 3072 bytes, but it was increased due to SOS+13 on b5som devices. You can further customize the size by calling this method prior to setup().

Field Documentation

_instance

LocationFusionRK * LocationFusionRK::_instance

staticprotected

Singleton instance of this class.

The object pointer to this class is stored here. It's NULL at system boot.

addToEventHandlers

std::vector<std::function<void(Variant &eventData, Variant &locVariant)> LocationFusionRK::addToEventHandlers)

protected

Vector of handlers to add more information to the location event.

Add using withAddToEventHandler(). You can add multiple handlers.

addTower

bool LocationFusionRK::addTower = false

protected

When building a location publish, add serving tower information.

Default is false, set uskng withAddTower().

addWiFi

bool LocationFusionRK::addWiFi = false

protected

When building a location publish, add Wi-Fi access point information.

Default is false, set uskng withAddWiFi().

enableCmdFunction

bool LocationFusionRK::enableCmdFunction = true

protected

Add a function handler for "cmd".

This is enabled by default and must be enabled for loc-enhanced on device to work.

manualPublishRequested

bool LocationFusionRK::manualPublishRequested = false

protected

true when a manual publish has been requested

This can be requested when offline as it will be handled when online. This can also be used in once and periodic modes to publish npw, out of schedule.

mutex

os_mutex_t LocationFusionRK::mutex = 0

protected

Mutex to protect shared resources.

This is initialized in setup() so make sure you call the setup() method from the global application setup.

nextPublishMs

uint64_t LocationFusionRK::nextPublishMs = 0

protected

When to publish next in periodic mode. Compare to System.millis().

Since this is a uint64_t it does not roll over so comparisons are easier.

thread

Thread* LocationFusionRK::thread = 0

protected

Worker thread instance class.

This is initialized in setup() so make sure you call the setup() method from the global application setup.

---

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

• src/LocationFusionRK.h
• src/LocationFusionRK.cpp