#include <LocationFusionRK.h>
|
| os_mutex_t | mutex = 0 |
| | Mutex to protect shared resources.
|
| |
| Thread * | thread = 0 |
| | Worker thread instance class.
|
| |
|
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::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
|
| |
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();
◆ PublishFrequency
How often to publish location.
| Enumerator |
|---|
| manual | Only when requested.
|
| once | Once after connecting to the cloud.
|
| periodic | Periodically (period is configurable)
|
◆ LocationFusionRK() [1/2]
| LocationFusionRK::LocationFusionRK |
( |
| ) |
|
|
protected |
◆ LocationFusionRK() [2/2]
This class is a singleton and cannot be copied
◆ functionHandler()
| int LocationFusionRK::functionHandler |
( |
const Variant & | eventData | ) |
|
|
protected |
Called from the Particle.function handler for "cmd".
- Parameters
-
- Returns
- int
Calls commandHandlers, added with withCmdHandler.
◆ functionHandlerStatic()
| int LocationFusionRK::functionHandlerStatic |
( |
String | cmd | ) |
|
|
staticprotected |
Called from the Particle.function handler for "cmd".
- Parameters
-
- Returns
- int
Parses cmd as JSON and the calls the non-static functionHandler.
◆ getPublishFrequency()
Get the current publish frequency. Default is manual.
- Returns
- PublishFrequency
◆ instance()
◆ locEnhanced()
| void LocationFusionRK::locEnhanced |
( |
const Variant & | eventData | ) |
|
|
protected |
Called when a "loc-enhanced" cmd function is received.
- Parameters
-
Calls locEnhancedHandlers.
◆ locEnhancedStatic()
| void LocationFusionRK::locEnhancedStatic |
( |
const Variant & | eventData | ) |
|
|
staticprotected |
Called when a "loc-enhanced" cmd function is received.
- Parameters
-
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=()
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 |
( |
| ) |
|
◆ 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
◆ statePublishWait()
| void LocationFusionRK::statePublishWait |
( |
| ) |
|
|
protected |
Internal state handler for waiting for the publish to complete.
Exit conditions:
- When publish completes -> stateConnected
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.
◆ withAddToEventHandler()
| LocationFusionRK & LocationFusionRK::withAddToEventHandler |
( |
std::function< void(Variant &eventData, Variant &locVariant)> | handler | ) |
|
|
inline |
Add an "add to event" handler.
- Parameters
-
- 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()
Add serving cellular tower information to the loc event. Default is false.
- Parameters
-
- Returns
- LocationFusionRK&
This can be called on devices without cellular (P2, for example) and it will be ignored.
◆ withAddWiFi()
Add Wi-Fi access points nearby to the loc event. Default is false.
- Parameters
-
- 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
-
- 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()
Enables or disables the "cmd" function handler. Default is enabled.
- Parameters
-
- 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
-
- 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()
◆ withPublishOnce()
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
-
- 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.
◆ _instance
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:
