install-software.md

👈 Back to main page

Software Installtion & Flashing your ESP32

Important

This project is an add-on to your already built Open Source Watch Winder (OSWW).

• This project requires a microncontroller which replaces the Pi Pico used in the OSWW.
• The Raspberry Pi Pico is incompatible with this project and must be swapped.

Getting Started

Prerequisites

• Download Visual Studio Code (VSCode)
• Download PlatformIO

Flashing your microcontroller

1. Download this repository. You can do this via git or by downloading the repository as a ZIP.
   • If you downloaded the repository as a zip, uzip it before proceeding to step 2.
   
2. Open the extracted folder (or cloned repository if using git) in Visual Studio Code
3. Build Options - (PWM, OLED, Home Assistant)
   • if you're building Winderoo with an OLED screen, intend to use Home Assistant, or you desire fine-grained motor control (pulse width modulation), you must enable some of the following build flags to tell PlatformIO to include additional libraries.
   • To toggle these build flags, navigate to the file called platformio.ini:
     
     • In this file, you'll see the following block of code:

       build_flags =
           -D OLED_ENABLED=false
           -D PWM_MOTOR_CONTROL=false
           -D HOME_ASSISTANT_ENABLED=false

       • Change -D HOME_ASSISTANT_ENABLED=false to -D HOME_ASSISTANT_ENABLED=true to enable Winderoo's Home Assistant integration

         • 🚦 I'd strongly recommend you have a dedicated MQTT user; do not use your main account.

         • If this feature is enabled, you must add your Home Assistant's IP, username, and password.

           • You can add them in main.cpp inside the configuration block:

           // Home Assistant Configuration
           const char* HOME_ASSISTANT_BROKER_IP = "YOUR_HOME_ASSISTANT_IP";
           const char* HOME_ASSISTANT_USERNAME = "REPLACE_THIS_WITH_HOME_ASSISTANT_LOGIN_USERNAME";
           const char* HOME_ASSISTANT_PASSWORD = "REPLACE_THIS_WITH_HOME_ASSISTANT_LOGIN_PASSWORD";

       • Change -D OLED_ENABLED=false to -D OLED_ENABLED=true to enable OLED screen support
       • Change -D PWM_MOTOR_CONTROL=false to -D PWM_MOTOR_CONTROL=true to enable PWM motor control; at the time of writing, Winderoo with PWM only supports MX1508 derived motor controllers.

         • PWM_MOTOR_CONTROL is an experimental flag. You will encounter incorrect cycle time estimation and other possible bugs unless you align the motor speed to 20 RPM (see Troubleshooting). Use at your own risk.

   • PlatformIO will now compile Winderoo with OLED screen, Home Assistant, and or PWM motor support
4. Select 'PlatformIO' (alien/insect looking button) on the workspace menu and wait for visual studio code to finish initializing the project
   
5. Expand the main heading: "esp32doit-devkit-v1":
   
6. Expand the "General" heading, then click Upload. You'll see a message if the code was uploaded successfully:
   
7. Now expand the "Platform" heading, then click Upload Filesystem Image. You'll see a message if the code was uploaded successfully:
   
8. All done! Your microcontroller should now have 2 LEDs illuminated (see beneath). If it does, proceed to Next steps. If not, try to upload the code & file system again.
   
9. If you have a different LED state, compare it with this table:
   • Understanding Winderoo's LED Blink Status

Next steps

Ok, you've got 2 LEDs illuminated on your board. Great! Let's make sure the code works.

1. Get out your mobile device (phone/tablet) and navigate to the Wi-Fi / wireless network list. You'll want to find and join a WiFi network called "Winderoo Setup."
   • It may take a minute or so to connect, or look like it isn't doing anything. Hold tight, it is.
2. Once you've connected to "Winderoo Setup", a captive page will open called "WifiManger Winderoo Setup."
3. Tap "Configure WiFi"
4. Tap on the network you want to add Winderoo to, this is likely your home WiFi network
5. Enter your WiFi network's password then tap "Save." Wait until the captive page closes itself.
6. Re-join your home WiFi network
7. Open up a web browser and try to navigate to the following webpage:
   • http://winderoo.local/
8. If you see Winderoo's user interface, you're all done!
   • Here is an overview of Winderoo's user interface

Home Assistant

If you've enabled Winderoo's Home Assistant integration, Winderoo will stream a number of entities into Home Assistant over MQTT. If you're unsure what MQTT or need to set this up in Home Assistant, please see this document.

Winderoo should be automatically discovered by Home Assistant within 60 seconds. The following entities are available to Home Assistant:

 -  button.winderoo_start
 -  button.winderoo_stop

 -  sensor.winderoo_status            : "Winding | Stopped"
 -  sensor.winderoo_wifi_reception    : "Excellent | Good | Fair | Poor"
 
 -  number.winderoo_rotations_per_day : 100 <-> 960 

 -  select.winderoo_direction         : "CCW | BOTH | CW"
 -  select.winderoo_hour              : 00 <-> 23
 -  select.winderoo_minutes           : 00 <-> 50
 
 -  switch.winderoo_timer_enabled     : "true | false"
 -  switch.winderoo_oled              : "true | false"
 -  switch.winderoo_power             : "true | false"

You can replicate Winderoo's GUI with a basic Home Assistant card:

Home Assistant GUI

Code

type: entities entities: - entity: sensor.winderoo_status - entity: number.winderoo_rotations_per_day name: Rotations Per Day - entity: select.winderoo_direction name: Direction - entity: button.winderoo_start name: Start - entity: button.winderoo_stop name: Stop - entity: switch.winderoo_timer_enabled name: Timer Enabled - entity: select.winderoo_hour name: Hour - entity: select.winderoo_minutes name: Minutes - entity: switch.winderoo_oled name: OLED - entity: switch.winderoo_power name: Power title: Winderoo show_header_toggle: false

Troubleshooting

Motor Turns too fast when using PWM

Warning

PWM_MOTOR_CONTROL is an experimental flag. You will encounter incorrect cycle time estimation and other possible bugs unless you align the motor speed to 20 RPM.

• The default speed is 145 (8-bit resolution), where 0 is the slowest and 255 is the fastest. You can modify this value here:
  • MotorControl.cpp
    • Change the value for the variable motorSpeed to any value between 0 and 255
    • After changing that value, you must recompile the software and upload it to your ESP32
• You can also tweak the rotational timing value. By default this is set at 8 seconds to complete one revolution.
  • To change this value, change the variable durationInSecondsToCompleteOneRevolution here:
  • main.cpp