diff --git a/README.rst b/README.rst index 8710e6f..735714c 100644 --- a/README.rst +++ b/README.rst @@ -63,7 +63,7 @@ Pinout .. image:: https://github.com/2bndy5/CircuitPython_Cirque_Pinnacle/raw/master/docs/_static/Cirque_GlidePoint-Circle-Trackpad.png :target: https://www.mouser.com/new/cirque/glidepoint-circle-trackpads/ -The above picture is a example of the Cirque GlidePoint circle trackpad. This picture +The above picture is an example of the Cirque GlidePoint circle trackpad. This picture is chosen as the test pads (larger copper circular pads) are clearly labeled. The test pads are extended to the `12-pin FFC/FPC cable `_ connector (the white block near the diff --git a/circuitpython_cirque_pinnacle/glidepoint.py b/circuitpython_cirque_pinnacle/glidepoint.py index e023eae..6ab31d8 100644 --- a/circuitpython_cirque_pinnacle/glidepoint.py +++ b/circuitpython_cirque_pinnacle/glidepoint.py @@ -4,32 +4,36 @@ """ __version__ = "0.0.0-auto.0" __repo__ = "https://github.com/2bndy5/CircuitPython_Cirque_Pinnacle.git" -from time import sleep +import time from struct import pack, unpack -from adafruit_bus_device.spi_device import SPIDevice -from adafruit_bus_device.i2c_device import I2CDevice - -RELATIVE = 0x00 -ANYMEAS = 0x01 -ABSOLUTE = 0x02 -GAIN_100 = 0xC0 -GAIN_133 = 0x80 -GAIN_166 = 0x40 -GAIN_200 = 0x00 -FREQ_0 = 0x02 -FREQ_1 = 0x03 -FREQ_2 = 0x04 -FREQ_3 = 0x05 -FREQ_4 = 0x06 -FREQ_5 = 0x07 -FREQ_6 = 0x09 -FREQ_7 = 0x0B -MUX_REF1 = 0x10 -MUX_REF0 = 0x08 -MUX_PNP = 0x04 -MUX_NPN = 0x01 -CRTL_REPEAT = 0x80 -CRTL_PWR_IDLE = 0x40 +from micropython import const +try: + from ubus_device import SPIDevice, I2CDevice +except ImportError: + from adafruit_bus_device.spi_device import SPIDevice + from adafruit_bus_device.i2c_device import I2CDevice + +RELATIVE = const(0x00) +ANYMEAS = const(0x01) +ABSOLUTE = const(0x02) +GAIN_100 = const(0xC0) +GAIN_133 = const(0x80) +GAIN_166 = const(0x40) +GAIN_200 = const(0x00) +FREQ_0 = const(0x02) +FREQ_1 = const(0x03) +FREQ_2 = const(0x04) +FREQ_3 = const(0x05) +FREQ_4 = const(0x06) +FREQ_5 = const(0x07) +FREQ_6 = const(0x09) +FREQ_7 = const(0x0B) +MUX_REF1 = const(0x10) +MUX_REF0 = const(0x08) +MUX_PNP = const(0x04) +MUX_NPN = const(0x01) +CRTL_REPEAT = const(0x80) +CRTL_PWR_IDLE = const(0x40) class PinnacleTouch: """The abstract base class for driving the Pinnacle ASIC.""" @@ -41,10 +45,10 @@ def __init__(self, dr_pin=None): if firmware_id != 7 or firmware_ver != 0x3A: raise OSError("Cirque Pinnacle ASIC not responding") # init internal attributes w/ factory defaults after power-on-reset - self._mode = 0 # 0 means relative mode which is factory default after power-on-reset + self._mode = 0 # 0 means relative mode which is factory default self.detect_finger_stylus() self._rap_write(0x0A, 30) # z-idle packet count - self._rap_write_bytes(3, [0, 1, 2]) # configure relative (& absolute mode) + self._rap_write_bytes(3, [0, 1, 2]) # configure relative mode self.set_adc_gain(0) self.calibrate(True) # enables all compensations @@ -57,22 +61,25 @@ def feed_enable(self): @feed_enable.setter def feed_enable(self, is_on): is_enabled = self._rap_read(4) - if is_enabled & 1 != is_on: # save ourselves the unnecessary transaction + if is_enabled & 1 != is_on: + # save ourselves the unnecessary transaction is_enabled = (is_enabled & 0xFE) | is_on self._rap_write(4, is_enabled) @property def data_mode(self): - """This attribute controls which mode the data report is configured for.""" + """This attribute controls which mode the data report is configured + for.""" return self._mode @data_mode.setter def data_mode(self, mode): if mode not in (ANYMEAS, RELATIVE, ABSOLUTE): - raise ValueError("unrecognised input value for data mode. Use 0 for Relative mode, " - "1 for AnyMeas mode, or 2 for Absolute mode.") + raise ValueError("unrecognised input value for data mode. Use 0 " + "for Relative mode, 1 for AnyMeas mode, or 2 " + "for Absolute mode.") self._mode = mode - sys_config = self._rap_read(3) & 0xE7 # clear flags specific to AnyMeas mode + sys_config = self._rap_read(3) & 0xE7 # clear AnyMeas mode flags if mode in (RELATIVE, ABSOLUTE): # for relative/absolute mode if self.data_mode == ANYMEAS: # if leaving AnyMeas mode self._rap_write_bytes(3, [ @@ -86,37 +93,43 @@ def data_mode(self, mode): self._rap_write(4, 1 | mode) else: # for AnyMeas mode if self.dr_pin is None: # this mode requires the use of DR IRQ pin - raise AttributeError("Data Ready digital input (interupt) pin is None, " - "please specify the dr_pin attribute for AnyMeas mode") + raise AttributeError("Data Ready digital input (interupt) pin " + "is None, please specify the dr_pin " + "attribute for AnyMeas mode") # disable tracking computations for AnyMeas mode self._rap_write(3, sys_config | 0x08) - sleep(0.01) # wait 10 ms for tracking measurements to expire - self.anymeas_mode_config() # configure registers for the AnyMeas mode + time.sleep(0.01) # wait 10 ms for tracking measurements to expire + self.anymeas_mode_config() # configure registers for AnyMeas @property def hard_configured(self): - """This `bool` attribute can be used to inform applications about factory - customized hardware configuration.""" + """This `bool` attribute can be used to inform applications about + factory customized hardware configuration.""" return bool(self._rap_read(0x1f)) - def relative_mode_config(self, rotate90=False, taps=True, secondary_tap=True, - glide_extend=True, intellimouse=False): - """Configure settings specific to Relative mode (AKA Mouse mode) data reporting.""" + def relative_mode_config(self, rotate90=False, taps=True, + secondary_tap=True, glide_extend=True, + intellimouse=False): + """Configure settings specific to Relative mode (AKA Mouse mode) data + reporting.""" if self.data_mode == RELATIVE: config2 = rotate90 << 7 | (not glide_extend) << 4 | ( not secondary_tap) << 2 | (not taps) << 1 | intellimouse self._rap_write(5, config2) - def absolute_mode_config(self, z_idle_count=30, invert_x=False, invert_y=False): - """Configure settings specific to Absolute mode (reports axis positions).""" + def absolute_mode_config(self, z_idle_count=30, invert_x=False, + invert_y=False): + """Configure settings specific to Absolute mode (reports axis + positions).""" if self.data_mode == ABSOLUTE: self._rap_write(0x0A, max(0, min(z_idle_count, 255))) - config1 = (self._rap_read(4) & 0x3F) | (invert_y << 7) | (invert_x << 6) + config1 = self._rap_read(4) & 0x3F + config1 |= (invert_y << 7) | (invert_x << 6) self._rap_write(4, config1) def report(self, only_new=True): - """This function will return touch event data from the Pinnacle ASIC (including empty - packets on ending of a touch event).""" + """This function will return touch event data from the Pinnacle ASIC + (including empty packets on ending of a touch event).""" if self._mode == ANYMEAS: return None return_vals = None @@ -143,15 +156,16 @@ def report(self, only_new=True): return return_vals def clear_flags(self): - """This function clears the "Data Ready" flag which is reflected with the ``dr_pin``.""" + """This function clears the "Data Ready" flag which is reflected with + the ``dr_pin``.""" self._rap_write(2, 0) # delay 50 microseconds per official example from Cirque - sleep(0.00005) + time.sleep(0.00005) @property def allow_sleep(self): - """This attribute specifies if the Pinnacle ASIC is allowed to sleep after about 5 seconds - of idle (no input event).""" + """This attribute specifies if the Pinnacle ASIC is allowed to sleep + after about 5 seconds of idle (no input event).""" return bool(self._rap_read(3) & 4) @allow_sleep.setter @@ -169,7 +183,8 @@ def shutdown(self, is_off): @property def sample_rate(self): - """This attribute controls how many samples (of data) per second are reported.""" + """This attribute controls how many samples (of data) per second are + reported.""" return self._rap_read(9) @sample_rate.setter @@ -188,29 +203,35 @@ def sample_rate(self, val): val = val if val in (100, 80, 60, 40, 20, 10) else 100 self._rap_write(9, val) - def detect_finger_stylus(self, enable_finger=True, enable_stylus=True, sample_rate=100): - """This function will configure the Pinnacle ASIC to detect either finger, - stylus, or both.""" + def detect_finger_stylus(self, enable_finger=True, + enable_stylus=True, sample_rate=100): + """This function will configure the Pinnacle ASIC to detect either + finger, stylus, or both.""" finger_stylus = self._era_read(0x00EB) finger_stylus |= (enable_stylus << 2) | enable_finger self._era_write(0x00EB, finger_stylus) self.sample_rate = sample_rate - def calibrate(self, run, tap=True, track_error=True, nerd=True, background=True): - """Set calibration parameters when the Pinnacle ASIC calibrates itself.""" + def calibrate(self, run, tap=True, track_error=True, nerd=True, + background=True): + """Set calibration parameters when the Pinnacle ASIC calibrates + itself.""" if self.data_mode != ANYMEAS: - cal_config = tap << 4 | track_error << 3 | nerd << 2 | background << 1 + cal_config = (tap << 4) | (track_error << 3) | (nerd << 2) + cal_config |= background << 1 self._rap_write(7, cal_config | run) if run: while self._rap_read(7) & 1: pass # calibration is running - self.clear_flags() # now that calibration is done + self.clear_flags() # now that calibration is done @property def calibration_matrix(self): - """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.""" - # combine every 2 bytes from resulting buffer to form a list of signed 16-bits integers + """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.""" + # combine every 2 bytes from resulting buffer into list of signed + # 16-bits integers return list(unpack('46h', self._era_read_bytes(0x01DF, 92))) @calibration_matrix.setter @@ -219,7 +240,7 @@ def calibration_matrix(self, matrix): matrix += [0] * (46 - len(matrix)) # save time on bus interactions by pausing feed now prev_feed_state = self.feed_enable - self.feed_enable = False # required for ERA functions anyway + self.feed_enable = False # required for ERA functions anyway # be sure to not write more than allowed for index in range(46): # write 2 bytes at a time @@ -229,7 +250,8 @@ def calibration_matrix(self, matrix): self.feed_enable = prev_feed_state # resume previous feed state def set_adc_gain(self, sensitivity): - """Sets the ADC gain in range [0,3] to enhance performance based on the overlay type""" + """Sets the ADC gain in range [0,3] to enhance performance based on + the overlay type""" if 0 <= sensitivity < 4: val = self._era_read(0x0187) & 0x3F val |= sensitivity << 6 @@ -237,15 +259,17 @@ def set_adc_gain(self, sensitivity): else: raise ValueError("{} is out of bounds [0,3]".format(sensitivity)) - def tune_edge_sensitivity(self, x_axis_wide_z_min=0x04, y_axis_wide_z_min=0x03): + def tune_edge_sensitivity(self, x_axis_wide_z_min=0x04, + y_axis_wide_z_min=0x03): """Changes thresholds to improve detection of fingers.""" self._era_write(0x0149, x_axis_wide_z_min) self._era_write(0x0168, y_axis_wide_z_min) def anymeas_mode_config(self, gain=GAIN_200, frequency=FREQ_0, - sample_length=512, mux_ctrl=MUX_PNP, apperture_width=500, - ctrl_pwr_cnt=1): - """This function configures the Pinnacle ASIC to output raw ADC measurements.""" + sample_length=512, mux_ctrl=MUX_PNP, + apperture_width=500, ctrl_pwr_cnt=1): + """This function configures the Pinnacle ASIC to output raw ADC + measurements.""" if self.data_mode == ANYMEAS: anymeas_config = [2, 3, 4, 0, 4, 0, 19, 0, 0, 1] anymeas_config[0] = gain | frequency @@ -258,8 +282,9 @@ def anymeas_mode_config(self, gain=GAIN_200, frequency=FREQ_0, self.clear_flags() def measure_adc(self, bits_to_toggle, toggle_polarity): - """This blocking function instigates and returns the measurements (a signed short) from - the Pinnacle ASIC's ADC (Analog to Digital Converter) matrix.""" + """This blocking function instigates and returns the measurements (a + signed short) from the Pinnacle ASIC's ADC (Analog to Digital + Converter) matrix.""" self.start_measure_adc(bits_to_toggle, toggle_polarity) result = self.get_measure_adc() while result is None: # wait till measurements are complete @@ -267,20 +292,22 @@ def measure_adc(self, bits_to_toggle, toggle_polarity): return result def start_measure_adc(self, bits_to_toggle, toggle_polarity): - """A non-blocking function that starts measuring ADC values in AnyMeas mode.""" - if self._mode != ANYMEAS: + """A non-blocking function that starts measuring ADC values in + AnyMeas mode.""" + if self._mode == ANYMEAS: tog_pol = [] # assemble list of register buffers for i in range(3, -1, -1): tog_pol.append((bits_to_toggle >> (i * 8)) & 0xFF) for i in range(3, -1, -1): tog_pol.append((toggle_polarity >> (i * 8)) & 0xFF) - # write toggle and polarity parameters to register 0x13 - 0x1A (PACKET_BYTE_1 + 8) + # write toggle and polarity parameters to register 0x13 - 0x1A self._rap_write_bytes(0x13, tog_pol) # initiate measurements self._rap_write(3, self._rap_read(3) | 0x18) def get_measure_adc(self): - """A non-blocking function that returns ADC measurement on completion.""" + """A non-blocking function that returns ADC measurement on + completion.""" if self._mode != ANYMEAS: return None if not self.dr_pin.value: @@ -339,7 +366,7 @@ def _era_write(self, reg, value): self.feed_enable = prev_feed_state # resume previous feed state def _era_write_bytes(self, reg, value, numb_bytes): - # NOTE this is rarely used as it only writes 1 value to multiple registers + # rarely used as it only writes 1 value to multiple registers prev_feed_state = self.feed_enable self.feed_enable = False # accessing raw memory, so do this self._rap_write(0x1B, value) # write value @@ -353,7 +380,8 @@ def _era_write_bytes(self, reg, value, numb_bytes): # pylint: disable=no-member,too-few-public-methods class PinnacleTouchI2C(PinnacleTouch): - """Parent class for interfacing with the Pinnacle ASIC via the I2C protocol.""" + """Parent class for interfacing with the Pinnacle ASIC via the I2C + protocol.""" def __init__(self, i2c, address=0x2A, dr_pin=None): self._i2c = I2CDevice(i2c, (address << 1)) # per datasheet super(PinnacleTouchI2C, self).__init__(dr_pin=dr_pin) @@ -379,17 +407,20 @@ def _rap_write(self, reg, value): def _rap_write_bytes(self, reg, values): self._i2c.device_address &= 0xFE # set write flag buf = b'' - for index, byte in enumerate(values): # works for bytearrays/lists/tuples - # Pinnacle doesn't auto-increment register addresses for I2C write operations + for index, byte in enumerate(values): # for bytearrays/lists/tuples + # Pinnacle doesn't auto-increment register addresses for + # I2C write operations # Also truncate int elements of a list/tuple buf += bytearray([(reg + index) | 0x80, byte & 0xFF]) with self._i2c as i2c: i2c.write(buf) class PinnacleTouchSPI(PinnacleTouch): - """Parent class for interfacing with the Pinnacle ASIC via the SPI protocol.""" + """Parent class for interfacing with the Pinnacle ASIC via the SPI + protocol.""" def __init__(self, spi, ss_pin, dr_pin=None): - self._spi = SPIDevice(spi, chip_select=ss_pin, baudrate=12000000, phase=1) + self._spi = SPIDevice(spi, chip_select=ss_pin, baudrate=12000000, + phase=1) super(PinnacleTouchSPI, self).__init__(dr_pin=dr_pin) def _rap_read(self, reg): diff --git a/circuitpython_cirque_pinnacle/glidepoint_lite.py b/circuitpython_cirque_pinnacle/glidepoint_lite.py index 68f99a1..d023044 100644 --- a/circuitpython_cirque_pinnacle/glidepoint_lite.py +++ b/circuitpython_cirque_pinnacle/glidepoint_lite.py @@ -3,8 +3,11 @@ __version__ = "0.0.0-auto.0" __repo__ = "https://github.com/2bndy5/CircuitPython_Cirque_Pinnacle.git" import time -from adafruit_bus_device.spi_device import SPIDevice -from adafruit_bus_device.i2c_device import I2CDevice +try: + from ubus_device import SPIDevice, I2CDevice +except ImportError: + from adafruit_bus_device.spi_device import SPIDevice + from adafruit_bus_device.i2c_device import I2CDevice RELATIVE = 0x00 ABSOLUTE = 0x02 diff --git a/docs/api.rst b/docs/api.rst index 6617529..eaf801f 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,11 +1,8 @@ .. currentmodule:: circuitpython_cirque_pinnacle -PinnacleTouch API -================== - About the lite version ----------------------- +====================== This library includes a "lite" version of the module ``glidepoint.py`` titled ``glidepoint_lite.py``. The lite version is limited to only Relative and Absolute data modes. It has been developed to @@ -22,6 +19,9 @@ ATSAMD21 M0). The following functionality has been removed from the lite version * ``_era_write_bytes()`` (private member for accessing the Pinnacle ASIC's memory) * all comments and docstrings (meaning ``help()`` will provide no specific information) +PinnacleTouch API +================== + Accepted Constants ------------------ @@ -29,20 +29,20 @@ Data Modes *********** Allowed symbols for configuring the Pinanacle ASIC's data reporting/measurements. -.. data:: circuitpython_cirque_pinnacle.glidepoint.RELATIVE - :annotation: =0 + .. data:: circuitpython_cirque_pinnacle.glidepoint.RELATIVE + :annotation: =0 - Alias symbol for specifying Relative mode (AKA Mouse mode). + Alias symbol for specifying Relative mode (AKA Mouse mode). -.. data:: circuitpython_cirque_pinnacle.glidepoint.ANYMEAS - :annotation: =1 + .. data:: circuitpython_cirque_pinnacle.glidepoint.ANYMEAS + :annotation: =1 - Alias symbol for specifying "AnyMeas" mode (raw ADC measurement) + Alias symbol for specifying "AnyMeas" mode (raw ADC measurement) -.. data:: circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE - :annotation: =2 + .. data:: circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE + :annotation: =2 - Alias symbol for specifying Absolute mode (axis positions) + Alias symbol for specifying Absolute mode (axis positions) AnyMeas mode Gain ****************** @@ -50,21 +50,21 @@ AnyMeas mode Gain Allowed ADC gain configurations of AnyMeas mode. The percentages defined here are approximate values. -.. data:: circuitpython_cirque_pinnacle.glidepoint.GAIN_100 + .. data:: circuitpython_cirque_pinnacle.glidepoint.GAIN_100 - around 100% gain + around 100% gain -.. data:: circuitpython_cirque_pinnacle.glidepoint.GAIN_133 + .. data:: circuitpython_cirque_pinnacle.glidepoint.GAIN_133 - around 133% gain + around 133% gain -.. data:: circuitpython_cirque_pinnacle.glidepoint.GAIN_166 + .. data:: circuitpython_cirque_pinnacle.glidepoint.GAIN_166 - around 166% gain + around 166% gain -.. data:: circuitpython_cirque_pinnacle.glidepoint.GAIN_200 + .. data:: circuitpython_cirque_pinnacle.glidepoint.GAIN_200 - around 200% gain + around 200% gain AnyMeas mode Frequencies @@ -75,37 +75,37 @@ AnyMeas mode Frequencies parameter to `anymeas_mode_config()` specified is less than 500 nanoseconds, then the frequency will be larger than what is described here (& vice versa). -.. data:: circuitpython_cirque_pinnacle.glidepoint.FREQ_0 + .. data:: circuitpython_cirque_pinnacle.glidepoint.FREQ_0 - frequency around 500,000Hz + frequency around 500,000Hz -.. data:: circuitpython_cirque_pinnacle.glidepoint.FREQ_1 + .. data:: circuitpython_cirque_pinnacle.glidepoint.FREQ_1 - frequency around 444,444Hz + frequency around 444,444Hz -.. data:: circuitpython_cirque_pinnacle.glidepoint.FREQ_2 + .. data:: circuitpython_cirque_pinnacle.glidepoint.FREQ_2 - frequency around 400,000Hz + frequency around 400,000Hz -.. data:: circuitpython_cirque_pinnacle.glidepoint.FREQ_3 + .. data:: circuitpython_cirque_pinnacle.glidepoint.FREQ_3 - frequency around 363,636Hz + frequency around 363,636Hz -.. data:: circuitpython_cirque_pinnacle.glidepoint.FREQ_4 + .. data:: circuitpython_cirque_pinnacle.glidepoint.FREQ_4 - frequency around 333,333Hz + frequency around 333,333Hz -.. data:: circuitpython_cirque_pinnacle.glidepoint.FREQ_5 + .. data:: circuitpython_cirque_pinnacle.glidepoint.FREQ_5 - frequency around 307,692Hz + frequency around 307,692Hz -.. data:: circuitpython_cirque_pinnacle.glidepoint.FREQ_6 + .. data:: circuitpython_cirque_pinnacle.glidepoint.FREQ_6 - frequency around 267,000Hz + frequency around 267,000Hz -.. data:: circuitpython_cirque_pinnacle.glidepoint.FREQ_7 + .. data:: circuitpython_cirque_pinnacle.glidepoint.FREQ_7 - frequency around 235,000Hz + frequency around 235,000Hz AnyMeas mode Muxing @@ -117,21 +117,21 @@ AnyMeas mode Muxing .. note:: The sign of the measurements taken in AnyMeas mode is inverted depending on which muxing gate is specified (when specifying an individual gate polarity). -.. data:: circuitpython_cirque_pinnacle.glidepoint.MUX_REF1 + .. data:: circuitpython_cirque_pinnacle.glidepoint.MUX_REF1 - enables a builtin capacitor (~0.5pF). See note in `measure_adc()` + enables a builtin capacitor (~0.5pF). See note in `measure_adc()` -.. data:: circuitpython_cirque_pinnacle.glidepoint.MUX_REF0 + .. data:: circuitpython_cirque_pinnacle.glidepoint.MUX_REF0 - enables a builtin capacitor (~0.25pF). See note in `measure_adc()` + enables a builtin capacitor (~0.25pF). See note in `measure_adc()` -.. data:: circuitpython_cirque_pinnacle.glidepoint.MUX_PNP + .. data:: circuitpython_cirque_pinnacle.glidepoint.MUX_PNP - enable PNP sense line + enable PNP sense line -.. data:: circuitpython_cirque_pinnacle.glidepoint.MUX_NPN + .. data:: circuitpython_cirque_pinnacle.glidepoint.MUX_NPN - enable NPN sense line + enable NPN sense line AnyMeas mode Control @@ -140,13 +140,13 @@ AnyMeas mode Control These constants control the number of measurements performed in `measure_adc()`. The number of measurements can range [0, 63]. -.. data:: circuitpython_cirque_pinnacle.glidepoint.CRTL_REPEAT + .. data:: circuitpython_cirque_pinnacle.glidepoint.CRTL_REPEAT - required for more than 1 measurement + required for more than 1 measurement -.. data:: circuitpython_cirque_pinnacle.glidepoint.CRTL_PWR_IDLE + .. data:: circuitpython_cirque_pinnacle.glidepoint.CRTL_PWR_IDLE - triggers low power mode (sleep) after completing measurements + triggers low power mode (sleep) after completing measurements PinnacleTouch @@ -155,37 +155,37 @@ PinnacleTouch Constructor ************************* -.. autoclass:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch - :no-members: + .. autoclass:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch + :no-members: - :param ~microcontroller.Pin dr_pin: 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 detirmine if the data being reported is new. + :param ~microcontroller.Pin dr_pin: 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 detirmine if the data being reported is new. - .. important:: This parameter must be specified if your application is going to use the - Pinnacle ASIC's :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS` - mode (a rather experimental measuring of raw ADC values). + .. important:: This parameter must be specified if your application is going to use the + Pinnacle ASIC's :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS` + mode (a rather experimental measuring of raw ADC values). data_mode ************************* -.. autoattribute:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.data_mode + .. autoattribute:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.data_mode - Valid input values are :attr:`~circuitpython_cirque_pinnacle.glidepoint.RELATIVE` for - relative/mouse mode, :attr:`~circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE` for - absolute positioning mode, or :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS` - (referred to as "AnyMeas" in specification sheets) mode for reading ADC values. + Valid input values are :attr:`~circuitpython_cirque_pinnacle.glidepoint.RELATIVE` for + relative/mouse mode, :attr:`~circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE` for + absolute positioning mode, or :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS` + (referred to as "AnyMeas" in specification sheets) mode for reading ADC values. - :Returns: + :Returns: - - ``0`` for Relative mode (AKA mouse mode) - - ``1`` for AnyMeas mode (raw ADC measurements) - - ``2`` for Absolute mode (X & Y axis positions) + - ``0`` for Relative mode (AKA mouse mode) + - ``1`` for AnyMeas mode (raw ADC measurements) + - ``2`` for Absolute mode (X & Y axis positions) - .. important:: When switching from :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS` to - :attr:`~circuitpython_cirque_pinnacle.glidepoint.RELATIVE` or - :attr:`~circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE` all configurations are reset, and - must be re-configured by using `absolute_mode_config()` or `relative_mode_config()`. + .. important:: When switching from :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS` to + :attr:`~circuitpython_cirque_pinnacle.glidepoint.RELATIVE` or + :attr:`~circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE` all configurations are reset, and + must be re-configured by using `absolute_mode_config()` or `relative_mode_config()`. Relative or Absolute mode ************************* @@ -193,437 +193,437 @@ Relative or Absolute mode feed_enable ^^^^^^^^^^^^^^^^^^^^^^^ -.. autoattribute:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.feed_enable + .. autoattribute:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.feed_enable - This function only applies to :attr:`~circuitpython_cirque_pinnacle.glidepoint.RELATIVE` - or :attr:`~circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE` mode, otherwise if `data_mode` is set to - :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS`, then this function will do nothing. + This function only applies to :attr:`~circuitpython_cirque_pinnacle.glidepoint.RELATIVE` + or :attr:`~circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE` mode, otherwise if `data_mode` is set to + :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS`, then this function will do nothing. hard_configured ^^^^^^^^^^^^^^^^^^^^^^^ -.. autoattribute:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.hard_configured + .. autoattribute:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.hard_configured - See note about product labeling in `Model Labeling Scheme `_. (read only) + See note about product labeling in `Model Labeling Scheme `_. (read only) - :Returns: - `True` if a 470K ohm resistor is populated at the junction labeled "R4" + :Returns: + `True` if a 470K ohm resistor is populated at the junction labeled "R4" relative_mode_config() ^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.relative_mode_config - - (write only) - - This function only applies to :attr:`~circuitpython_cirque_pinnacle.glidepoint.RELATIVE` - mode, otherwise if `data_mode` is set to - :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS` or - :attr:`~circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE`, then this function does nothing. - - :param bool rotate90: Specifies if the axis data is altered for 90 degree rotation before - reporting it (essentially swaps the axis data). Default is `False`. - :param bool taps: Specifies if all taps should be reported (`True`) or not - (`False`). Default is `True`. This affects ``secondary_tap`` option as well. - :param bool 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 bool glide_extend: A patended feature that allows the user to glide their finger off - the edge of the sensor and continue gesture with the touch event. Default is `True`. - This feature is always disabled if `hard_configured` is `True`. - :param bool 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`. + .. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.relative_mode_config + + (write only) + + This function only applies to :attr:`~circuitpython_cirque_pinnacle.glidepoint.RELATIVE` + mode, otherwise if `data_mode` is set to + :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS` or + :attr:`~circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE`, then this function does nothing. + + :param bool rotate90: Specifies if the axis data is altered for 90 degree rotation before + reporting it (essentially swaps the axis data). Default is `False`. + :param bool taps: Specifies if all taps should be reported (`True`) or not + (`False`). Default is `True`. This affects ``secondary_tap`` option as well. + :param bool 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 bool glide_extend: A patended feature that allows the user to glide their finger off + the edge of the sensor and continue gesture with the touch event. Default is `True`. + This feature is always disabled if `hard_configured` is `True`. + :param bool 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`. absolute_mode_config() ^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.absolute_mode_config + .. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.absolute_mode_config - (write only) + (write only) - This function only applies to :attr:`~circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE` - mode, otherwise if `data_mode` is set to - :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS` or - :attr:`~circuitpython_cirque_pinnacle.glidepoint.RELATIVE`, then this function does nothing. + This function only applies to :attr:`~circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE` + mode, otherwise if `data_mode` is set to + :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS` or + :attr:`~circuitpython_cirque_pinnacle.glidepoint.RELATIVE`, then this function does nothing. - :param int 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 bool invert_x: Specifies if the x-axis data is to be inverted before reporting it. - Default is `False`. - :param bool invert_y: Specifies if the y-axis data is to be inverted before reporting it. - Default is `False`. + :param int 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 bool invert_x: Specifies if the x-axis data is to be inverted before reporting it. + Default is `False`. + :param bool invert_y: Specifies if the y-axis data is to be inverted before reporting it. + Default is `False`. report() ^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.report - - This function only applies to :attr:`~circuitpython_cirque_pinnacle.glidepoint.RELATIVE` - or :attr:`~circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE` mode, otherwise if `data_mode` is set to - :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS`, then this function returns `None` and does nothing. - - :param bool only_new: This parameter can be used to ensure the data reported is only new - data. Otherwise the data returned can be either old data or new data. 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 - detirmine if the data is new. - - :Returns: `None` if the ``only_new`` parameter is set `True` and there is no new data to - report. Otherwise, a `list` or `bytearray` of parameters that describe the (touch or - button) event. The structure is as follows: - - .. list-table:: - :header-rows: 1 - :widths: 1, 5, 5 - - * - Index - - Relative (Mouse) mode - - as a `bytearray` - - Absolute Mode - - as a `list` - * - 0 - - Button Data [1]_ - - one unsigned byte - - Button Data [1]_ - - one unsigned byte - * - 1 - - change in x-axis [2]_ - - -128 |LessEq| X |LessEq| 127 - - x-axis Position - - 128 |LessEq| X |LessEq| 1920 - * - 2 - - change in y-axis [2]_ - - -128 |LessEq| Y |LessEq| 127 - - y-axis Position - - 64 |LessEq| Y |LessEq| 1472 - * - 3 - - change in scroll wheel - - -128 |LessEq| SCROLL |LessEq| 127 [3]_ - - z-axis Magnitude - - .. [1] The returned button data is a byte in which each bit represents a button. - The bit to button order is as follows: - - 0. [LSB] Button 1 (thought of as Left button in Relative/Mouse mode). If ``taps`` - parameter is passed as `True` when calling `relative_mode_config()`, a single - tap will be reflected here. - 1. Button 2 (thought of as Right button in Relative/Mouse mode). If ``taps`` and - ``secondary_tap`` parameters are passed as `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 passed as - `True` when calling `relative_mode_config()`. - 2. Button 3 (thought of as Middle or scroll wheel button in Relative/Mouse mode) - .. [2] The axis data reported in Relative/Mouse mode is in two's - comliment form. Use Python's :py:func:`struct.unpack()` to convert the - data into integer form (see `Simple Test example `_ - for how to use this function). - - The axis data reported in Absolute mode is always positive as the - xy-plane's origin is located to the top-left, unless ``invert_x`` or ``invert_y`` - parameters to `absolute_mode_config()` are manipulated to change the perspective - location of the origin. - .. [3] In Relative/Mouse mode the scroll wheel data is only reported if the - ``intellimouse`` parameter is passed as `True` to `relative_mode_config()`. - Otherwise this is an empty byte as the - returned `bytearray` follows the buffer structure of a mouse HID report (see - `USB Mouse example `_). - .. |LessEq| unicode:: U+2264 + .. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.report + + This function only applies to :attr:`~circuitpython_cirque_pinnacle.glidepoint.RELATIVE` + or :attr:`~circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE` mode, otherwise if `data_mode` is set to + :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS`, then this function returns `None` and does nothing. + + :param bool only_new: This parameter can be used to ensure the data reported is only new + data. Otherwise the data returned can be either old data or new data. 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 + detirmine if the data is new. + + :Returns: `None` if the ``only_new`` parameter is set `True` and there is no new data to + report. Otherwise, a `list` or `bytearray` of parameters that describe the (touch or + button) event. The structure is as follows: + + .. list-table:: + :header-rows: 1 + :widths: 1, 5, 5 + + * - Index + - Relative (Mouse) mode + + as a `bytearray` + - Absolute Mode + + as a `list` + * - 0 + - Button Data [1]_ + + one unsigned byte + - Button Data [1]_ + + one unsigned byte + * - 1 + - change in x-axis [2]_ + + -128 |LessEq| X |LessEq| 127 + - x-axis Position + + 128 |LessEq| X |LessEq| 1920 + * - 2 + - change in y-axis [2]_ + + -128 |LessEq| Y |LessEq| 127 + - y-axis Position + + 64 |LessEq| Y |LessEq| 1472 + * - 3 + - change in scroll wheel + + -128 |LessEq| SCROLL |LessEq| 127 [3]_ + - z-axis Magnitude + + .. [1] The returned button data is a byte in which each bit represents a button. + The bit to button order is as follows: + + 0. [LSB] Button 1 (thought of as Left button in Relative/Mouse mode). If ``taps`` + parameter is passed as `True` when calling `relative_mode_config()`, a single + tap will be reflected here. + 1. Button 2 (thought of as Right button in Relative/Mouse mode). If ``taps`` and + ``secondary_tap`` parameters are passed as `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 passed as + `True` when calling `relative_mode_config()`. + 2. Button 3 (thought of as Middle or scroll wheel button in Relative/Mouse mode) + .. [2] The axis data reported in Relative/Mouse mode is in two's + comliment form. Use Python's :py:func:`struct.unpack()` to convert the + data into integer form (see `Simple Test example `_ + for how to use this function). + + The axis data reported in Absolute mode is always positive as the + xy-plane's origin is located to the top-left, unless ``invert_x`` or ``invert_y`` + parameters to `absolute_mode_config()` are manipulated to change the perspective + location of the origin. + .. [3] In Relative/Mouse mode the scroll wheel data is only reported if the + ``intellimouse`` parameter is passed as `True` to `relative_mode_config()`. + Otherwise this is an empty byte as the + returned `bytearray` follows the buffer structure of a mouse HID report (see + `USB Mouse example `_). + .. |LessEq| unicode:: U+2264 clear_flags() ^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.clear_flags + .. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.clear_flags allow_sleep ^^^^^^^^^^^^^^^^^^^^^^^ -.. autoattribute:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.allow_sleep + .. autoattribute:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.allow_sleep - 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 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). + 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 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). shutdown ^^^^^^^^^^^^^^^^^^^^^^^ -.. autoattribute:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.shutdown + .. autoattribute:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.shutdown - `True` means powered down (AKA standby mode), and `False` means not powered down - (Active, Idle, or Sleep mode). + `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. + .. 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. sample_rate ^^^^^^^^^^^^^^^^^^^^^^^ -.. autoattribute:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.sample_rate + .. autoattribute:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.sample_rate - 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. + 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 function only applies to :attr:`~circuitpython_cirque_pinnacle.glidepoint.RELATIVE` - or :attr:`~circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE` mode, otherwise if `data_mode` is set to - :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS`, then this function will do nothing. + This function only applies to :attr:`~circuitpython_cirque_pinnacle.glidepoint.RELATIVE` + or :attr:`~circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE` mode, otherwise if `data_mode` is set to + :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS`, then this function will do nothing. detect_finger_stylus() ^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.detect_finger_stylus + .. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.detect_finger_stylus - :param bool enable_finger: `True` enables the Pinnacle ASIC's measurements to - detect if the touch event was caused by a finger or 5.25mm stylus. `False` disables - this feature. Default is `True`. - :param bool enable_stylus: `True` enables the Pinnacle ASIC's measurements to - detect if the touch event was caused by a 2mm stylus. `False` disables this - feature. Default is `True`. - :param int sample_rate: See the `sample_rate` attribute as this parameter manipulates that - attribute. + :param bool enable_finger: `True` enables the Pinnacle ASIC's measurements to + detect if the touch event was caused by a finger or 5.25mm stylus. `False` disables + this feature. Default is `True`. + :param bool enable_stylus: `True` enables the Pinnacle ASIC's measurements to + detect if the touch event was caused by a 2mm stylus. `False` disables this + feature. Default is `True`. + :param int 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()` + .. tip:: Consider adjusting the ADC matrix's gain to enhance performance/results using + `set_adc_gain()` calibrate() ^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.calibrate + .. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.calibrate - This function only applies to :attr:`~circuitpython_cirque_pinnacle.glidepoint.RELATIVE` - or :attr:`~circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE` mode, otherwise if `data_mode` is set to - :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS`, then this function will do nothing. + This function only applies to :attr:`~circuitpython_cirque_pinnacle.glidepoint.RELATIVE` + or :attr:`~circuitpython_cirque_pinnacle.glidepoint.ABSOLUTE` mode, otherwise if `data_mode` is set to + :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS`, then this function will do nothing. - :param bool 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. This parameter is required while the rest are optional keyword parameters. - :param bool tap: Enable dynamic tap compensation? Default is `True`. - :param bool track_error: Enable dynamic track error compensation? Default is `True`. - :param bool nerd: Enable dynamic NERD compensation? Default is `True`. This parameter has - something to do with palm detection/compensation. - :param bool background: Enable dynamic background compensation? Default is `True`. + :param bool 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. This parameter is required while the rest are optional keyword parameters. + :param bool tap: Enable dynamic tap compensation? Default is `True`. + :param bool track_error: Enable dynamic track error compensation? Default is `True`. + :param bool nerd: Enable dynamic NERD compensation? Default is `True`. This parameter has + something to do with palm detection/compensation. + :param bool background: Enable dynamic background compensation? Default is `True`. - .. note:: According to the datasheet, calibration of the sensor takes about 100 - milliseconds. This function will block until calibration is complete (if ``run`` is - `True`). It is recommended for typical applications to leave all optional parameters - in their default states. + .. note:: According to the datasheet, calibration of the sensor takes about 100 + milliseconds. This function will block until calibration is complete (if ``run`` is + `True`). It is recommended for typical applications to leave all optional parameters + in their default states. calibration_matrix ^^^^^^^^^^^^^^^^^^^^^^^ -.. autoattribute:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.calibration_matrix + .. autoattribute:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.calibration_matrix - 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`. + 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: + .. 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. + 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. set_adc_gain() ^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.set_adc_gain + .. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.set_adc_gain - (does not apply to AnyMeas mode). (write-only) + (does not apply to AnyMeas mode). (write-only) - :param int sensitivity: This 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. + :param int sensitivity: This 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``. + .. tip:: The official example code from Cirque for a curved overlay uses a value of ``1``. tune_edge_sensitivity() ^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.tune_edge_sensitivity + .. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.tune_edge_sensitivity - This function was ported from Cirque's example code and doesn't seem to have corresponding - documentation. I'm having trouble finding a memory map of the Pinnacle ASIC as this - function directly alters values in the Pinnacle ASIC's memory. USE AT YOUR OWN RISK! + This function was ported from Cirque's example code and doesn't seem to have corresponding + documentation. I'm having trouble finding a memory map of the Pinnacle ASIC as this + function directly alters values in the Pinnacle ASIC's memory. USE AT YOUR OWN RISK! AnyMeas mode ************* anymeas_mode_config() ^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.anymeas_mode_config - - Be sure to set the `data_mode` attribute to - :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS` before calling this function - otherwise it will do nothing. - - :param int gain: Sets the sensitivity of the ADC matrix. Valid values are the constants - defined in `AnyMeas mode Gain`_. Defaults to - :attr:`~circuitpython_cirque_pinnacle.glidepoint.GAIN_200`. - :param int frequency: Sets the frequency of measurements made by the ADC matrix. Valid - values are the constants defined in - `AnyMeas mode Frequencies`_. - Defaults :attr:`~circuitpython_cirque_pinnacle.glidepoint.FREQ_0`. - :param int 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 int 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 - :attr:`~circuitpython_cirque_pinnacle.glidepoint.MUX_PNP`. - :param int 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 int 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 (:attr:`~circuitpython_cirque_pinnacle.glidepoint.CRTL_PWR_IDLE` -- this - is not default) or if repetive measurements is allowed ( - :attr:`~circuitpython_cirque_pinnacle.glidepoint.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 - measuements. - - .. 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. + .. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.anymeas_mode_config + + Be sure to set the `data_mode` attribute to + :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS` before calling this function + otherwise it will do nothing. + + :param int gain: Sets the sensitivity of the ADC matrix. Valid values are the constants + defined in `AnyMeas mode Gain`_. Defaults to + :attr:`~circuitpython_cirque_pinnacle.glidepoint.GAIN_200`. + :param int frequency: Sets the frequency of measurements made by the ADC matrix. Valid + values are the constants defined in + `AnyMeas mode Frequencies`_. + Defaults :attr:`~circuitpython_cirque_pinnacle.glidepoint.FREQ_0`. + :param int 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 int 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 + :attr:`~circuitpython_cirque_pinnacle.glidepoint.MUX_PNP`. + :param int 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 int 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 (:attr:`~circuitpython_cirque_pinnacle.glidepoint.CRTL_PWR_IDLE` -- this + is not default) or if repetive measurements is allowed ( + :attr:`~circuitpython_cirque_pinnacle.glidepoint.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 + measuements. + + .. 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. measure_adc() ^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.measure_adc - - Internally this function calls `start_measure_adc()` and `get_measure_adc()` in sequence. - Be sure to set the `data_mode` attribute to - :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS` before calling this function - otherwise it will do nothing. - - :param int bits_to_toggle: This 4-byte integer specifies which bits the Pinnacle touch - controller should toggle. A bit of ``1`` flags that bit for toggling, and a bit of - ``0`` signifies that the bit should remain unaffected. - :param int toggle_polarity: This 4-byte integer specifies which polarity the specified - bits (from ``bits_to_toggle`` parameter) are toggled. A bit of ``1`` toggles that bit - positve, 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 :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS`, then this function returns - `None` and does nothing. - - :4-byte Integer Format: - .. 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 - - See `AnyMeas mode example `_ to understand how to - use these 4-byte integer polynomials. - - .. note:: Bits 29 and 28 represent the optional implementation of reference capacitors - built into the Pinnacle ASIC. To use these capacitors, the - corresponding constants - (:attr:`~circuitpython_cirque_pinnacle.glidepoint.AnyMeasMux.MUX_REF0` and/or - :attr:`~circuitpython_cirque_pinnacle.glidepoint.AnyMeasMux.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. + .. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.measure_adc + + Internally this function calls `start_measure_adc()` and `get_measure_adc()` in sequence. + Be sure to set the `data_mode` attribute to + :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS` before calling this function + otherwise it will do nothing. + + :param int bits_to_toggle: This 4-byte integer specifies which bits the Pinnacle touch + controller should toggle. A bit of ``1`` flags that bit for toggling, and a bit of + ``0`` signifies that the bit should remain unaffected. + :param int toggle_polarity: This 4-byte integer specifies which polarity the specified + bits (from ``bits_to_toggle`` parameter) are toggled. A bit of ``1`` toggles that bit + positve, 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 :attr:`~circuitpython_cirque_pinnacle.glidepoint.ANYMEAS`, then this function returns + `None` and does nothing. + + :4-byte Integer Format: + .. 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 + + See `AnyMeas mode example `_ to understand how to + use these 4-byte integer polynomials. + + .. note:: Bits 29 and 28 represent the optional implementation of reference capacitors + built into the Pinnacle ASIC. To use these capacitors, the + corresponding constants + (:attr:`~circuitpython_cirque_pinnacle.glidepoint.AnyMeasMux.MUX_REF0` and/or + :attr:`~circuitpython_cirque_pinnacle.glidepoint.AnyMeasMux.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. start_measure_adc() ^^^^^^^^^^^^^^^^^^^^ -.. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.start_measure_adc + .. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.start_measure_adc - See the parameters and table in `measure_adc()` as this is its helper function, and all - parameters there are used the same way here. + See the parameters and table in `measure_adc()` as this is its helper function, and all + parameters there are used the same way here. get_measure_adc() ^^^^^^^^^^^^^^^^^^^^ -.. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.get_measure_adc + .. automethod:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouch.get_measure_adc - This function is only meant ot be used in conjunction with `start_measure_adc()` for - non-blocking application. + This function is only meant ot be used in conjunction with `start_measure_adc()` for + non-blocking application. - :returns: - * `None` if `data_mode` is not set to `ANYMEAS` or if the "data ready" pin's signal is not - active (while `data_mode` is set to `ANYMEAS`) meaing 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()`. + :returns: + * `None` if `data_mode` is not set to `ANYMEAS` or if the "data ready" pin's signal is not + active (while `data_mode` is set to `ANYMEAS`) meaing 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()`. SPI & I2C Interfaces ******************** -.. autoclass:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouchSPI - :members: - :show-inheritance: + .. autoclass:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouchSPI + :members: + :show-inheritance: - :param ~busio.SPI 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 ~microcontroller.Pin ss_pin: The "slave select" pin output to the Pinnacle ASIC. + :param ~busio.SPI 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 ~microcontroller.Pin ss_pin: The "slave select" pin output to the Pinnacle ASIC. - See the base class for other instantiating parameters. + See the base class for other instantiating parameters. -.. autoclass:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouchI2C - :members: - :show-inheritance: + .. autoclass:: circuitpython_cirque_pinnacle.glidepoint.PinnacleTouchI2C + :members: + :show-inheritance: - :param ~busio.I2C 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 int address: The slave I2C address of the Pinnacle ASIC. Defaults to ``0x2A``. + :param ~busio.I2C 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 int address: The slave I2C address of the Pinnacle ASIC. Defaults to ``0x2A``. - See the base class for other instantiating parameters. + See the base class for other instantiating parameters.