From 4d47512510671417cc71fe6e5dfcf28c602a6748 Mon Sep 17 00:00:00 2001 From: Burcu Dogan Date: Fri, 27 Mar 2015 14:53:09 -0700 Subject: [PATCH] mobile/sensor: initialize the sensor package MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- sensor/sensor.go | 113 ++++++++++++++++++++++++++++++++++++ sensor/sensor_android.go | 26 +++++++++ sensor/sensor_notandroid.go | 28 +++++++++ 3 files changed, 167 insertions(+) create mode 100644 sensor/sensor.go create mode 100644 sensor/sensor_android.go create mode 100644 sensor/sensor_notandroid.go diff --git a/sensor/sensor.go b/sensor/sensor.go new file mode 100644 index 0000000..04098bd --- /dev/null +++ b/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) +} diff --git a/sensor/sensor_android.go b/sensor/sensor_android.go new file mode 100644 index 0000000..0735fcd --- /dev/null +++ b/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") +} diff --git a/sensor/sensor_notandroid.go b/sensor/sensor_notandroid.go new file mode 100644 index 0000000..52486f1 --- /dev/null +++ b/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") +}