Accelerometer

Accelerometer driver interface. More...

Modules
	QEMU accelerometer
	Accelerometer fed with samples from the QEMU host.

Data Structures
struct	AccelDriverSample
	Accelerometer sample. More...
struct	AccelRawBatch
	Batch of raw samples in a driver-owned buffer. More...
struct	AccelRawBatch.axis
	Per-axis source, indexed by IMUCoordinateAxis; encodes axis remapping and direction. More...

Typedefs
typedef void(*	AccelOffloadCallback) (void)
	Driver work to be run from thread context.

Functions
void	accel_init (void)
	Initialize the accelerometer.
void	accel_set_rotated (bool rotated)
	Set whether the axes are rotated by 180 degrees.
uint32_t	accel_set_sampling_interval (uint32_t interval_us)
	Set the sampling interval.
uint32_t	accel_get_sampling_interval (void)
	Get the sampling interval.
void	accel_set_num_samples (uint32_t num_samples)
	Set the maximum number of samples the driver may batch.
uint32_t	accel_get_max_num_samples (void)
	Get the maximum number of samples the driver can batch.
int	accel_peek (AccelDriverSample *data)
	Read the most recent sample.
void	accel_enable_shake_detection (bool on)
	Enable or disable shake detection.
bool	accel_get_shake_detection_enabled (void)
	Check whether shake detection is enabled.
void	accel_enable_double_tap_detection (bool on)
	Enable or disable double tap detection.
bool	accel_get_double_tap_detection_enabled (void)
	Check whether double tap detection is enabled.
void	accel_cb_new_sample (AccelDriverSample const *data)
	Deliver a new sample to the service.
void	accel_cb_new_samples (AccelRawBatch const *batch)
	Deliver a batch of new samples to the service.
void	accel_cb_shake_detected (IMUCoordinateAxis axis, int32_t direction)
	Report a detected shake to the service.
void	accel_cb_double_tap_detected (IMUCoordinateAxis axis, int32_t direction)
	Report a detected double tap to the service.
void	accel_offload_work_from_isr (AccelOffloadCallback cb)
	Run driver work in thread context, from an ISR.
void	accel_offload_work (AccelOffloadCallback cb)
	Run driver work in thread context.
void	accel_set_shake_sensitivity_high (bool sensitivity_high)
	Select high or normal shake sensitivity.
void	accel_set_shake_sensitivity_percent (uint8_t percent)
	Set the normal shake sensitivity.

Detailed Description

Accelerometer driver interface.

The driver is a thin layer over the hardware: it keeps no sample buffers and knows nothing about clients, tasks or subsampling. That is left to the accelerometer service, so that code shared by all drivers lives in one place. The interface is made of functions the driver implements and callbacks (accel_cb_*, accel_offload_*) the service implements.

Hardware state such as FIFO modes is hidden: the service only states its requirements (sampling interval, batch size) and the driver picks the hardware configuration.

uint32_t interval_us = accel_set_sampling_interval(40000);
accel_set_num_samples(MIN(25, accel_get_max_num_samples()));
 
void accel_cb_new_sample(AccelDriverSample const *data) {
  process(data->timestamp_us, data->x, data->y, data->z);
}

---

Data Structure Documentation

AccelDriverSample

struct AccelDriverSample

Accelerometer sample.

Data Fields
uint64_t	timestamp_us	Sample time in microseconds since the epoch, with no guaranteed precision.
int16_t	x	Acceleration along the x axis, in milli-g.
int16_t	y	Acceleration along the y axis, in milli-g.
int16_t	z	Acceleration along the z axis, in milli-g.

AccelRawBatch

struct AccelRawBatch

Batch of raw samples in a driver-owned buffer.

Handed to accel_cb_new_samples() so the service can scale and copy the samples in one pass instead of taking a callback per sample.

Data Fields
struct AccelRawBatch.axis	axis[3]	Per-axis source, indexed by IMUCoordinateAxis; encodes axis remapping and direction.
const uint8_t *	data	First raw sample, past any per-sample header.
uint64_t	first_timestamp_us	Timestamp of the first sample, in microseconds since the epoch.
uint16_t	num_samples	Number of samples in the buffer.
uint32_t	sampling_interval_us	Interval between samples, in microseconds.
int32_t	scale_den	Raw-count to milli-g denominator.
int32_t	scale_num	Raw-count to milli-g numerator: mg = raw * scale_num / scale_den.
uint8_t	stride	Bytes between consecutive samples, which lets the service skip e.g. FIFO tags.

AccelRawBatch.axis

struct AccelRawBatch.axis

Per-axis source, indexed by IMUCoordinateAxis; encodes axis remapping and direction.

Data Fields
uint8_t	offset	Byte offset of the little-endian int16 value within a sample.
int8_t	sign	Sign applied to the value, +1 or -1.

Typedef Documentation

AccelOffloadCallback

typedef void(* AccelOffloadCallback) (void)

Driver work to be run from thread context.

Function Documentation

accel_cb_double_tap_detected()

void accel_cb_double_tap_detected ( IMUCoordinateAxis  axis, int32_t  direction  )

extern

Report a detected double tap to the service.

Implemented by the service.

Parameters

axis	Axis the double tap was detected on.
direction	Positive or negative to tell the direction along axis.

accel_cb_new_sample()

void accel_cb_new_sample ( AccelDriverSample const *  data )

extern

Deliver a new sample to the service.

Implemented by the service. Called from thread context, with samples in increasing time order.

Note

May be called from within any accelerometer driver function. Avoid calling driver functions from it to prevent reentrancy issues.

Parameters

data	Sample, valid only for the duration of the call.

accel_cb_new_samples()

void accel_cb_new_samples ( AccelRawBatch const *  batch )

extern

Deliver a batch of new samples to the service.

Implemented by the service. Equivalent to calling accel_cb_new_sample() once per sample, oldest first, but lets the service scale and copy the whole batch in one pass. The same context and reentrancy rules apply.

Parameters

batch

Batch description; the pointers in it are valid only for the duration of the call.

accel_cb_shake_detected()

void accel_cb_shake_detected ( IMUCoordinateAxis  axis, int32_t  direction  )

extern

Report a detected shake to the service.

Implemented by the service. Filtering out shakes caused by the vibration motor is up to the implementer.

Parameters

axis	Axis the shake was detected on.
direction	Positive or negative to tell the direction along axis.

accel_enable_double_tap_detection()

void accel_enable_double_tap_detection

(

bool

on

)

Enable or disable double tap detection.

While enabled, the driver calls accel_cb_double_tap_detected() for every detected double tap; while disabled it does not.

Parameters

on	True to enable, false to disable.

accel_enable_shake_detection()

void accel_enable_shake_detection

(

bool

on

)

Enable or disable shake detection.

While enabled, the driver calls accel_cb_shake_detected() for every detected shake; while disabled it does not.

Parameters

on	True to enable, false to disable.

accel_get_double_tap_detection_enabled()

bool accel_get_double_tap_detection_enabled

(

void

)

Check whether double tap detection is enabled.

Returns

True if double tap detection is enabled.

accel_get_max_num_samples()

uint32_t accel_get_max_num_samples

(

void

)

Get the maximum number of samples the driver can batch.

Returns

Depth of the hardware FIFO, the upper bound for accel_set_num_samples().

accel_get_sampling_interval()

uint32_t accel_get_sampling_interval

(

void

)

Get the sampling interval.

Returns

Current sampling interval in microseconds.

accel_get_shake_detection_enabled()

bool accel_get_shake_detection_enabled

(

void

)

Check whether shake detection is enabled.

Returns

True if shake detection is enabled.

accel_init()

void accel_init

(

void

)

Initialize the accelerometer.

accel_offload_work()

void accel_offload_work ( AccelOffloadCallback  cb )

extern

Run driver work in thread context.

Implemented by the service: cb runs on the timer task with the accelerometer service lock held.

Parameters

cb	Work to run.

accel_offload_work_from_isr()

void accel_offload_work_from_isr ( AccelOffloadCallback  cb )

extern

Run driver work in thread context, from an ISR.

Implemented by the service: cb runs on the timer task with the accelerometer service lock held. Must be called from an ISR.

Parameters

cb	Work to run.

accel_peek()

int accel_peek

(

AccelDriverSample *

data

)

Read the most recent sample.

The driver may call accel_cb_new_sample() from within this function if batching is enabled (accel_set_num_samples() was last called with a non-zero value).

Parameters

[out]

data

Most recent sample.

Return values

0	Success.
nonzero	Failure.

accel_set_num_samples()

void accel_set_num_samples

(

uint32_t

num_samples

)

Set the maximum number of samples the driver may batch.

• 0: the driver must not call accel_cb_new_sample().
• 1: the driver calls accel_cb_new_sample() for every sample as soon as it is acquired.
• n > 1: the driver may queue up to n samples and then deliver them in rapid succession, the last one being the most recently acquired. This is only an upper bound, which the driver can use for power saving.

When n is lowered below the number of samples already queued, the driver flushes them before the new value takes effect, possibly from within this call.

Parameters

num_samples

Maximum number of samples to batch, at most accel_get_max_num_samples().

accel_set_rotated()

void accel_set_rotated

(

bool

rotated

)

Set whether the axes are rotated by 180 degrees.

Parameters

rotated

True if the sensor is mounted rotated by 180 degrees.

accel_set_sampling_interval()

uint32_t accel_set_sampling_interval

(

uint32_t

interval_us

)

Set the sampling interval.

The driver selects the longest supported interval that is equal to or shorter than the requested one, saturating at the shortest interval the hardware supports. The new interval takes effect immediately; the driver may flush queued samples first so that timestamps stay accurate.

Parameters

interval_us

Requested sampling interval in microseconds.

Returns

Sampling interval actually used, in microseconds.

accel_set_shake_sensitivity_high()

void accel_set_shake_sensitivity_high

(

bool

sensitivity_high

)

Select high or normal shake sensitivity.

In high sensitivity mode the detection threshold is at its minimum, so that any minor motion triggers a shake event; otherwise the threshold set by accel_set_shake_sensitivity_percent() applies. Does not enable shake detection.

Parameters

sensitivity_high

True for high sensitivity, false for normal.

accel_set_shake_sensitivity_percent()

void accel_set_shake_sensitivity_percent

(

uint8_t

percent

)

Set the normal shake sensitivity.

Does not enable shake detection.

Parameters

percent

Sensitivity from 0 (highest threshold, least sensitive) to 100 (lowest threshold, most sensitive).