Host Interface Configuration

Host Interface Overview

Often times, the touch microcontroller is just a part of the whole system. It needs to communicate with the host controller, reporting the touch status, and getting commands from the host. The current host interface implementation uses the I2C interface as the underlying physical layer to communicate with the host controller. As shown below, the host interface uses the mTouch® API to access the touch information and parameters, and it then stores this information in a virtual memory map. The I2C driver will then access this memory map upon request from the host controller. This feature provides easy access to the host system and easy migration path between different touch controllers.

hostinterface-overview.png

Host Interface Configuration

The Host Interface Configuration allows selecting the I2C module and customizing the memory map.

hostInterfaceConfiguration.png

Enable I2C Interface to the host:

This enables the host interface feature of the library, otherwise, it will not create any code for that purpose.

Device address and Address Mask:

These are the I2C module properties that display in the configuration for read-only purposes. You can edit these in the underlying I2C module or MSSP module that implements the I2C slave.

MSSP/I2C module:

For the device that has more than one MSSP/I2C module, you can select the module that is used by the mTouch library host interface feature. When you select the module, the previous module will be unloaded and the new selected module will be loaded into MPLAB® Code Configurator (MCC) automatically.

Add New Parameter:

The parameters are predefined, and you have the choice of enabling or disabling parameters for a project. Clicking the Add New Parameter button will add a previously disabled parameter to the enabled list. By default, the system will add the disabled parameter with the lowest address. To replace an existing parameter, you can click on the parameter's name to expand a dropdown list with all the disabled parameters, and then select the desired parameter to enable, as shown below:

hostInterfaceAddParameters.png

Delete Selected Parameter:

If you no longer desire to implement a parameter in the memory map, it may be deleted by selecting the unwanted parameter in the table (this will highlight the parameter row), and then clicking the Delete Selected Parameter button.

Parameter Table:

The Parameter Table displays the enabled parameters, which will be implemented in the memory map.

hostInterfaceParameterTable.png

Address:

Parameter address in the memory map. This can be changed to any address from 0x00 to 0xFF, just make sure that it doesn't overlap with other parameters.

Parameter:

Description of the parameter.

Read/Write:

Whether the parameter is read-only or writable. In general, status and data are read-only, and touch configuration is writable.

Block Byte Count:

The parameters have different byte counts based on their properties and the project configuration. For example, the Touch State parameter is a bit-field, which can represent eight buttons/proximity sensors in one byte, if there are 16 buttons in a project, then the block byte count will be two for Touch State, the first byte for the first eight buttons, and the second for the rest.

Host Interface Parameter Reference List

Parameter Default Start Address Description
Touch Reset 0x00 Writing "1" to this memory location will request a re-initialization of mTouch (not the whole controller). Be aware that it does not immediately call the MTOUCH_Initialize() function. Instead, it sets a flag internally to request the reset at the beginning of the next round of the scan. Reading from this location will return the request flag. If it is cleared, then it means the mTouch has executed the re-initialization, otherwise, the request is still pending.
Touch State 0x01 Read-only parameter, returning the button/proximity sensor state (0 for release and 1 for touch). Each button/proximity sensor uses 1 bit in the byte. When both proximity and button are enabled, the proximity state is listed first in the byte. For example, if there are two proximity sensors and six buttons in the project, then bit 0 and bit 1 will correspond to the states of proximity sensor 0 and proximity sensor 1, and bits 2-7 will corresponds to the states of buttons 0-5, respectively. The parameter will extend to more bytes if there are more than eight buttons and proximity sensors in one project.
Touch Deviation 0x10 Read-only parameter, returning the button/proximity deviation value. This is a block of bytes and the byte count depends on the number of buttons and proximity sensors. If both proximity sensors and buttons are enabled in the project, then the proximity sensor deviations will reside in lower addresses than the buttons'. For example, if the starting address is 0x10 and there is one proximity sensor and two buttons, then the deviation of the proximity sensor will be at 0x10, and button 0 and button 1 will be at 0x11 and 0x12, respectively.
Touch Threshold 0x30 Reading from this memory location will return the button/proximity deviation threshold. Writing to this location will set a new threshold for this button/proximity sensor. This is a block of bytes and the byte count depends on the number of buttons and proximity sensors. If both proximity sensors and buttons are created in the project, then the proximity sensor deviation thresholds will reside in lower addresses than the buttons'.
Touch Deviation Scaling 0x50 Reading from this memory location will return the button/proximity deviation scaling factor. Writing to this location will set a new scaling factor for this button/proximity sensor. This is a block of bytes and the byte count depends on the number of buttons and proximity sensors. If both proximity sensors and buttons are created in the project, then the proximity sensor deviation scaling factors will reside in lower addresses than the buttons'.
Slider Status 0x80 Read-only parameter, returning the slider status, including touch state, reburst state and position status. If there are multiple sliders created in the project, their statuses will be located sequentially from the starting address. The value is the return value of MTOUCH_Slider_Status_Get(). More details on the returned value can be found on the "mTouch® Capacitive Sensing Library Module API" page.
Slider Position 0x90 Read-only parameter, returning the slider/wheel value. The position is a 16-bit value, with the lower byte in the lower address. If there are multiple sliders/wheels created in the project, their values will be located sequentially from the starting address.
Surface Status 0xA0 Read-only parameter, returning the surface status, including touch state, reburst state and position status. Depending on whether the surface implementation uses one or two-finger detection, this can be a 1-byte or 2-byte parameter. If it uses one-finger detection then it has 1 byte, which is returned from MTOUCH_Surface_Status_Get(void). If it uses two-finger detection, then it has 2 bytes. The first byte is returned from MTOUCH_Surface_Contact_Status_Get(0) to the starting address, and the second byte is returned from MTOUCH_Surface_Contact_Status_Get(1) to the following address. More details on the returned value can be found on the "mTouch® Capacitive Sensing Library Module API" page.
Surface Horizontal Position 1 0xA1 Read-only parameter, returning the first finger horizontal touch position. The position is a 16-bit value, with the lower byte in lower address.
Surface Vertical Position 1 0xA3 Read-only parameter, returning the first finger vertical touch position. The position is a 16-bit value, with the lower byte in lower address.
Surface Horizontal Position 2 0xA5 Read-only parameter, returning the second finger horizontal touch position. The position is a 16-bit value, with the lower byte in lower address. This is only available for two-finger detection implementation.
Surface Vertical Position 2 0xA7 Read-only parameter, returning the second finger vertical touch position. The position is a 16-bit value, with the lower byte in lower address. This is only available for two-finger detection implementation.
Surface Gesture State 0xB0 Read-only parameter, returning 1 if there is a new gesture detected, otherwise returning 0.
Surface Gesture ID 0xB1 Read-only parameter, returning the detected gesture ID. All the gesture IDs can be found in the mtouch_gesture.h file. After reading the gesture ID, the surface gesture state will be auto-cleared.
Surface Gesture Value 0xB2 Read-only parameter, returning the additional information for wheel and pinch-zoom gesture. For wheel gesture, it returns a wheel counter that counts the rotations. For pinch-zoom, it returns the distance that the fingers have moved toward or away from each other.
Custom Field 0xF0 This is a hook for implementing user-defined data or action and can be extended to more locations after the starting address. Once the device receives the memory address that is equal or greater than this starting address, it will call the default read or write handler function, and these handler functions can be set by the user using MTOUCH_Memory_i2cSetCustomAddrReadHandler() and MTOUCH_Memory_i2cSetCustomAddrWriteHandler(). For more details, please see the "Host Interface Module" section on the "mTouch® Capacitive Sensing Library Module API" page.
© 2020 Microchip Technology, Inc.
Notice: ARM and Cortex are the registered trademarks of ARM Limited in the EU and other countries.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.