APPLICATION NOTE 7422

Maxim Gesture Sensor EVKit Serial API


Abstract:

Describes the serial interface of the Maxim Gesture Sensor EV kit, which enables rapid prototype development and gesture integration into an existing application using only the EV kit hardware.


Introduction

This document describes how to use the serial interface of the MAX25x05EVKIT. This interface enables another application or Systems-on-a-Chip (SoC) to obtain gesture recognition and tracking results from the EV kit, and allows the gesture engine to be configured for specific application requirements or contexts. This capability enables the user to quickly develop custom demos or add gesture control to existing applications, using only the EV kit hardware.

The serial interface can be implemented over the Universal Serial Bus (USB) virtual serial port or over a Universal Asynchronous Receiver-Transmitter (UART). The EV kit is shipped configured to use the USB serial port to work with the EV kit PC Graphical user Interface (GUI). If a UART serial interface is desired, custom firmware in binary format is available.

This document describes the serial interface commands and typical usage.

Serial Port Setup

As a USB device, the EV kit shows up as a COM port called Maxim Serial Port. The serial settings are as follows:

  • Baud Rate: 115200
  • Data: 8-bit
  • Parity: None
  • Stop: 1-bit
  • Flow Control: None

Power-Up Condition

On power-up of the EV kit, the MCU firmware programs the MAX25x05 registers to settings optimized for the gesture software. Therefore, manual register configuration is not necessary.

After the register configuration, the firmware begins monitoring of the MAX25x05's INTB pin for the end-of-conversion interrupt, which occurs at the end of every sampling cycle, indicating a frame of data is available to be read from the sensor. On receiving this interrupt, the firmware retrieves the 60 pixels of sensor data and passes this image to the gesture recognition library.

By default, the gesture library has all dynamic gestures enabled (context mask = 0x7F), and analog dial mode is disabled.

To summarize, after power-up, the EV kit MCU performs gesture recognition processes and results are available to an external application.

Commands

This section describes the commands available to the user.

ping

Description

Pings the processor to determine to verify communication. Processor responds with an 'ACK' string.

Parameters

None

poll

Description

This command is used to retrieve gesture results from the EV kit MCU.

Note that this command can be sent asynchronously with respect to the sample rate of the sensor, at a rate determined by the host application. But to avoid perceived lag in the gesture response, it should be sent as close to the sensor frame rate as possible, or at minimum 10 times per second. (Note that there is no benefit to sending this command faster than the sample rate of the sensor).

The poll command returns a data packet as a new-line ('\n') terminated string, with comma-delimited fields, in the following format: '[field 1],[field 2],…,[field 10]\n'

These fields are described in Table 1. See the Gesture Results Descriptions section of this document for additional explanations of each field.

Parameters

None

Table 1. Gesture Results Fields

Field Name Data Type
1 gesture result Integer
2 gesture state Integer
3 N samples Integer
4 max pixel Integer
5 x-position Float
6 y-position Float
7 rotation (radians) Float
8 active x-region Integer
9 active y-region Integer
10 time to linger-click event (milliseconds) Integer

gesture

gesture [mask]

Description

Sets the gesture engine to dynamic gesture recognition mode (swipes, rotations, air click) and masks (enable) specific gestures. Note that at power up, the gesture engine is already in gesture recognition.

Parameters

[mask] (optional) enables or disables specific gestures based on bit mask of this parameter. If this parameter is omitted, the mask is set to 0x7F, which enables all dynamic gestures. The mask bits are:

CLICK_ENABLE = 0x01 ROTATE_CW_ENABLE = 0x02 ROTATE_CCW_ENABLE = 0x04 SWIPE_LEFT_ENABLE = 0x08 SWIPE_RIGHT_ENABLE = 0x10 SWIPE_UP_ENABLE = 0x20 SWIPE_DOWN_ENABLE = 0x40

Note that bits can be OR'd. For example:

  • Enable rotations in both directions: mask = 0x06
  • Enable horizontal swipes: mask = 0x18
  • Enable all swipes = 0x78
  • Enable all gestures = 0x7F

Example

To enable clockwise and counter clockwise rotations ONLY, send the command: gesture 0x06

track

track [cols rows]

Description

Sets the gesture engine to object tracking and region selection mode.

In this mode, the gesture results packet has valid data in the following fields:

  • x,y position of object
  • Active region selection
  • Time to linger click event
  • Gestures LINGER_TO_CLICK only

Parameters

[cols rows] (optional) sets the number of rows and columns for region selection.

Example

To enable tracking mode with a 3x2 region selection grid, send the command:

track 3 2.

force cal

Description

Forces a pixel bias calibration to be performed. Only applies when in tracking/region selection mode.

Note the field-of-view should be clear of any objects when performing a calibration.

Parameters

None

analog

analog

Description

Enables and disables analog rotation mode. This mode causes the rotation gesture response to emulate an analog dial. The gear ratio parameter is used to set the ratio of actual rotation to the radians of rotation reported by the algorithm. Note that in this mode, the current radians of rotation is remembered from the previous rotation gesture. This mode can be used to emulate an analog dial in the final HMI application, such as position control, volume, etc., and allows for precise control.

Note that this command affects only the rotation field of the gesture results (see the poll command). Gesture events (ROTATE_CW and ROTATE_CCW) are not affected.

When the analog mode is enabled, the rotation field of the data frame ranges from 0:2π radians, i.e., it is always positive, because it is assumed this value is mapped to a dial, where all positions are positive. The user can rotate in either direction. But crossing zero in the counter clockwise direction causes the rotation field to transition from 0 to 2 π, rather than go negative.

In contrast, when the analog mode is turned off, the rotation field ranges from -2π:2π. Making a complete rotation of 2 π radians in either direction causes a rotate event.

Parameters

: This is the actual-finger-rotations-to-virtual-dial-rotation ratio. In other words, this is how many rotations the user needs to make with their finger to achieve one rotation of the virtual analog dial. Setting rotation factor to zero turns the analog mode off.

Examples

To turn on analog mode, with a gear ratio of 10 (10 finger rotations = 1 dial rotation)

analog 10

To turn off analog mode. (Digital dial mode, 1 finger rotation = 1 dial rotation)

analog 0

reg

reg

Description

Reads or writes to the MAX25x05 device registers.

Parameters

specifies if this is a register read or a register write operation.
is the register address to read/write to. Can be decimal or hex.
is the value to be written in the case of a write. In the case of a read, this is the number of bytes to read. Can be decimal or hex.

Examples

reg read 0x00 6

Reads six registers starting at register 0. Example response: 00 04 02 24 8C 08

reg read 4 1

Read register 4. Example response: 8C

reg write 0x06 0x0F

Write value 0x0F to register 6

ver

Description

Returns a string containing the firmware version information.

Parameters

None

Gesture Results Descriptions

This section describes the gesture results data obtained by the poll command.

Gesture Result

The gesture result values can be the following:

0 NONE
1 CLICK
2 ROTATE_CW
3 ROTATE_CCW
4 SWIPE_LEFT
5 SWIPE_RIGHT
6 SWIPE_UP
7 SWIPE_DOWN
8 RESERVED
9 RESERVED
10 LINGER_ON_REGION
11 RESERVED
12 ERROR

Gesture State

The gesture state can have the following values:

0 No object detected in FOV
1 Object in FOV, gesture-in-progress
2 Rotation-in-progress

N Samples

N samples is the current sample number of the current gesture. This is updated on every frame while the gesture state is non-zero.

Max Pixel

This is the maximum raw pixel value for the current frame.

X-position and Y-position

The is the x- and y-coordinate position of the object detected in the field-of-view. Units are pixels, with (0,0) in the upper left of the heatmap view. Note that these fields are only used to determine object position when in tracking mode.

Rotation

Reports real-time rotation in radians. Range is -2π:2π in digital rotation mode. The range is 0:2π in analog rotation mode.

Active X-Region and Active Y-Region

These fields are only available in the tracking mode, which enables region selection. These fields give the current x,y region of the object in the FOV. Position (0,0) is the upper left region.