QwiicNES

The Qwiicnes component provides a driver for the SparkFun Qwiic NES Controller.

QwiicNES Example
- How to use example
  - Hardware Required
  - Build and Flash
- Example Output

API Reference

Header File

components/qwiicnes/include/qwiicnes.hpp

Functions

Warning

doxygenfunction: Unable to resolve function “operator==” with arguments None in doxygen xml output for project “esp-docs” from directory: /home/runner/work/espp/espp/doc/_build/en/esp32/xml_in/. Potential matches:

- bool operator==(const AdcConfig &lhs, const AdcConfig &rhs)
- bool operator==(const Config &rhs) const = default
- bool operator==(const DetentConfig &lhs, const DetentConfig &rhs)
- bool operator==(const Hsv &rhs) const = default
- bool operator==(const PinConfig &rhs) const = default
- bool operator==(const PointerData &rhs) const = default
- bool operator==(const Rgb &rhs) const = default
- bool operator==(const TouchpadData &rhs) const = default
- bool operator==(const TouchpadData &rhs) const = default
- bool operator==(const Vector2d &other) const
- bool operator==(const espp::Bm8563::Date &lhs, const espp::Bm8563::Date &rhs)
- bool operator==(const espp::Bm8563::DateTime &lhs, const espp::Bm8563::DateTime &rhs)
- bool operator==(const espp::Bm8563::Time &lhs, const espp::Bm8563::Time &rhs)
- bool operator==(const espp::QwiicNes::ButtonState &lhs, const espp::QwiicNes::ButtonState &rhs)
- bool operator==(const espp::St25dv::IT_STS &lhs, const espp::St25dv::IT_STS &rhs)

Unions

espp::QwiicNes::ButtonState.__unnamed11__

Public Members

struct espp::QwiicNes::ButtonState::[anonymous]::[anonymous] [anonymous]

uint8_t raw

Classes

class QwiicNes : public espp::BasePeripheral<>

A class to interface with the Qwiic NES controller.

This class is used to interface with the Qwiic NES controller. The Qwiic NES controller is a breakout board for the NES controller. The Qwiic NES controller uses the I2C bus to communicate.

Example

    // make the I2C that we'll use to communicate
    espp::I2c i2c({
        .port = I2C_NUM_0,
        .sda_io_num = (gpio_num_t)CONFIG_EXAMPLE_I2C_SDA_GPIO,
        .scl_io_num = (gpio_num_t)CONFIG_EXAMPLE_I2C_SCL_GPIO,
    });
    // now make the qwiicnes which decodes the data
    espp::QwiicNes qwiicnes(
        {.write = std::bind(&espp::I2c::write, &i2c, std::placeholders::_1, std::placeholders::_2,
                            std::placeholders::_3),
         .read_register =
             std::bind(&espp::I2c::read_at_register, &i2c, std::placeholders::_1,
                       std::placeholders::_2, std::placeholders::_3, std::placeholders::_4),
         .log_level = espp::Logger::Verbosity::WARN});
    // and finally, make the task to periodically poll the qwiicnes and print
    // the state
    auto task_fn = [&quit_test, &qwiicnes](std::mutex &m, std::condition_variable &cv) {
      static espp::QwiicNes::ButtonState last_button_state;
      std::error_code ec;
      qwiicnes.update(ec);
      if (ec) {
        fmt::print("QwiicNes update failed: {}\n", ec.message());
        return true; // stop the task
      }
      auto button_state = qwiicnes.get_button_state();
      if (button_state != last_button_state) {
        fmt::print("Button state: {}\n", button_state);
        quit_test = button_state.select && button_state.start;
        last_button_state = button_state;
      }
      // NOTE: sleeping in this way allows the sleep to exit early when the
      // task is being stopped / destroyed
      {
        std::unique_lock<std::mutex> lk(m);
        cv.wait_for(lk, 50ms);
      }
      return false; // don't stop the task
    };
    auto task = espp::Task({.callback = task_fn,
                            .task_config = {.name = "Qwiicnes Task"},
                            .log_level = espp::Logger::Verbosity::WARN});
    task.start();

Public Types

enum class Button : int

The buttons on the NES controller. @deftails The values in this enum match the button’s corresponding bit field in the byte returned by read_current_state() and read_button_accumulator().

Values:

enumerator A

enumerator B

enumerator SELECT

enumerator START

enumerator UP

enumerator DOWN

enumerator LEFT

enumerator RIGHT

typedef std::function<bool(uint8_t)> probe_fn

Function to probe the peripheral

Param address: The address to probe
Return: True if the peripheral is found at the given address

Public Functions

inline explicit QwiicNes(const Config &config)

Construct a new QwiicNes object.

Parameters: config – The configuration for the QwiicNes class.

inline bool is_pressed(Button button) const

Return true if the given button is pressed.

This function uses the accumulated button states which are updated by the update() function.

Parameters: button – The button to check.
Returns: true if the given button is pressed.

inline ButtonState get_button_state() const

Return the current state of the buttons.

This function uses the accumulated button states which are updated by the update() function.

Returns: The current state of the buttons.

inline void update(std::error_code &ec)

Update the state of the buttons.

This function reads the current state of the buttons and updates the accumulated button states. This function should be called periodically to ensure the accumulated button states are up to date. This function will log an error if it fails to read the current state of the buttons. The accumulated states represent all buttons which have been pressed since the last time this function was called.

See also

get_button_state()

See also

is_pressed()

Parameters: ec – The error code if the function fails.

inline uint8_t read_current_state(std::error_code &ec)

Read the current state of the buttons.

This function will log an error if it fails to read the current state of the buttons. This function does not update the accumulated button states. To update the accumulated button states, call the update() function. The current state represents the buttons which are currently pressed.

Parameters: ec – The error code if the function fails.
Returns: The current state of the buttons.

inline uint8_t read_address(std::error_code &ec)

Read the current I2C address of the device.

This function will log an error if it fails to read the current I2C address of the device. The I2C address is a 7-bit value. The 7-bit I2C address is shifted left by 1 bit and the least significant bit is set to 0. For example, if the I2C address is 0x54, then the value returned by this function will be 0xA8.

Parameters: ec – The error code if the function fails.
Returns: The current I2C address of the device.

inline void update_address(uint8_t new_address, std::error_code &ec)

Update the I2C address of the device.

This function will log an error if it fails to update the I2C address of the device. The I2C address is a 7-bit value. The 7-bit I2C address is shifted left by 1 bit and the least significant bit is set to 0.

Parameters

new_address – The new I2C address of the device.
ec – The error code if the function fails.

inline bool probe (std::error_code &ec) requires(UseAddress)

Probe the peripheral

Note

This function is thread safe

Note

If the probe function is not set, this function will return false and set the error code to operation_not_supported

Note

This function is only available if UseAddress is true

Parameters: ec – The error code to set if there is an error
Returns: True if the peripheral is found

inline void set_address (uint8_t address) requires(UseAddress)

Set the address of the peripheral

Note

This function is thread safe

Note

This function is only available if UseAddress is true

Parameters: address – The address of the peripheral

inline void set_probe (const probe_fn &probe) requires(UseAddress)

Set the probe function

Note

This function is thread safe

Note

This should rarely be used, as the probe function is usually set in the constructor. If you need to change the probe function, consider using the set_config function instead.

Note

This function is only available if UseAddress is true

Parameters: probe – The probe function

inline void set_write(const write_fn &write)

Set the write function

Note

This function is thread safe

Note

This should rarely be used, as the write function is usually set in the constructor. If you need to change the write function, consider using the set_config function instead.

Parameters: write – The write function

inline void set_read(const read_fn &read)

Set the read function

Note

This function is thread safe

Note

This should rarely be used, as the read function is usually set in the constructor. If you need to change the read function, consider using the set_config function instead.

Parameters: read – The read function

inline void set_read_register(const read_register_fn &read_register)

Set the read register function

Note

This function is thread safe

Note

This should rarely be used, as the read register function is usually set in the constructor. If you need to change the read register function, consider using the set_config function instead.

Parameters: read_register – The read register function

inline void set_write_then_read(const write_then_read_fn &write_then_read)

Set the write then read function

Note

This function is thread safe

Note

This should rarely be used, as the write then read function is usually set in the constructor. If you need to change the write then

Parameters: write_then_read – The write then read function

inline void set_separate_write_then_read_delay(const std::chrono::milliseconds &delay)

Set the delay between the write and read operations in write_then_read

Note

This function is thread safe

Note

This should rarely be used, as the delay is usually set in the constructor. If you need to change the delay, consider using the set_config function instead.

Note

This delay is only used if the write_then_read function is not set to a custom function and the write and read functions are separate functions.

Parameters: delay – The delay between the write and read operations in write_then_read

inline void set_config(const Config &config)

Set the configuration for the peripheral

Note

This function is thread safe

Note

The configuration should normally be set in the constructor, but this function can be used to change the configuration after the peripheral has been created - for instance if the peripheral could be found on different communications buses.

Parameters: config – The configuration for the peripheral

inline void set_config(Config &&config)

Set the configuration for the peripheral

Note

This function is thread safe

Note

The configuration should normally be set in the constructor, but this function can be used to change the configuration after the peripheral has been created - for instance if the peripheral could be found on different communications buses.

Parameters: config – The configuration for the peripheral

inline const std::string &get_name() const

Get the name of the component

Note

This is the tag of the logger

Returns: A const reference to the name of the component

inline void set_log_tag(const std::string_view &tag)

Set the tag for the logger

Parameters: tag – The tag to use for the logger

inline espp::Logger::Verbosity get_log_level() const

Get the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Returns: The verbosity level of the logger

inline void set_log_level(espp::Logger::Verbosity level)

Set the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Parameters: level – The verbosity level to use for the logger

inline void set_log_verbosity(espp::Logger::Verbosity level)

Set the log verbosity for the logger

See also

set_log_level

See also

Logger::Verbosity

See also

Logger::set_verbosity

Note

This is a convenience method that calls set_log_level

Parameters: level – The verbosity level to use for the logger

inline espp::Logger::Verbosity get_log_verbosity() const

Get the log verbosity for the logger

See also

get_log_level

See also

Logger::Verbosity

See also

Logger::get_verbosity

Note

This is a convenience method that calls get_log_level

Returns: The verbosity level of the logger

inline void set_log_rate_limit(std::chrono::duration<float> rate_limit)

Set the rate limit for the logger

See also

Logger::set_rate_limit

Note

Only calls to the logger that have _rate_limit suffix will be rate limited

Parameters: rate_limit – The rate limit to use for the logger

Public Static Functions

static inline bool is_pressed(uint8_t state, Button button)

Return true if the given button is pressed.

Parameters

state – The byte returned by read_current_state().
button – The button to check.

Returns

true if the given button is pressed.

Public Static Attributes

static constexpr uint8_t DEFAULT_ADDRESS = (0x54): The default I2C address of the device.

struct ButtonState

The state of the buttons on the NES controller.

Contains the state of each button on the NES controller.

ButtonState.__unnamed11__

ButtonState.__unnamed11__.__unnamed13__

struct Config

The configuration for the QwiicNes class.

Public Members

BasePeripheral::write_fn write: The function to write data to the I2C bus.

BasePeripheral::read_register_fn read_register: The function to write then read data from the I2C bus.

espp::Logger::Verbosity log_level = {espp::Logger::Verbosity::WARN}: The log level for the class.