Plumb through new "matched bluetooth vehicle" from the phone to the server and to the trip

[shankari]

@JGreenlee @louisg1337 @the-bay-kay for visibility and feedback

[shankari]

We need to make some design decisions before implementing this feature.

Decision 1: Do we need to store this as a separate object, or should we treat it as a statemachine transition?
When we use the iOS visit API, we generate VISIT_STARTED and VISIT_ENDED transitions in the current state.
Given that our primary use case here is to use the beacon region enter and exit to detect the start and stop of fleet vehicles, can we just use similar BEACON_STARTED and BEACON_ENDED messages?

I think that is not the best option. Some challenges with that approach:

• the transition object only has the current state and the new transition. For this use case, it is crucial to also include at least the UUID, since we want to map that to the actual type of car
• in the long-term, non-fleet case, not every enter/exit will be associated with a state machine transition. For example, a transition between a bicycle with a beacon and a bus with a beacon would be a section change, and would not not necessarily reflect a state change.
• if the enter/exit is noisy, we may transition already using the geofence

The third is not a great argument, since the visit transitions may also not trigger an FSM transition if the geofence has already triggered. But I think that the second is really compelling. So let's go with a separate object.

Decision 2: Should the separate object be a manual/ or a background/?
Per the data model, I think it should be a background/ object. Although it is not necessarily being continuously sensed now, there is no manual intervention required to generate it. And in the future, I guess we could also periodically monitor the signal strength during the course of the trip to ensure that the enter was not an outlier, or with Bluetooth classic across phones, etc.

Decision 3: What should the data structure look like?
Here's a proposal based on copying the BLE beacon + classic structure over and combining it with vehicle information. @JGreenlee, is this consistent with what you had in mind for the values in the dynamic config?

{
    bluetoothType: CLASSIC | BLE
    bluetoothDetails: BluetoothClassicDetails | BLEDetails
    vehicleType: CAR | BUS | BICYCLE | ...
    vehicleDetails: CarDetails (can potentially include BikeDetails | BusDetails | .... in the future as we expand)
}

BluetoothClassicDetails (from https://developer.apple.com/documentation/externalaccessory/eaaccessory?language=objc)
The original spec also has firmware revision and hardware revision. Not sure how many of those incidental fields are required for our use case. Need to experiment and tweak
{
    name:
    manufacturer:
    modelNumber:
    serialNumber:
    protocolStrings:
    connectionID:
}

BLEDetails (basically, region and event type, I am also supporting range although it is not clear if we will need to use it
{
    uuid:
    major:
    minor:
    proximity: UNKNOWN | IMMEDIATE | NEAR | FAR
    rssi:
    tx:
    accuracy:
}

vehicleDetails
{
    license:
    make:
    model:
    year:
    engine: ICE | HYBRID | BEV | HYDROGENV | BIOV
}

[JGreenlee]

For decision 3, would this be the structure of the stored background/ object?

I thought this would only include the bluetooth beacon information.

And I thought the vehicle information would be in the dynamic config. Something like this:

{
  ...
  "vehicle_identities": [
    {
      "value": "e_car_1234",
      "bluetooth_ids": ["00:1A:2B:3C:4D:5E"],
      "name": "Leaf A",
      "baseMode":"E_CAR",
      "met_equivalent":"IN_VEHICLE",
      "kgCo2PerKm": 0.08216,
      "vehicle_info": {
        "make": "Nissan",
        "model": "Leaf",
        "year": 2018,
        "license": "AAA 1234"
      }
    },
    {
      "value": "e_car_5678",
      "bluetooth_ids": ["00:1A:2B:3C:4D:5F"],
      "name": "Leaf B",
      "baseMode":"E_CAR",
      "met_equivalent":"IN_VEHICLE",
      "kgCo2PerKm": 0.08216,
      "vehicle_info": {
        "make": "Nissan",
        "model": "Leaf",
        "year": 2020,
        "license": "BBB 5678"
      }
    }
  ],
  ...
}

[JGreenlee]

If we are going to support BLE and Bluetooth classic (maybe in the future), and these have different properties, what about having 2 different types: background/bluetooth_ble and background/bluetooth_classic

[shankari]

For decision 3, would this be the structure of the stored background/ object?
Yes.

I thought this would only include the bluetooth beacon information.
And I thought the vehicle information would be in the dynamic config. Something like this:

That could also work. Per my conversation with @the-bay-kay, since we have to have the full list of UUIDs to "register" them, it would be easy enough to have all the information in the background/ object as well. Is that correct, @louisg1337?

Let us think through the various options and their pros and cons.

Must happen native code must receive a list of BLE beacons so that it can create the appropriate "regions". The list must come from the dynamic config so that it can be different for each fleet.
Question 1: How are the beacons configured:

1. UI reads dynamic config and passes it in to native code via a function call
   a. UI only passes in BLE UUIDs
   b. UI passes in full vehicle_identifier object
2. The dynamic config is saved into local storage as usual (unchanged)
   • The native code reads the dynamic config directly from native config and configures the regions

Question 2: What do the background objects look like?

1. Native code generates background/ objects with only beacon UUID
   • When UI displays "draft" trips, it reads the background/ objects, maps them to the dynamic config, and creates the draft composite trips with the vehicle information filled in
   • On the server, we read the dynamic config match the background/ objects to sections and copy them into the confirmed and composite objects. Note that reading the dynamic config on the server is relatively new.
2. Native code generates background/ objects with beacon UUID + whole vehicle information
   - When UI displays "draft" trips, it reads the background/ objects and displays them
   - On the server, we match the background/ objects to sections and copy them (no need to read and handle the dynamic config)

For the decisions:
Q1: I think (2) is better because I am not sure how long the regions persist and when they are deleted. On android, for example, IIRC that all location-based geofences are deleted when the app is updated. If we have the native code read the values and register directly, we can do so even if the user hasn't launched the app.
Q2: I don't have a strong preference. (2) is a bit easier to implement, but will take up a little more storage.

@JGreenlee do you have a preference?

[shankari]

Also, I had a question around must happen (aka native code must receive a list of BLE beacons so that it can create the appropriate "regions"). From the iOS docs, it looks like we can have multiple beacons with the same UUID and different major and minor values https://developer.apple.com/documentation/corelocation/determining_the_proximity_to_an_ibeacon_device?language=objc

The UUID (universally unique identifier) is a 128-bit value that uniquely identifies your app’s beacons.
The major value is a 16-bit unsigned integer that you use to differentiate groups of beacons with the same UUID.

...

The most important point to me here is the part which says "your app’s beacons". Since the beacons are really intended for use with OpenPATH, maybe we can configure them all with the same UUID, that is hardcoded (or put into an app-level config) into OpenPATH. Then we only need to listen for one UUID, note that the major and minor values can be wildcards in the scan. This might also be good for long-term scalability, so that we don't run into the maximum number of geofences we can create. At least for location-based regions on iOS, this limit seems to be 20.

Regions are shared resources that rely on specific hardware capabilities. To ensure that all apps can participate in region monitoring, Core Location prevents any single app from monitoring more than 20 regions simultaneously. To work around this limitation, monitor only regions that are close to the user’s current location. As the user moves, update the list based on the user’s new location.

I did not find a similar number of beacon-based regions, but the message above says "Core Location" and this SO post claims that the limit also applies to beacon regions
https://stackoverflow.com/questions/8734101/what-is-the-maximum-number-of-regions-that-can-be-monitored-with-startmonitoring#comment52676399_8734329
(20 for location, 20 for beacons)

Further, the example for how to use the beacons
https://developer.apple.com/documentation/corelocation/determining_the_proximity_to_an_ibeacon_device?language=objc
makes it very clear that the UUID and the identifier are expected to be fixed on a per-app basis.

@louisg1337, is it possible for us to experiment with multiple beacons configured with the same UUID? If we leave the major and minor keys as blank while registering the region, does the callback return them? Or do we have to start scanning to get that information? It is fairly clear that the major and minor values will show up if we start scanning.

We can't test this with the current UI since the hardcoded values have the major and minor key defined. Fortunately I made a change last night that allows us to put new entries into the list. Or of course, you can just edit the current app to remove major and minor keys.

We need to answer this first thing because it will affect everything downstream

If we are going to search for a hardcoded (or app-level configured) UUID, then the native code does not need a list of UUIDs from the dynamic config, which means that we have a strong vote for the second option for Question 2.

[JGreenlee]

@JGreenlee do you have a preference?

After seeing the approaches for Q2 laid out, I don't have a strong preference either.

One reason I might express a slight preference for (2) is that it allows the native code to be agnostic of vehicles. It would only have to worry about beacons, so the native code would be a bit simpler and more generic.

On the server, we read the dynamic config match the background/ objects to sections and copy them into the confirmed and composite objects. Note that reading the dynamic config on the server is relatively new.

Would we necessarily have to do this? What if the trip object just had value?. This would be similar to what we do for mode+purpose labels; the trip object just has the string value for the label and the UI looks up baseMode, met, and co2PerKm from the label_options config.

[shankari]

Added two, about to add third entry	After adding the third entry

[shankari]

The plugin that we use requires both an identifier and a UUID. This is because the call to create a beacon used to require both a UUID and an identifier.
https://developer.apple.com/documentation/corelocation/clbeaconregion/3183025-initwithuuid?language=objc

However, that call is now deprecated. We should not be using CLBeaconRegion anymore, we should be using CLBeaconIdentityCondition. This new class only requires a UUID. It has no reference to an identifier.

Even in the old days, the identifier was static and hardcoded

        // Match all beacons with the specified UUID
        let proximityUUID = UUID(uuidString: 
               "39ED98FF-2900-441A-802F-9C398FC199D2")
        let beaconID = "com.example.myBeaconRegion"
            
        // Create the region and begin monitoring it.
        let region = CLBeaconRegion(proximityUUID: proximityUUID!,
               identifier: beaconID)

Note also that the UUID in the new method is of type NSUUID, which is a 128-bit value created to conform to RFC 4122. It cannot be an arbitrary string. So from the example above, we must use "39ED98FF..." and we cannot use "com.example.myBeaconRegion"

Since the identifier is still required in the plugin, I am going to use a hardcoded value for it, edu.berkeley.eecs.emission to be consistent with the example.

Note also that the way to avoid specifying the major and minor values is to use undefined
https://github.com/louisg1337/cordova-plugin-ibeacon?tab=readme-ov-file#specify-wildcard-uuid-android-only

[shankari]

Optional major and minor	Refactored display to highlight UUID and major/minor

[shankari]

I am working on a PR to simulate BLE scans e-mission/e-mission-phone#1140

[shankari]

It's going to be a bit tricky to know how to display the matches to see if we have minor and major values without running the code, since there is not much documentation (from the iOS level up) around what this may look like. Let's just stringify the result and display it for now.