Understanding ESP-SimHub Configuration

Overview

The src/main.cpp file is the heart of your ESP-SimHub project. This file determines what features your device will support and how it will interact with SimHub. Think of it as your device’s blueprint.

Configuration Process

1. Planning Your Device

Before modifying any code:

• Decide what features you need (buttons, encoders, displays, LEDs, etc.)- Select your ESP board if you haven’t already.
  • ESP8266 are more affordable but have less memory and pins. They’re good for driving WS2812B/NeoPixel LEDs or MAX7219 LED matrices.
  • ESP32 have more memory and pins. They’re good for driving larger displays, matrices, and combinations of features into a single device.
• Map out your pin connections. This is specific to your ESP board. Get the pinout from the manufacturer or vendor.
• Consider power requirements
• Plan your connectivity needs (WiFi, Wired), Bluetooth SimHub is not supported.

2. Understanding the Code Structure

The src/main.cpp file is organized into several key sections:

1. Feature Definitions: At the top, features are enabled/disabled using #define statements
2. Pin Assignments: Where you define which GPIO pins connect to your hardware
3. Setup Configuration: Initial device configuration in the setup() function
4. Main Loop: Handles ongoing device operations in the loop() function

3. Making Changes

To modify your device’s configuration:

1. Open src/main.cpp in your IDE
2. Enable/disable features using #define statements. Start with a single feature enabled and continue to add features incrementally after testing each one.
3. Configure pins according to your wiring
4. Add any custom logic you need
5. Build and upload to test changes using Platformio

4. Testing Your Configuration

After making changes:

1. Compile the code to check for errors
2. Upload to your device
3. Connect to SimHub. If no connection, try disabling features one by one until you find the culprit.
4. Test each feature in SimHub.
   • If feature is known to work, and doesn’t, report it.
   • If not, show interest in the Discord or GitHub Issues.
5. Monitor serial output for debugging if using WiFi only.

Best Practices

• Test Incrementally: Add and test one feature at a time
• Power Management: Be mindful of power requirements when enabling features
• Pin Compatibility: Double-check pin assignments for your specific board, some boards expose pins that may crash your device if used.

Common Pitfalls

• Memory Limitations: Enabling too many features can exceed device memory and not compile.
• Pin Conflicts: Assigning multiple features to the same pin will be problematic.
• Power Issues: Insufficient power for LED strips or multiple devices may damage your device.
• WiFi Stability: Poor connection can affect device performance.
• Crashes look like bad pairing with SimHub: The firmware executes most code when connected or connecting to SimHub. Crashes look like bad pairing with SimHub. Try disabling feature by feature to find the culprit.

Getting Help

If you run into issues:

1. Join the community discussions Discord
2. Review or post a GitHub Issue
3. Ask ChatGPT or Claude

Next Steps

• Browse configuration examples in Configuration Examples