{"id":19506698,"url":"https://github.com/unclegrumpy/moonlight_8266","last_synced_at":"2025-04-26T02:32:48.292Z","repository":{"id":53166154,"uuid":"321590657","full_name":"UncleGrumpy/Moonlight_8266","owner":"UncleGrumpy","description":"ESP8266 WebSocket server to control a single RGB . With a moon themed web interface for use with a 3-D printed Moon lamp.","archived":false,"fork":false,"pushed_at":"2024-10-21T18:55:30.000Z","size":383,"stargazers_count":2,"open_issues_count":5,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-22T11:20:10.013Z","etag":null,"topics":["arduino-ide","eeprom","esp01","esp8266","littlefs","moon-lamp","ota","rgb-led","websocket"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UncleGrumpy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-15T07:44:37.000Z","updated_at":"2024-10-21T18:55:28.000Z","dependencies_parsed_at":"2024-10-22T19:32:36.862Z","dependency_job_id":null,"html_url":"https://github.com/UncleGrumpy/Moonlight_8266","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UncleGrumpy%2FMoonlight_8266","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UncleGrumpy%2FMoonlight_8266/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UncleGrumpy%2FMoonlight_8266/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UncleGrumpy%2FMoonlight_8266/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UncleGrumpy","download_url":"https://codeload.github.com/UncleGrumpy/Moonlight_8266/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224023706,"owners_count":17242998,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino-ide","eeprom","esp01","esp8266","littlefs","moon-lamp","ota","rgb-led","websocket"],"created_at":"2024-11-10T22:38:00.813Z","updated_at":"2024-11-10T22:38:02.758Z","avatar_url":"https://github.com/UncleGrumpy.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\n Copyright 2020-2024 Winford (Uncle Grumpy) \u003cwinford@object.stream\u003e\n SPDX-License-Identifier: MIT\n--\u003e\n\n# Moonlight_8266\n\n[![Compile Sketch](https://github.com/UncleGrumpy/Moonlight_8266/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/UncleGrumpy/Moonlight_8266/actions/workflows/build.yml) [![CodeQL](https://github.com/UncleGrumpy/Moonlight_8266/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/UncleGrumpy/Moonlight_8266/actions/workflows/codeql.yml) [![REUSE Compliance Check](https://github.com/UncleGrumpy/Moonlight_8266/actions/workflows/reuse.yml/badge.svg?branch=main)](https://github.com/UncleGrumpy/Moonlight_8266/actions/workflows/reuse.yml) [![Check Arduino Formatting](https://github.com/UncleGrumpy/Moonlight_8266/actions/workflows/formatting.yml/badge.svg?branch=main)](https://github.com/UncleGrumpy/Moonlight_8266/actions/workflows/formatting.yml) [![Check JavaScript/HTML formatting](https://github.com/UncleGrumpy/Moonlight_8266/actions/workflows/web_lint.yml/badge.svg?branch=main)](https://github.com/UncleGrumpy/Moonlight_8266/actions/workflows/web_lint.yml)\n\nRGB Color Picker web server for ESP-01 (or ESP826)\n\n## About\n\nThis firmware is designed to create a web interface to control an RGB LED inside a 3-d printed moon lamp.  I used this\namazing design I found at https://www.thingiverse.com/thing:4102658.\n\n## Prerequisites\n\nThis sketch is updated to build with ArduinoIDE 2.x\n\nThis sketch depends on the [WebSockets](https://github.com/Links2004/arduinoWebSockets) library, which can be installed from the ArduinoIDE _Library Manager_.\nThe `WebSockets` library depends on the [ESPAsyncTCP](https://github.com/me-no-dev/ESPAsyncTCP) library, also available in the ArduinoIDE _Library Manager_.\n\nTo upload the web content to the ESP8266 you will need the [arduino-littlefs-upload](https://github.com/earlephilhower/arduino-littlefs-upload) plugin for ArduinoIDE 2.x. (For the old java based ArduinoIDE 1.x use [arduino-esp8266littlefs-plugin](https://github.com/earlephilhower/arduino-esp8266littlefs-plugin)) The directions for that project say to put the [vsix](https://github.com/earlephilhower/arduino-littlefs-upload/releases) file in to the `~/.arduinoIDE/plugins/` (`C:\\Users\\\u003cusername\u003e\\.arduinoIDE\\plugins\\` on Windows) directory, but for it show up in the _Command Palette_ I had to put it also in the `~/.arduinoIDE/plugin-storage/` directory. So in the end I decided to place the real `arduino-littlefs-upload-1.0.0.vsix` file into `~/.arduinoIDE/plugin-storage/` and put a symlink to that file into `~/.arduinoIDE/plugins/`. I don't know the recommended way to set up plugins, but that worked for me.\n\nThere is now optional support for the [ESPAsyncWebServer](https://github.com/me-no-dev/ESPAsyncWebServer) library for async http server.  This library requires the [ESPAsyncTCP](https://github.com/me-no-dev/ESPAsyncTCP]) library to work on ESP8266, which should be installed automatically when you install the `ESPAsyncWebServer` through the ArduinoIDE _Library Manager_.  If both of these libraries are not installed the build will default to using the stock [ESP8266WebServer](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer) library included in the [ESP8266 core board support](https://github.com/esp8266/Arduino).\n\n## Usage\n\nThe ESP creates a captive WiFi network `Moonlight`. Use any browser connected to the same network to visit http://moon.local to\ncontrol the color. If your browser \"cannot find the server\" at that address for some reason the control interface can\nalso be reached at: `http://192.168.4.1`.\n\nAll of the web pages are self contained with no references to external resources so it will work anywhere. This also\nmakes the device more secure because no requests can be redirected to malicious content. Privacy is also respected for\nthe same reasons, Google and your ISP won't be tracking those requests if they never happen!\nWeb pages are stored on LittleFS and new files or updated content can be uploaded at: http://moon.local/edit.html\n\n## Features\n\n* Low battery waning. When the voltage level of the battery drops too low to produce accurate color the moon will turn red and fade up and down in brightness to alert the user that the battery needs to be recharged.\n* Save default color settings (including Rainbow mode) to EEPROM. Even though this board does not have a real EEPROM I decided to use the flash emulated EEPROM just to keep the hardware settings separate from the web pages that are stored on the LittleFS partition of the flash.\n\n## Building and Flashing\n\n`Config.h` can be edited, all configurable definitions have been moved there. If you need to change the type of RGB LED used or the pins the LED is connected to, that is the place to do it. This project was originally built using a common  All options are commented. \n\nCurrently this is the only way to set up STA mode and connect to an existing WiFI network, but the updated preferences storing subsystem already has support for storing up to three WiFi networks.  The WiFiMulti library has been used, so once a network control page and websocket handlers are added, the web interface should be used. Setting this option in Config.h may be removed after web UI configuration is added.\n\nAfter you have successfully build and uploaded the sketch you still need to upload the data files used by the HTTP server to the LittleFS filesystem in flash. If you have properly installed the [arduino-littlefs-upload](https:/ github.com/earlephilhower/arduino-littlefs-upload) plugin, it will appear in the _Command Palette_ (`[Ctrl] + [Shift] + [P]` or `[⌘] + [Shift] + [P]` on MacOS) as `Upload LittleFS to Pico/ESP8266`. This plugin will automatically create the LittleFS filesystem, add the files, and upload the content to the correct flash address.\n\n### LittleFS Upload Procedure\n\nAfter pressing **`[Ctrl]+[Shift]+[P]`**, I typed \"**`Upload`**\" after the prompt (**`\u003e`**). Click on \"**Upload** LittleFS to Pico/ESP8266\", which is being pointed to in the screenshot below.\n\n![Image](https://github.com/UncleGrumpy/Moonlight_8266/blob/main/upload_littlefs.png \"upload LittleFS screenshot\")\n\n### ArduinoIDE recommended settings\n\n- For extended battery life use 80 MHz for the CPU Frequency.\n- Recommended formatting is (FS: 192KB / OTA: ~406KB). FS should be at least 160KB.\n- IwIP variant: \"v2 Higher Bandwidth\"\n- Flash Mode: `qio`, if your module supports it. This will speed up reading the web pages from LittleFS. Otherwise `dio`. \n\n## Wiring Chart (ESP-01) for Moon Lamp\n\n| ESP-01 pin | resistor value |  RGB LED pin   |\n|:-----------|:--------------:|:---------------|\n| GPIO2 (D3) | 100 Ohm        | Red            |\n| GPIO1 (Tx) | 470 Ohm        | Green          |\n| GPIO3 (Rx) | 220 Ohm        | Blue           |\n| GPIO0      | Must be left floating for voltage measurements to work! | :x: |\n| __________ | _______________________________________________________ | ____________________________________________ |\n| 3v3        | :x:            | PWR - For common anode (default and recommended configuration) |\n| GND        | :x:            | GND - For common cathode (change `COMMON_ANODE` to `false` in **Config.h**) |\n\nFor other ESP8266 boards, you may use any other pins for the LED colors, but if you intend to\nuse the project battery powered `pin 0` should be left floating. This is necessary to take the ADC battery\nlevel reading, and change the lamp to red when the device needs recharging.\n\nThe ESP-01 uses 3.3 volts, if you are using a board with 5V (like Arduino) adjust your resistor\nvalues accordingly. Your RGB LED will likely be different so adjust the resistor values until you\nget a true bright white when all three are on at 100%. The easiest way to do this is just use the\nRGB LED and your test resistors on a breadboard with a 3.3V power supply. Even easier than fishing\nthrough a pile of resistors is to use 2 variable resistors and measure the final setting with a\nmultimeter. Either way use a 100 Ohm resistor (220r for 5V) for the red; it will always appear the\ndimmest, and find the sweet spot for the green and blue.\n\nFor battery powered operation I use a 100K resistor for the CH_PD pull-up. This minimized the\npower drain on the battery. You can use a 10K or 1K, or for bread boarding just connect it directly\nto the same 3.3V rail as the VCC.\n\nI used an 18650 Li-ion battery and USB charge/discharge module for power. After trying may buck \nconverters I ended up using a 1N4728 diode, in line with the + voltage as a voltage \"regulator\"\ninstead.  This is ABSOLUTELY NOT foolproof. My charge regulator stops charging at 4.1 volts, many\nwill charge up to 4.2 volts. If you are going to try this make sure to check your data sheets, take\nmeasurements and make adjustments if necessary.  This diode causes about a 1/2 volt drop, bringing\nthe output of a full battery down to 3.6 volts - the safe maximum voltage for the ESP-01. My battery\nregulator cuts power when the battery drops below 3.5 volts. Again this works out perfectly because\nthe ESP-01 can safely operate down to 3.0 volts, which is exactly the power being supplied after\nthe diode drops 1/2 volt. The over discharge protection of my module cuts power before the ESP browns\nout, but the LEDs will not be supplied with enough current to operate reliably when the battery is very\nnearly depleted.  That was a big part of my motivation to make the moon turn red and fade in and out when\nthe power was nearly depleted, along with having a way to provide a warning to the user.  The other\nbig advantage managing my voltage this way is that by leaving GPIO 0 floating you can take direct\nbattery readings with the ESP-01 without needing a voltage divider or any additional pins.  I plan on\nadding a battery level indicator to the web interface, but at the moment battery voltage is being\nreported on the JavaScript console of the web client.\n\n### A safer battery design\n\nIn the next hardware revision of this project I plan on using LiFePo4 batteries, which will not\nrequire the 1N4728 diode, since the entire safe range of the battery falls in the safe voltage\nrange of operation as an ESP8266, or other ESP32 chips.  This will just require adding one more\nconfiguration option to set the low voltage detect, since the voltage measured will be the actual\nbattery voltage (not the voltage after the drop caused by the diode).  These batteries are much\nsafer than Li-ion battery chemistry.\n\nFuture revisions will likely be based on a more modern chip like the ESP32-C2, C3 or ESP32-C6. The\nperformance VS power consumption of the newer RISC-V chips is far superior to the old 8266.\n\n## Note on future support\n\nIf I find the spare time I will a definition to the top of the file to allow inverting the pwm signal if\na common anode RGB LED is used, but this project is quite old and may be archived in the future.  I have\nplans on a much better version, that will support ESP32, and all of the common RGB LEDs, including\nNeoPixels, and DotStars in addition to the \"old school\" 4-pin RBG LEDs used in this version.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funclegrumpy%2Fmoonlight_8266","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funclegrumpy%2Fmoonlight_8266","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funclegrumpy%2Fmoonlight_8266/lists"}