Relative or Absolute mode API

Data Structures

class circuitpython_cirque_pinnacle.RelativeReport(buf: bytes | bytearray = b'\x00\x00\x00\x00')[source]

A class to represent data reported by PinnacleTouch.read() when PinnacleTouch.data_mode is set to PINNACLE_RELATIVE.

Parameters:
buf: bytes | bytearray = b'\x00\x00\x00\x00'

A buffer object used to unpack initial values for the buttons, x, y, and scroll attributes. If not specified, then all attributes are set to 0.

buttons : int

The button data is a byte in which each bit represents a button. The bit to button order is as follows:

  1. [LSBit] Button 1 (thought of as Left button on a mouse). If the taps parameter is True when calling relative_mode_config(), a single tap will be reflected here.

  2. Button 2 (thought of as Right button on a mouse). If taps and secondary_tap parameters are True when calling relative_mode_config(), a single tap in the perspective top-left-most corner will be reflected here; secondary taps are constantly disabled if hard_configured returns True. Note that the top-left-most corner can be perspectively moved if rotate90 parameter is True when calling relative_mode_config().

  3. Button 3 (thought of as Middle or scroll wheel button on a mouse)

x : int

The change in X-axis ranging [-127, 127].

y : int

The change in Y-axis ranging [-127, 127].

scroll : int

The change in scroll counter ranging [-127, 127]. This data is only reported if the intellimouse parameter is True to relative_mode_config().

property buffer : bytes

A read-only property to return a bytes object that can be used as a Mouse HID report buffer.

class circuitpython_cirque_pinnacle.AbsoluteReport(buttons: int = 0, x: int = 0, y: int = 0, z: int = 0)[source]

A class to represent data reported by PinnacleTouch.read() when PinnacleTouch.data_mode is set to PINNACLE_ABSOLUTE.

Each parameter is used as the initial value for the corresponding attribute. If not specified, then the attribute is set to 0.

buttons : int

The button data is a byte in which each bit represents a button. The bit to button order is as follows:

  1. [LSBit] Button 1.

  2. Button 2.

  3. Button 3.

x : int

The position on the X axis ranging [0, 2047]. The datasheet recommends the X-axis value should be clamped to the range [128, 1920] for reliability.

y : int

The position on the Y axis ranging [0, 1535]. The datasheet recommends the Y-axis value should be clamped to the range [64, 1472] for reliability.

z : int

The magnitude of the Z axis (ranging [0, 255]) can be used as the proximity of the finger to the trackpad. 0 means no proximity. The maximum value reported may be influenced by set_adc_gain().

PinnacleTouch API

PinnacleTouch.feed_enable

This bool attribute controls if the touch/button event data is reported (True) or not (False).

This function only applies to PINNACLE_RELATIVE or PINNACLE_ABSOLUTE mode. Otherwise if data_mode is set to PINNACLE_ANYMEAS, then this attribute will have no effect.

PinnacleTouch.hard_configured

This read-only bool attribute can be used to inform applications about factory customized hardware configuration. See note about product labeling in Model Labeling Scheme.

Returns:

True if a 470K ohm resistor is populated at the junction labeled “R4”

PinnacleTouch.relative_mode_config(taps: bool = True, rotate90: bool = False, secondary_tap: bool = True, intellimouse: bool = False, glide_extend: bool = False)[source]

Configure settings specific to Relative mode (AKA Mouse mode) data reporting.

This function only applies to PINNACLE_RELATIVE mode, otherwise if data_mode is set to PINNACLE_ANYMEAS or PINNACLE_ABSOLUTE, then this function does nothing.

Parameters:
taps: bool = True

Specifies if all taps should be reported (True) or not (False). Default is True. This affects the secondary_tap parameter as well.

rotate90: bool = False

Specifies if the axis data is altered for 90 degree rotation before reporting it (essentially swaps the axis data). Default is False.

secondary_tap: bool = True

Specifies if tapping in the top-left corner (depending on orientation) triggers the secondary button data. Defaults to True. This feature is always disabled if hard_configured is True.

intellimouse: bool = False

Specifies if the data reported includes a byte about scroll data. Default is False. Because this flag is specific to scroll data, this feature is always disabled if hard_configured is True.

glide_extend: bool = False

A patented feature that allows the user to glide their finger off the edge of the sensor and continue gesture with the touch event. Default is False. This feature is always disabled if hard_configured is True.

PinnacleTouch.absolute_mode_config(z_idle_count: int = 30, invert_x: bool = False, invert_y: bool = False)[source]

Configure settings specific to Absolute mode (reports axis positions).

This function only applies to PINNACLE_ABSOLUTE mode, otherwise if data_mode is set to PINNACLE_ANYMEAS or PINNACLE_RELATIVE, then this function does nothing.

Parameters:
z_idle_count: int = 30

Specifies the number of empty packets (x-axis, y-axis, and z-axis are 0) reported (every 10 milliseconds) when there is no touch detected. Defaults to 30. This number is clamped to range [0, 255].

invert_x: bool = False

Specifies if the x-axis data is to be inverted before reporting it. Default is False.

invert_y: bool = False

Specifies if the y-axis data is to be inverted before reporting it. Default is False.

PinnacleTouch.available() → bool[source]

Determine if there is fresh data to report.

If the dr_pin parameter is specified upon instantiation, then the specified input pin is used to detect if the data is new. Otherwise the SW_DR flag in the STATUS register is used to determine if the data is new.

Returns:

True if there is fresh data to report, otherwise False.

PinnacleTouch.read(report: AbsoluteReport | RelativeReport, read_buttons: bool = True) → None[source]

This function will return touch (& button) event data from the Pinnacle ASIC.

This function only applies to PINNACLE_RELATIVE or PINNACLE_ABSOLUTE mode. Otherwise if data_mode is set to PINNACLE_ANYMEAS, then this function does nothing.

Parameters:
report: AbsoluteReport | RelativeReport

A AbsoluteReport or RelativeReport object (depending on the currently set data_mode) that is used to store the described touch and/or button event data.

read_buttons: bool = True

A flag that can be used to skip reading the button data from the Pinnacle. Default (True) will read the button data and store it in the report object’s buttons attribute. This is really only useful to speed up read operations when not using the Pinnacle’s button input pins.

Warning

If PINNACLE_RELATIVE mode’s tap detection is enabled, then setting this parameter to False can be deceptively inaccurate when reporting tap gestures.

PinnacleTouch.clear_status_flags(post_delay=True)[source]

This function clears the “Data Ready” flag which is reflected with the dr_pin.

Parameters:
post_delay=True

If True, then this function waits the recommended 50 milliseconds before exiting. Only set this to False if the following instructions do not require access to the Pinnacle ASIC.

PinnacleTouch.allow_sleep

This attribute specifies if the Pinnacle ASIC is allowed to sleep after about 5 seconds of idle (no input event).

Set this attribute to True if you want the Pinnacle ASIC to enter sleep (low power) mode after about 5 seconds of inactivity (does not apply to PINNACLE_ANYMEAS mode). While the touch controller is in sleep mode, if a touch event or button press is detected, the Pinnacle ASIC will take about 300 milliseconds to wake up (does not include handling the touch event or button press data).

PinnacleTouch.shutdown

This attribute controls power of the Pinnacle ASIC. True means powered down (AKA standby mode), and False means not powered down (Active, Idle, or Sleep mode).

Note

The ASIC will take about 300 milliseconds to complete the transition from powered down mode to active mode. No touch events or button presses will be monitored while powered down.

PinnacleTouch.sample_rate

This attribute controls how many samples (of data) per second are reported.

Valid values are 100, 80, 60, 40, 20, 10. Any other input values automatically set the sample rate to 100 sps (samples per second). Optionally, 200 and 300 sps can be specified, but using these values automatically disables palm (referred to as “NERD” in the specification sheet) and noise compensations. These higher values are meant for using a stylus with a 2mm diameter tip, while the values less than 200 are meant for a finger or stylus with a 5.25mm diameter tip.

This attribute only applies to PINNACLE_RELATIVE or PINNACLE_ABSOLUTE mode. Otherwise if data_mode is set to PINNACLE_ANYMEAS, then this attribute will have no effect.

PinnacleTouch.detect_finger_stylus(enable_finger: bool = True, enable_stylus: bool = True, sample_rate: int = 100)[source]

This function will configure the Pinnacle ASIC to detect either finger, stylus, or both.

Parameters:
enable_finger: bool = True

True enables the Pinnacle ASIC’s measurements to detect if the touch event was caused by a finger or 5.25 mm stylus. False disables this feature. Default is True.

enable_stylus: bool = True

True enables the Pinnacle ASIC’s measurements to detect if the touch event was caused by a 2 mm stylus. False disables this feature. Default is True.

sample_rate: int = 100

See the sample_rate attribute as this parameter manipulates that attribute.

Tip

Consider adjusting the ADC matrix’s gain to enhance performance/results using set_adc_gain()

PinnacleTouch.calibrate(run: bool = True, tap: bool = True, track_error: bool = True, nerd: bool = True, background: bool = True) → bool[source]

Set calibration parameters when the Pinnacle ASIC calibrates itself.

This function only applies to PINNACLE_RELATIVE or PINNACLE_ABSOLUTE mode. Otherwise if data_mode is set to PINNACLE_ANYMEAS, then this function will have no effect.

Parameters:
run: bool = True

If True, this function forces a calibration of the sensor. If False, this function just writes the following parameters to the Pinnacle ASIC’s “CalConfig1” register.

tap: bool = True

Enable dynamic tap compensation? Default is True.

track_error: bool = True

Enable dynamic track error compensation? Default is True.

nerd: bool = True

Enable dynamic NERD compensation? Default is True. This parameter has something to do with palm detection/compensation.

background: bool = True

Enable dynamic background compensation? Default is True.

Returns:
False
True
PinnacleTouch.calibration_matrix

This attribute returns a list of the 46 signed 16-bit (short) values stored in the Pinnacle ASIC’s memory that is used for taking measurements.

This matrix is not applicable in AnyMeas mode. Use this attribute to compare a prior compensation matrix with a new matrix that was either loaded manually by setting this attribute to a list of 46 signed 16-bit (short) integers or created internally by calling calibrate() with the run parameter as True.

Note

A paraphrased note from Cirque’s Application Note on Comparing compensation matrices:

If any 16-bit values are above 20K (absolute), it generally indicates a problem with the sensor. If no values exceed 20K, proceed with the data comparison. Compare each 16-bit value in one matrix to the corresponding 16-bit value in the other matrix. If the difference between the two values is greater than 500 (absolute), it indicates a change in the environment. Either an object was on the sensor during calibration, or the surrounding conditions (temperature, humidity, or noise level) have changed. One strategy is to force another calibration and compare again, if the values continue to differ by 500, determine whether to use the new data or a previous set of stored data. Another strategy is to average any two values that differ by more than 500 and write this new matrix, with the average values, back into Pinnacle ASIC.

PinnacleTouch.set_adc_gain(sensitivity: int)[source]

Sets the ADC gain in range [0, 3] to enhance performance based on the overlay type (does not apply to AnyMeas mode).

Parameters:
sensitivity: int

Specifies how sensitive the ADC (Analog to Digital Converter) component is. 0 means most sensitive, and 3 means least sensitive. A value outside this range will raise a ValueError exception.

Tip

The official example code from Cirque for a curved overlay uses a value of 1.

PinnacleTouch.tune_edge_sensitivity(x_axis_wide_z_min: int = 4, y_axis_wide_z_min: int = 3)[source]

Changes thresholds to improve detection of fingers.

Warning

This function was ported from Cirque’s example code and doesn’t seem to have corresponding documentation. This function directly alters values in the Pinnacle ASIC’s memory. USE AT YOUR OWN RISK!