Tutorial: Touching the Freedom KL25Z Board

Posted on by

I have covered several aspects of the Freescale KL25Z Freedom board with a tutorial: LED, Accelerometer and RTOS. One peripheral on the board is missing so far: the touch slider area:

Freedom KL25Z Board Touch Slider Area

Freedom KL25Z Board Touch Slider Area

The Kinetis device has implemented a TSS (Touch Sensing Software) in the silicon. It helps a lot to implement a capacitive touch sensing application, but requires a lot of reference manual reading. Luckily there is a Processor Expert driver which simplifies things a lot. So in this tutorial I’m using that Processor Expert component.

Creating the Project

I’m not going into the details to create a Processor Expert project with CodeWarrior for MCU10.3 here. You should be able to find all the needed information in the LED, Accelerometer and RTOS tutorials.

Alternatively, it is possible to add the touch support to any of the above tutorial projects.

Related Tutorials

Adding the TSS_Library Processor Expert Component

From the Components Library view, I add the TSS_Library component to my project, either with the context menu (Add to project), with the ‘+’ icon in that view or simply double clicking on the TSS_Library component:

Adding TSS_Library Processor Expert Component

Adding TSS_Library Processor Expert Component

Where are the Electrodes?

Looking at the board schematics, it shows that there are two electrodes, connected to PTB16/Channel9 and PTB17/Channel10:

FRDM-KL25Z TSI Schematics (Source: Freescale)

FRDM-KL25Z TSI Schematics (Source: Freescale)

Adding the Electrodes

This two electrodes needs to be configured. For this I select the TSS_Library component in my project. In the Component Inspector view define/add two electrodes. For this I press the ‘+’ sign to increase the number of Electrodes to two.

Hint 1: If the Component Inspector view is not visible: use the context menu ‘Inspector’ on the TSS_Library icon.

Hint 2: In order two show the ‘+’ and ‘-‘ sign for the number of electrodes as shown in the screenshot below, I need to click (!) into the field.

Adding Electrodes

Adding Electrodes

With this, I set it up to use two electrodes:

Using two Electrodes

Using two Electrodes

Setting the Controls

The really cool thing with this Processor Expert component is that it provides support for all kind of controls. So I add one slider control, and for now I go with the default settings:

Definition of controls

Definition of controls

Note that this is an *ASLIDER* (Analog Slider) control. I have it configured that it has a range of 0..64, and that the values will be in a structure named TSS1_cKey0. This structure name and value range is what we will use later when the TSS library detects a touch.

Adding LEDs

In my code I want to show the status of the slider on the RGB LED of my board. I do not explain the steps how to add the LEDs to my project, as this is explained in details in the LED tutorial.

Hint: I can copy-paste the LED component from my other tutorial projects. That way it only takes seconds to have it in my new project.

Touch Project with LEDs added

Touch Project with LEDs added

Generating Processor Expert Driver Code

Now I can generate my driver code based on my settings. The simplest way is to select the project and to use the ‘Generate Processor Expert Code’ button:

Generate Processor Expert Code

Generate Processor Expert Code

The generated code is placed into the ‘Generated_Code’ project folder, which now has my TSS driver code based on my settings:

Generated TSS Driver Code with TSS Files

Generated TSS Driver Code with TSS Files

Initializing the TSS Library

I have not initialized the TSS library. For this I need to call the Configure() function. An easy way to call that function is to drag&drop that method into my source code:

Configuring the TSS Library: drag&drop the method

Configuring the TSS Library: drag&drop the method

TSS Library Task Function

The other thing is: I need to periodically call the TSS library with a call to TSS_Task(). So my code in main needs to add this in a loop:

int main(void)
/*lint -restore Enable MISRA rule (6.3) checking. */
{
  /* Write your local variable definition here */

  /*** Processor Expert internal initialization. DON'T REMOVE THIS CODE!!! ***/
  PE_low_level_init();
  /*** End of Processor Expert internal initialization.                    ***/

  Configure(); /* initialize TSS library */
  for(;;) {
    TSS_Task(); /* call TSS library to process touches */
  }
  /*** Don't write any code pass this line, or it will be deleted during code generation. ***/
  /*** RTOS startup code. Macro PEX_RTOS_START is defined by the RTOS component. DON'T MODIFY THIS CODE!!! ***/
  #ifdef PEX_RTOS_START
    PEX_RTOS_START();                  /* Startup of the selected RTOS. Macro is defined by the RTOS component. */
  #endif
  /*** End of RTOS startup code.  ***/
  /*** Processor Expert end of main routine. DON'T MODIFY THIS CODE!!! ***/
  for(;;){}
  /*** Processor Expert end of main routine. DON'T WRITE CODE BELOW!!! ***/
} /*** End of main routine. DO NOT MODIFY THIS TEXT!!! ***/

TSS Library Callback

The function TSS_Task() will detect if the slider has been touched, and will call a callback. This callback is named ‘fcallBack()‘. For my first (and only) control in the system this is TSS1_fCallback0():

TSS Library Callback

TSS Library Callback

Double clicking on that callback event jumps the editor view to the user callback function of it in Events.c:

TSS Event Callback in Events.c

TSS Event Callback in Events.c

Remember the Range and Structure Name we defined in the control? Now it is time to use it here and to turn on a LED depending on the range value. This is implemented with following code:

void TSS1_fCallBack0(TSS_CONTROL_ID u8ControlId)
{
  (void)u8ControlId; /* avoid warning */
  LED1_Put(TSS1_cKey0.Position<=20);
  LED2_Put(TSS1_cKey0.Position>20 && TSS1_cKey0.Position<=40);
  LED3_Put(TSS1_cKey0.Position>40 && TSS1_cKey0.Position<=64);
}

Touching it

The rest is easy: compile, download and run it on the board. With this, LED1 is on if I touch it on the left, LED2 is on if I touch it in the middle, and LED3 is on if I touch it on the right :-).

Touch on the left: red LED on

Touch on the left: red LED on

Touch in the Middle: Green LED on

Touch in the Middle: Green LED on

Touch on the right: blue LED on

Touch on the right: blue LED on

Summary

Using capacitive touch functionality is usually not easy. But the TSS Processor Expert component delivered with the Eclipse based CodeWarrrior for MCU10.3 makes it really easy. For sure there are a lot of things which can be fine tuned (sensitivity, resolution, kind of controls), but I hope this gives an idea what can be implemented. Additionally there is a lot of documentation about the TSS library available here.

The sources of the project discussed in this tutorial are available here.

Happy Touching 🙂

71 thoughts on “Tutorial: Touching the Freedom KL25Z Board”

  3. I observed the the slider response is non-linear : gradual at the lower end, and rapid at the upper end.
    Also, there a chatter at the transition point.
    Does the TSS library have any features to linearise/debounce the slider reading, or do we need a lookup or a math formula to do this ?

    Thank You.

    Like

    Reply ↓

    • the demo is very, very simple. To have a better or smoother response, simply apply your own trigger points. In the example code, I simply test on a numerical threshold value which is not (too) simple.

      Like

      Reply ↓

  4. Pingback: Using the Reset Button on the Freedom Board as User Button | MCU on Eclipse

  5. Hello Erich. Thanks for this post.
    I am testing a custom K60 board, with a Capacitive Touch Keypad. Following your example, in a Processor Expert project, I add a TSS library (TSS1), and inside a KEYPAD control (directed to PTB16 port). This work ok. But when I try to add an additional control with an additional electrode, the MCU doesn’t run the software. Is an additional step that I’m not doing? There is something that I need to configure to work with two or more electrodes? What is the “shielding signal” in a electrode? (I ask that because my keypad have a “shield” pin, but is short to GND, so I don’t connect it).
    Thanks for your attention and your post.
    Kind regards.

    Like

    Reply ↓

  7. Hello Erich,
    fist of all thank you for that great homepage. It helped me a lot to get to know my FRDM-Board ^^
    I am currently working as an intern and have to install the board for a school student coming next week. I have as hardly as no experience with embedded programming.
    I somehow managed it to connect my FRDM-KL05Z with my PC. I was told to use the IAR Workbench for Debugging….so far so good. I found your Tutorial about ProcessorExpert and IAR -> worked very well for me. This Drag/Drop is fantastic!

    But as soon as I try to install the TSS my IAR can’t link the project anymore. I do the steps above (selct the correct ports, generate the code etc.) and establish a connection between the workbench and the processor expert files as you wrote in one of your other tutorials. But every time I try to build the files I get multiple errors on the TSS functions and variables. Is there any possibility to proof weather my PE files are correct or not or do you have any idea what could cause the problem with the tss-libary?
    Tank you in advance 🙂

    Like

    Reply ↓

    • Hello,
      thanks for that positive feedback :-).
      About the TSS library: some parts of the library come with as library, as Freescale does not provide the source files 😦 For my project on GitHub this is libTSS_KXX_M0.a. So it could be that the IAR linker is having a problem with the library, as the one I’m usiing is for gcc (not for IAR). Can you check if it can link that library in your project? I guess this is your problem, or the library you have is not for IAR?

      Like

      Reply ↓

      • Thank you for your quick answer. Indeed there are different .a files for different linker. I added the correct lib-files to my workbench project but didn’t get it to work as well. Maybe I didn’t add it correctly (as I told you I started programming yesterday :D)
        But the shared lib-files are the same for both linkers. Now I have to figure out how to get my linker to the correct file :/
        But thank you for the hint

        Like

        Reply ↓

  8. Hi there, I realy like your site. Content is awesome but I have problem with this guide. TSS1_fCallBack0 is never entered and I don’t know why. Any suggestions?

    Like

    Reply ↓

    • Freesale decided *not* to provide the source code for TSS :-(. So the code for TSS_Task() is inside the library for TSS which is linked to the application. But you cannot debug it on source level as there is no source file availble for it. Which means you cannot port things to another compiler/microcontroller too.

      Like

      Reply ↓

  10. how can I fix this trouble? “Can’t find a source file at “C:\Users\p\workspace\Freedom_Touch\Sources\TSS\libTSS_KXX_M0.a(TSS_Filters.o):TSS_Filters.c” “

    Like

    Reply ↓

  11. Hi Erich,

    Thanks for making these tutorials. I’ve never worked with something like Processor Expert before, and it seems like it is a pretty powerful tool. I’ve read your guide on this page quite thoroughly, and can’t seem to get the TSS library to work properly. I added “..Sources/TSS” to my includes, and for whatever reason it is giving me the following undefined reference errors: TSS_Task, TSS_SetSystemConfig, TSS_SetASliderConfig, TSS_Init.

    I’m using the newest versions of Eclipse Kepler, using the exact syntax that you used in your provided source files, and have had success with your LED blinking tutorials. Any ideas on what could be causing this issue?

    Thanks,
    Dan

    Like

    Reply ↓

  12. Hi,
    Could you please help me?
    I have follow the instruction but there is one problem that i had,
    when i start choosing the Aslider,
    Now it has 2 control which is control0 and control1 btw im using cw10.5
    maybe i should change the input?
    the input1 says that “The same item was already used”
    both value is in “0”

    Like

    Reply ↓

  13. Hello I try to do the same project with Kinetis Design Studio but I do not. Can you help me? thank you
    michael

    Like

    Reply ↓

  14. Hi Erich
    I built your code and ran it on a FRDM-KL25 then (because I want to use the TSS to implement buttons rather than sliders) I edited the TSS PE component so that one of the slider pins is a KEYPAD control type. I modified the TSS1_fCallBack0() in Events.c to flash an LED when the key press is detected:
    LED2_Neg();
    I get transitions of the LED corresponding to exactly 16 key presses, then no more. I added instrumentation to the for(;;) loop and see that this loop continues to run and TSS_Task() is called. A scope shows the touch sensor waveform on the slider electrode. TSS1_fOnFault() is not called. Any ideas?

    When this is sorted I I’d like to add it to a FreeRTOS project. How is that done? It seems necessary to call TSS_Task() frequently. (I put an experimental delay in my for(;;) loop and my button does not behave well).

    Finally, it looks like different stub code gets generated in TSS1_fCallBack0() depending on the type of control selected (ASLIDER, KEYPAD etc) – but the code is not regenerated if you change the control type. I found I had to delete the component and re-add it.

    Like

    Reply ↓

    • I had not much success with the TSS library, because it is delivered in object file format and not in source form. So many things are simply obscure and if something does not work, there is no way to investigate :-(.
      So I simply stopped using the TSS library. Using it with FreeRTOS should be no problem: simply have a task where you call TSS_Task() frequently enough.

      Like

      Reply ↓

  15. Hi Erich,
    Another excellent article from you.
    Is there any document describing what is the algorithm I should be following if I don’t want to use TSS library or processor expert?
    I just want to use TSI module. Right now what I’m doing is after initialization and calibration whatever data I get in TSI_DATA register I consider it as baseline value and then set an arbitrary threshold value greater than the baseline[this i do by trial and error based on the value I’m getting when the electrode is touched]. Then in while loop I continuously scan the electrodes and decide whether touch event is happened or not, by comparing the data value which i recieved now and the threshold value previously set.
    Is this enough? or can you suggest a better algorithm to do this?

    Thanks,

    Like

    Reply ↓

    • I think Freescale decided not to release the sources of their TSS library because either they want to patent it, or they want to keep it secret. For sure they seem to use someting non-trivial.
      I’m not the expert in touch sensing, but your approach sounds feasible (and I used a similar approach in the past). What you need to consider is some kind of ‘rolling calibration’, as the values might change over time (humidity, temperature, etc) or detecting shortcuts (blocked contacts, etc). I have not really researched a lot, but there might be even some open source algorithms out there. But I think for a simple ‘touch or no touch’ things are fairly easy. It gets more complicated with multi-touch or with sliding values/etc.

      Like

      Reply ↓

  16. Pingback: Comparing CodeWarrior with Kinetis Design Studio | MCU on Eclipse

  17. What version of TSS was this post based on? I notice a few different parameters in the default 3.1 – have set to 3.0 and looks very similar.

    I appreciate there is no source for TSS_Task(), but neither can I drag and drop this, nor find it anywhere. Do I just type it in by hand, and it will work – or is there something missing in CW10.6?

    Like

    Reply ↓

    • Answered my own question (partially) – I spotted the version in one of the screen captures, so by setting it manually, I’m duplicating the context of the article.

      I tried just chucking in TSS_Task() to see if it would compile, which it did.

      I am not, however, seeing any events. At what minimum rate should TSS_Task() be sampling?

      Like

      Reply ↓

      • Just type in the name, as you did. There is no documentation to my understanding which tells you how frequently you have to call the TSS_Task(). But I would call it say every 50 ms or 20 ms.
        I have to say that I stopped using the TSS library: it does not work reliable enough for me, and it was not worth the efforts. I have made a few demos/experiments, and they work sometimes good enough, sometimes not. The fact that the code is available in object/library form only and no sources pretty much made it impossible to find out what is going wrong. So I ended up not using it any more. Good luck!

        Like

        Reply ↓

  18. Hi Erich,
    Big thanks to your great job!!!I’ve already tryed KDS and some PE components and it looks great to have such a powerfull instrument.
    I’ve failed to build TSI example. It seems to me that KDS dont want to pick up TSI library. I installed FS TSI library and add it to TSS folder i Sources. But still have all function like TSS_Init, TSS_SetSystemConfig red colored. May be you have some proposals for me.
    BIg thanks,
    Alexey.

    Like

    Reply ↓

      • Wow! Thanks for response.
        It was megafast reply. I had prepared to wait for couple a days 🙂 You must have been a superman!!! I was the happiest man on the planet when my led toggled with that touchsensing:).
        For additional info: It works with the Erick link above. I used k20_frdm board and link to library :
        \Freescale_TSS_3_1\lib\lib_cw_gcc
        and paste in the field Libraries(-l) next string:
        TSS_KXX_M4 (however libfile name is libTSS_KXX_M4.a). Name like libTSS_KXX_M4 or libTSS_KXX_M4.a have not worked. Dont get why-have to learn info about linker.
        Anyway problem is solved. The sun is shining:)
        Virtual champagne to Erick!

        Like

        Reply ↓

  19. I am trying to use TSS library for the twr-k60n512 touchpads in a PE project, when I add the TSS_library component, I end up in a hard fault. I am using basic configuration as in this post. Any pointers?

    Like

    Reply ↓

  20. Points me to 0x6cd, which is at the line “ldr r3, [r5, #0]” in the snippet below.
    cbz r2, 0x6e0
    000006c8: bl 0x674
    000006cc: ldr r3, [r5, #0]
    000006ce: adds r4, #12
    122 __S_romp[index].Source != 0 ||
    000006d0: ldr r1, [r3, r4]
    000006d2: add r3, r4
    000006d4: ldr r0, [r3, #4]

    So the initialization process, copying rom to ram, an autogenerated startup file which works without the TSS library. What is going on?

    Like

    Reply ↓

    • Oh yeah, in build I have this warning: /Project_Settings/Startup_Code/startup.c:43:9: warning: array ‘__S_romp’ assumed to have one element [enabled by default]

      Like

      Reply ↓

      • Thanks. Got it. I needed extern modifier for struct RomInfo which comes from the linker script i believe.
        from “RomInfo __S_romp[] __attribute__((weak));”
        to “extern RomInfo __S_romp[] __attribute__((weak));”

        Like

        Reply ↓

  21. Hi Erich,
    I’m developing a device using kinetis K20 microcontroller where there is a touch sensing keyboard and a LCD 7 inches placed near it. The problem I have is the following: when I turn off and than turn on the device, sometimes it doesn’t read the touched button, its behavior has been changed. I think that the system calibration is different from the before (it’s my idea). Could you help me to solve this problem? Could the LCD be the cause of the problem? Do you know if there is a better moment where initialize the TSS?
    I tried to change the electrode sensibility, but the device reads wrong buttons.

    Many thanks for your support.

    Stefano

    Like

    Reply ↓

    • Hi Stefano,
      Yes, the LCD is very likely the problem: internally of the LCD (depends on the technology) there is a voltage charge pump which can be very noisy. I think this is disturging your electrodes.

      Like

      Reply ↓

  22. Hi Erich, thank you for your blog is very useful.
    I tried to add the TSS_Library on my project and, although I see no obvious problem, I can get the “Number of Controls” and Controls sections. There is a single Electrode defined, but even if I increase the number of electrodes no Control option appears.
    I’m using KDS2.0 and the MCU is a K10. Any advice would be welcome. Thank you.

    Like

    Reply ↓

      • I can’t use KDS3.0 for my project because in this version nanolibc no longer supports c++ exceptions.
        I tried to play with some properties, but hadn’t been able to make controls appear. So I was checking if I had missed something. I’ll try to start a new empty project to see if I can get it working. Thank you.

        Like

        Reply ↓

    • The TSS1_fCallBack0() function gets called from inside the TSS library for touch events, based on the configuration.
      I think you cannot get repeated events if you keep it touched. Only if you change the status. You could implement this outside of the callback?

      Like

      Reply ↓

      • For repetitive events do I need to implement out of callback? I need to create a routine to detect the electrode pressed?

        Like

        Reply ↓

        • Yes, I think so. You should get ‘touch’ and ‘released’ events. So while it is ‘touched’ you can generate additional events outside the TSS library until you receive a ‘released’ event from the TSS library.
          That’s how I would do it.

          Like

  24. Hey Erich!
    Is there a simple way to make the LEDs function as momentary on-off when a touch event happens and then concludes? Been playing with the code and can just not find a way…

    Like

    Reply ↓

  25. Hi Erich! I am usign KDS v3 and KL46Z, I follow your instruction in this post and this other post https://community.nxp.com/thread/330174

    All works fine with the TSS library if I choose KEYPAD as Control Type, but if I choose ASLIDER, the KDS shows me:

    Generator: ERROR: There are errors in the project, please review components configuration. It is not possible to generate code.

    I tried different things without success, Do you know what happen?

    Thanks!

    Like

    Reply ↓

    • No, I don’t know what did cause this. The problem I see is that this TSS library or component seems not to be maintained any more, so there is little help we can expect to have things fixed. I guess the solution would be to create a custom touch library instead?

      Like

      Reply ↓

What do you think?

This site uses Akismet to reduce spam. Learn how your comment data is processed.