add support for ranging angles and elevation

[sdetweil]

started adding support for angles and elevation on ranging..
because the 2 platform create different source objects/values,
I change the rangingCallback to support the raw values, distance, azimuth and elevation
and added those to the device table

I added some of the IOS current model support for convergence and
my existing code updates the config returned from the remote device, with the cameraAssistance needed
and that is what the NISession.run() is done against.

some values are missing from the Nearby object for
pending convergence, needing light, horizontal movement and vertical movement.
it appears those are bit values in the convergence status, see

didUpdateAlgorithmConvergence: NIAlgorithmConvergence,

i comment inserted my ios swift code (HW running QANI, not UCI firmware) for that.. I don't see those values in the Nearby classes. without convergence, only get distance..

I posted in the Qorvo forums about convergence

from the apple dev docs

Apple Developer Documentation

Initiating and maintaining a session | Apple Developer Documentation
Measure the relative position of a nearby device and coach the user to sustain interaction.

Increase line of sight with Camera Assistance
In iOS 16, (sept 22, iPhone 14) , Camera Assistance (isCameraAssistanceEnabled) increases the device’s line of sight to a larger area that surrounds the device. This provides a nearby object’s distance and direction in a wider range of environmental conditions, in addition to the object’s horizontalAngle and verticalDirectionEstimate.

==============
Camera Assistance provides a direction outside of the narrow line of sight ===>only after first encountering the peer device once within the narrow line of sight. <==== (convergence, moving the phone around)
To use Camera Assistance in an interaction session, ensure the device supports the feature first by checking the value of supportsCameraAssistance.

it does NOT mention, if you DON’T set cameraAssistance to true, then you ONLY get distance.
which killed our app functionality.

----- on my other hardware, mentioned in the issue, the phone doesn't range. an intermediate device does the BLE scanning and UCI ranging under the covers. so the app is completely isolated from the OS.. just uses BLE to talk to the intermediate board.

the app just gets the BLE device scan results, and the start/stop ranging command results and the UCI ranging status notifications. (NTFs)

I don't know if you want to invest in the non-UCI apple implementation, but I haven't seen any indication that they will go this way

.... doah, was looking a the java doc, not kotlin
the other thing is on the ranging status
https://developer.android.com/reference/androidx/core/uwb/RangingPosition

says the Position, holds measurements, which have declared methods. getDirection()....
BUT not..
and if you look in https://developer.android.com/reference/androidx/core/uwb/RangingMeasurement
it has a function getValue()
BUT not..
there is a value operator on measurement,

but the getAzimuth/Elevation are supposed to support the optional NULL if not present, but the value does not
Unless there is a kotlin side effect here
….
I have a UWB Pixel coming next week to see how this works..

[dustedrob]

Hi! Appreciate the contribution! Let me go over this in the next day or so and merge it. Thank you

[sdetweil]

I also need to update the readme.

As far as I know, Android can only range with one device at a time (one:one).
not one:many, altho Fira and uci support it
I do see the doc says 1:many

iOS is only one:one
So I currently startScan/stopScan , find all devices
Then startRanging(Id)

one quirk, when multiple users are trying to discover and range, there is a moment when a device is not found when another app is connecting to discover the characteristics, or when ranging with another phone
So on startRanging() I scan again to validate that device is still available to range with this phone

[sdetweil]

this might require controlee firmware change, (I'm going to test with mine for the config write back)
the peripheral once connected from central, can query the central over the connection for its services and characteristics supported by a gatt server on the central side.. no central advertise required..