hub.motion – Motion

The motion module lets you access the 6-degree of freedom MEMS sensor in the hub. You can measure the hub acceleration, angular velocity, and orientation. You can also detect certain motion events such as free fall.

The default orientation of the hub is horizontal, with the lights and buttons on top and the USB charging port facing forward. For example, this is how the hub is mounted in a vehicle robot such as TRICKY.

To understand the directions of motion, it can be helpful to imagine that you are sitting in the hub, as the driver of the vehicle:

  • Yaw: Positive values up to 179 degrees mean that the car has steered to the right. Negative values down to -180 mean you have steered to the left.

  • Pitch: Positive means you are driving up a hill, so that the front of the car points upward, up to 90 degrees. Negative means you are driving downhill, down to -90 degrees.

  • Roll: Positive values up to 179 degrees means your car is leaning to the right, as if driving only on its right wheels. Negative values down to -180 mean your car is leaning to the left, as if driving on its left wheels.

Using the same analogy as a driver in your car, the following applies about axes and acceleration values:

  • The positive X axis points to the right of your car: A positive acceleration along the X axis means you are accelerating to the right. Negative means to the left.

  • The positive Y axis points to the front of your car: A positive acceleration along the Y axis means you are accelerating forward, as if pressing the gas. Negative means backward, as if hitting the brakes or reversing.

  • The positive Z axis points up. A positive acceleration along the Z axis means that you are accelerating upward. Negative means downward.

Likewise, the following applies for angular velocity:

  • A positive angular rate velocity the X axis means you are tilting upward.

  • A positive angular rate velocity the Y axis mean you are rolling to the right.

  • A positive angular rate velocity the Z axis mean you are steering to the left.

You can specify how the hub is aligned in your model using the hub.motion.align_to_model() function. This way, the values will be adjusted such that the analogies above still apply even if your hub isn’t mounted horizontally in your model.

hub.motion.accelerometer(filtered=False) → Tuple[int, int, int]

Gets the acceleration of the hub along the x, y, and z axis.

Parameters

filtered – Selecting True gives a more stable value, but it is delayed by 10-100 milliseconds. Selecting False gives the unfiltered value.

Returns

Acceleration of the hub with units of cm/s^2. On a perfectly level surface, this gives (0, 0, 981).

hub.motion.gyroscope(filtered=False) → Tuple[int, int, int]

Gets the angular velocity of the hub along the x, y, and z axis.

Parameters

filtered – Selecting True gives a more stable value, but it is delayed by 10-100 milliseconds. Selecting False gives the unfiltered value.

Returns

Angular velocity with units of degrees per second.

hub.motion.align_to_model(top: int, front: int) → None
hub.motion.align_to_model(nsamples: int, callback: Callable[[int], None]) → None
hub.motion.align_to_model(top: int, front: int, nsamples: int, callback: Callable[[int], None]) → None

Sets the default hub orientation and/or calibrates the gyroscope.

The hub must not move while calibrating. It takes about one second by default.

Changing the model alignment affects most other methods in this module. They will now be relative to the hub alignment that you specify.

Keyword Arguments

  • top – Which hub side is at the top of your model. See the hub constants for all possible values.

  • front – Which hub side is on the front of your model.

  • nsamples – Number of samples for calibration between 0 and 10000. It is 100 by default.

  • callback – Function that will be called when calibration is complete. It must accept one argument. Choose None to disable the callback. This is the default.

hub.motion.yaw_pitch_roll() → Tuple[int, int, int]
hub.motion.yaw_pitch_roll(yaw_preset: int) → None
hub.motion.yaw_pitch_roll(yaw_correction: float) → None

Gets the yaw, pitch, and roll angles of the hub, or resets the yaw.

The yaw_correction is an optional keyword argument to improve the accuracy of the yaw value after one full turn. To use it:

  • Reset the yaw angle to zero using hub.motion.yaw_pitch_roll(0).

  • Rotate the hub smoothly exactly one rotation clockwise.

  • Call error = hub.motion.yaw_pitch_roll()[0] to get the yaw error.

  • The error should be 0. If it is not, you can set the correction using hub.motion.yaw_pitch_roll(yaw_correction=error).

  • For even more accuracy, you can turn clockwise 5 times, and use error / 5 as the correction factor.

Keyword Arguments

  • yaw_preset – Sets the current yaw to the given value (-180 to 179).

  • yaw_correction – Adjusts the gain of the yaw axis values. See the yaw adjustment section below.

Returns

If no arguments are given, this returns a tuple of yaw, pitch, and roll values in degrees.

hub.motion.orientation() → int
hub.motion.orientation(callback: Callable[[int], None]) → int

Gets which hub side of the hub is mostly pointing up.

Keyword Arguments

callback – Function that will be called when the orientation changes. It must accept one argument, which will tell you which hub side is up. Choose None to disable the callback. This is the default.

Returns

Number representing which side is up. See hub constants for all possible values.

hub.motion.gesture() → int
hub.motion.gesture(callback: Callable[[int], None]) → int

Gets the most recent gesture that the hub has made since this function was last called.

Keyword Arguments

callback – Function that will be called when a gesture is detected. It must accept one argument, which will tell you which gesture was detected. Choose None to disable the callback. This is the default.

Returns

Number representing the gesture. See motion constants for all possible values. If no gesture was detected since this function was last called, it returns None.

Constants

These values are used by the hub.motion.gesture() function.

hub.motion.TAPPED = 0

The hub was tapped.

hub.motion.DOUBLETAPPED = 1

The hub was quickly tapped twice.

hub.motion.SHAKE = 2

The hub was shaken.

hub.motion.FREEFALL = 3

The hub fell.