Tutorial: Using the mobile/remote accelerometer

24 November 2015

Tutorial: Using the mobile/remote accelerometer

One of the cool things about the new Apple TV Remote is that it has a built-in accelerometer, and similar to mobile devices, this allows you to guage the device’s position/orientation in space. Essentially, on either a mobile device or the remote control, the accelerometer makes three discrete measurements based on the orientation and center point of the device.

Accelerometer events

The accelerometer event returns several useful values, including:

• event.name — This property will always be "accelerometer".
• event.isShake — This property will be true if a rapid movement of the device is detected.
• event.xGravity / event.yGravity / event.zGravity — These events are probably the most useful. They are normalized, so you get a value between -1.0 and 1.0. These values are also smoothed out to adjust for micro-movements and prevent jerky actions.
• event.xInstant, event.yInstant, event.zInstant — These values report the change since the last event, for instance the current event.xGravity minus the last event.xGravity.
• event.xRaw, event.yRaw, event.zRaw — These values are the actual values from the device (there is no filtering or smoothing applied).
• event.deltaTime — Accelerometer events come at somewhat predictable intervals based on the value set by the system.setAccelerometerInterval() function, but they are not guaranteed to arrive on time. This is where the event.deltaTime comes in. It allows you to get the time between events so you can provide additional smoothing as needed.

All of the “gravity,” “instant,” and “raw” values assume that the device is being held in “portrait” orientation. This is very common for people holding the Apple TV Remote (the remote being held like a traditional TV/audio remote control). However, if you’re designing a landscape-oriented app like a racing game, you might want the remote to be held in “landscape” orientation (like a traditional console game controller) in order to emulate a steering wheel. In this case, you should adjust your values by 90 degrees.

Implementation

Let’s look at a simple implementation of the accelerometer. This app will create a blue circle and allow you to move it around the screen by moving/orienting the device.

For this simple example, we create a dot (circle), color it blue, and set up some text display objects to show the values received from the accelerometer event.

Accelerometer events require a listener function, served by our onTilt() function. Inside the function, we update the on-screen values based on the current accelerometer data.

Next, we add the values of event.xGravity and event.yGravity to the dot’s x and y position. This will move the dot around the screen. Following this, we write four conditional statements to constrain the dot to the screen bounds.

In the final block of the function, we test to see if the device was shaken and swap the color between red and blue each time a shake is detected.

Finally, on the last line of the example, we enable the "accelerometer" event handler.

Conclusion

Using the accelerometer is an important part of getting your apps to run properly on tvOS — after all, not every control scheme can be accomplished with simple up/down/left/right key events or axis inputs. For example, consider a classic game like “Fruit Ninja.” On a mobile device, you couldn’t use the accelerometer to slash the fruit, but now with an accelerometer-enabled remote, you could detect slashing motions by tracking the accelerometer’s values.