"""
A driver module for the Cirque Pinnacle ASIC on the Cirque capacitive touch
based circular trackpads.
"""
__version__ = "0.0.0-auto.0"
__repo__ = "https://github.com/2bndy5/CircuitPython_Cirque_Pinnacle.git"
import time
import struct
try:
from typing import Optional, List, Union, Iterable
except ImportError:
pass
from micropython import const
import digitalio
import busio
from adafruit_bus_device.spi_device import SPIDevice
from adafruit_bus_device.i2c_device import I2CDevice
#: A mode to measure changes in X & Y axis positions. See :doc:`rel_abs`.
PINNACLE_RELATIVE: int = const(0x00)
#: A mode for raw ADC measurements. See :doc:`anymeas`.
PINNACLE_ANYMEAS: int = const(0x01)
#: A mode to measure X, Y, & Z axis positions. See :doc:`rel_abs`.
PINNACLE_ABSOLUTE: int = const(0x02)
PINNACLE_GAIN_100: int = const(0xC0) #: around 100% gain
PINNACLE_GAIN_133: int = const(0x80) #: around 133% gain
PINNACLE_GAIN_166: int = const(0x40) #: around 166% gain
PINNACLE_GAIN_200: int = const(0x00) #: around 200% gain
PINNACLE_FREQ_0: int = const(0x02) #: frequency around 500,000 Hz
PINNACLE_FREQ_1: int = const(0x03) #: frequency around 444,444 Hz
PINNACLE_FREQ_2: int = const(0x04) #: frequency around 400,000 Hz
PINNACLE_FREQ_3: int = const(0x05) #: frequency around 363,636 Hz
PINNACLE_FREQ_4: int = const(0x06) #: frequency around 333,333 Hz
PINNACLE_FREQ_5: int = const(0x07) #: frequency around 307,692 Hz
PINNACLE_FREQ_6: int = const(0x09) #: frequency around 267,000 Hz
PINNACLE_FREQ_7: int = const(0x0B) #: frequency around 235,000 Hz
PINNACLE_MUX_REF1: int = const(0x10) #: enables a builtin capacitor (~0.5 pF).
PINNACLE_MUX_REF0: int = const(0x08) #: enables a builtin capacitor (~0.25 pF).
PINNACLE_MUX_PNP: int = const(0x04) #: enable PNP sense line
PINNACLE_MUX_NPN: int = const(0x01) #: enable NPN sense line
PINNACLE_CRTL_REPEAT: int = const(0x80) #: required for more than 1 measurement
#: triggers low power mode (sleep) after completing measurements
PINNACLE_CRTL_PWR_IDLE: int = const(0x40)
# Defined constants for Pinnacle registers
_FIRMWARE_ID: int = const(0x00)
_STATUS: int = const(0x02)
_SYS_CONFIG: int = const(0x03)
_FEED_CONFIG_1: int = const(0x04)
_FEED_CONFIG_2: int = const(0x05)
_FEED_CONFIG_3: int = const(0x06)
_CAL_CONFIG: int = const(0x07)
_SAMPLE_RATE: int = const(0x09)
_Z_IDLE: int = const(0x0A)
# _Z_SCALER: int = const(0x0B)
# _SLEEP_INTERVAL: int = const(0x0C) # time of sleep until checking for finger
# _SLEEP_TIMER: int = const(0x0D) # time after idle mode until sleep starts
_PACKET_BYTE_0: int = const(0x12)
_PACKET_BYTE_1: int = const(0x13)
_ERA_VALUE: int = const(0x1B)
_ERA_ADDR: int = const(0x1C)
_ERA_CONTROL: int = const(0x1E)
_HCO_ID: int = const(0x1F)
[docs]
class AbsoluteReport:
"""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``.
"""
def __init__(self, buttons: int = 0, x: int = 0, y: int = 0, z: int = 0):
self.buttons: int = buttons
"""The button data is a byte in which each bit represents a button.
The bit to button order is as follows:
0. [LSBit] Button 1.
1. Button 2.
2. Button 3.
"""
self.x: int = x
"""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."""
self.y: int = y
"""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."""
self.z: int = z
"""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()`."""
def __repr__(self) -> str:
return "<AbsoluteReport B1: {} B2: {} B3: {} X: {} Y: {} Z: {}>".format(
self.buttons & 1,
self.buttons & 2,
self.buttons & 4,
self.x,
self.y,
self.z,
)
[docs]
class RelativeReport:
"""A class to represent data reported by `PinnacleTouch.read()` when
`PinnacleTouch.data_mode` is set to `PINNACLE_RELATIVE`.
:param buf: 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``.
"""
def __init__(self, buf: Union[bytes, bytearray] = b"\0\0\0\0"):
data = struct.unpack("Bbbb", buf[:4])
self.buttons: int = data[0]
"""The button data is a byte in which each bit represents a button.
The bit to button order is as follows:
0. [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.
1. 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()`.
2. Button 3 (thought of as Middle or scroll wheel button on a mouse)
"""
self.x: int = data[1] #: The change in X-axis ranging [-127, 127].
self.y: int = data[2] #: The change in Y-axis ranging [-127, 127].
self.scroll: int = data[3]
"""The change in scroll counter ranging [-127, 127]. This data is only reported
if the ``intellimouse`` parameter is ``True`` to `relative_mode_config()`.
"""
@property
def buffer(self) -> bytes:
"""A read-only property to return a `bytes` object that can be used as a Mouse
HID report buffer."""
return struct.pack("Bbbb", self.buttons, self.x, self.y, self.scroll)
def __repr__(self) -> str:
return (
"<RelativeReport "
"Left: {} Right: {} Middle: {} X: {} Y: {} Scroll: {}>".format(
self.buttons & 1,
self.buttons & 2,
self.buttons & 4,
self.x,
self.y,
self.scroll,
)
)
[docs]
class PinnacleTouch:
"""The abstract base class for driving the Pinnacle ASIC.
:param dr_pin: |dr_pin_parameter|
.. important:: |dr_pin_note|
.. |dr_pin_parameter| replace:: The input pin connected to the Pinnacle ASIC's "Data
Ready" pin. If this parameter is not specified, then the SW_DR (software data
ready) flag of the STATUS register is used to determine if the data being
reported is new.
.. |dr_pin_note| replace:: This parameter must be specified if your application is
going to use the Pinnacle ASIC's `PINNACLE_ANYMEAS` mode (a rather experimental
measuring of raw ADC values).
"""
def __init__(self, dr_pin: Optional[digitalio.DigitalInOut] = None):
self.dr_pin = dr_pin
if self.dr_pin is not None:
self.dr_pin.switch_to_input()
firmware_id, firmware_ver = self._rap_read_bytes(_FIRMWARE_ID, 2)
if firmware_id != 7 or firmware_ver != 0x3A:
raise RuntimeError("Cirque Pinnacle ASIC not responding")
self._intellimouse = False
self._mode = PINNACLE_RELATIVE
self.detect_finger_stylus()
self._rap_write(_Z_IDLE, 30) # z-idle packet count
self._rap_write_bytes(_SYS_CONFIG, bytes(3)) # config data mode, power, etc
self.set_adc_gain(0)
while self.available():
self.clear_status_flags()
if not self.calibrate() and dr_pin is not None:
raise AttributeError(
"Calibration did not complete. Check wiring to `dr_pin`."
)
self.feed_enable = True
@property
def feed_enable(self) -> bool:
"""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.
"""
return bool(self._rap_read(_FEED_CONFIG_1) & 1)
@feed_enable.setter
def feed_enable(self, is_on: bool):
is_enabled = self._rap_read(_FEED_CONFIG_1)
if bool(is_enabled & 1) != is_on:
# save ourselves the unnecessary transaction
is_enabled = (is_enabled & 0xFE) | bool(is_on)
self._rap_write(_FEED_CONFIG_1, is_enabled)
@property
def data_mode(self) -> int:
"""This attribute controls the mode for which kind of data to report. The
supported modes are `PINNACLE_RELATIVE`, `PINNACLE_ANYMEAS`,
`PINNACLE_ABSOLUTE`. Default is `PINNACLE_RELATIVE`.
.. important::
When switching from `PINNACLE_ANYMEAS` to `PINNACLE_RELATIVE` or
`PINNACLE_ABSOLUTE`, all configurations are reset, and must be re-configured
by using `absolute_mode_config()` or `relative_mode_config()`.
"""
return self._mode
@data_mode.setter
def data_mode(self, mode: int):
if mode not in (PINNACLE_ANYMEAS, PINNACLE_RELATIVE, PINNACLE_ABSOLUTE):
raise ValueError("Unrecognized input value for data_mode.")
sys_config = self._rap_read(_SYS_CONFIG) & 0xE7 # clear AnyMeas mode flags
if mode in (PINNACLE_RELATIVE, PINNACLE_ABSOLUTE):
if self._mode == PINNACLE_ANYMEAS: # if leaving AnyMeas mode
self._rap_write(_CAL_CONFIG, 0x1E) # enables all compensations
self._rap_write(_Z_IDLE, 30) # 30 z-idle packets
self._mode = mode
self.sample_rate = 100
# set mode flag, enable feed, disable taps in Relative mode
self._rap_write_bytes(_SYS_CONFIG, bytes([sys_config, 1 | mode, 2]))
else: # not leaving AnyMeas mode
self._mode = mode
self._rap_write(_FEED_CONFIG_1, 1 | mode) # set mode flag, enable feed
self._intellimouse = False
else: # for AnyMeas mode
if self.dr_pin is None: # AnyMeas requires the DR pin
raise AttributeError(
"need the Data Ready (DR) pin specified for AnyMeas mode"
)
# disable tracking computations for AnyMeas mode
self._rap_write(_SYS_CONFIG, sys_config | 0x08)
time.sleep(0.01) # wait for tracking computations to expire
self._mode = mode
self.anymeas_mode_config() # configure registers for AnyMeas
@property
def hard_configured(self) -> bool:
"""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 <HCO>`.
:Returns:
``True`` if a 470K ohm resistor is populated at the junction labeled "R4"
"""
return bool(self._rap_read(_HCO_ID) & 0x80)
[docs]
def relative_mode_config(
self,
taps: bool = True,
rotate90: bool = False,
secondary_tap: bool = True,
intellimouse: bool = False,
glide_extend: bool = False,
):
"""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.
:param taps: Specifies if all taps should be reported (``True``) or not
(``False``). Default is ``True``. This affects the ``secondary_tap``
parameter as well.
:param rotate90: Specifies if the axis data is altered for 90 degree rotation
before reporting it (essentially swaps the axis data). Default is ``False``.
:param secondary_tap: 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``.
:param intellimouse: 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``.
:param glide_extend: 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``.
"""
if self._mode == PINNACLE_RELATIVE:
config2 = (rotate90 << 7) | ((not glide_extend) << 4)
config2 |= ((not secondary_tap) << 2) | ((not taps) << 1)
self._rap_write(_FEED_CONFIG_2, config2 | bool(intellimouse))
if intellimouse:
# send required cmd to enable intellimouse
req_seq = bytes([0xF3, 0xC8, 0xF3, 0x64, 0xF3, 0x50])
self._rap_write_cmd(req_seq)
# verify w/ cmd to read the device ID
response = self._rap_read_bytes(0xF2, 3)
self._intellimouse = response.startswith(b"\xF3\x03")
[docs]
def absolute_mode_config(
self, z_idle_count: int = 30, invert_x: bool = False, invert_y: bool = False
):
"""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.
:param z_idle_count: 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].
:param invert_x: Specifies if the x-axis data is to be inverted before reporting
it. Default is ``False``.
:param invert_y: Specifies if the y-axis data is to be inverted before reporting
it. Default is ``False``.
"""
if self._mode == PINNACLE_ABSOLUTE:
self._rap_write(_Z_IDLE, max(0, min(z_idle_count, 255)))
config1 = self._rap_read(_FEED_CONFIG_1) & 0x3F | (invert_y << 7)
self._rap_write(_FEED_CONFIG_1, config1 | (invert_x << 6))
[docs]
def available(self) -> bool:
"""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``.
"""
if self.dr_pin is None:
return bool(self._rap_read(_STATUS) & 0x0C)
return self.dr_pin.value
[docs]
def read(
self, report: Union[AbsoluteReport, RelativeReport], read_buttons: bool = True
) -> None:
"""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.
:param report: 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.
:param read_buttons: 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 :attr:`~RelativeReport.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.
"""
if self._mode == PINNACLE_ABSOLUTE: # if absolute mode
skip = (not read_buttons) * 2
data = self._rap_read_bytes(_PACKET_BYTE_0 + skip, 6 - skip)
self.clear_status_flags(False)
assert isinstance(report, AbsoluteReport)
if read_buttons:
report.buttons &= 0xF8
report.buttons = data[0] & 7
report.x = data[2 - skip] | ((data[4 - skip] & 0x0F) << 8)
report.y = data[3 - skip] | ((data[4 - skip] & 0xF0) << 4)
report.z = data[5 - skip] & 0x3F
elif self._mode == PINNACLE_RELATIVE: # if in relative mode
assert isinstance(report, RelativeReport)
has_scroll = self._intellimouse
read_buttons = bool(read_buttons) # enforce bool data type
data = self._rap_read_bytes(
_PACKET_BYTE_0 + (not read_buttons), 2 + has_scroll + read_buttons
)
self.clear_status_flags(False)
if read_buttons:
report.buttons &= 0xF8
report.buttons = data[0] & 7
unpacked = struct.unpack("b" * (2 + has_scroll), data[read_buttons:])
report.x, report.y = unpacked[0:2]
if len(unpacked) > 2:
report.scroll = unpacked[2]
[docs]
def clear_status_flags(self, post_delay=True):
"""This function clears the "Data Ready" flag which is reflected with
the ``dr_pin``.
:param post_delay: 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."""
self._rap_write(_STATUS, 0)
if post_delay:
time.sleep(0.00005) # per official examples from Cirque
@property
def allow_sleep(self) -> bool:
"""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).
"""
return bool(self._rap_read(_SYS_CONFIG) & 4)
@allow_sleep.setter
def allow_sleep(self, is_enabled: bool):
self._rap_write(
_SYS_CONFIG, (self._rap_read(_SYS_CONFIG) & 0xFB) | (is_enabled << 2)
)
@property
def shutdown(self) -> bool:
"""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.
"""
return bool(self._rap_read(_SYS_CONFIG) & 2)
@shutdown.setter
def shutdown(self, is_off: bool):
self._rap_write(
_SYS_CONFIG, (self._rap_read(_SYS_CONFIG) & 0xFD) | (is_off << 1)
)
@property
def sample_rate(self) -> int:
"""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.
"""
return self._rap_read(_SAMPLE_RATE)
@sample_rate.setter
def sample_rate(self, val: int):
if self._mode != PINNACLE_ANYMEAS:
if val in (200, 300):
# disable palm & noise compensations
self._rap_write(_FEED_CONFIG_3, 10)
reload_timer = 6 if val == 300 else 0x09
self._era_write_bytes(0x019E, reload_timer, 2)
val = 0
else:
# enable palm & noise compensations
self._rap_write(_FEED_CONFIG_3, 0)
self._era_write_bytes(0x019E, 0x13, 2)
val = val if val in (100, 80, 60, 40, 20, 10) else 100
self._rap_write(_SAMPLE_RATE, val)
[docs]
def detect_finger_stylus(
self,
enable_finger: bool = True,
enable_stylus: bool = True,
sample_rate: int = 100,
):
"""This function will configure the Pinnacle ASIC to detect either
finger, stylus, or both.
:param enable_finger: ``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``.
:param enable_stylus: ``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``.
:param sample_rate: 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()`
"""
finger_stylus = self._era_read(0x00EB)
finger_stylus |= (enable_stylus << 2) | enable_finger
self._era_write(0x00EB, finger_stylus)
self.sample_rate = sample_rate
[docs]
def calibrate(
self,
run: bool = True,
tap: bool = True,
track_error: bool = True,
nerd: bool = True,
background: bool = True,
) -> bool:
"""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.
:param run: 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.
:param tap: Enable dynamic tap compensation? Default is ``True``.
:param track_error: Enable dynamic track error compensation? Default is
``True``.
:param nerd: Enable dynamic NERD compensation? Default is ``True``. This
parameter has something to do with palm detection/compensation.
:param background: Enable dynamic background compensation? Default is ``True``.
:Returns:
``False``
- If `data_mode` is not set to `PINNACLE_RELATIVE` or
`PINNACLE_ABSOLUTE`.
- If the calibration ``run`` timed out after 100 milliseconds.
``True``
- If `data_mode` is set to `PINNACLE_RELATIVE` or `PINNACLE_ABSOLUTE`
and the calibration is **not** ``run``.
- If the calibration ``run`` successfully finishes.
"""
if self._mode not in (PINNACLE_RELATIVE, PINNACLE_ABSOLUTE):
return False
cal_config = (tap << 4) | (track_error << 3) | (nerd << 2)
cal_config |= background << 1
self._rap_write(_CAL_CONFIG, cal_config | run)
timeout = time.monotonic_ns() + 100000000
if run:
done = False
while not done and time.monotonic_ns() < timeout:
done = self.available() # calibration is running
if done:
self.clear_status_flags() # now that calibration is done
return done
return True
@property
def calibration_matrix(self) -> List[int]:
"""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.
"""
# combine every 2 bytes from resulting buffer into list of signed
# 16-bits integers
return list(struct.unpack("46h", self._era_read_bytes(0x01DF, 92)))
@calibration_matrix.setter
def calibration_matrix(self, matrix: List[int]):
matrix += [0] * (46 - len(matrix)) # pad short matrices w/ 0s
for index in range(46):
buf = struct.pack("h", matrix[index])
self._era_write(0x01DF + index * 2, buf[0])
self._era_write(0x01DF + index * 2 + 1, buf[1])
[docs]
def set_adc_gain(self, sensitivity: int):
"""Sets the ADC gain in range [0, 3] to enhance performance based on
the overlay type (does not apply to AnyMeas mode).
:param sensitivity: 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``.
"""
if not 0 <= sensitivity < 4:
raise ValueError("sensitivity is out of bounds [0,3]")
val = self._era_read(0x0187) & 0x3F | (sensitivity << 6)
self._era_write(0x0187, val)
[docs]
def tune_edge_sensitivity(
self, x_axis_wide_z_min: int = 0x04, y_axis_wide_z_min: int = 0x03
):
"""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!
"""
self._era_write(0x0149, x_axis_wide_z_min)
self._era_write(0x0168, y_axis_wide_z_min)
[docs]
def anymeas_mode_config(
self,
gain: int = PINNACLE_GAIN_200,
frequency: int = PINNACLE_FREQ_0,
sample_length: int = 512,
mux_ctrl: int = PINNACLE_MUX_PNP,
apperture_width: int = 500,
ctrl_pwr_cnt: int = 1,
):
"""This function configures the Pinnacle ASIC to output raw ADC
measurements.
Be sure to set the `data_mode` attribute to `PINNACLE_ANYMEAS` before calling
this function, otherwise it will do nothing.
:param gain: Sets the sensitivity of the ADC matrix. Valid values are the
constants defined in `AnyMeas mode Gain`_. Defaults to `PINNACLE_GAIN_200`.
:param frequency: Sets the frequency of measurements made by the ADC matrix.
Valid values are the constants defined in `AnyMeas mode Frequencies`_.
Defaults to `PINNACLE_FREQ_0`.
:param sample_length: Sets the maximum bit length of the measurements made by
the ADC matrix. Valid values are ``128``, ``256``, or ``512``. Defaults to
``512``.
:param mux_ctrl: The Pinnacle ASIC can employ different bipolar junctions
and/or reference capacitors. Valid values are the constants defined in
`AnyMeas mode Muxing`_. Additional combination of these constants is also
allowed. Defaults to `PINNACLE_MUX_PNP`.
:param apperture_width: Sets the window of time (in nanoseconds) to allow for
the ADC to take a measurement. Valid values are multiples of 125 in range
[``250``, ``1875``]. Erroneous values are clamped/truncated to this range.
.. note:: The ``apperture_width`` parameter has a inverse
relationship/affect on the ``frequency`` parameter. The approximated
frequencies described in this documentation are based on an aperture
width of 500 nanoseconds, and they will shrink as the apperture width
grows or grow as the aperture width shrinks.
:param ctrl_pwr_cnt: Configure the Pinnacle to perform a number of measurements
for each call to `measure_adc()`. Defaults to 1. Constants defined in
`AnyMeas mode Control`_ can be used to specify if is sleep is allowed
(`PINNACLE_CRTL_PWR_IDLE` -- this is not default) or if repetitive
measurements is allowed (`PINNACLE_CRTL_REPEAT`) if number of measurements
is more than 1.
.. warning::
There is no bounds checking on the number of measurements specified
here. Specifying more than 63 will trigger sleep mode after performing
measurements.
.. tip::
Be aware that allowing the Pinnacle to enter sleep mode after taking
measurements will slow consecutive calls to `measure_adc()` as the
Pinnacle requires about 300 milliseconds to wake up.
"""
if self._mode == PINNACLE_ANYMEAS:
buffer = bytearray(10)
buffer[0] = gain | frequency
buffer[1] = max(1, min(int(sample_length / 128), 3))
buffer[2] = mux_ctrl
buffer[4] = max(2, min(int(apperture_width / 125), 15))
buffer[6] = _PACKET_BYTE_1
buffer[9] = ctrl_pwr_cnt
self._rap_write_bytes(_FEED_CONFIG_2, buffer)
self._rap_write_bytes(_PACKET_BYTE_1, bytes(8))
self.clear_status_flags()
[docs]
def measure_adc(self, bits_to_toggle: int, toggle_polarity: int) -> Optional[int]:
"""This blocking function instigates and returns the measurements (a
signed short) from the Pinnacle ASIC's ADC (Analog to Digital Converter) matrix.
Internally this function calls `start_measure_adc()` and `get_measure_adc()` in
sequence. Be sure to set the `data_mode` attribute to `PINNACLE_ANYMEAS` before
calling this function otherwise it will do nothing.
Each of the parameters are a 4-byte integer (see
:ref:`format table below <polynomial-fmt>`) in which each bit corresponds to
a capacitance sensing electrode in the sensor's matrix (12 electrodes for
Y-axis, 16 electrodes for X-axis). They are used to compensate for varying
capacitances in the electrodes during measurements.
:param bits_to_toggle: A bit of ``1`` flags that electrode's output for
toggling, and a bit of ``0`` signifies that the electrode's output should
remain unaffected.
:param toggle_polarity: This specifies which polarity the output of the
electrode(s) (specified with corresponding bits in ``bits_to_toggle``
parameter) should be toggled (forced). A bit of ``1`` toggles that bit
positive, and a bit of ``0`` toggles that bit negative.
:Returns:
A 2-byte `bytearray` that represents a signed short integer. If `data_mode`
is not set to `PINNACLE_ANYMEAS`, then this function returns `None` and does
nothing.
.. _polynomial-fmt:
:4-byte Integer Format:
Bits 31 & 30 are not used and should remain ``0``. Bits 29 and 28 represent
the optional implementation of reference capacitors built into the Pinnacle
ASIC. To use these capacitors, the corresponding constants
(`PINNACLE_MUX_REF0` and/or `PINNACLE_MUX_REF1`) must be passed to
`anymeas_mode_config()` in the ``mux_ctrl`` parameter, and their
representative bits must be flagged in both ``bits_to_toggle`` &
``toggle_polarity`` parameters.
.. csv-table:: byte 3 (MSByte)
:stub-columns: 1
:widths: 10, 5, 5, 5, 5, 5, 5, 5, 5
"bit position",31,30,29,28,27,26,25,24
"representation",N/A,N/A,Ref1,Ref0,Y11,Y10,Y9,Y8
.. csv-table:: byte 2
:stub-columns: 1
:widths: 10, 5, 5, 5, 5, 5, 5, 5, 5
"bit position",23,22,21,20,19,18,17,16
"representation",Y7,Y6,Y5,Y4,Y3,Y2,Y1,Y0
.. csv-table:: byte 1
:stub-columns: 1
:widths: 10, 5, 5, 5, 5, 5, 5, 5, 5
"bit position",15,14,13,12,11,10,9,8
"representation",X15,X14,X13,X12,X11,X10,X9,X8
.. csv-table:: byte 0 (LSByte)
:stub-columns: 1
:widths: 10, 5, 5, 5, 5, 5, 5, 5, 5
"bit position",7,6,5,4,3,2,1,0
"representation",X7,X6,X5,X4,X3,X2,X1,X0
.. seealso::
Review `AnyMeas mode example <examples.html#anymeas-mode-example>`_ to
understand how to use these 4-byte integers.
"""
if self._mode != PINNACLE_ANYMEAS:
return None
self.start_measure_adc(bits_to_toggle, toggle_polarity)
while not self.available():
pass # wait till measurements are complete
return self.get_measure_adc()
[docs]
def start_measure_adc(self, bits_to_toggle: int, toggle_polarity: int):
"""A non-blocking function that starts measuring ADC values in
AnyMeas mode.
See the parameters and table in `measure_adc()` as this is its helper function,
and all parameters there are used the same way here.
"""
if self._mode == PINNACLE_ANYMEAS:
tog_pol = bytearray(8) # assemble list of register buffers
for i in range(3, -1, -1):
tog_pol[3 - i] = (bits_to_toggle >> (i * 8)) & 0xFF
tog_pol[3 - i + 4] = (toggle_polarity >> (i * 8)) & 0xFF
# write toggle and polarity parameters to register 0x13 - 0x1A
self._rap_write_bytes(_PACKET_BYTE_1, tog_pol)
# clear_status_flags() and initiate measurements
self._rap_write_bytes(_STATUS, b"\0\x18")
[docs]
def get_measure_adc(self) -> Optional[int]:
"""A non-blocking function that returns ADC measurement on
completion.
This function is only meant to be used in conjunction with `start_measure_adc()`
for non-blocking application. Be sure that `available()` returns ``True`` before
calling this function as it will `clear_status_flags()` that `available()` uses.
:returns:
* `None` if `data_mode` is not set to `PINNACLE_ANYMEAS` or if the "data
ready" pin's signal is not active (while `data_mode` is set to
`PINNACLE_ANYMEAS`) meaning the Pinnacle ASIC is still computing the ADC
measurements based on the 4-byte polynomials passed to
`start_measure_adc()`.
* a `bytearray` that represents a signed 16-bit integer upon completed ADC
measurements based on the 4-byte polynomials passed to
`start_measure_adc()`.
"""
if self._mode != PINNACLE_ANYMEAS:
return None
data = self._rap_read_bytes(0x11, 2)
self.clear_status_flags()
return struct.unpack("h", data)[0]
def _rap_read(self, reg: int) -> int:
raise NotImplementedError()
def _rap_read_bytes(self, reg: int, numb_bytes: int) -> bytearray:
raise NotImplementedError()
def _rap_write(self, reg: int, value: int):
raise NotImplementedError()
def _rap_write_cmd(self, cmd: bytes):
raise NotImplementedError()
def _rap_write_bytes(self, reg: int, values: Iterable[int]):
raise NotImplementedError()
def _era_read(self, reg: int) -> int:
prev_feed_state = self.feed_enable
if prev_feed_state:
self.feed_enable = False # accessing raw memory, so do this
self._rap_write_bytes(_ERA_ADDR, bytes([reg >> 8, reg & 0xFF]))
self._rap_write(_ERA_CONTROL, 1) # indicate reading only 1 byte
while self._rap_read(_ERA_CONTROL): # read until reg == 0
pass # also sets Command Complete flag in Status register
buf = self._rap_read(_ERA_VALUE) # get value
self.clear_status_flags()
if prev_feed_state:
self.feed_enable = prev_feed_state # resume previous feed state
return buf
def _era_read_bytes(self, reg: int, numb_bytes: int) -> bytes:
buf = b""
prev_feed_state = self.feed_enable
if prev_feed_state:
self.feed_enable = False # accessing raw memory, so do this
self._rap_write_bytes(_ERA_ADDR, bytes([reg >> 8, reg & 0xFF]))
for _ in range(numb_bytes):
self._rap_write(_ERA_CONTROL, 5) # indicate reading sequential bytes
while self._rap_read(_ERA_CONTROL): # read until reg == 0
pass # also sets Command Complete flag in Status register
buf += bytes([self._rap_read(_ERA_VALUE)]) # get value
self.clear_status_flags()
if prev_feed_state:
self.feed_enable = prev_feed_state # resume previous feed state
return buf
def _era_write(self, reg: int, value: int):
prev_feed_state = self.feed_enable
if prev_feed_state:
self.feed_enable = False # accessing raw memory, so do this
self._rap_write(_ERA_VALUE, value) # write value
self._rap_write_bytes(_ERA_ADDR, bytes([reg >> 8, reg & 0xFF]))
self._rap_write(_ERA_CONTROL, 2) # indicate writing only 1 byte
while self._rap_read(_ERA_CONTROL): # read until reg == 0
pass # also sets Command Complete flag in Status register
self.clear_status_flags()
if prev_feed_state:
self.feed_enable = prev_feed_state # resume previous feed state
def _era_write_bytes(self, reg: int, value: int, numb_bytes: int):
# rarely used as it only writes 1 value to multiple registers
prev_feed_state = self.feed_enable
if prev_feed_state:
self.feed_enable = False # accessing raw memory, so do this
self._rap_write(_ERA_VALUE, value) # write value
self._rap_write_bytes(_ERA_ADDR, bytes([reg >> 8, reg & 0xFF]))
self._rap_write(_ERA_CONTROL, 0x0A) # indicate writing sequential bytes
for _ in range(numb_bytes):
while self._rap_read(_ERA_CONTROL): # read until reg == 0
pass # also sets Command Complete flag in Status register
self.clear_status_flags()
if prev_feed_state:
self.feed_enable = prev_feed_state # resume previous feed state
# pylint: disable=no-member
[docs]
class PinnacleTouchI2C(PinnacleTouch):
"""A derived class for interfacing with the Pinnacle ASIC via the I2C protocol.
:param i2c: The object of the I2C bus to use. This object must be shared among other
driver classes that use the same I2C bus (SDA & SCL pins).
:param address: The slave I2C address of the Pinnacle ASIC. Defaults to ``0x2A``.
:param dr_pin: |dr_pin_parameter|
.. important:: |dr_pin_note|
"""
def __init__(
self,
i2c: busio.I2C,
address: int = 0x2A,
dr_pin: Optional[digitalio.DigitalInOut] = None,
):
self._i2c = I2CDevice(i2c, address)
super().__init__(dr_pin=dr_pin)
def _rap_read(self, reg: int) -> int:
return self._rap_read_bytes(reg, 1)[0]
def _rap_read_bytes(self, reg: int, numb_bytes: int) -> bytearray:
buf = bytes([reg | 0xA0]) # per datasheet
with self._i2c as i2c:
i2c.write(buf) # includes a STOP condition
buf = bytearray(numb_bytes) # for response(s)
# auto-increments register for each byte read
i2c.readinto(buf)
return buf
def _rap_write(self, reg: int, value: int):
self._rap_write_bytes(reg, bytes([value]))
def _rap_write_bytes(self, reg: int, values: Iterable[int]):
buf = b""
for index, byte in enumerate(values):
# Pinnacle doesn't auto-increment register
# addresses for I2C write operations
buf += bytes([(reg + index) | 0x80, byte & 0xFF])
self._rap_write_cmd(buf)
def _rap_write_cmd(self, cmd: bytes):
with self._i2c as i2c:
i2c.write(cmd)
[docs]
class PinnacleTouchSPI(PinnacleTouch):
"""A derived class for interfacing with the Pinnacle ASIC via the SPI protocol.
:param spi: The object of the SPI bus to use. This object must be shared among other
driver classes that use the same SPI bus (MOSI, MISO, & SCK pins).
:param ss_pin: The "slave select" pin output to the Pinnacle ASIC.
:param spi_frequency: The SPI bus speed in Hz. Default is the maximum 13 MHz.
:param dr_pin: |dr_pin_parameter|
.. important:: |dr_pin_note|
"""
def __init__(
self,
spi: busio.SPI,
ss_pin: digitalio.DigitalInOut,
spi_frequency: int = 13000000,
dr_pin: Optional[digitalio.DigitalInOut] = None,
):
self._spi = SPIDevice(spi, chip_select=ss_pin, phase=1, baudrate=spi_frequency)
super().__init__(dr_pin=dr_pin)
def _rap_read(self, reg: int) -> int:
buf_out = bytes([reg | 0xA0]) + b"\xFB" * 3
buf_in = bytearray(len(buf_out))
with self._spi as spi:
spi.write_readinto(buf_out, buf_in)
return buf_in[3]
def _rap_read_bytes(self, reg: int, numb_bytes: int) -> bytearray:
# using auto-increment method
buf_out = bytes([reg | 0xA0]) + b"\xFC" * (1 + numb_bytes) + b"\xFB"
buf_in = bytearray(len(buf_out))
with self._spi as spi:
spi.write_readinto(buf_out, buf_in)
return buf_in[3:]
def _rap_write_cmd(self, cmd: bytes):
with self._spi as spi:
spi.write(cmd)
def _rap_write(self, reg: int, value: int):
self._rap_write_cmd(bytes([(reg | 0x80), value]))
def _rap_write_bytes(self, reg: int, values: Iterable[int]):
for i, val in enumerate(values):
self._rap_write(reg + i, val)