1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
|
/*
* Copyright (C) 2014 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.
*/
/*
* Activity Recognition HAL. The goal is to provide low power, low latency, always-on activity
* recognition implemented in hardware (i.e. these activity recognition algorithms/classifers
* should NOT be run on the AP). By low power we mean that this may be activated 24/7 without
* impacting the battery drain speed (goal in order of 1mW including the power for sensors).
* This HAL does not specify the input sources that are used towards detecting these activities.
* It has one monitor interface which can be used to batch activities for always-on
* activity_recognition and if the latency is zero, the same interface can be used for low latency
* detection.
*/
#ifndef ANDROID_ACTIVITY_RECOGNITION_INTERFACE_H
#define ANDROID_ACTIVITY_RECOGNITION_INTERFACE_H
#include <hardware/hardware.h>
__BEGIN_DECLS
#define ACTIVITY_RECOGNITION_HEADER_VERSION 1
#define ACTIVITY_RECOGNITION_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION_2(0, 1, ACTIVITY_RECOGNITION_HEADER_VERSION)
#define ACTIVITY_RECOGNITION_HARDWARE_MODULE_ID "activity_recognition"
#define ACTIVITY_RECOGNITION_HARDWARE_INTERFACE "activity_recognition_hw_if"
/*
* Define types for various activities. Multiple activities may be active at the same time and
* sometimes none of these activities may be active.
*
* Each activity has a corresponding type. Only activities that are defined here should use
* android.activity_recognition.* prefix. OEM defined activities should not use this prefix.
* Activity type of OEM-defined activities should start with the reverse domain name of the entity
* defining the activity.
*
* When android introduces a new activity type that can potentially replace an OEM-defined activity
* type, the OEM must use the official activity type on versions of the HAL that support this new
* official activity type.
*
* Example (made up): Suppose Google's Glass team wants to detect nodding activity.
* - Such an activity is not officially supported in android L
* - Glass devices launching on L can implement a custom activity with
* type = "com.google.glass.nodding"
* - In M android release, if android decides to define ACITIVITY_TYPE_NODDING, those types
* should replace the Glass-team-specific types in all future launches.
* - When launching glass on the M release, Google should now use the official activity type
* - This way, other applications can use this activity.
*/
#define ACTIVITY_TYPE_IN_VEHICLE "android.activity_recognition.in_vehicle"
#define ACTIVITY_TYPE_ON_BICYCLE "android.activity_recognition.on_bicycle"
#define ACTIVITY_TYPE_WALKING "android.activity_recognition.walking"
#define ACTIVITY_TYPE_RUNNING "android.activity_recognition.running"
#define ACTIVITY_TYPE_STILL "android.activity_recognition.still"
#define ACTIVITY_TYPE_TILTING "android.activity_recognition.tilting"
/* Values for activity_event.event_types. */
enum {
/*
* A flush_complete event which indicates that a flush() has been successfully completed. This
* does not correspond to any activity/event. An event of this type should be added to the end
* of a batch FIFO and it indicates that all the events in the batch FIFO have been successfully
* reported to the framework. An event of this type should be generated only if flush() has been
* explicitly called and if the FIFO is empty at the time flush() is called it should trivially
* return a flush_complete_event to indicate that the FIFO is empty.
*
* A flush complete event should have the following parameters set.
* activity_event_t.event_type = ACTIVITY_EVENT_FLUSH_COMPLETE
* activity_event_t.activity = 0
* activity_event_t.timestamp = 0
* activity_event_t.reserved = 0
* See (*flush)() for more details.
*/
ACTIVITY_EVENT_FLUSH_COMPLETE = 0,
/* Signifies entering an activity. */
ACTIVITY_EVENT_ENTER = 1,
/* Signifies exiting an activity. */
ACTIVITY_EVENT_EXIT = 2
};
/*
* Each event is a separate activity with event_type indicating whether this activity has started
* or ended. Eg event: (event_type="enter", activity="ON_FOOT", timestamp)
*/
typedef struct activity_event {
/* One of the ACTIVITY_EVENT_* constants defined above. */
uint32_t event_type;
/*
* Index of the activity in the list returned by get_supported_activities_list. If this event
* is a flush complete event, this should be set to zero.
*/
uint32_t activity;
/* Time at which the transition/event has occurred in nanoseconds using elapsedRealTimeNano. */
int64_t timestamp;
/* Set to zero. */
int32_t reserved[4];
} activity_event_t;
typedef struct activity_recognition_module {
/**
* Common methods of the activity recognition module. This *must* be the first member of
* activity_recognition_module as users of this structure will cast a hw_module_t to
* activity_recognition_module pointer in contexts where it's known the hw_module_t
* references an activity_recognition_module.
*/
hw_module_t common;
/*
* List of all activities supported by this module including OEM defined activities. Each
* activity is represented using a string defined above. Each string should be null terminated.
* The index of the activity in this array is used as a "handle" for enabling/disabling and
* event delivery.
* Return value is the size of this list.
*/
int (*get_supported_activities_list)(struct activity_recognition_module* module,
char const* const* *activity_list);
} activity_recognition_module_t;
struct activity_recognition_device;
typedef struct activity_recognition_callback_procs {
// Callback for activity_data. This is guaranteed to not invoke any HAL methods.
// Memory allocated for the events can be reused after this method returns.
// events - Array of activity_event_t s that are reported.
// count - size of the array.
void (*activity_callback)(const struct activity_recognition_callback_procs* procs,
const activity_event_t* events, int count);
} activity_recognition_callback_procs_t;
typedef struct activity_recognition_device {
/**
* Common methods of the activity recognition device. This *must* be the first member of
* activity_recognition_device as users of this structure will cast a hw_device_t to
* activity_recognition_device pointer in contexts where it's known the hw_device_t
* references an activity_recognition_device.
*/
hw_device_t common;
/*
* Sets the callback to invoke when there are events to report. This call overwrites the
* previously registered callback (if any).
*/
void (*register_activity_callback)(const struct activity_recognition_device* dev,
const activity_recognition_callback_procs_t* callback);
/*
* Activates monitoring of activity transitions. Activities need not be reported as soon as they
* are detected. The detected activities are stored in a FIFO and reported in batches when the
* "max_batch_report_latency" expires or when the batch FIFO is full. The implementation should
* allow the AP to go into suspend mode while the activities are detected and stored in the
* batch FIFO. Whenever events need to be reported (like when the FIFO is full or when the
* max_batch_report_latency has expired for an activity, event pair), it should wake_up the AP
* so that no events are lost. Activities are stored as transitions and they are allowed to
* overlap with each other. Each (activity, event_type) pair can be activated or deactivated
* independently of the other. The HAL implementation needs to keep track of which pairs are
* currently active and needs to detect only those pairs.
*
* activity_handle - Index of the specific activity that needs to be detected in the list
* returned by get_supported_activities_list.
* event_type - Specific transition of the activity that needs to be detected.
* max_batch_report_latency_ns - a transition can be delayed by at most
* “max_batch_report_latency” nanoseconds.
* Return 0 on success, negative errno code otherwise.
*/
int (*enable_activity_event)(const struct activity_recognition_device* dev,
uint32_t activity_handle, uint32_t event_type, int64_t max_batch_report_latency_ns);
/*
* Disables detection of a specific (activity, event_type) pair.
*/
int (*disable_activity_event)(const struct activity_recognition_device* dev,
uint32_t activity_handle, uint32_t event_type);
/*
* Flush all the batch FIFOs. Report all the activities that were stored in the FIFO so far as
* if max_batch_report_latency had expired. This shouldn't change the latency in any way. Add
* a flush_complete_event to indicate the end of the FIFO after all events are delivered.
* See ACTIVITY_EVENT_FLUSH_COMPLETE for more details.
* Return 0 on success, negative errno code otherwise.
*/
int (*flush)(const struct activity_recognition_device* dev);
// Must be set to NULL.
void (*reserved_procs[16 - 4])(void);
} activity_recognition_device_t;
static inline int activity_recognition_open(const hw_module_t* module,
activity_recognition_device_t** device) {
return module->methods->open(module,
ACTIVITY_RECOGNITION_HARDWARE_INTERFACE, (hw_device_t**)device);
}
static inline int activity_recognition_close(activity_recognition_device_t* device) {
return device->common.close(&device->common);
}
__END_DECLS
#endif // ANDROID_ACTIVITY_RECOGNITION_INTERFACE_H
|