maXTouch low-level component

See Quick start guide for the maXTouch component.

This component provides low-level read/write access to the configuration and data registers on a maXTouch device. It has only been tested on mxt143E parts, but it should be easy to add support for other maXTouch devices. This is a common API for all supported architectures in ASF.

The component is not interrupt driven and the maXTouch device has to be polled to see if there are any pending messages, and the mxt_read_message function reads out the messages pending. For reading out only touch events, the mxt_read_touch_event function can be used. As mentioned the component is not interrupt driven, but by configuring a pin change interrupt on the CHG pin, the application can receive interrupts when there are messages pending.

Data Structures
struct	mxt_conf_messageprocessor_t5
	Object message. More...
struct	mxt_device
	maXTouch device information data container struct More...
struct	mxt_gen_commandprocessor_t6
	Commandprocessor T6 object. More...
struct	mxt_info_object
	Identification header. More...
struct	mxt_object
	Object table entry. More...
struct	mxt_report_id_map
	Map of the report ID vs object type and instance. More...
struct	mxt_touch_event
	Touch event struct. More...

Typedefs
typedef void(*	mxt_message_handler_t )(struct mxt_device *device, struct mxt_conf_messageprocessor_t5 *message)
	Message handler prototype. More...

Enumerations
enum	mxt_object_type {   MXT_GEN_MESSAGEPROCESSOR_T5 = 5,   MXT_GEN_COMMANDPROCESSOR_T6 = 6,   MXT_GEN_POWERCONFIG_T7 = 7,   MXT_GEN_ACQUISITIONCONFIG_T8 = 8,   MXT_TOUCH_MULTITOUCHSCREEN_T9 = 9,   MXT_SPT_COMMSCONFIG_T18 = 18,   MXT_SPT_MESSAGECOUNT_T44 = 44,   MXT_PROCG_TOUCHSUPPRESSION_T48 = 48 }
	Object types. More...

Functions
status_code_t	mxt_close_device (struct mxt_device *device)
	Closes the twi connection and frees memory. More...
int8_t	mxt_get_message_count (struct mxt_device *device)
	Get pending message count. More...
uint16_t	mxt_get_object_address (struct mxt_device *device, uint8_t object_id, uint8_t instance)
	Get memory address to object. More...
enum mxt_object_type	mxt_get_object_type (struct mxt_device *device, struct mxt_conf_messageprocessor_t5 *message)
	Get object type from message. More...
status_code_t	mxt_init_device (struct mxt_device *device, twi_master_t interface, uint8_t chip_adr, uint32_t chgpin)
	Initialize maXTouch device connected to TWIx module. More...
bool	mxt_is_message_pending (struct mxt_device *device)
	Report if there is any pending messages in the queue. More...
status_code_t	mxt_load_configuration (struct mxt_device *device, void *configuration_data)
status_code_t	mxt_probe_device (twi_master_t interface, uint8_t chip_adr)
	Probe for a maXTouch connected to a specific TWI line. More...
status_code_t	mxt_process_messages (struct mxt_device *device)
	Process message queue on maXTouch device. More...
status_code_t	mxt_read_config_object (struct mxt_device *device, mxt_memory_adr memory_adr, void *obj_data)
	Read object configuration. More...
status_code_t	mxt_read_config_reg (struct mxt_device *device, mxt_memory_adr memory_adr, uint8_t *value)
	Read object register. More...
status_code_t	mxt_read_message (struct mxt_device *device, struct mxt_conf_messageprocessor_t5 *message)
	Get next message in queue. More...
status_code_t	mxt_read_touch_event (struct mxt_device *device, struct mxt_touch_event *touch_event)
	Read next touch event in queue, skip other events (other events are lost) More...
void	mxt_set_message_handler (struct mxt_device *device, mxt_message_handler_t handler)
	Set message handler. More...
status_code_t	mxt_write_config_object (struct mxt_device *device, mxt_memory_adr memory_adr, void *obj_data)
	Write object configuration. More...
status_code_t	mxt_write_config_reg (struct mxt_device *device, mxt_memory_adr memory_adr, uint8_t value)
	Write object register. More...

COMMSCONFIG T18 object control register bit positions
#define	MXT_COMMSCONFIG_T18_CHG_MODE_bp   2
#define	MXT_COMMSCONFIG_T18_DISMNTR_bp   7

COMMANDPROCESSOR T6 object register offset
#define	MXT_GEN_COMMANDPROCESSOR_RESET   0
#define	MXT_GEN_COMMANDPROCESSOR_BACKUPNV   1
#define	MXT_GEN_COMMANDPROCESSOR_CALIBRATE   2
#define	MXT_GEN_COMMANDPROCESSOR_REPORTALL   3
#define	MXT_GEN_COMMANDPROCESSOR_DIAGNOSTIC   5

Touch event types
#define	MXT_UNGRIP_EVENT   1
#define	MXT_SUPPRESS_EVENT   2
#define	MXT_AMP_EVENT   4
#define	MXT_VECTOR_EVENT   8
#define	MXT_MOVE_EVENT   16
#define	MXT_RELEASE_EVENT   32
#define	MXT_PRESS_EVENT   64
#define	MXT_DETECT_EVENT   128

#define MXT_AMP_EVENT   4

#define MXT_COMMSCONFIG_T18_CHG_MODE_bp   2

#define MXT_COMMSCONFIG_T18_DISMNTR_bp   7

#define MXT_DETECT_EVENT   128

#define MXT_GEN_COMMANDPROCESSOR_BACKUPNV   1

#define MXT_GEN_COMMANDPROCESSOR_CALIBRATE   2

Referenced by mxt_init().

#define MXT_GEN_COMMANDPROCESSOR_DIAGNOSTIC   5

#define MXT_GEN_COMMANDPROCESSOR_REPORTALL   3

#define MXT_GEN_COMMANDPROCESSOR_RESET   0

Referenced by mxt_init().

#define MXT_MOVE_EVENT   16

#define MXT_PRESS_EVENT   64

#define MXT_RELEASE_EVENT   32

#define MXT_SUPPRESS_EVENT   2

#define MXT_UNGRIP_EVENT   1

#define MXT_VECTOR_EVENT   8

typedef void(* mxt_message_handler_t)(struct mxt_device *device, struct mxt_conf_messageprocessor_t5 *message)

Message handler prototype.

Parameters

*device	Pointer to mxt_device struct
*message	Pointer to mxt_message struct

enum mxt_object_type

Object types.

Enumerator
MXT_GEN_MESSAGEPROCESSOR_T5
MXT_GEN_COMMANDPROCESSOR_T6
MXT_GEN_POWERCONFIG_T7
MXT_GEN_ACQUISITIONCONFIG_T8
MXT_TOUCH_MULTITOUCHSCREEN_T9
MXT_SPT_COMMSCONFIG_T18
MXT_SPT_MESSAGECOUNT_T44
MXT_PROCG_TOUCHSUPPRESSION_T48

status_code_t mxt_close_device

(

struct mxt_device *

device

)

Closes the twi connection and frees memory.

Parameters

*device

Pointer to mxt_device instance

Returns

Operation result status code

References mxt_device::info_object, mxt_device::object_list, mxt_device::report_id_map, and STATUS_OK.

int8_t mxt_get_message_count

(

struct mxt_device *

device

)

Get pending message count.

Parameters

*device

Pointer to mxt_device instance

Returns

Number of pending messages in the queue

References twi_package_t::addr, ERR_IO_ERROR, mxt_device::interface, mxt_device::mxt_chip_adr, mxt_get_object_address(), MXT_SPT_MESSAGECOUNT_T44, STATUS_OK, and twi_master_read().

uint16_t mxt_get_object_address	(	struct mxt_device *	device,
		uint8_t	object_id,
		uint8_t	instance
	)

Get memory address to object.

Parameters

*device	Pointer to mxt_device instance
object_id	Object ID
instance	Object instance

Returns

Object memory address on maXTouch device. 0 if object not found

References mxt_device::info_object, mxt_info_object::obj_count, mxt_device::object_list, mxt_object::start_address, and mxt_object::type.

Referenced by mxt_get_message_count(), mxt_init(), and mxt_read_message().

enum mxt_object_type mxt_get_object_type	(	struct mxt_device *	device,
		struct mxt_conf_messageprocessor_t5 *	message
	)

Get object type from message.

Parameters

*device	Pointer to mxt_device instance
*message	Message buffer

Returns

Operation

References mxt_report_id_map::object_type, mxt_device::report_id_map, and mxt_conf_messageprocessor_t5::reportid.

Referenced by mxt_read_touch_event().

status_code_t mxt_init_device	(	struct mxt_device *	device,
		twi_master_t	interface,
		uint8_t	chip_adr,
		uint32_t	chgpin
	)

Initialize maXTouch device connected to TWIx module.

Parameters

*interface	Pointer to TWI register set
*device	Pointer to mxt_device instance
chip_adr	I2C address to maXTouch device
chgpin	IOPORT pin instance attached to the maXTouch device's /CHG pin

Returns

Operation result status code

References mxt_device::chgpin, ERR_BAD_DATA, mxt_device::handler, mxt_device::interface, mxt_device::multitouch_report_offset, mxt_device::mxt_chip_adr, mxt_create_report_id_map(), mxt_get_report_id_offset(), mxt_info_le_to_cpu(), mxt_read_info_block(), MXT_TOUCH_MULTITOUCHSCREEN_T9, mxt_validate_info_block(), status, and STATUS_OK.

Referenced by mxt_init().

bool mxt_is_message_pending

(

struct mxt_device *

device

)

Report if there is any pending messages in the queue.

Parameters

*device

Pointer to mxt_device instance

Returns

Return /CHG pin status

References mxt_device::chgpin, and ioport_get_pin_level().

Referenced by main(), mxt_handler(), mxt_process_messages(), and mxt_read_touch_event().

status_code_t mxt_load_configuration	(	struct mxt_device *	device,
		void *	configuration_data
	)

status_code_t mxt_probe_device	(	twi_master_t	interface,
		uint8_t	chip_adr
	)

Probe for a maXTouch connected to a specific TWI line.

Parameters

interface	Pointer to TWI register set
*chip_adr	I2C address to maXTouch device

Returns

Operation result status code

References twi_package_t::addr, ERR_BAD_ADDRESS, mxt_info_object::family_ID, MXT_FAMILY_143E, MXT_MEM_ADDR, MXT_VARIANT_143E, status, STATUS_OK, twi_master_read(), TWI_SUCCESS, and mxt_info_object::variant_ID.

status_code_t mxt_process_messages

(

struct mxt_device *

device

)

Process message queue on maXTouch device.

Parameters

*device

Pointer to mxt_device instance

Returns

Operation result status code

References ERR_BAD_ADDRESS, mxt_device::handler, mxt_is_message_pending(), mxt_read_message(), status, and STATUS_OK.

status_code_t mxt_read_config_object	(	struct mxt_device *	device,
		mxt_memory_adr	memory_adr,
		void *	obj_data
	)

Read object configuration.

Parameters

*device	Pointer to mxt_device instance
memory_adr	Memory address to the object
*obj_data	Pointer to a large enough memory buffer

Returns

Operation result status code

References twi_package_t::addr, ERR_IO_ERROR, mxt_device::interface, mxt_device::mxt_chip_adr, mxt_get_object_size(), STATUS_OK, and twi_master_read().

status_code_t mxt_read_config_reg	(	struct mxt_device *	device,
		mxt_memory_adr	memory_adr,
		uint8_t *	value
	)

Read object register.

Parameters

*device	Pointer to mxt_device instance
memory_adr	Memory address to the register
*value	Pointer to a 1 byte buffer to store the data in

Returns

Operation result status code

References twi_package_t::addr, ERR_IO_ERROR, mxt_device::interface, mxt_device::mxt_chip_adr, STATUS_OK, and twi_master_read().

status_code_t mxt_read_message	(	struct mxt_device *	device,
		struct mxt_conf_messageprocessor_t5 *	message
	)

Get next message in queue.

Parameters

*device	Pointer to mxt_device instance
*message	Pointer to mxt_message instance

Returns

Operation result status code

References twi_package_t::addr, ERR_IO_ERROR, mxt_device::interface, mxt_device::mxt_chip_adr, MXT_GEN_MESSAGEPROCESSOR_T5, mxt_get_object_address(), MXT_TWI_MSG_SIZE_T5, mxt_validate_message(), STATUS_OK, and twi_master_read().

Referenced by mxt_process_messages(), and mxt_read_touch_event().

status_code_t mxt_read_touch_event	(	struct mxt_device *	device,
		struct mxt_touch_event *	touch_event
	)

Read next touch event in queue, skip other events (other events are lost)

Parameters

*device	Pointer to mxt_device instance
*touch_event	Pointer to mxt_touch_event instance

Returns

Operation result status code

References ERR_BAD_DATA, mxt_touch_event::id, mxt_conf_messageprocessor_t5::message, mxt_device::multitouch_report_offset, mxt_get_object_type(), mxt_is_message_pending(), mxt_read_message(), MXT_TOUCH_MULTITOUCHSCREEN_T9, mxt_conf_messageprocessor_t5::reportid, mxt_touch_event::size, status, mxt_touch_event::status, STATUS_OK, mxt_touch_event::x, and mxt_touch_event::y.

Referenced by mxt_handler().

void mxt_set_message_handler	(	struct mxt_device *	device,
		mxt_message_handler_t	handler
	)

Set message handler.

Parameters

*device	Pointer to mxt_device instance
handler	Message handler function

References mxt_device::handler.

status_code_t mxt_write_config_object	(	struct mxt_device *	device,
		mxt_memory_adr	memory_adr,
		void *	obj_data
	)

Write object configuration.

Parameters

*device	Pointer to mxt_device instance
memory_adr	Memory address to the object
*obj_data	Pointer to memory buffer containing object data

Returns

Operation result status code

References twi_package_t::addr, ERR_IO_ERROR, mxt_device::interface, mxt_device::mxt_chip_adr, mxt_get_object_size(), STATUS_OK, and twi_master_write().

Referenced by mxt_init().

status_code_t mxt_write_config_reg	(	struct mxt_device *	device,
		mxt_memory_adr	memory_adr,
		uint8_t	value
	)

Write object register.

Parameters

*device	Pointer to mxt_device instance
memory_adr	Memory address to register
value	Value to be written to register

Returns

Operation result status code

References twi_package_t::addr, ERR_IO_ERROR, mxt_device::interface, mxt_device::mxt_chip_adr, STATUS_OK, and twi_master_write().

Referenced by mxt_init().