IMU Data Format & API

IMU Data

For detailed field descriptions, see IMUFrame Properties in API Reference.

IMU Coordinate System

Coordinate Frame (iPhone device frame):

• X-axis: Right (when holding phone in portrait)

• Y-axis: Up (toward top of device)

• Z-axis: Forward (out of screen)

IMU Data Explained

The IMU data follows Apple's CoreMotion framework conventions. For comprehensive details, refer to Apple's CoreMotion Documentation.

Accelerometer

Total acceleration measured by the device's accelerometer hardware.

• Unit: G (gravitational force units, where $1G = 9.81 \text{ m/s}^2$)

Gyroscope

Angular velocity around each axis.

• Unit: rad/s (radians per second)

Magnetometer

Magnetic field strength detected by the device.

• Unit: μT (microteslas)

Gravity Vector

Component of acceleration due to Earth's gravitational pull, isolated from user motion.

• Unit: G (gravitational force units)

• Magnitude: $|\vec{g}| \approx 1.0G$ when stationary

• Usage: Determining device orientation relative to Earth

• Reference: CMDeviceMotion.gravity

User Acceleration

Acceleration from user motion, with gravity removed.

• Unit: G (gravitational force units)

• Formula: $\vec{a}_{user} = \vec{a}_{total} - \vec{g}$

• Reference: CMDeviceMotion.userAcceleration

Attitude (Quaternion)

Device orientation in 3D space.

• Format: $[q_x, q_y, q_z, q_w]$ (quaternion)

• Reference: CMAttitude

API Reference

IMUDataSubscriber

Constructor:

IMUDataSubscriber(ip, port=8002, hwm=1, conflate=True, verbose=False)

Parameters:

• ip (str): iPhone's IP address

• port (int): Port number (default: 8002, fixed for IMU data)

• hwm (int): High water mark (default: 1, keeps only latest message)

• conflate (bool): Message conflation (default: True)

• verbose (bool): Print connection info (default: False)

Usage:

# Create IMU subscriber
sub = IMUDataSubscriber("192.168.1.100")
​
# Continuously receive IMU data
for data in sub:
    print(data.accelerometer)
    print(data.gyroscope)
​
# Close when done
sub.close()

Main Methods:

Method	Returns	Description
get()	IMUFrame or None	Get latest IMU data frame
get_timestamp()	float or None	Get timestamp only
get_accelerometer()	np.ndarray or None	Get accelerometer only
get_gyroscope()	np.ndarray or None	Get gyroscope only
get_magnetometer()	np.ndarray or None	Get magnetometer only
get_gravity()	np.ndarray or None	Get gravity vector only
get_user_acceleration()	np.ndarray or None	Get user acceleration only
get_attitude()	np.ndarray or None	Get attitude quaternion only
close()	None	Close connection

Note:

• The subscriber is iterable, so you can use for data in sub: to receive frames continuously.

• All get_*() methods accept an optional timeout parameter (default: 1000ms).

IMUFrame

Data object returned by get() or when iterating. For data format details and physical meanings, see IMU Data Format Reference above.

Properties:

Property	Type	Description
timestamp	float	Unix timestamp in seconds
accelerometer	np.ndarray	Accelerometer $[a_x, a_y, a_z]$ in G
gyroscope	np.ndarray	Gyroscope $[\omega_x, \omega_y, \omega_z]$ in rad/s
magnetometer	np.ndarray	Magnetometer $[m_x, m_y, m_z]$ in μT
gravity	np.ndarray	Gravity $[g_x, g_y, g_z]$ in G
user_acceleration	np.ndarray	User acceleration $[u_x, u_y, u_z]$ in G
attitude	np.ndarray	Attitude quaternion $[q_x, q_y, q_z, q_w]$

Helper Properties:

Property	Type	Description
has_accelerometer	bool	Check if accelerometer data exists
has_gyroscope	bool	Check if gyroscope data exists
has_magnetometer	bool	Check if magnetometer data exists
has_gravity	bool	Check if gravity data exists
has_user_acceleration	bool	Check if user acceleration exists
has_attitude	bool	Check if attitude data exists