Adds HAL for ultrasonics to EVS 1.1
- Adds new structs in types.h
- Adds two new .hal IEvsUltrasonicsArray and IEvsUltrasonicsArrayStream
- Adds new APIs calls in IEvsEnumerator
- Adds empty default implementation for all
Bug: 148619310
Test: Build and functionality tested with demo app.
Change-Id: I8b501c7328d4c02cc694b5a2c73a519ca6d87710
diff --git a/automotive/evs/1.1/Android.bp b/automotive/evs/1.1/Android.bp
index 17f31e4..f9bccef 100644
--- a/automotive/evs/1.1/Android.bp
+++ b/automotive/evs/1.1/Android.bp
@@ -12,6 +12,8 @@
"IEvsCameraStream.hal",
"IEvsDisplay.hal",
"IEvsEnumerator.hal",
+ "IEvsUltrasonicsArray.hal",
+ "IEvsUltrasonicsArrayStream.hal",
],
interfaces: [
"android.frameworks.automotive.display@1.0",
diff --git a/automotive/evs/1.1/IEvsEnumerator.hal b/automotive/evs/1.1/IEvsEnumerator.hal
index 84dd21f..d604e4f 100644
--- a/automotive/evs/1.1/IEvsEnumerator.hal
+++ b/automotive/evs/1.1/IEvsEnumerator.hal
@@ -18,12 +18,13 @@
import IEvsCamera;
import IEvsDisplay;
+import IEvsUltrasonicsArray;
import @1.0::IEvsEnumerator;
import @1.0::EvsResult;
import android.hardware.camera.device@3.2::Stream;
/**
- * Provides the mechanism for EVS camera discovery
+ * Provides the mechanism for EVS camera and ultrasonics array discovery
*/
interface IEvsEnumerator extends @1.0::IEvsEnumerator {
/**
@@ -76,4 +77,33 @@
* @return display EvsDisplay object to be used.
*/
openDisplay_1_1(uint8_t id) generates (IEvsDisplay display);
+
+ /**
+ * Returns a list of all ultrasonics array available to the system.
+ * Will return an empty vector if ultrasonics is not supported.
+ *
+ * @return ultrasonicsArrays A list of ultrasonics available for EVS service.
+ */
+ getUltrasonicsArrayList() generates (vec<UltrasonicsArrayDesc> ultrasonicsArrays);
+
+ /**
+ * Gets the IEvsUltrasonicsArray associated with a ultrasonicsArrayId from a
+ * UltrasonicsDataDesc
+ *
+ * @param ultrasonicsArrayId A unique identifier of the ultrasonic array.
+ * @return evsUltrasonicsArray IEvsUltrasonicsArray object associated with a
+ * given ultrasonicsArrayId.
+ */
+ openUltrasonicsArray(string ultrasonicsArrayId) generates (
+ IEvsUltrasonicsArray evsUltrasonicsArray);
+
+ /**
+ * Return the specified IEvsUltrasonicsArray interface as no longer in use
+ *
+ * When the IEvsUltrasonicsArray object is no longer required, it must be released.
+ * NOTE: Data streaming must be cleanly stopped before making this call.
+ *
+ * @param evsUltrasonicsArray EvsUltrasonics array object to be closed.
+ */
+ closeUltrasonicsArray(IEvsUltrasonicsArray evsUltrasonicsArray);
};
diff --git a/automotive/evs/1.1/IEvsUltrasonicsArray.hal b/automotive/evs/1.1/IEvsUltrasonicsArray.hal
new file mode 100644
index 0000000..ae4f941
--- /dev/null
+++ b/automotive/evs/1.1/IEvsUltrasonicsArray.hal
@@ -0,0 +1,81 @@
+/*
+ * Copyright 2020 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.hardware.automotive.evs@1.1;
+
+import @1.0::EvsResult;
+import UltrasonicsArrayDesc;
+import UltrasonicsDataFrameDesc;
+import IEvsUltrasonicsArrayStream;
+
+/**
+ * HAL interface for ultrasonics sensor array.
+ */
+interface IEvsUltrasonicsArray {
+ /**
+ * Returns the ultrasonic sensor array information.
+ *
+ * @return info The description of this ultrasonic array. This must be the
+ * same value as reported by IEvsEnumerator::getUltrasonicsArrayList().
+ */
+ getUltrasonicArrayInfo() generates (UltrasonicsArrayDesc info);
+
+ /**
+ * Specifies the depth of the buffer chain the ultrasonic sensors is
+ * asked to support.
+ *
+ * Up to this many data frames may be held concurrently by the client of IEvsUltrasonicsArray.
+ * If this many frames have been delivered to the receiver without being returned
+ * by doneWithFrame, the stream must skip frames until a buffer is returned for reuse.
+ * It is legal for this call to come at any time, even while streams are already running,
+ * in which case buffers should be added or removed from the chain as appropriate.
+ * If no call is made to this entry point, the IEvsUltrasonicsArray must support at least one
+ * data frame by default. More is acceptable.
+ *
+ * @param bufferCount Number of buffers the client of
+ * IEvsUltrasonicsArray may hold concurrently.
+ * @return result EvsResult::OK is returned if this call is successful.
+ * Will return EvsResult::INVALID_ARG on invalid bufferCount.
+ */
+ setMaxFramesInFlight(uint32_t bufferCount) generates (EvsResult result);
+
+ /**
+ * Requests to start the stream.
+ *
+ * @param stream Implementation of IEvsUltrasonicsArrayStream.
+ * @return result EvsResult::OK is returned if this call is successful. Returns
+ * EvsResult::STREAM_ALREADY_RUNNING if stream is already running.
+ */
+ startStream(IEvsUltrasonicsArrayStream stream) generates (EvsResult result);
+
+ /**
+ * Requests to stop the delivery of the ultrasonic array data frames.
+ *
+ * Because delivery is asynchronous, frames may continue to arrive for
+ * some time after this call returns. Each must be returned until the
+ * closure of the stream is signaled to the IEvsCameraStream.
+ * This function cannot fail and is ignored if the stream isn't running.
+ */
+ stopStream();
+
+ /**
+ * Notifies the UltrasonicsDataDesc is consumed that was received from
+ * IEvsUltrasonicsArrayStream.
+ *
+ * @param dataFrameDesc Ultrasonics data descriptor.
+ */
+ doneWithDataFrame(UltrasonicsDataFrameDesc dataFrameDesc);
+};
diff --git a/automotive/evs/1.1/IEvsUltrasonicsArrayStream.hal b/automotive/evs/1.1/IEvsUltrasonicsArrayStream.hal
new file mode 100644
index 0000000..f95209f
--- /dev/null
+++ b/automotive/evs/1.1/IEvsUltrasonicsArrayStream.hal
@@ -0,0 +1,40 @@
+/*
+ * Copyright 2020 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.hardware.automotive.evs@1.1;
+
+import UltrasonicsDataFrameDesc;
+import @1.1::EvsEventDesc;
+
+/**
+ * Implemented on client side to receive asynchronous ultrasonic data
+ * deliveries.
+ */
+interface IEvsUltrasonicsArrayStream {
+ /**
+ * Receives calls from the HAL each time a data frame is ready.
+ *
+ * @param dataFrameDesc Ultrasonic array data frame descriptor.
+ */
+ oneway deliverDataFrame(UltrasonicsDataFrameDesc dataFrameDesc);
+
+ /**
+ * Receives calls from the HAL each time an event happens.
+ *
+ * @param event Event EVS event with possible event information.
+ */
+ oneway notify(EvsEventDesc event);
+};
diff --git a/automotive/evs/1.1/default/EvsEnumerator.cpp b/automotive/evs/1.1/default/EvsEnumerator.cpp
index 0319560..415841c 100644
--- a/automotive/evs/1.1/default/EvsEnumerator.cpp
+++ b/automotive/evs/1.1/default/EvsEnumerator.cpp
@@ -355,6 +355,28 @@
return pRecord;
}
+// TODO(b/148608401): Add default implementation with dummy data.
+Return<void> EvsEnumerator::getUltrasonicsArrayList(getUltrasonicsArrayList_cb _hidl_cb) {
+ hidl_vec<UltrasonicsArrayDesc> ultrasonicsArrayDesc;
+ _hidl_cb(ultrasonicsArrayDesc);
+ return Void();
+}
+
+// TODO(b/148608401): Add default implementation with dummy data.
+Return<sp<IEvsUltrasonicsArray>> EvsEnumerator::openUltrasonicsArray(
+ const hidl_string& ultrasonicsArrayId) {
+ (void)ultrasonicsArrayId;
+ sp<IEvsUltrasonicsArray> pEvsUltrasonicsArray;
+ return pEvsUltrasonicsArray;
+}
+
+// TODO(b/148608401): Add default implementation with dummy data.
+Return<void> EvsEnumerator::closeUltrasonicsArray(
+ const ::android::sp<IEvsUltrasonicsArray>& evsUltrasonicsArray) {
+ (void)evsUltrasonicsArray;
+ return Void();
+}
+
} // namespace implementation
} // namespace V1_1
} // namespace evs
diff --git a/automotive/evs/1.1/default/EvsEnumerator.h b/automotive/evs/1.1/default/EvsEnumerator.h
index 9415953..12fd018 100644
--- a/automotive/evs/1.1/default/EvsEnumerator.h
+++ b/automotive/evs/1.1/default/EvsEnumerator.h
@@ -65,6 +65,11 @@
Return<bool> isHardware() override { return true; }
Return<void> getDisplayIdList(getDisplayIdList_cb _list_cb) override;
Return<sp<IEvsDisplay_1_1>> openDisplay_1_1(uint8_t port) override;
+ Return<void> getUltrasonicsArrayList(getUltrasonicsArrayList_cb _hidl_cb) override;
+ Return<sp<IEvsUltrasonicsArray>> openUltrasonicsArray(
+ const hidl_string& ultrasonicsArrayId) override;
+ Return<void> closeUltrasonicsArray(
+ const ::android::sp<IEvsUltrasonicsArray>& evsUltrasonicsArray) override;
// Implementation details
EvsEnumerator(sp<IAutomotiveDisplayProxyService> windowService = nullptr);
diff --git a/automotive/evs/1.1/types.hal b/automotive/evs/1.1/types.hal
index aafdb70..b34e7e7 100644
--- a/automotive/evs/1.1/types.hal
+++ b/automotive/evs/1.1/types.hal
@@ -177,3 +177,194 @@
*/
ABSOLUTE_ZOOM,
};
+
+/**
+ * Structure identifies and describes an ultrasonics array in the car.
+ *
+ * A ultrasonics array represents a group of ultrasonic sensors within the
+ * car. These may be sensors that are physically connected to the same hardware
+ * control unit or represent a logical group of sensors like front and back.
+ * The HAL is responsible for filling out this structure for each Ultrasonics
+ * Array.
+ */
+struct UltrasonicsArrayDesc {
+ /**
+ * Unique identifier for the ultrasonic array. This may be a path or name of the
+ * physical control device or a string identifying a logical group of sensors forming an array
+ * such as "front_array" and "back_array".
+ */
+ string ultrasonicsArrayId;
+
+ /**
+ * Maximum number of readings (points on waveform) provided per sensor in
+ * each data frame. Used by client to pre-allocate required memory buffer for
+ * incoming data.
+ */
+ uint32_t maxReadingsPerSensorCount;
+
+ /**
+ * Maximum number of receiver sensors in a data frame. Must be between 1
+ * and sensorCount. Used by client to pre-allocate required memory buffer for
+ * incoming data.
+ */
+ uint32_t maxReceiversCount;
+
+ /**
+ * The order of sensors specified should preferably be in clockwise order
+ * around the car, starting from front left-most sensor.
+ */
+ vec<UltrasonicSensor> sensors;
+};
+
+/**
+ * Structure for rotation expressed as quaternions.
+ * Convention used: Unit quaternion with hamilton convention.
+ */
+struct RotationQuat {
+ float x;
+ float y;
+ float z;
+ float w;
+};
+
+/** Structure for translation with x, y and z units. */
+struct Translation {
+ float x;
+ float y;
+ float z;
+};
+
+/**
+ * Provides the orientation and location of a car sensor relative to the android automotive
+ * coordinate system:
+ * https://source.android.com/devices/sensors/sensor-types#auto_axes
+ * The sensor pose defines the transformation to be applied to the android automotive axes to
+ * obtain the sensor local axes.
+ * The pose consists of rotation, (specified as a quaternions) and translation
+ * (vector with x, y, z).
+ * This rotation and translation applied to the sensor data in the sensor's local coordinate
+ * system transform the data to the automotive coordinate system.
+ * i.e Pcar = ( Rot * Psensor ) + Trans
+ * Here Pcar is a point in automotive coordinate system and Psensor is a point in the sensor's
+ * coordinate system.
+ * Example:
+ * For a sensor on the front bumper and on the left corner of the car with its X axis pointing to
+ * the front, the sensor is located at (-2, 4, 0) meters w.r.t android automotive axes and the
+ * sensor local axes has a rotation of 90 degrees counter-clockwise w.r.t android automotive axes
+ * when viewing the car from top on the +Z axis side:
+ *
+ * ↑X sensor
+ * Y←∘______
+ * | | front
+ * | car |
+ * | ↑Y |
+ * | ∘→X | rear
+ * |______|
+ *
+ * For this example the rotation and translation will be:
+ * Rotation = + 90 degrees around Z axis = (0.7071, 0, 0, 0.7071) as a unit quaternion.
+ * Translation = (-2, 4, 0) in meters = (-2000, 4000, 0) in milli-meters.
+ * Note: Every sensor type must specify its own pose.
+ */
+struct SensorPose {
+ /**
+ * Rotation part of the sensor pose, expressed as a unit quaternion.
+ */
+ RotationQuat rotation;
+
+ /**
+ * Translation part of the sensor pose, in (x, y, z) format with milli-meter units.
+ */
+ Translation translation;
+};
+
+/**
+ * Structure that contains all information of an ultrasonic sensor.
+ */
+struct UltrasonicSensor {
+ /**
+ * Pose provides the orientation and location of the ultrasonic sensor within the car.
+ * The +Y axis points along the center of the beam spread the X axis to the right and the Z
+ * axis in the up direction.
+ */
+ SensorPose pose;
+
+ /**
+ * Maximum range of the sensor in milli-metres.
+ */
+ float maxRange;
+
+ /**
+ * Half-angle of the angle of measurement of the sensor, relative to the
+ * sensor’s x axis, in radians.
+ */
+ float angleOfMeasurement;
+};
+
+/**
+ * Structure that describes the data frame received from an ultrasonics array.
+ *
+ * Each data frame returned consists of received waveform signals from a subset
+ * of sensors in an array as indicated by the receiversIdList. The signal is
+ * transmitted at a particular time instant indicated by timestampNs from a
+ * subset of sensors in the array as provided in the transmittersIdList.
+ */
+struct UltrasonicsDataFrameDesc {
+ /**
+ * Timestamp of the start of the transmit signal for this data frame.
+ * Timestamp unit is nanoseconds and is obtained from android elapsed realtime clock which is
+ * the time since system was booted and includes deep sleep.
+ * timeOfFlight readings are future-deltas to this timestamp.
+ */
+ uint64_t timestampNs;
+
+ /**
+ * Identifier of data frame. Used by implementation for managing multiple frames in flight.
+ */
+ uint32_t dataFrameId;
+
+ /**
+ * List of indexes of sensors in range [0, sensorCount - 1] that
+ * transmitted the signal for this data frame.
+ */
+ vec<uint8_t> transmittersIdList;
+
+ /**
+ * List of indexes of sensors in range [0, sensorCount - 1] that received
+ * the signal. The order of ids must match the order of the waveforms in the
+ * waveformsData.
+ * Size of list is upper bound by maxReceiversCount.
+ */
+ vec<uint8_t> receiversIdList;
+
+ /**
+ * List of the number of readings corresponding to each ultrasonics sensor in
+ * the receiversIdList. Order of the readings count must match the order in
+ * receiversIdList.
+ * Size of list is upper bound by maxReadingsPerSensorCount.
+ */
+ vec<uint32_t> receiversReadingsCountList;
+
+ /**
+ * Shared memory object containing the waveforms data. Contains one waveform
+ * for each sensor specified in receiversIdList, in order.
+ * Each waveform is represented by a number of readings, which are sample
+ * points on the waveform. The number of readings for each waveform is as
+ * specified in the receiversReadingsCountList.
+ * Each reading is a pair of time Of flight and resonance.
+ * Time of flight (float): Time between transmit and receive signal in nanoseconds.
+ * Resonance (float): Resonance at time on waveform in range [0.0, 1.0].
+ *
+ * The structure of shared memory (example with 2 waveforms, each with 2 readings):
+ *
+ * Byte: | 0 | 1-4 | 5-8 | 9-12 | 13-16 || 17 | 18-21 | 22-25 | 26-29 | 30-33 |
+ * Data: | RecId1 | TOF1 | RES1 | TOF2 | RES2 || RecId2 | TOF1 | RES1 | TOF2 | RES2 |
+ * | Waveform1 || Waveform2 |
+ * Here:
+ * RecId : Receiver's Id. Order matches the receiversIdList, type uint8_t
+ * TOF : Time of flight, type float (4 bytes)
+ * RES : Resonance, type float (4 bytes)
+ * Note: All readings and waveforms are contigious with no padding.
+ */
+ memory waveformsData;
+};