Skip to content
This repository has been archived by the owner on Apr 28, 2022. It is now read-only.

Software installation

Jump to bottom
Tobias Blum edited this page Jul 7, 2019 · 39 revisions

You need to complete the following steps to build your development environment that enables you to flash the McLighting software to your ESP8622.

For instructions to setup McLighting using PlatformIO, see here:
YouTube-McLighting-PIO

Table of contents:

Setup the Arduino IDE

Download and install the Arduino IDE (tested with 1.8.5) from https://www.arduino.cc/en/Main/Software

In the Arduino IDE, open the preferences dialog and enter the following URL as "Additional Boards Manger URL" as shown below: http://arduino.esp8266.com/stable/package_esp8266com_index.json Preferences

Close the dialoge box and go to "Tools" > "Board: <some board>" > "Boards Manager ...". Another window will pop up. Here search for "esp" and install "esp8266 by ESP8266 Community" in version 2.4.1.

Preferences

Again close this window and go to "Tools" > "Board: " and here choose "NodeMCU 1.0 (ESP-12E Module)".

After that you should make some more tweaks:

  • Set the CPU frequency to 80 MHz
  • Set the Flash Size to "4M (1M SPIFFS)". <-- Double check this!
  • Set the upload speed to 115200 (you could try to set it higher, but it could cause problems).
  • Select the right COM port.
  • Set "IwIP Variant" to "v2 Higher Bandwidth".

Note for ESP-01 users (boards with only 512k of memory):
Have a look here. User @carlymx has provided detailed instructions.

Board settings

Used Libraries

Go to "Sketch" > "Include Library" > "Manage Libraries ..." and install the following libraries by searching for them and installing:

  • WiFiManager by @tzapu (tested with version 0.14.0)

  • WebSockets by @Links2004 (tested with version 2.1.4)

  • Adafruit NeoPixel by @adafruit (tested with 1.2.3)

  • ArduinoJson by @bblanchon (tested with 6.11.1)
    Only when you have activated Homeassistant integration in definitions.h.
    https://arduinojson.org/

  • AMQTT integration (enabled by default)

    • Async MQTT by @marvinroger (tested with 0.8.2)
      Only when you have activated AMQTT in definitions.h.
    • Needs ESPAsyncTCP:
      (Download the library repository as ZIP. Load that library into to Arduino software by: "Sketch > Include Library > Add .ZIP Library".)

  • MQTT (Alternative to AMQTT)

    • PubSubClient by @knolleary (tested with 2.7.0) Only when you have activated MQTT in definitions.h.

  • WS2812FX by kitesurfer1404 (enabled by default)

    • WS2812FX by @Harm Aldick (tested with 1.2.0)

  • NeoAnimationFX by @debsahu (Alternative to WS2812FX)

    • Go to: https://github.com/debsahu/NeoAnimationFX and download the library repository as ZIP. Load that library into to Arduino software by: "Sketch > Include Library > Add .ZIP Library".
    • Needs NeoPixelBus by @Makuna (tested with 2.2.9)
      Install via library manager

  • E.131 (if enabled)

    • ESPAsyncUDP by @me-no-dev Only when you have activated E131 in definitions.h.
      (Download the library repository as ZIP. Load that library into to Arduino software by: "Sketch > Include Library > Add .ZIP Library".)
    • ESPAsyncE131 by @forkineye (tested with 1.0.0)

Compiling and upload

Now open the MC Lighting Arduino sketch in the IDE via "File" > "Open ...". Have a look at the "definitions.h" and change the values here to fit your setup:

// Neopixel
#define PIN 5         // PIN where neopixel / WS2811 strip is attached
#define NUMLEDS 24    // Number of leds in the strip

const char HOSTNAME[] = "McLighting01";   // Friedly hostname

#define HTTP_OTA             // If defined, enable ESP8266HTTPUpdateServer OTA code
//#define ENABLE_OTA         // If defined, enable Arduino OTA code
#define ENABLE_AMQTT         // If defined, enable Async MQTT code
//#define ENABLE_MQTT        // If defined, enable MQTT client code

Attention:
Starting with McLighting v2.2.1 you don't need to configure this before compilation. You do the PIN/RGBmode/NUMLEDS configuration later dynamically via REST calls.

If you don't want to use Arduino OTA or ESP8266HTTPUpdateServer functionality, comment or delete the "HTTP_OTA" and "ENABLE_OTA" line, e.g. //#define ENABLE_OTA.

If you don't want to use MQTT functionality, comment or delete the "ENABLE_AMQTT" and "ENABLE_MQTT" line, e.g. //#define ENABLE_AMQTT. Make sure that you set a unique mqtt_clientid for each McLighting.

Now you have done everything to get all the dependencies. You should now be able to build the software by choosing "Sketch" > "Verify / Compile" (or clicking the tick mark in the tool bar).

Please verify that you have connected the ESP board correctly to your computer via USB and that the correct COM port is chosen.

Now you should be able to upload the compiled sketch to the board via "Sketch" > "Upload" (hit "Ctrl + U" or by clicking the right arrow in the tool bar). This could take a while for the first compilation.

Connecting to your WiFi

The next step is to connect the ESP8266 to your wifi. The project uses the great WiFiManger library to provide a captive portal.

The steps are shown in detail here: https://github.com/tzapu/WiFiManager#how-it-works

I also created a little video that shows the steps:
Captive Portal

If you have eabled MQTT-API you should enter your credentials here.

In short words:

  • Start up your ESP8266, the little LED on the module should blink now and the LEDs should all be green.
  • The ESP8266 opens up a new WiFi Network with the name you provided in the definitions.h.
  • Connect your PC or Smartphone to the Wifi and follow the steps to provide your WiFi credentials.
  • The ESP8266 restarts and should be reachable via it's name or IP (have a look at the debug output in the Arduino software).

Upload the webpage to the SPIFFS filesystem (not needed if you're on v2.2.1 or later)

If you're on v2.2.1 or later McLighting has a built in HTML UI, so you don't need to upload it manually.

If you're on a version before 2.2.1, or want to use a alternative UI:
Next step is to upload the webpages to the ESP8266. This is done that way:

  1. Go to http://YOUR_ESP8266_HOSTNAME_OR_IP/upload.
  2. A simple upload form should appear.
  3. Upload the index.htm from the "McLighting\clients\web\build" directory. You should see a blank page as a result. 4. Optional: Upload the edit.htm.gz to get a editor for your filesystem via http://YOUR_ESP8266_HOSTNAME_OR_IP/upload.

If upload doesn't work, please check if your setting for "Flash size" in the Arduino IDE is correct (at least 128K SPIFFS size).

Alternatively you can upload the files via this PlugIn: https://github.com/esp8266/arduino-esp8266fs-plugin

Configure PIN / RGB mode / NUMLEDS (only for v2.2.1 or later)

You should be able now to open the McLighting UI by calling: http://YOUR_ESP8266_HOSTNAME_OR_IP/ but most likely it won't react to your commands. This is because you need to tell McLighting where your strip is connected, which RGB mode to use an how many LEDs your strip has. You do this by just calling:\ http://YOUR_ESP8266_HOSTNAME_OR_IP/pixelconf?ct=16&rgbo=grb&pin=4

You can use the following parameters:

  1. Number of LEDs (ct)
    Set the ct parameter to the number of LEDs
  2. RGB mode (rgbo)
    RGB Pixel Order (grb/gbr/rgb/rbg/brg/bgr) "grb" is a good guess, if you're unsure.
  3. PIN (pin)
    Choose the PIN where you connected the strip data line: (16/5/4/0/2/14/12/13/15/3/1)
Clone this wiki locally