vehicle "heartbeat"

[jean-populus]

Is your feature request related to a problem? Please describe.

We would like to "hear" from vehicles who are parked in the PROW to know if they are still there and ok. Currently we're making assumptions about their location and state - using a lookback period (#749) to determine when vehicles are lost.

Describe the solution you'd like

The concept of a vehicle "heartbeat" where we can verify through communication with the vehicle that it's still out there. Perhaps this can be integrated into MDS Provider /vehicles .

Is this a breaking change

• I'm not sure

Impacted Spec

• provider

Describe alternatives you've considered

n/a

Additional context

see 2022.02.17 working group discussion

[dirkdk]

In the Vehicles endpoint, we could add a field last_heard_from_time. This field would hold the date/time at which the last communication of the vehicle was received.

At Spin we use this quite a bit internally. Our vehicles send indeed heartbeats back on a fairly frequent interval so we know they are still functional and connected to our backend.

[jean-populus]

copying @ezmckinn comment here from #749

ezmckinn commented 8 days ago

I can confirm that this issue also causes confusion from the operator side, and would support capturing this in the spec in some way.

An initial question is, where would a heartbeat be represented? Is that in /status_changes, with an event_type of status_check? Or would we just track a heartbeat internally, and show our scooters in the /vehicles endpoint each time we hear from them internally? Personally I prefer an explicit representation of the heartbeat in /status_changes, but curious as to what others think.

A second question is, how often do cities need to hear from scooters? One heart beat per day? We'll have to strike a balance between reporting enough status changes to meet cities' use cases, without cluttering the /status_changes feed.

A third question: are heartbeats state dependent? If a scooter is removed, do we need to report its heartbeat? If the primary use case here is checking up on vehicles in the PROW to verify that they are still functional, I'd suggest that status changes need only be reported for scooters in the PROW.

[jean-populus]

I think from a city perspective hearing from scooters more frequently is better in order to adjust any counts (aka shorter lookback period). From the steering committees quick survey it seems most operators are getting an internal "heartbeat" at least every 10 minutes.

[schnuerle]

Here is a comment we received from DC:

Lower end of the scale was every minute—at 5-10 minutes we would capture all operators.

The data the operators are receiving has a little bit of variance but always seems to include:

• Battery percentage (also a requirement for GBFS?)
• The lock status
• Timestamp

Other information that may be gathered/analyzed includes:

• GPS location—which takes battery so may not be included
• Enriching the GPS location to know if it’s been moved
• Connectivity data
• Gyroscope
• Motor data
• Battery metrics
• Any error codes

[jiffyclub]

I like the idea of a last_heard_from_time in the /vehicles endpoint, I think we'd get a lot of utility out of that. But how I imagine the heartbeat working is to add a heartbeat event_type and have operators include these as events in the status changes feeds every X hours (I'd recommend every 12 or 24 hours). It's not a "status change" per se since the vehicle's state would not be changing, but this is where the information would be most useful from the perspective of identifying vehicles that have left the PROW without a removed event being sent. Once we have the expectation that we will receive at least one event from every vehicle every 24 hours even if the vehicle is doing nothing but sitting in place we can stop counting any vehicle for which we have not received an event in 24 hours (or 48 or 72 hours as a grace period).

[dirkdk]

@jiffyclub that sounds like two different changes, one for Vehicles and one for Status Changes. I think the Vehicles one is much more straightforward and might be limited work to add to the standard.

For a status change of event_type heartbeat we may need more time to iron out the different source events, what frequency etc. I would want to be careful and not add source events that have a really high frequency (location updates, battery updates).

[ezmckinn]

I agree with @dirkdk on this point — a last_heard_from_time in vehicles seems more aligned with the intention of the heartbeat concept, which I understand as making sure the vehicle is still in working condition. Adding an event type of heartbeat when the actual status of the vehicle hasn't change would obscure more meaningful status updates like trip_end, and require extra logic to parse those out.

[jiffyclub]

The issue with only putting a heartbeat into the /vehicles endpoint is that it's not part of the historical record available via the status changes endpoint. It can tell us about now, but not any other time. If we've pulled a broad time range of data from status changes and are compiling vehicle counts it's useful to have some signal in those events saying "this vehicle is still operational out there" even though it hasn't registered any other kind of event in the last week. Without a heartbeat in the status changes we're still stuck trying to negotiate lookback windows with different regions and operators, which this heartbeat is meant to address. (Or figuring out how to have a historical record from the /vehicles endpoint, which it is not meant to do.)

[jiffyclub]

I tried to put together a summary of the options we've discussed and the pros/cons of each:

Heartbeats in /vehicles

Providers could put a last_heard_from_time in the MDS /vehicles endpoint so consumers can track when a vehicle was last known to be in that location.

Pros

• /vehicles is a natural place for info about vehicles currently in the PROW
• This requires a limited change to MDS itself
• Probably not much work for operators

Cons

• /vehicles can only give data about vehicles in the PROW (or recently in the PROW) at the time of the request
• We still need a lookback period for handling vehicles that never have a removed event in the status changes feed but have left the PROW

Heartbeats in status changes

Create a new event type that providers would include in their status changes feeds once per day for each vehicle to indicate that they had contact with that vehicle at the time of the event, or maybe that they had had contact with the vehicle within X hours preceding the event time.

Pros

• Heartbeats would be included in historic data for use in determining past vehicle counts, which removes the need for a lookback period

Cons

• Work involved in adding a new event type
• Work defining when heartbeats should be sent, what exactly a heartbeat means
• Does adding to status changes imply adding to agency?

[schnuerle]

Nice summary @jiffyclub.

One clarification I think is /vehicles also returns vehicles NOT in the PROW for the most part (90 minutes till removal for some states), which affects a con in the first option.

"Since all states are returned, care should be taken to filter out states not in the PROW if doing vehicle counts. For the states elsewhere and removed which include vehicles not in the PROW but provide some operational clarity for agencies, these must only persist in the feed for 90 minutes before being removed."

[jiffyclub]

Oh nice @schnuerle, I'm not sure I realized we'd made that clarification into the spec. I updated the point above. In practice, I'm not sure we often see removed vehicles in the /vehicles feed, but I haven't done a wide survey of that (and very few operators are on MDS 1.2, when the clarification was added).

[jean-populus]

Instead of requesting a vehicle heartbeat to help standardize a lookback period we're going to move forward with changing the vehicle state "unknown" and incorporating a "last heard" concept.

See proposal to change vehicle state "unknown" and notes from 2022.10.13 WG meeting