AN14184: Using SmartDMA for Keyscan on MCX N Series MCU

1 Introduction

This application note introduces the keyscan solution for MCX N Series MCUs, covering its introduction, features, API examples, and a demonstration. All MCX N Series MCUs include a SmartDMA coprocessor, which effectively offloads the Arm core and enables high-speed I/O operations.

2 Target Application

As the name suggests, the keyscan solution is commonly used for keypad scanning applications, such as computer keyboards. However, it can also be used in other scenarios requiring continuous scanning of I/O port inputs.

3 Keyscan Interface

The keyscan solution does not have a fixed interface. It can be used for matrix scanning or row/column scanning. The number of scanned keys can be one, or from one to two hundred.

A common computer keyboard typically has 101, 104, or 87 keys. A small keypad might use a 4x4 layout, totaling 16 keys. It can also be used for irregular key matrices. In essence, the button layout and number of buttons are customizable.

This application note uses a 4x4 matrix keypad. However, due to incomplete interface compatibility, it only supports an 8-key configuration in a 2x4 layout. To achieve a 16-key configuration, hardware modifications with jumper wires are necessary.

4 Keyscan Solution Features

• 4x4 Keyscan
• Ultra-fast keyscan, without Arm core intervention (>= 8kHz reporting rate)
• Programmable debouncing time
• Easy support for 8x16 layout and other sizes
• Easy portability to other platforms

5 Function Description

This section describes the functionality of the keyscan solution.

5.1 Keyscan Engine

SmartDMA, as a coprocessor for MCX N Series MCUs, offers high instruction execution efficiency. It can complete keyscan operations quickly and efficiently. During the scanning process of button operations, the Arm core is not required. An interrupt is sent to the Arm core only when a key value changes. The Arm core then only needs to read the key value from RAM.

5.2 Keyscan Driver Library

SmartDMA instructions use machine code. These codes implement the keyscan solution's functionality and are provided as C arrays. This application includes some API examples. These API examples can be used to initialize the engine, configure pins, and start or stop keyscan.

5.3 System Clock

The keyscan engine shares the system clock with the Arm core. Lowering the system clock frequency will reduce the speed at which SmartDMA executes code.

5.4 Memory Usage

SmartDMA code must be loaded and executed at a fixed memory address, which is 0x04000000 in this application. Changing the instruction execution location requires regenerating the instruction code array.

5.5 Hardware Description

Connect the PmodKYPD board to the FRDM-MCXN947 board as shown in Figure 1.

Figure 1: Demonstration Hardware. This figure shows the PmodKYPD 16-button keypad and the FRDM-MCXN947 development board connected via a Pmod interface. The PmodKYPD features a 4x4 matrix keypad. The FRDM-MCXN947 is an evaluation board for the MCX N series MCUs.

Note: The PmodKYPD board can be purchased from: https://store.digilentinc.com/pmod-kypd-16-button-keypad. Figure 2 shows the schematic of the PmodKYPD.

5.6 Pin Description

Figure 4 illustrates how to connect the PmodKYPD board and the FRDM-MCXN947 board.

Figure 4: Hardware Connection. This diagram shows the PmodKYPD keypad connected to the MCXN947 microcontroller. The keypad's rows (ROW1-ROW4) are connected to specific pins (P3_2, P3_3, P5_6, P0_20) on the MCXN947, and its columns (COL1-COL4) are connected to other pins (P0_17, P0_18, P0_16, P0_19) via pull-up resistors.

5.7 Keyscan Timing

When a key is not pressed, SmartDMA continuously outputs waveforms on each column. However, when a key is pressed, the waveform of its row matches the waveform of its column, allowing the identification of the pressed key.

6 Software Description

This section introduces the SmartDMA keyscan example and its functionality.

6.1 Demonstration Example Description

The demonstration code in this example is generated as a standalone "Hello World" project using a configuration tool. This project adds I/O initialization code and SmartDMA driver code.

6.2 SmartDMA Function Array

The SmartDMA keyscan API is located in the fsl_smartdma_mcxn.h file. It defines an enumeration for API indices, including kSMARTDMA_Keyscan_4x4 for using SmartDMA to control GPIO for keyscan.

6.3 SmartDMA Initialization

The fsl_smartdma_mcxn.c file contains an array named s_smartdmaKeyscanFirmware, which implements the SmartDMA keyscan functions. Encapsulating the SmartDMA functions into an array reduces the user's research cost for SmartDMA and allows users to directly use the implemented module functions, thereby speeding up application development.

The following functions implement SmartDMA initialization:

6.3.1 Initialize SmartDMA

To enable SmartDMA, perform the following steps:

• Clear the SmartDMA reset signal.
• Enable the SmartDMA clock.
• Enable the SmartDMA IRQ.

6.3.2 Install SmartDMA Firmware

The SmartDMA function module must be placed at a fixed memory address to work correctly. In this application, it must be placed at 0x04000000.

Example code snippets:

/*! @brief The firmware used for keyscan. */
extern const uint8_t s_smartdmaKeyscanFirmware[];
/*! @brief The s_smartdmaKeyscanFirmware firmware memory address. */
#define SMARTDMA_KEYSCAN_MEM_ADDR 0x04000000U
/*! @brief Size of s_smartdmacameraFirmware */
#define SMARTDMA_KEYSCAN_FIRMWARE_SIZE (s_smartdmaKeyscanFirmwareSize)

The process of installing SmartDMA firmware essentially copies the code array of the SmartDMA function module to a specified RAM address. The code snippet is as follows:

SMARTDMA_InitWithoutFirmware();
SMARTDMA_InstallFirmware(SMARTDMA_KEYSCAN_MEM_ADDR, s_smartdmaKeyscanFirmware, SMARTDMA_KEYSCAN_FIRMWARE_SIZE);

6.3.3 SmartDMA Callback Routine

SmartDMA can actively trigger an interrupt on the Arm core, for example, after data transfer is complete. SmartDMA has a corresponding interrupt number (SMARTDMA_IRQHandler) in the Arm vector table. A callback function can be installed during the SmartDMA configuration phase.

Example code snippet:

SMARTDMA_InstallCallback(SmartDMA_keyscan_callback, NULL);

In the callback function, the Arm core can read the pressed key value and log it.

6.3.4 Start SmartDMA API

In the application, define a structure to set parameters related to SmartDMA. These parameters include the address of the data buffer, the length of data transfer, and the address of the SmartDMA protocol stack space. Most importantly, find an API that must execute the SmartDMA function block code.

Example code snippet:

smartdmaParam.smartdma_stack = (uint32_t*)g_samrtdma_stack;
smartdmaParam.p_gpio_reg = (uint32_t*)g_keyscan_gpio_register;
smartdmaParam.p_keyvalue = (uint32_t*)KeyValue;
smartdmaParam.p_keycan_interval = (uint32_t*)&g_keyscan_interval;
SMARTDMA_Boot(kSMARTDMA_Keyscan_4x4, &smartdmaParam, 0x2);

The startup process involves assigning the address of the corresponding API to the SmartDMA program counter and then starting the function block execution.

7 Download and Run Demonstration on FRDM-MCXN947

This section describes how to prepare and run the demonstration on the FRDM-MCXN947 board.

7.1 Prepare Demonstration

1. Connect a USB Type-C to micro-USB cable between the PC host and the USB port on the development board.
2. Open a serial terminal on the PC for the serial device and configure it with the following settings:
   • Baud rate: 115200
   • Data bits: 8
   • Parity: None
   • Stop bits: 1
   • Flow control: None
3. Download the program to the target board.
4. Press the reset button on the board or start debugging in the Integrated Development Environment (IDE) to run the demonstration.

7.2 Run Demonstration

1. When the demonstration program executes, the serial terminal will display the following lines:

   SmartDMA keyscan example

2. Press a button on the PmodKYPD. The serial terminal will display lines similar to these:

   Button 2 is pressed
   Button 1 is pressed
   Button B is pressed
   Button 6 is pressed
   Button 5 is pressed

8 Download and Run Demonstration on FRDM-MCXN236

This section describes how to prepare and run the demonstration on the FRDM-MCXN236 board.

8.1 Prepare Demonstration

1. Connect a USB Type-C to micro-USB cable between the PC host and the USB port on the development board.
2. Open a serial terminal on the PC for the serial device and configure it with the following settings:
   • Baud rate: 115200
   • Data bits: 8
   • Parity: None
   • Stop bits: 1
   • Flow control: None
3. Download the program to the target board.
4. Press the reset button on the board or start debugging in the Integrated Development Environment (IDE) to run the demonstration.

8.2 Run Demonstration

1. When the demonstration program executes, the serial terminal will display the following lines:

   SmartDMA keyscan example

2. Press a button on the PmodKYPD. The serial terminal will display lines similar to these:

   Button 2 is pressed
   Button 1 is pressed
   Button B is pressed
   Button 6 is pressed
   Button 5 is pressed

9 Description of Source Code in This Document

The example code shown in this document is provided under the following copyright and BSD-3-Clause license:

Copyright © 2024 NXP Semiconductors. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

10 Revision History

Table 2 summarizes the revisions of this document.

Legal Information

Definitions

Draft: A draft status on a document indicates that the content is still under internal review and subject to formal approval, which may result in modifications or additions. NXP Semiconductors does not give any representations or warranties as to the accuracy or completeness of information included in a draft version of a document and shall have no liability for the consequences of use of such information.

Disclaimers:

Limited warranty and liability: Information in this document is believed to be accurate and reliable. However, NXP Semiconductors does not give any representations or warranties, expressed or implied, as to the accuracy or completeness of such information and shall have no liability for the consequences of use of such information. NXP Semiconductors takes no responsibility for the content in this document if provided by an information source outside of NXP Semiconductors. In no event shall NXP Semiconductors be liable for any indirect, incidental, punitive, special or consequential damages (including - without limitation - lost profits, lost savings, business interruption, costs related to the removal or replacement of any products or rework charges) whether or not such damages are based on tort (including negligence), warranty, breach of contract or any other legal theory. Notwithstanding any damages that customer might incur for any reason whatsoever, NXP Semiconductors' aggregate and cumulative liability towards customer for the products described herein shall be limited in accordance with the Terms and conditions of commercial sale of NXP Semiconductors.

Right to make changes: NXP Semiconductors reserves the right to make changes to information published in this document, including without limitation specifications and product descriptions, at any time and without notice. This document supersedes and replaces all information supplied prior to the publication hereof.

Suitability for use: NXP Semiconductors products are not designed, authorized or warranted to be suitable for use in life support, life-critical or safety-critical systems or equipment, nor in applications where failure or malfunction of an NXP Semiconductors product can reasonably be expected to result in personal injury, death or severe property or environmental damage. NXP Semiconductors and its suppliers accept no liability for inclusion and/or use of NXP Semiconductors products in such equipment or applications and therefore such inclusion and/or use is at the customer's own risk.

Applications: Applications that are described herein for any of these products are for illustrative purposes only. NXP Semiconductors makes no representation or warranty that such applications will be suitable for the specified use without further testing or modification. Customers are responsible for the design and operation of their applications and products using NXP Semiconductors products, and NXP Semiconductors accepts no liability for any assistance with applications or customer product design. It is customer's sole responsibility to determine whether the NXP Semiconductors product is suitable and fit for the customer's applications and products planned, as well as for the planned application and use of customer's third party customer(s). Customers should provide appropriate design and operating safeguards to minimize the risks associated with their applications and products. NXP Semiconductors does not accept any liability related to any default, damage, costs or problem which is based on any weakness or default in the customer's applications or products, or the application or use by customer's third party customer(s). Customer is responsible for doing all necessary testing for the customer's applications and products using NXP Semiconductors products in order to avoid a default of the applications and the products or of the application or use by customer's third party customer(s). NXP does not accept any liability in this respect.

Terms and conditions of commercial sale: NXP Semiconductors products are sold subject to the general terms and conditions of commercial sale, as published at https://www.nxp.com.cn/profile/terms, unless otherwise agreed in a valid written individual agreement. In case an individual agreement is concluded only the terms and conditions of the respective agreement shall apply. NXP Semiconductors hereby expressly objects to applying the customer's general terms and conditions with regard to the purchase of NXP Semiconductors products by customer.

Export control: This document as well as the item(s) described herein may be subject to export control regulations. Export might require a prior authorization from competent authorities.

Suitability for use in non-automotive qualified products: Unless this document expressly states that this specific NXP Semiconductors product is automotive qualified, the product is not suitable for automotive use. It is neither qualified nor tested in accordance with automotive testing or application requirements. NXP Semiconductors accepts no liability for inclusion and/or use of non-automotive qualified products in automotive equipment or applications. In the event that customer uses the product for design-in and use in automotive applications to automotive specifications and standards, customer (a) shall use the product without NXP Semiconductors' warranty of the product for such automotive applications, use and specifications, and (b) whenever customer uses the product for automotive applications beyond NXP Semiconductors' specifications such use shall be solely at customer's own risk, and (c) customer fully indemnifies NXP Semiconductors for any liability, damages or failed product claims resulting from customer design and use of the product for automotive applications beyond NXP Semiconductors' standard warranty and NXP Semiconductors' product specifications.

Translations: A non-English (translated) version of a document, including the legal information in that document, is for reference only. The English version shall prevail in case of any discrepancy between the translated and English versions.

Security: Customer understands that all NXP products may be subject to unidentified vulnerabilities or may support established security standards or specifications with known limitations. Customer is responsible for the design and operation of its applications and products throughout their lifecycles to reduce the effect of these vulnerabilities on customer's applications and products. Customer's responsibility also extends to other open and/or proprietary technologies supported by NXP products for use in customer's applications. NXP accepts no liability for any vulnerability. Customer should regularly check security updates from NXP and follow up appropriately. Customer shall select products with security features that best meet rules, regulations, and standards of the intended application and make the ultimate design decisions regarding its products and is solely responsible for compliance with all legal, regulatory, and security related requirements concerning its products, regardless of any information or support that may be provided by NXP. NXP has a Product Security Incident Response Team (PSIRT) (reachable at PSIRT@nxp.com) that manages the investigation, reporting, and solution release to security vulnerabilities of NXP products.

NXP B.V.: NXP B.V. is not an operating company and it does not distribute or sell products.

Trademarks: Notice: All referenced brands, product names, service names, and trademarks are the property of their respective owners. NXP - wordmark and logo are trademarks of NXP B.V.