Maxim Gesture Sensor EVKit Serial API
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.
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
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.
This section describes the commands available to the user.
Pings the processor to determine to verify communication. Processor responds with an 'ACK' string.
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.
Table 1. Gesture Results Fields
|10||time to linger-click event (milliseconds)||Integer|
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.
[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
To enable clockwise and counter clockwise rotations ONLY, send the command: gesture 0x06
track [cols rows]
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
[cols rows] (optional) sets the number of rows and columns for region selection.
To enable tracking mode with a 3x2 region selection grid, send the command:
track 3 2.
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.
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.
To turn on analog mode, with a gear ratio of 10 (10 finger rotations = 1 dial rotation)
To turn off analog mode. (Digital dial mode, 1 finger rotation = 1 dial rotation)
Reads or writes to the MAX25x05 device registers.
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
Returns a string containing the firmware version information.
Gesture Results Descriptions
This section describes the gesture results data obtained by the poll command.
The gesture result values can be the following:
The gesture state can have the following values:
0 No object detected in FOV
1 Object in FOV, gesture-in-progress
N samples is the current sample number of the current gesture. This is updated on every frame while the gesture state is non-zero.
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.
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.