Looking for support? Find help on discord ☝️

Firmware for the modular Split Flap Display created by Morgan Manly

• Instructables ( Original )
• Print Files ( Original, 37 characters version )
• Print Files ( Extended, 48 characters version )
• Original firmware

• Fully 3D Printed Modular Split Flap Display with 37 or 48 Characters Per Module
• Small Size, 8 Modules are 320mm, 3 Modules are 130mm Wide. 80mm tall (original version) or 94mm (extended version) tall
• Fully configurable and controllable via Web Interface
  • Switch Between Operation Modes, modes include custom input, date mode, and time mode
  • Configure WiFi, Timezone, and hardware settings
  • Module calibration interface for precise alignment
• MQTT Support with automatic reconnection
• OTA Firmware / Filesystem updating

• Motor Timing Improvements: Enhanced accuracy and consistency
  • Fixed timing inconsistencies in motor control loop
  • Improved sensor polling with fresh timestamps
  • Reduced I2C error recovery delay (10ms → 2ms)
  • Added I2C timeout protection (5ms) to prevent hangs
• MQTT Reliability: Improved accuracy when receiving MQTT messages
  • Busy flag prevents concurrent display operations
  • Message queuing when display is active
  • Consistent accuracy across MQTT and multi-word modes
• Module Calibration: Web-based offset adjustment for precise character alignment
• I2C Connectivity Testing: Diagnostic endpoint to verify module communication
• Improved Reliability:
  • Smart WiFi/MQTT reconnection with exponential backoff
  • Stepper motor wake-up sequence for consistent performance
  • Watchdog protection for long-running operations
  • Enhanced error recovery with I2C communication tracking
• Code Quality: Named constants, input validation, and comprehensive error logging

See ENHANCEMENTS.md for detailed documentation.

For timing analysis and future improvements, see:

• TIMING_ISSUES.md - Comprehensive timing analysis
• MQTT_ACCURACY_FIX.md - MQTT reliability improvements
• ACCURACY_IMPROVEMENTS.md - Future enhancement roadmap

_{* Requires manually resetting the board into firmware upload mode by holding BOOT, pressing & releasing RESET, then releasing BOOT prior to upload. After uploading is successful, either press & release RESET or power cycle the board to put it in normal operation mode.}

1. Install dependencies
   • PlatformIO Core CLI
   • Node Version Mananger
   • ClangFormat (Only required if contributing code)
2. Download or clone this git repository.
3. Open a terminal and cd to the project root
4. Install required version of npm for the project - nvm install
5. Install build dependencies - npm install
6. Connect the ESP32 to your computer using a USB cable.
7. Build everything and upload to the board - npm run build

• Automatically formats all source code ( npm run format - if needed )
• Compiles and minifies all frontend assets ( npm run assets )
• Downloads all required arduino / esp32 libraries
• Compiles and uploads the esp32 firmware ( npm run pio:firmware or pio run -t upload -e <environment> )
• Compiles and uploads the littlefs filesystem ( npm run pio:filesystem or pio run -t uploadfs -e <environment> )

1. Enjoy!

On the settings page set an OTA password to enable OTA updatable firmware. Use this same password for your auth flag in platformio.ini, and then use a device environment with *_ota appended (ie esp32_s3_ota) to upload a new firmware and/or filesystem

1. Create a GitHub account if necessary and login.
2. Fork this repository.
3. Clone your forked repository to your local machine.

• git clone https://github.com/your-username/Split-Flap-Display.git

1. Install the dependencies listed in Setup Instructions
2. Skip step 2, complete the setup and use npm run build to test and upload your changes.

1. Start a new branch with a descriptive name.
2. Compile and upload your changes

• npm run pio:firmware or pio run -t upload -e <environment> to compile firmware and upload
• npm run pio:filesystem or pio run -t uploadfs -e <environment> to compile the filesystem from src/web and upload
• You can do both together using npm run pio or pio run -t upload -t uploadfs -e <environment>

1. When ready, commit and push your changes to your forked repository.
2. Open a pull request to this repository.