Installation
This is going to assume you have at least basic familiarity with the Arduino IDE and that it is installed on your local machine. If you need to install the IDE or need assistance with the basic functions like adding boards or libraries, please see Getting Started with Arduino.
If you haven't programmed with the ESP8266 in the Arduino IDE before, you will need to add the ESP8266 family of boards. The ESP8266 is not included by default in the Board Manager. You will need to add the following URL to your Preferences --> Options --> Additional Board Manager URLs:
https://arduino.esp8266.com/stable/package_esp8266com_index.json
Next, go the Boards Manager and search for 'ESP8266'. Select the ESP8266 by Community and install. If you need additional assistance with installing the board core, see Installing Additional Cores.
The recommended way to do this is to go to the latest release, scroll down to the Assets and download the Source Code (zip) or Source Code (tar.gz) file. Unzip this file into a temporary location on your local machine. For the Arduino sketch, we are interested in the 'clock_main' folder. The other folders are references or for use in Home Assistant.
Create a new folder in your Arduino project location (for Windows, the default is /Documents/Arduino). Copy the entire clock_main folder into this newly created project folder. When complete, your folder and file structure should look something like this:
The ESP8266FS tools will allow you to update the contents of the /data folder to the ESP8266 flash memory. The /data folder contains the necessary files for the integrated web server. You will only need to upload these files on the first install of a new board and will not need to repeat the process unless the web server files are changed. To install this tool:
- Download the tool: https://github.com/esp8266/arduino-esp8266fs-plugin/releases/download/0.2.0/ESP8266FS-0.2.0.zip.
- In your Arduino sketchbook directory, create tools directory if it doesn't exist yet
- Unpack the tool into tools directory (the path will look like <home_dir>/Arduino/tools/ESP8266FS/tool/esp8266fs.jar)
- Restart Arduino IDE
A few additional libraries will be needed for this project. If you haven't already, open the clock_main.ino file in the Arduino IDE. Add the following libraries if they do not already exist in your environment (You do not need to download these and should install via the IDE library manager. Links are only provided if you want more details or opt to manually install the libraries):
All other necessary libraries should be installed as part of the ESP8266 core. But if you get any compile errors related to a library, check the top of the .ino file for the libraries (#include <library name.h>) and install any that are missing. See Installing Additional Libraries if you need further information on installing libraries.
Before your first upload, you'll need to open and edit the Credentials.h file and enter your wifi SSID and password, along with your MQTT user and password if you plan on using MQTT/Home Assistant. Edit and save this file within the Arduino IDE or using any text editor.
Next, open the Settings.h file and, at a minimum, update the following parameters to match your particular build/environment:
-
MILLI_AMPS: Set to match the power supply you are using for the clock (in milliamps) -
MQTTMODE: Set to 1 to enable MQTT, 0 to disable -
MQTTSERVER: The IP address or URL of your MQTT broker (if MQTT enabled) -
MQTTPORT: The port for your MQTT broker (if MQTT enabled)
There are various other boot default options and settings you can change in this file as well. See Initial Setup, Settings and Options for more details on the various options. Save the Settings.h file.
THIS STEP ONLY NEEDS TO BE COMPLETED ON THE INTIAL INSTALL OF A NEW BOARD. If later versions of the .ino file are released or you make other changes to settings, options, etc. and need to upload the sketch again, you do not need to repeat this step. You will only need to upload the contents of the /data folder to flash memory again if you are initializing a new board or make changes to the web server files in the /data folder. Be sure you've completed the "Install the ESP8266FS Tool" step above.
Remove your board from the clock assembly if it is installed. You cannot upload initial files via USB while the board is installed in the clock. After initial install, you will be able to upload files over-the-air (OTA).
Open the Arudino IDE if it isn't open and load the clock_main.ino file. Connect the board to your development machine via a data USB cable.
- Make sure you have selected your board (Wemos D1 R1 if built as described), port, and closed Serial Monitor
- Select Tools > ESP8266 Sketch Data Upload. This should start uploading the files into ESP8266 flash file system. When done, IDE status bar will display
SPIFFS Image Uploadedmessage.
*If you receive an error message, disconnect the board, close and reopen the Arduino IDE, reload the .ino file, reconnect the board and try again. Assure that the correct board and port are selected.
Again, with your board removed from the clock assembly and connected via USB data cable, compile the clock_main.ino file within the Arduino IDE. If you receive no compile errors, assure once again you have selected the proper board and port and upload the sketch to your board. If you see the 'Hard resetting via RTS Pin', then your code successfully upload and the board was rebooted and should be running the new code.
This step is optional, but is recommended to assure that everything is installed properly and the web server is running before reinstalling the board in the clock assembly. After the boot is rebooted following the upload, use your router or other tools to locate the IP address of the board. The board should appear as ESP-nnnnnn (where nnnnnn is the last six digits of the board's MAC address). If you do not see the ESP on your network, check your wifi settings in the Credentials.h file. If you make any changes to this file, save the file and then upload the .ino file again.
Open up a browser and enter the board's IP address (ex. 192.168.1.199). The built in web browser should show the main page:
If you see this page displayed, congratulations! You've successfully installed the program and the board is connected to your wifi. You can now disconnect the board from your machine and reinstall in the clock assembly. Then proceed with the Initial Setup, Settings and Options.