If you like SimRacingController Library... buy me a beer
Advanced Arduino library for creating SimRacing button boxes with matrix button, direct GPIO, encoders and MCP23017 I2C expander support. Designed specifically for racing simulator controllers, this library offers a robust and efficient solution for building custom control panels.
- Button matrix management with configurable debounce
- Direct GPIO button support with debounce
- Rotary encoder support with:
- Configurable sensitivity (1-4x)
- Real-time speed detection
- Error checking and recovery
- Optional push button support
- Absolute position tracking
- MCP23017 I2C expander support:
- Up to 8 devices (128 additional inputs)
- Configurable internal pullups
- Optional interrupt support
- Built-in debounce
- Multiple profiles support
- Event-driven architecture with callbacks
- Power saving mode with configurable timeout
- Thread-safe operations
- Enhanced error handling and reporting
- Efficient memory management
- Hardware-agnostic design
- Open Arduino IDE
- Go to Tools > Manage Libraries...
- Search for "SimRacingController"
- Click Install
- Download latest release as ZIP
- In Arduino IDE: Sketch > Include Library > Add .ZIP Library
- Select downloaded ZIP file
- Restart Arduino IDE
- Arduino Uno/Nano (ATmega328P)
- Arduino Mega
- Arduino Leonardo
- Arduino Pro Micro
- ESP8266 based boards
- ESP32 based boards
- Push buttons for matrix/GPIO
- Diodes (1N4148 or similar) for button matrix
- Rotary encoders (optional)
- Pull-up resistors (10kΩ) if not using internal pull-ups
- MCP23017 I2C expanders (optional)
#include <SimRacingController.h>
// Matrix configuration
const int MATRIX_ROWS = 3;
const int MATRIX_COLS = 3;
const int rowPins[MATRIX_ROWS] = {2, 3, 4};
const int colPins[MATRIX_COLS] = {5, 6, 7};
// GPIO configuration
const int NUM_GPIO = 2;
const int gpioPins[NUM_GPIO] = {8, 9};
// Encoder configuration
const int NUM_ENCODERS = 2;
const int encoderPinsA[NUM_ENCODERS] = {10, 12};
const int encoderPinsB[NUM_ENCODERS] = {11, 13};
const int encoderBtnPins[NUM_ENCODERS] = {14, 15}; // Optional
// MCP23017 configuration
const uint8_t NUM_MCP = 2;
McpConfig mcpConfigs[NUM_MCP] = {
McpConfig(0x20, true, false), // Address 0x20, pullups on, no interrupt
McpConfig(0x21, true, true, 16) // Address 0x21, pullups on, interrupt on pin 16
};
// Create controller
SimRacingController controller;
// Callback functions
void onMatrixChange(int profile, int row, int col, bool state) {
Serial.printf("Matrix [%d,%d] = %d (Profile %d)\n", row, col, state, profile);
}
void onGpioChange(int profile, int gpio, bool state) {
Serial.printf("GPIO %d = %d (Profile %d)\n", gpio, state, profile);
}
void onEncoderChange(int profile, int encoder, int direction) {
Serial.printf("Encoder %d: %s (Profile %d)\n",
encoder, direction > 0 ? "CW" : "CCW", profile);
}
void onMcpChange(int profile, int device, int pin, bool state) {
Serial.printf("MCP %d Pin %d = %d (Profile %d)\n",
device, pin, state, profile);
}
void setup() {
Serial.begin(115200);
// Configure inputs
controller.setMatrix(rowPins, MATRIX_ROWS, colPins, MATRIX_COLS);
controller.setGpio(gpioPins, NUM_GPIO);
controller.setEncoders(encoderPinsA, encoderPinsB, encoderBtnPins, NUM_ENCODERS);
controller.setMcpDevices(mcpConfigs, NUM_MCP);
// Set callbacks
controller.setMatrixCallback(onMatrixChange);
controller.setGpioCallback(onGpioChange);
controller.setEncoderCallback(onEncoderChange);
controller.setMcpCallback(onMcpChange);
// Initialize controller
if (!controller.begin()) {
Serial.println("Error: " + String(controller.getLastError().message));
while(1); // Stop if initialization fails
}
}
void loop() {
controller.update();
}Simple button, encoder and MCP23017 reading with serial output.
- File:
examples/Basic/Basic.ino
Complete setup showing all features including:
- Matrix and GPIO button handling
- Encoder configuration and reading
- MCP23017 expander support
- Power management
- Error handling
- Profile management
- File:
examples/Advanced/Advanced.ino
Complete setup for Assetto Corsa Competizione with:
- Button mappings for common functions
- Encoder settings for TC, ABS, etc.
- Multiple profiles support
- File:
examples/ButtonBox_ACC/ButtonBox_ACC.ino
Requirements:
- KeySequence library
- ACC shortcuts configuration (
Sequenze.h)
- Efficient scanning algorithm
- Configurable debounce
- No ghosting with proper diode configuration
- Independent state tracking
- Active-low logic
- Simple direct button connection
- Same debounce as matrix
- Active-low logic with pullups
- Ideal for single buttons
- Configurable sensitivity (1-4x)
- Real-time speed detection
- Error checking and reporting
- Optional push button support
- Absolute position tracking
- Efficient state machine implementation
- Up to 8 devices (128 inputs)
- Configurable internal pullups
- Optional interrupt support
- Individual pin debounce
- Error detection and recovery
- Active-low logic
- Efficient I2C communication
- Automatic sleep mode
- Configurable timeout
- Wake on activity
- Low power consumption
- Pin state preservation
- Comprehensive error reporting
- Error callbacks
- Validation checks
- Recovery mechanisms
- Detailed error messages
- Fork repository
- Create feature branch
- Submit pull request
- GitHub Issues: Technical issues, bugs
- GitHub Discussions: Questions, ideas
- Email: [email protected]
MIT License - See LICENSE file
- Added enhanced MCP23017 support
- Improved error handling system
- Added power management
- Added thread safety
- Enhanced encoder reliability
- Improved debouncing
- Added communication timeouts
- Enhanced memory management
- Added direct GPIO button support
- Improved encoder handling
- Better memory management
- Enhanced documentation
- Small fixes
- Initial release
- Basic matrix support
- Encoder functionality
- Profile management