1 /*
2  * Copyright (C) 2019 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package android.car.experimental;
17 
18 import android.annotation.FloatRange;
19 import android.os.Parcel;
20 import android.os.Parcelable;
21 
22 import java.util.Objects;
23 
24 /**
25  * Event about a driver's awareness level at a certain point in time.
26  *
27  * <p>Driver Awareness is an abstract concept based on a driver's cognitive situational awareness
28  * of the environment around them. This metric can be approximated based on signals about the
29  * driver's behavior, such as where they are looking or how much their interact with the headunit
30  * in the car.
31  *
32  * <p>Furthermore, what constitutes the boundaries of no awareness and full awareness must be based
33  * on the UX Research through real-world studies and driving simulation. It is the responsibility
34  * of {@link DriverAwarenessSupplier}s to understand how their sensor input fits with current
35  * research in order to determine the appropriate awareness value.
36  *
37  * @hide
38  */
39 public final class DriverAwarenessEvent implements Parcelable {
40 
41     private final long mTimeStamp;
42 
43     @FloatRange(from = 0.0f, to = 1.0f)
44     private final float mAwarenessValue;
45 
46     /**
47      * Creator for {@link Parcelable}.
48      */
49     public static final Parcelable.Creator<DriverAwarenessEvent> CREATOR =
50             new Parcelable.Creator<DriverAwarenessEvent>() {
51                 public DriverAwarenessEvent createFromParcel(Parcel in) {
52                     return new DriverAwarenessEvent(in);
53                 }
54 
55                 public DriverAwarenessEvent[] newArray(int size) {
56                     return new DriverAwarenessEvent[size];
57                 }
58             };
59 
60     /**
61      * Creates an instance of a {@link DriverAwarenessEvent}.
62      *
63      * @param timeStamp      the time that the awareness value was sampled, in milliseconds elapsed
64      *                       since system boot
65      * @param awarenessValue the driver's awareness level at this point in time, ranging from 0, no
66      *                       awareness, to 1, full awareness
67      */
DriverAwarenessEvent(long timeStamp, @FloatRange(from = 0.0f, to = 1.0f) float awarenessValue)68     public DriverAwarenessEvent(long timeStamp,
69             @FloatRange(from = 0.0f, to = 1.0f) float awarenessValue) {
70         mTimeStamp = timeStamp;
71         mAwarenessValue = awarenessValue;
72     }
73 
74     /**
75      * Parcelable constructor.
76      */
DriverAwarenessEvent(Parcel in)77     private DriverAwarenessEvent(Parcel in) {
78         mTimeStamp = in.readLong();
79         mAwarenessValue = in.readFloat();
80     }
81 
82     /**
83      * Returns the time at which this driver awareness value was inferred based on the car's
84      * sensors. It is the elapsed time in milliseconds since system boot.
85      */
getTimeStamp()86     public long getTimeStamp() {
87         return mTimeStamp;
88     }
89 
90     /**
91      * The current driver awareness value, where 0 is no awareness and 1 is full awareness.
92      */
93     @FloatRange(from = 0.0f, to = 1.0f)
getAwarenessValue()94     public float getAwarenessValue() {
95         return mAwarenessValue;
96     }
97 
98     @Override
describeContents()99     public int describeContents() {
100         return 0;
101     }
102 
103     @Override
writeToParcel(Parcel dest, int flags)104     public void writeToParcel(Parcel dest, int flags) {
105         dest.writeLong(mTimeStamp);
106         dest.writeFloat(mAwarenessValue);
107     }
108 
109     @Override
equals(Object o)110     public boolean equals(Object o) {
111         if (this == o) {
112             return true;
113         }
114         if (!(o instanceof DriverAwarenessEvent)) {
115             return false;
116         }
117         DriverAwarenessEvent that = (DriverAwarenessEvent) o;
118         return mTimeStamp == that.mTimeStamp
119                 && Float.compare(that.mAwarenessValue, mAwarenessValue) == 0;
120     }
121 
122     @Override
hashCode()123     public int hashCode() {
124         return Objects.hash(mTimeStamp, mAwarenessValue);
125     }
126 
127     @Override
toString()128     public String toString() {
129         return String.format("DriverAwarenessEvent{timeStamp=%s, awarenessValue=%s}",
130                 mTimeStamp, mAwarenessValue);
131     }
132 }
133