mobile/sensor: initialize the sensor package

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>

sensor/sensor.go

@@ -0,0 +1,113 @@
+// 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)
+}

sensor/sensor_android.go

@@ -0,0 +1,26 @@
+// 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
+
+import "time"
+
+type manager struct {
+}
+
+func enable(m *manager, t Type, delay time.Duration) error {
+	panic("not implemented")
+}
+
+func disable(m *manager, t Type) error {
+	panic("not implemented")
+}
+
+func read(m *manager, e []Event) (n int, err error) {
+	panic("not implemented")
+}
+
+func close(m *manager) error {
+	panic("not implemented")
+}

sensor/sensor_notandroid.go

@@ -0,0 +1,28 @@
+// 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.
+
+// +build !android
+
+package sensor
+
+import "time"
+
+type manager struct {
+}
+
+func enable(m *manager, t Type, delay time.Duration) error {
+	panic("not implemented")
+}
+
+func disable(m *manager, t Type) error {
+	panic("not implemented")
+}
+
+func read(m *manager, e []Event) (n int, err error) {
+	panic("not implemented")
+}
+
+func close(m *manager) error {
+	panic("not implemented")
+}