My fancy, event-based keypad reader library PushME is on my website for a while and its time to add FreeRTOS support now. Since reading multiple buttons and keeping track of events like long-press or repetitive-press is a critical task for many embedded projects, the FreeRTOS version will help you on medium to large scale FreeRTOS projects. Let’s get hands dirty ?

Design with FreeRTOS

Experts know that in FreeRTOS there is no unique way to implement your code architecture but many options are available. Preferences between different methods like using mutex or binary-semaphore is up to your requirements and trade-offs. So I created a single task out of keypadRead() function of original library. This task sleeps for a while every time using vTaskDelay(), so there is no problem giving high task priority. It could also be a software timer depending on the task priority of the timer service.

The most straightforward replacement for long-press and debounce timeouts is of course FreeRTOS timer. But unfortunately those timers can’t be configured for being checked for timeout but they have their own obligatory callback. Since we need a timer that can be polled for expiration, this callback has to be a dummy place holder function keypadDummyTimerCallback(). We will create one-shot timers using xTimerCreate() and poll them using xTimerIsTimerActive(). This seems the only way for replacing the timeout functionality of the original library with FreeRTOS timer. Switching between different delays is done by a call to xTimerChangePeriod() is followed by xTimerReset(). Here task can be preempted between two calls by higher priority tasks but fortunately large tolerances is acceptable for those timers.

Finally, the keypadRead() task can monitor the buttons and keys with success. Next thing to do is the communication between this task and the clients.

There are many options for talking to clients. The most user-friendly option is implementing a subscribing mechanism such that every client could subscribe its desired key combinations and PushME could unblock them using binary-semaphore by xSemaphoreGive() on match. However it is the bulkiest way of doing this.

Another option is using 1-dimensional queue and posting the results with xQueueOverwrite(). This option is cool for the library side but the client has to poll the last event with xQueueReceive() for a match. If there are multiple listeners everybody should peek the queue by xQueuePeek() instead of emptying the queue. But waking up (unblocking) all the clients on every cycle of the library is not so efficient.

The last but the best option is event-group since this method provides wake-on-match functionality. To be more specific, every client can block on a specific key combination using xEventGroupWaitBits() which is the most efficient way for our case. Although this option does what we need, it has two problems. First problem is on the library side. It has no method for overwriting/setting the value at once. First we need to clear old value using xEventGroupClearBits() then set the new value using xEventGroupSetBits(). Another problem is that the client does not have the option to check/compare the whole event-group value with the expected but can only check for 1 bits. What I try to say is, a client waiting for 0x06 will also unblock for 0x07 by-design. Due to the drawbacks of event-group, I additionally provide queue option to the user.

The Library Code

Here is the library code.

And header file follows.

Usage Example

Now let’s see the usage. Please check the following example.

Download

This is an ongoing work and I want to make a united library code that can be used with both FreeRTOS and Porty/Punctual (That’s why the current version is on a different branch). You can get the whole project here that can be run on STM32-VLDiscovery board out-of-the-box. Have good time using it ?

 

Tags: button reader, freertos, freertos button, keypad for freertos, keypad library, keypad reader, pushme, rtos, stm32