Host Interface Configuration
Oftentimes, the touch microcontroller is just a part of the whole system. It needs to communicate with the host controller, report the touch status, and get 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 an easy migration path between different touch controllers.
Host Interface Configuration
The Host Interface Configuration allows selecting the I2C module and customizing the memory map.
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 newly 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:
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.
The Parameter Table
The Parameter Table displays the enabled parameters, which will be implemented in the memory map.
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. |
