ArduinoIDE - xoseperez/espurna GitHub Wiki

Installing the Arduino IDE

🔴 NOTICE that Arduino IDE support is provided as-is and is not guaranteed to work well (or, at all). Please consider using VS Code + PlatformIO extension or PlatformIO CLI.

You can install the Arduino IDE by downloading it from arduino.cc. Do not download the installer but the compressed file targeted to your OS. This way you will be able to decompress it on your system or on an USB pendrive for instance and carry it with you anywhere. They call it portable Arduino IDE.

All you have to do is decompress it (unzip it or unbzip it) where you want, open the folder and create a "portable" subfolder there. Now you can open the Arduino IDE by clicking on the executable.

Setting up the IDE

Minimum required version is 2.x.x

Install the Arduino Core for ESP8266

First step is to install support for ESP8266 based boards on the Arduino IDE through the Board Manager. These instruction are copied and adapted from the Arduino Core for ESP8266 documentation here: https://github.com/esp8266/Arduino/.

  • Start Arduino and open Preferences window.
  • Enter https://arduino.esp8266.com/stable/package_esp8266com_index.json into Additional Board Manager URLs field. You can add multiple URLs, separating them with commas.
  • Open Boards Manager from Tools > Board menu and find esp8266 platform (and don't forget to select your ESP8266 board from Tools > Board menu after installation).
  • Select the version you need from a drop-down box.
  • Click install button.

Add a new flash layout

This step is not required but strongly recommended.

Since version 1.13.6, ESPurna includes custom board configurations to help with IDE builds:

Depending on the Core version that you want to use, choose either latest or 2.3.0 directories.

Installing dependencies

The ESPurna project relies on several 3rd party and custom libraries. These libraries have to be loaded in you arduino environment before attempting to build the project. Some of these libraries are available through the library manager in Arduino IDE, others you will have to install them manually.

Arduino IDE - Library options

Libraries

🔴 When updating your local sources, make sure to come back here and update our libraries before reporting any issues!

Click on the "Manage Libraries" menu under "Sketch > Include Library". You will be presented a form with a search box on top. The first thing it will do is to connect to the Arduino servers to download the latest list of available libraries. Then you will have to search and install them. Please note that some libraries are optional and depend on the functionalities you want to include.

Arduino IDE - Library options

For the most up-to-date list, please see code/platformio.ini lib_deps = ... in the [common] section.
In case the library is missing from the Library Manager, you would need to manually install it, see the list below.

Core libraries

Button management, WiFi control and settings storage inspired by:

  • Xose Pérez's DebounceEvent (Notice! No need to install)
  • Xose Pérez's JustWifi (Notice! No need to install)
  • The PatternAgents (et al.) Embedis (Notice! No need to install)

Optional libraries, depending on specific ..._SUPPORT flags

You will have to install manually the libraries that are not available from the Library Manager. The Arduino IDE lets you install a library from a ZIP file, so we will download all the required libraries from their repositories in a ZIP file and install them. You can look for them manually but I have gathered the URLs to those ZIP files here for convenience:

Manual installation

Download the ZIP files from the links in the table below only for those libraries you actually need. If you are unsure start with the mandatory ones. Then use the menu under "Sketch > Include Library > Add .ZIP Library..." and load them one by one.

Arduino IDE - Library options

Depending on your level of GIT confidence you can check out the repositories for all of them into your library folder instead of installing them as ZIP files.

Library Source code Supported version .zip
Core libraries
ArduinoJson https://github.com/bblanchon/ArduinoJson https://github.com/bblanchon/ArduinoJson/archive/v5.13.5.zip
AsyncMqttClient https://github.com/marvinroger/async-mqtt-client https://github.com/marvinroger/async-mqtt-client/archive/v0.8.1.zip
ESPAsyncTCP https://github.com/me-no-dev/ESPAsyncTCP https://github.com/me-no-dev/ESPAsyncTCP/archive/7e9ed22.zip
ESPAsyncWebServer https://github.com/me-no-dev/ESPAsyncWebServer https://github.com/me-no-dev/ESPAsyncWebServer/archive/b0c6144.zip
EEPROM_Rotate https://github.com/xoseperez/eeprom_rotate https://github.com/xoseperez/eeprom_rotate/archive/0.9.2.zip
JustWifi https://github.com/mcspr/justwifi https://github.com/mcspr/justwifi/archive/2cb9e769.zip
Optional
arduino-mqtt https://github.com/256dpi/arduino-mqtt https://github.com/256dpi/arduino-mqtt/archive/196556b6.zip
pubsubclient https://github.com/knolleary/pubsubclient https://github.com/knolleary/pubsubclient/archive/v2.8.zip
Brzo I2C https://github.com/pasko-zh/brzo_i2c https://github.com/pasko-zh/brzo_i2c/archive/1.3.3.zip
fauxmo ESP https://github.com/vintlabs/fauxmoESP https://github.com/vintlabs/fauxmoESP/archive/refs/tags/3.4.zip
HLW8012 https://github.com/xoseperez/hlw8012 https://github.com/xoseperez/hlw8012/archive/1.1.0.zip
my92xx https://github.com/xoseperez/my92xx https://github.com/xoseperez/my92xx/archive/3.0.1.zip
nofuss https://bitbucket.org/xoseperez/nofuss https://bitbucket.org/xoseperez/nofuss/get/0.3.0.zip
PZEM004T https://github.com/olehs/PZEM004T https://github.com/olehs/PZEM004T/archive/2b1b5e74.zip
OneWire https://github.com/PaulStoffregen/OneWire https://github.com/PaulStoffregen/OneWire/archive/2.3.5.zip
NewPing https://bitbucket.org/teckel12/arduino-new-ping https://bitbucket.org/teckel12/arduino-new-ping/get/1.9.1.zip
Adafruit SI1145 https://github.com/adafruit/Adafruit_SI1145_Library https://github.com/adafruit/Adafruit_SI1145_Library/archive/1.1.1.zip
IRremoteESP8266 https://github.com/crankyoldgit/IRremoteESP8266 https://github.com/crankyoldgit/IRremoteESP8266/archive/2.7.20.zip
RCSwitch https://github.com/1technophile/rc-switch https://github.com/1technophile/rc-switch/archive/11402652.zip
RFM69 https://github.com/LowPowerLab/RFM69 https://github.com/LowPowerLab/RFM69/archive/7008d57a.zip
RPNLib https://github.com/mcspr/rpnlib https://github.com/mcspr/rpnlib/archive/0.24.1.zip
SparkFun VEML6075 https://github.com/sparkfun/SparkFun_VEML6075_Arduino_Library https://github.com/sparkfun/SparkFun_VEML6075_Arduino_Library/archive/V_1.0.3.zip
VL53L1X https://github.com/pololu/vl53l1x-arduino https://github.com/pololu/vl53l1x-arduino/archive/1.0.1.zip
MAX6675 https://github.com/mcleng/MAX6675-Library https://github.com/mcleng/MAX6675-Library/archive/2.0.1.zip
ESP8266 oled ssd1306 https://github.com/ThingPulse/esp8266-oled-ssd1306 https://github.com/ThingPulse/esp8266-oled-ssd1306/archive/3398c97.zip
BSEC Arduino https://github.com/BoschSensortec/BSEC-Arduino-library https://github.com/BoschSensortec/BSEC-Arduino-library/archive/c5503e0.zip

Open ESPurna in the IDE

Assuming you have already checked out the project from github using git, you just have to open the 'code/espurna/espurna.ino' file. The rest of the files will open as tabs in the IDE. Unfortunately the IDE does not support opening files under subfolders, and that includes the configuration files you will have to modify in the next step.

Configuring the hardware

The ESPurna firmware uses build flags to target specific boards or enable support for certain sensors. The Arduino IDE does not have a friendly way to specify build flags from the interface so the best option is to manually modify the 'code/espurna/config/arduino.h' file to define what we want to build. Edit that file with your favorite editor (it's not accessible from the IDE, the pic below is from Atom) and uncomment the options to suit your need. In the example below we are compiling for Sonoff TH with DHT support.

Arduino IDE - Hardware configuration from Atom

Also, you might want to take a look at other compilation options and default values in 'code/espurna/config/general.h'.

Building & Flashing the firmware

First you will have to choose the right board and memory map. Here you have a list of the supported board types and the suggested configuration:

Board type Board names Flash size Flash mode IwIP
ESP-12 based modules Wemos D1 & D1 mini, NodeMCU, Electrodragon, OpenEnergyMonitor MQTT Relay Board,... 4M (1M SPIFFS) DOUT LWIP v2
Generic ESP8285 module Sonoff 4CH, Sonoff 4CH Pro, Sonoff Touch, Sonoff B1, Sonoff T1, AI-Thinker Wifi Light 1M (no SPIFFS) DOUT LWIP v2
Generic ESP8266 module All the rest 1M (no SPIFFS) DOUT LWIPv2

When using custom boards.local.txt and ld scripts:

Board type Board names Flash size Flash mode IwIP
Generic ESP8266 module Any DOUT Any

There will be 4 additional flash sizes available:

  • 1M (1 EEPROM Sector, no SPIFFS)
  • 2M (4 EEPROM Sectors, 1M SPIFFS)
  • 4M (4 EEPROM Sectors, 1M SPIFFS)
  • 4M (4 EEPROM Sectors, 3M SPIFFS)

Arduino IDE - Library options

Now you are ready to build the project clicking on the 'tick' button. Take a close look at the output window in the IDE for errors (in red). Common errors here could be missing libraries (go back to the installing dependencies section above) or the "Unsupported hardware" error, meaning you have not defined the target device (go back to the configuring hardware section).

Finally, if there were no errors, connect your device (check the Hardware document for instruction on how to connect your device to flash it), choose the port your programmer is listening to, and flash it clicking on the 'upload' button.


1 See MQTT configuration.
2 See I2C configuration.
3 See Sensors configuration.
4 See Lights configuration.
5 See RPN Rules configuration.
6 See RFBridge configuration.

⚠️ **GitHub.com Fallback** ⚠️