4d47512510
Sensors package will contain APIs to read data from a wide variety of movement, position and other physical signals. This CL contains the initial APIs that are targeting event-based sensors. Some of the concerns that influenced the APIs are: - Target game developers. Latency is critical, allow output rates up to ~10 samples per second. - It’s rarely possible to predetermine the minimally viable sample rate requirement of the app. - Allow users to set an upper bound rate to avoid garbage and preserve battery life. - Allow multiple instances of accelerometer, gyroscope, magnetometer and altimeter sensors to be started. Optimize the share of the underlying resources as long as it is not a bottleneck for the sample rate. - Prefer blocking APIs. An automatic poll-timeout could be useful if we’re far behind the sample rate. But, sensor initialization and waking-up significantly take longer and there is no easy way to determine a sensor is in either one of these states. - Provide timestamps for each event to determine the actual rate of the sensor data. - Allow user to return multiple events from each call. Buffering the events at the cost of additional latency is sometimes more neglectable than the overhead of a function call that polls the events one by one. Allow user to determine how many items they want to buffer. The typical latency of a read a single event is 56 usec. Reading 8-16 events at once has a relatively lower bound per event. For high precision throughput, the opportunity to minimize a function call overhead could be useful. - Allow users to check the sensor availability on the device. Change-Id: I9582c8f025d9f922d9635e247d60817f95bdacb9 Reviewed-on: https://go-review.googlesource.com/8174 Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>
114 lines
3.1 KiB
Go
114 lines
3.1 KiB
Go
// Copyright 2015 The Go Authors. All rights reserved.
|
|
// Use of this source code is governed by a BSD-style
|
|
// license that can be found in the LICENSE file.
|
|
|
|
// Package sensor provides sensor events from various movement sensors.
|
|
package sensor
|
|
|
|
import (
|
|
"errors"
|
|
"sync"
|
|
"time"
|
|
)
|
|
|
|
// Type represents a sensor type.
|
|
type Type int
|
|
|
|
var sensorNames = map[Type]string{
|
|
Accelerometer: "Accelerometer",
|
|
Gyroscope: "Gyrsocope",
|
|
Magnetometer: "Magnetometer",
|
|
}
|
|
|
|
// String returns the string representation of the sensor type.
|
|
func (t Type) String() string {
|
|
if n, ok := sensorNames[t]; ok {
|
|
return n
|
|
}
|
|
return "Unknown sensor"
|
|
}
|
|
|
|
var (
|
|
Accelerometer = Type(0)
|
|
Gyroscope = Type(1)
|
|
Magnetometer = Type(2)
|
|
)
|
|
|
|
// Event represents a sensor event.
|
|
type Event struct {
|
|
// Sensor is the type of the sensor the event is coming from.
|
|
Sensor Type
|
|
|
|
// Timestamp is a device specific event time in nanoseconds.
|
|
// Timestamps are not Unix times, they represent a time that is
|
|
// only valid for the device's default sensor.
|
|
Timestamp int64
|
|
|
|
// Data is the event data.
|
|
//
|
|
// If the event source is Accelerometer,
|
|
// - Data[0]: acceleration force in x axis in m/s^2
|
|
// - Data[1]: acceleration force in y axis in m/s^2
|
|
// - Data[2]: acceleration force in z axis in m/s^2
|
|
//
|
|
// If the event source is Gyroscope,
|
|
// - Data[0]: rate of rotation around the x axis in rad/s
|
|
// - Data[1]: rate of rotation around the y axis in rad/s
|
|
// - Data[2]: rate of rotation around the z axis in rad/s
|
|
//
|
|
// If the event source is Magnetometer,
|
|
// - Data[0]: force of gravity along the x axis in m/s^2
|
|
// - Data[1]: force of gravity along the y axis in m/s^2
|
|
// - Data[2]: force of gravity along the z axis in m/s^2
|
|
//
|
|
Data []float64
|
|
}
|
|
|
|
// Manager multiplexes sensor event data from various sensor sources.
|
|
type Manager struct {
|
|
once sync.Once
|
|
m *manager // platform-specific implementation of the underlying manager
|
|
}
|
|
|
|
func (m *Manager) init() {
|
|
m.m = &manager{}
|
|
}
|
|
|
|
// Enable enables a sensor with the specified delay rate.
|
|
// If there are multiple sensors of type t on the device, Enable uses
|
|
// the default one.
|
|
// If there is no default sensor of type t on the device, an error returned.
|
|
// Valid sensor types supported by this package are Accelerometer,
|
|
// Gyroscope, Magnetometer and Altimeter.
|
|
func (m *Manager) Enable(t Type, delay time.Duration) error {
|
|
m.once.Do(m.init)
|
|
if t < 0 || int(t) >= len(sensorNames) {
|
|
return errors.New("sensor: unknown sensor type")
|
|
}
|
|
return enable(m.m, t, delay)
|
|
}
|
|
|
|
// Disable disables to feed the manager with the specified sensor.
|
|
func (m *Manager) Disable(t Type) error {
|
|
m.once.Do(m.init)
|
|
if t < 0 || int(t) >= len(sensorNames) {
|
|
return errors.New("sensor: unknown sensor type")
|
|
}
|
|
return disable(m.m, t)
|
|
}
|
|
|
|
// Read reads a series of events from the manager.
|
|
// It may read up to len(e) number of events, but will return
|
|
// less events if timeout occurs.
|
|
func (m *Manager) Read(e []Event) (n int, err error) {
|
|
m.once.Do(m.init)
|
|
return read(m.m, e)
|
|
}
|
|
|
|
// Close stops the manager and frees the related resources.
|
|
// Once Close is called, Manager becomes invalid to use.
|
|
func (m *Manager) Close() error {
|
|
m.once.Do(m.init)
|
|
return close(m.m)
|
|
}
|