User IO

BitMasher has eight buttons that the user can press to interact with the device: a D-Pad (up, down, left, right), A, B, Menu and Shift buttons.

Button States and Voltages

The buttons are directly connected to the MCU's GPIO pins and are active low. This means that the MCU pin will read 2.5 V when a button is not pressed and 0 V when it is pressed:

Pin Voltage Levels for Button Interactions

Querying Button States

BM_UserIOServices contains functions that query the states of the buttons. There are however two types of states that can be read from the button: current state and edge state.

Current State

BM_UserIO_getButtonState reads the state of a single button at any given time. Alternatively, the state of all buttons can be read using BM_UserIO_getAllButtonStates which expects a pointer to a uint32_t variable, buttonStates in its parameter. The states of all of the buttons are packed into buttonStates - that is, each bit represents the state of a button:

Button Mapping on BM_UserIO_getAllButtonStates Output

The following example first reads the state of the A button before reading the state of all buttons:

uint32_t buttonState = 0;

//  Read the state of the A button
BM_UserIO_getButtonState(BM_USERIO_A, &buttonState);
if (!buttonState)
    //  Button is pressed
else
    //  Button is released

//  Read the state of all buttons and check the state of button A
BM_UserIO_getAllButtonStates(&buttonState);
if (!(buttonState & (1 << BM_USERIO_A))
    //  A Button is pressed

Note that if the button is pressed, buttonState should return 0 as the signals are active low.

Edge State

There may be times where reading the button's state transition may be preferred. The functions, BM_UserIO_getButtonEdgeState and BM_UserIO_getAllButtonEdgeStates can be used to detect whether or not a state transition has occurred.

These functions expect a BM_UserIO_Edge parameter which can be either BM_USERIO_RISING or BM_USERIO_FALLING. Rising Edge means that the button is released while Falling Edge means that the button is pressed:

Voltage Signals of Button Presses/Releases

The example code checks for a falling edge transition on button A:

uint32_t buttonEdgeState = 0;

//  Get the edge state of button A
BM_UserIO_getButtonEdgeState(BM_USERIO_A, &buttonEdgeState, BM_USERIO_FALLING);
if (buttonEdgeState)
    //  Falling edge is detected

//  Get the edge state for all buttons
BM_UserIO_getAllButtonEdgeStates(&buttonEdgeState, BM_USERIO_FALLING);

//  Check to see if button A has a falling edge
if (buttonEdgeState & (1 << BM_USERIO_A))
    //  Falling edge detected on button A

Getting edge transition information relies on the fact that BM_UserIO_update must be called periodically. However, when creating scenes, you will not need to worry about calling this function as the controllers typically do this for you.