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