*** This page is under construction ***

Setup

Model Lights, in conjunction with the model-lights.ino Arduino sketch, is used to control lighting effects built into plastic model kits. A modeler would embed programmable RGB LEDs into the interior of their creation, along with an appropriate microcontroller, and use Model Lights to control the color, brightness and effect of each individual LED. Currently Model Lights only supports a model of the U.S.S. Enterprise, but support for more models will be added as time permits. It is available as an Android app on the Google Play Store and as a web app hosted on this server.

You will need:

  1. some programmable RGB LEDs (WS2812 or something similar)
  2. an ESP microcontroller (ESP8266 or ESP32) along with an appropriate power supply and sundry electronic components
  3. the Arduino IDE along with the appropriate core platform for your microcontroller (ESP8266 Arduino Core or ESP32 Arduino Core)
  4. the model-lights sketch and these libraries:

I'm going to assume you have some experience with the Arduino IDE, ESP and WS2812 hardware. If not, Adafruit has some nice guides for their NeoPixel products and instructables.com has useful articles that describe the ESP/WS2812 hardware setup. Pay particular attention to Adafruit's Best Practices guide (link). It will save you some headaches.

Install the Arduino IDE and appropriate ESP8266 or ESP32 platform as described on their web pages. To test things out, you'll need to supply power to an RGB LED and wire its Din pin to one of the ESP's GPIO pins Then edit the model-lights.ino sketch's DATA_PIN parameter to reflect the GPIO pin you're using for your project: #define DATA_PIN 12 Upload the model-lights sketch to your ESP. If all is well, the LED should briefly flash green (during WiFi initialization), then you should see the default effect, a single white LED.



Network Configuration

Initially the ESP has no knowledge of any nearby network connections, so a one-time process needs to be completed in order to configure the microprocessor's WiFi settings. The model-lights sketch implements a simple WiFi Manager (similar to the official WifiManager library), which allows you to configure the ESP to automatically connect to your local WiFi network.

When your ESP powers up for the first time it creates a WiFi access point called "ESP-WIFI-MANAGER". Use a cell phone or computer to temporarily connect to the access point.



Then open a browser window to the WiFi Manager's home page at the IP address "192.168.4.1". Enter your local WiFi network's SSID and password, then click the Submit button. The ESP will reboot and automatically connect to the specified WiFi network. The network's SSID and password are stored in the ESP's non-volatile EEPROM memory, so from now on, it will try to connect to this network every time it powers up.



Using Model Lights

The Model Lights home screen shows an image of a model and is where you'll spend most of your time.

The home screen consists of three sections:

Overview
A collection of thumbnail images each representing the model from a different perspective. Selecting a thumbnail, brings the appropriate perspective into the Detail view.
Detail view
A view of the model from the selected perspective. The view shows various "touchpoints" each representing an LED light in the interior of the model. A blue touchpoint indicates an inactive LED (i.e. an LED which has not been configured in the Model Lights Settings menu). A green touchpoint indicates an active LED that can be configured in the LED view.
LED view
A view with sliders used to set the color, brightness and effect for the selected LED.

But before we can start creating our model lighting we need to configure our lights. In the Model Lights menu, select Settings.

The Settings screen consists of two sections:

ESP Settings
Here you can assign a name to the ESP. If you have a lot of models, this just makes it easier to identify which one you're currently working on. You also specify the IP address assigned to the ESP by your network router (the assigned IP address is displayed in the Serial Monitor of the Arduino IDE).

Network administration is a little beyond the scope of this documentation, but if you want to ensure the ESP gets the same IP address every time it's booted, you should assign it a reserved IP address in your router's LAN configuration settings. See this knowledge base article for Netgear routers.
LED Settings

A list of all the LED lights embedded in your model, in the order they are hardwired together. Since RGB LEDs are electrically connected in series, where each LED passes data to the next LED in the chain, it's important to get the order of LEDs correct.

Initially, there's only one LED in the list, which is assigned to the model's primary hull. This is the first LED in the chain, the one connected to the ESP's GPIO pin. If the first LED doesn't happen to be embedded in the model's primary hull, you can use the dropdown box to assign it to another location.

To add more LEDs to the list, tap the Add Light button. This will create another entry in the list of lights, with the LED location "unassigned". Tap the location dropdown and select a location for the newly added LED. Repeat this process for all LEDs in your model. Remember to assign the LEDs in the order they are wired together. If you make a mistake and need to remove an LED from the list, just tap the trashcan icon.

If you have previously configured the settings for a model and uploaded them to an ESP, you can transfer the settings from the ESP to the Model Lights app by entering the ESP's IP address in the "IP or Host" field and tapping the Fetch Settings button. This can be handy if you have more then one model with embedded LEDs.

After a while your Settings screen should have a complete list of all the LEDs in your model. Like so:

Now that you've completed the settings for your model, go back to the home screen by tapping "Home" in the Model Lights menu

A green touchpoint will appear for each location in the model that has been assigned an LED. Blue touchpoints will appear for any location that has not been assigned an LED. Use the thumbnails at the top of the screen to view the model from different angles. Tap a green touchpoint to select an LED to work with. Then adjust the LED's color, brightness or effect using the corresponding slider.

If the Auto Upload toggle is enabled, any change to the sliders will be immediately transmitted to the ESP and the model lights will change accordingly. If, for some reason, Model Lights can't make a network connection to the ESP, then Auto Upload will be disabled.