Project

General

Profile

Using the Fiddle

Introduction

The Fiddle is a small ready-made generic gadget providing some basic UI (User Interface) and peripherals.

It features WiFi, MicroSD, a 128x32 I2C OLED display, a 5-way tactile switch (mini-joystick) as well as 2 user buttons and one reset button.
A library is provided to simplify development of applications using this add-on.

This page will present some usage examples for this module.

Using the library

In order to use the fiddle library, it needs to be added to the list of dependencies in dfe.conf:

# Firmware Element Configuration
# ...
deps:
  - fiddle

Initialization

Before anything, we need to initialize the library. Assuming we're using the eloop library (instructions here), we can place this in our init method:

#include <fiddle/fiddle.h>

// Init
void init()
{
    // Initialize Fiddle module
    fiddle_init();
}

Drawing to the display

The display included in the Fiddle is a classic I2C OLED display. Another tutorial explains how to use it: Using an I2C OLED display.

Reading input

Once the library is initialized, we can read user input from it. The fiddle_input_read method (from fiddle/input.h) will return a byte (uint8_t) representing the state of all buttons (5-way tactile switch + buttons):

uint8_t fiddle_input_raw()
Returns a byte (uint8_t) representing the immediate state of all buttons

However, this only provides "raw" information. While it may be useful in certain cases, most applications will want "clean" output:

uint8_t fiddle_input_clean()
Returns a byte (uint8_t) representing the de-bounced state of all buttons

Even better, a function is provided to provide clean input with decent key rates when called repeatedly from your main loop:

uint8_t fiddle_input_update()
Returns a byte (uint8_t) representing the immediate state of all buttons

Macros are also provided to check the bits of the return value:
  • FIDDLE_INPUT_UP(i) -> Joystick up
  • FIDDLE_INPUT_DOWN(i) -> Joystick down
  • FIDDLE_INPUT_LEFT(i) -> Joystick left
  • FIDDLE_INPUT_RIGHT(i) -> Joystick right
  • FIDDLE_INPUT_CENTER(i) -> Joystick center (press down)
  • FIDDLE_INPUT_BTN1(i) -> Button 1
  • FIDDLE_INPUT_BTN2(i) -> Button 2

This means we can check the state of each button as follows (for simplicity, we're using the eloop library):

#include <fiddle/fiddle.h>
#include <fiddle/input.h>
#include <ssd1306/ssd1306.h>
#include <ssd1306/fb.h>
#include <ssd1306/txt.h>

// Init
void init()
{
    // Initialize Fiddle
    fiddle_init();
}

// Loop
void loop()
{
    uint8_t i;

    // Clear display
    ssd1306_fb_clear();

    // Update Inpput Layer
    i = fiddle_input_update();

    // Display some info
    if(FIDDLE_INPUT_UP(i))      { ssd1306_txt("UP pressed!", 0, 0); }
    if(FIDDLE_INPUT_DOWN(i))    { ssd1306_txt("DOWN pressed!", 0, 0); }
    if(FIDDLE_INPUT_LEFT(i))    { ssd1306_txt("LEFT pressed!", 0, 0); }
    if(FIDDLE_INPUT_RIGHT(i))   { ssd1306_txt("RIGHT pressed!", 0, 0); }

    // Update display
    ssd1306_draw();
}

Simplified UI API

The Fiddle library provides a UI abstraction layer. This is just a header file that can be included into a project to provide some syntactic sugar.

If the Fiddle is the main UI for your project, using the ui.h header is recommended.
This will help keep your code simple to read and understand.

Rewriting the previous example using this abstraction layer looks like the following:

#include <fiddle/fiddle.h>
#include <fiddle/ui.h>

// Init
void init()
{
    // Initialize Fiddle
    fiddle_init();
}

// Loop
void loop()
{
    uint8_t i;

    // Clear display
    clear_display();

    // Read Input
    i = input_update();

    // Display some info
    if(is_down_pressed(i))      { draw_text("UP pressed!", 0, 0); }
    if(is_up_pressed(i))        { draw_text("DOWN pressed!", 0, 0); }
    if(is_left_pressed(i))      { draw_text("LEFT pressed!", 0, 0); }
    if(is_right_pressed(i))     { draw_text("RIGHT pressed!", 0, 0); }

    // Update display
    update_display();
}

Available abstractions

The complete list of abstractions is available in the header file fiddle/ui.h.