Position.info.heading vs Activity.info.heading and limitations

Background -
I'm trying to understand what Position.info.heading actually indicates, and what the limitations of that number really are.
After doing a bit of searching on the forum, I see a number of threads that indicate that the number provided is problematic so app developers have been putting time into "massaging" the number to get something that's more useful in their apps.

I've built and side-loaded the PositionSample app for a bit of testing, and I've loaded and experimented with a Sailing app that provided sources, as well as contacting the developer of that app.
My observations are.....
- The Sailing app uses raw data from Position.info.heading, so changes in reported heading are a direct reflection of the reporting from the Position class.
- In that app, and in the PositionSample app, the heading value does not change for long periods of time at low speeds (walking). I'll be doing more testing.
- Another app, called RaceQs reports heading. That developer has posted here about problems with Position.info.heading, and about reported time of GPS samples, and has stated that coming up with a Course Over Ground that is useful at low speeds takes a lot of massaging of the data.
- The RaceQs app reports meaningful Course over Ground almost immediately and at low speeds.
- All of these tests were done with GPS signal status being shown as GOOD.

Conclusions -
- It looks like there are limitations on the Position.info.heading values and reporting that I cannot find a description of in the API documentation, or on this forum.
- Developers like the RaceQs developer seem to have found that to get meaningful numbers, they have to develop their own substitute for Position.info.heading

Questions -
- What can I, and other developers count on from Position.info.heading ?
- Does the calculation of that value stop below some speed, and if so.... when does it start and stop ?
- Is there a difference between the value reported in Position.info.heading and in Activity.info.heading, or in any other reporting of heading ?
- What is the best, most accurate source of heading information, and what limitations on accuracy are associated with that source ?

After spending some time looking for these answers, I don't find them.
I hope someone at Garmin, or developers who have already been down this road will provide definitive answers.

Thanks

Jeff over 7 years ago

Thanks Jim.
I'll take a look at the bug reporting rules tomorrow.

jim_m_58 over 7 years ago

Coleman and Brandon are really good at addressing stuff in the bug report forum. That's the way to have Garmin take interest, as they might miss things in a general thread..

peterdedecker over 7 years ago

I agree with Jeff that the info.currentHeading should relate to the direction that you are moving in and (when you are moving) it shouldn't care about the direction the watch is pointing to at all...

example:
app: https://apps.garmin.com/fr-FR/apps/9...8-b6024d672e0e
source code: https://github.com/ravenfeld/Connect...eld-BackToHome

An example that can make this clear are the back to home fields which work fine (well good enough) when you hold the watch in front of you whilst running but point in the "wrong" direction when swinging your arm during the normal run motion (because the currentHeading is wrong at that time)....

(as a workaround you could get around the issue by calculating the real heading yoursef as from a point you were a few seconds before to where you are now, but I also would prefer to see the currentHeading show the direction of motion)

Brandon.ConnectIQ over 7 years ago

I'd like to take a closer look at this because there's a lot flying around in this thread. Here's what I've boiled things down to:

What does Position.info.heading represent?
What does Activity.info.currentHeading represent?
Are there differences between Position.info.heading and Activity.info.currentHeading?
Is there a movement threshold is for heading values, and if there is one, what is that threshold?

My understanding, and the way these are documented, is that the heading values provided by Position and Activity represent the same value--the true north referenced direction of travel when moving, and the compass orientation when not moving. The movement threshold is, roughly speaking, walking speed. I don't know that we publish the exact threshold, but I'd say 1 m/s is probably a pretty good estimate. Raw GPS position has a lot of noise, so we have to set a threshold for movement to prevent the heading value from jumping around when moving slowly or standing still.

Off the top of my head, I'd suggest taking a look at Activity.info.track as a possible alternative, since it provides the direction of travel in radians. However, I think there's still a lot left to be clarified here, so let me do some more digging to see if I can get some more details.

Jeff over 7 years ago

Hi Brandon,
I'm testing on a VivoactiveHR, and have the latest SDK and Eclipse plug-in, and the SW version on the VivoactiveHR is 4.00.
I just re-tested the PositionSample app, which I've modified to report Position.info.heading in degrees to 4 decimal places, and GPS Quality along with lat/lon, altitude and speed, to check to see if it reports the compass orientation when I'm standing still and rotating the watch, or when I'm walking slowly.

It does not.
It reports a fixed value....
If I walk fast enough to start getting heading updates, then slow down again, the last updated value is reported repeatedly until I walk fast again.
So it seems that Position.info.heading does not report compass orientation when the watch is stopped, or moving slowly.

Position.info continues to report changes in lat/lon and speed at very low speeds.
These values are subject to the same noise that the heading value would be, so I don't see the logic behind stopping reports of heading at low speeds.
If, for some reason, it makes sense to say that speed is not adequate to calculate a heading, then I'd think that the calculation of speed would be equally suspect, and it would make sense to have the system indicate INVALID in some way. At a minimum, it makes sense to me to document the limitation that's being imposed on heading reporting.

Brandon.ConnectIQ over 7 years ago

Okay, I have some preliminary answers here. I'm going to further clarify some of this, but I can at least explain how this should behave. First, a couple of definitions:

Heading - the direction you are facing (or the direction the bow of a boat or the nose of a plane is pointing), independent of direction of travel; the compass orientation
Course - the direction of travel, independent of heading; this is also referred to as the track by Garmin

Position.info.heading provides course data (I'm still confirming whether it gives heading information when not moving)
Sensor.info.heading provides heading data
Activity.info.currentHeading provides heading data (however, course data is available in Activity.info.track)

I believe the intended behavior makes sense because:

The Position module is essentially the GPS sensor module, which cannot provide a true heading
The Sensor module is all non-GPS sensors (e.g. the electronic compass), which can provide a true heading but not track/course info
The Activity module uses all available sensors, so is able to provide both within the context of an Activity

Unfortunately, I think we at least have a couple of things that have confused things for folks:

Position.info.heading is poorly named - it would be more accurate to call it Position.info.track
The Activity.info.heading documentation is incorrect and should match the Sensor.info.heading documentation

I still need to test these to confirm the behavior empirically--at this point, I'm just going off what the code tells me it should be doing. I'll continue to investigate and add more detail once I have more to share.

Brandon.ConnectIQ over 7 years ago

Hi Brandon,
I just re-tested the PositionSample app, which I've modified to report Position.info.heading in degrees to 4 decimal places, and GPS Quality along with lat/lon, altitude and speed, to check to see if it reports the compass orientation when I'm standing still and rotating the watch, or when I'm walking slowly.

It does not.
It reports a fixed value....
If I walk fast enough to start getting heading updates, then slow down again, the last updated value is reported repeatedly until I walk fast again.
So it seems that Position.info.heading does not report compass orientation when the watch is stopped, or moving slowly.

Thanks for the update! This sounds consistent with what I've found so far, and seems to confirm my suspicion that Position does not, in fact, provide compass heading when standing still.

Alan.raceQs over 7 years ago

Thanks for the clarifications Brandon,

Coming from a GPS background, I would like to see Position.info.heading renamed to indicate that it is "course over ground" or COG. I think "track" is not specific enough.
I am using the Position module exclusively for my app and so have not run into the difficulties that Jeff has described.

Any news on resolving the timestamp issues (a) 5% slow, b) system time, c) 30 years off)?

Jeff over 7 years ago

To be clear, I've only been working with Position.info.
I mentioned Activity.info because it seemed possible that the data there would provide what I'm looking for, but I haven't done any testing with it.

Brandon.ConnectIQ over 7 years ago

A little more info... I created a test app that shows the heading values from all three modules, and I was able to confirm that:

1. Position, Sensor, and Activity all return the compass heading when standing still on fenix 5
2. Position switches to course (track, COG) when moving on fenix 5, Sensor and Activity do not
3. Position does not display compass heading at all on vivoactive HR (consistent with what Jeff sees, it seems to display the last course value or something), but does switch to course when moving.

I think we have enough information to start deciding how to approach addressing things.

Coming from a GPS background, I would like to see Position.info.heading renamed to indicate that it is "course over ground" or COG. I think "track" is not specific enough.

I'll include this in my report--I'm not sure what we'll decide, but this will be taken into consideration.

Any news on resolving the timestamp issues (a) 5% slow, b) system time, c) 30 years off)?

We have a plan in place to get these fixed. Fortunately, they aren't rooted in problems with the underlying GPS system, but things that need to be addressed in Connect IQ.