# Overview NeoCandle is a simple tea light candle simulation based on ATtiny25/45/85 using 5mm NeoPixels (WS2812), LDR light sensor (GL5528) and IR remote receiver (TSOP4838). It can be controlled by an IR remote control with two buttons and has a timer mode for automatic shutdown after a set time as well as an LDR mode in which the candle is automatically switched on and off depending on the intensity of the ambient light. - Project Video (YouTube): https://youtu.be/n4UFV3BMcBM - Firmware (Github): https://github.com/wagiminator/ATtiny85-TinyCandle  # Software ## Candle Simulation The simulation code is based on the great work of [Mark Sherman](https://github.com/carangil/candle). With most LED candles, the random flickering is rather silly and lacks the spooky element of candlelight: shadows cast by the candle move because the flame is in motion. With NeoCandle, four NeoPixels are arranged in a square, the intensity of the four LEDs forms a "center" of light balance that can be moved around smoothly. This 'physics-based' candlelight has the following properties: - The flame has a position and a velocity. - If the position is not centered, the velocity will accelerate towards the center in proportion to the displacement (hooke's law of springs). - The velocity has a very small damping value, which means that corrections towards the center always overshoot a bit (underdamped system). - Random "pushes" into the center position of the light are performed to mimic random drafts. - The strength of the drafts changes periodically (alternating periods of calm and windiness). ## NeoPixel Implementation The control of NeoPixels with 8-bit microcontrollers is usually done with software bit-banging. However, this is particularly difficult at low clock rates due to the relatively high data rate of the protocol and the strict timing requirements. The essential protocol parameters for controlling the WS2812 NeoPixels (or similar 800kHz addressable LEDs) can be found in the [datasheet](https://cdn-shop.adafruit.com/datasheets/WS2812.pdf).  Fortunately, the timing is nowhere near as strict as the data sheet suggests. The following timing rules can be derived from the excellent articles by [Josh Levine](https://wp.josh.com/2014/05/13/ws2812-neopixels-are-not-so-finicky-once-you-get-to-know-them/) and [Tim](https://cpldcpu.wordpress.com/2014/01/14/light_ws2812-library-v2-0-part-i-understanding-the-ws2812/) and should **work with all 800kHz addressable LEDs**: |Pulse|Parameter|Min|Typical|Max| |:-|:-|-:|-:|-:| |T0H|"0"-Bit, HIGH time|65 ns|350 ns|500 ns| |T1H|"1"-Bit, HIGH time|625 ns|700 ns|8500 ns| |T0L|"0"-Bit, LOW time|450 ns|800 ns|8500 ns| |T1L|"1"-Bit, LOW time|450 ns|600 ns|8500 ns| |TCT|Total Cycle Time|1150 ns|1250 ns|9000 ns| |RES|Latch, LOW time|9 µs|50 µs|280 µs| Apart from T0H, the maximum values can be even higher, depending on when the NeoPixels actually latch the sent data (with some types only after 280µs!). This also makes it possible to work without a buffer and thus without the use of SRAM. The software essentially only has to ensure that **T0H is a maximum of 500ns and T1H is at least 625ns**, so that the pixels can reliably differentiate "0" from "1" and that the time between sending two bytes is less than the latch time. Assuming that the microcontroller runs with a clock frequency of 8 MHz, the following simple bit-banging function for the transmission of a data byte to the NeoPixels string was implemented: ```c // Send a byte to the pixels string void NEO_sendByte(uint8_t byte) { // CLK comment uint8_t count = 8; // 8 bits, MSB first asm volatile ( "sbi %[port], %[pin] \n\t" // 2 DATA HIGH "sbrs %[byte], 7 \n\t" // 1-2 if "1"-bit skip next instruction "cbi %[port], %[pin] \n\t" // 2 "0"-bit: DATA LOW after 3 cycles "add %[byte], %[byte] \n\t" // 1 byte Board -> ATtinyCore** and select **ATtiny25/45/85 (No bootloader)**. - Go to **Tools** and choose the following board options: - **Chip:** ATtiny25 or 45 or 85 (depending on your chip) - **Clock:** 8 MHz (internal) - **Millis/Micros:** disabled - **B.O.D.Level:** disabled - Leave the rest at the default settings - Connect your programmer to your PC and to the ICSP header on the board. - Go to **Tools -> Programmer** and select your ISP programmer (e.g. [USBasp](https://aliexpress.com/wholesale?SearchText=usbasp)). - Go to **Tools -> Burn Bootloader** to burn the fuses. - Open NeoCandle sketch and click **Upload**. ### If using the precompiled hex-file - Make sure you have installed [avrdude](https://learn.adafruit.com/usbtinyisp/avrdude). - Connect your programmer to your PC and to the ISCP header on the board. - Open a terminal. - Navigate to the folder with the hex-file. - Execute the following command (if necessary replace "t85" with your chip and "usbasp" with the programmer you use): ``` avrdude -c usbasp -p t85 -U lfuse:w:0xe2:m -U hfuse:w:0xd7:m -U efuse:w:0xff:m -U flash:w:neocandle.hex ``` ### If using the makefile (Linux/Mac) - Make sure you have installed [avr-gcc toolchain and avrdude](http://maxembedded.com/2015/06/setting-up-avr-gcc-toolchain-on-linux-and-mac-os-x/). - Connect your programmer to your PC and to the ICSP header on the board. - Open the makefile and change the chip if you are not using ATtiny85 and the programmer if you are not using usbasp. - Open a terminal. - Navigate to the folder with the makefile and the Arduino sketch. - Run "make install" to compile, burn the fuses and upload the firmware. # Operating Instructions - Connect a 5V power supply to the Micro-USB socket or a battery to the respective board header. - The NeoCandle should immediately mimic the flickering of a candle. The device is now in **TIMER mode** and switches off automatically after the time programmed in the code has elapsed. You can switch it off at any time by pressing the power-off button on the IR remote control and switch it back on with the power-on button. - If the power-on button on the IR remote control is pressed while the NeoCandle is switched on, it changes to **LDR mode**. This change is indicated by a short blue light animation. In LDR mode, NeoCandle switches on and off automatically depending on the intensity of the ambient light. Pressing the power-on or power-off button on the IR remote control switches back to TIMER mode. # References, Links and Notes 1. [ATtiny25/45/85 Datasheet](https://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-2586-AVR-8-bit-Microcontroller-ATtiny25-ATtiny45-ATtiny85_Datasheet.pdf) 2. [WS2812 Datasheet](https://cdn-shop.adafruit.com/datasheets/WS2812.pdf) 3. [TSOP4838 Datasheet](https://www.vishay.com/docs/82459/tsop48.pdf) 4. [GL5528 Datasheet](https://cdn.sparkfun.com/datasheets/Sensors/LightImaging/SEN-09088.pdf) 5. [Josh Levine's Article about NeoPixels](https://wp.josh.com/2014/05/13/ws2812-neopixels-are-not-so-finicky-once-you-get-to-know-them/) 6. [Tim's Article about NeoPixels](https://cpldcpu.wordpress.com/2014/01/14/light_ws2812-library-v2-0-part-i-understanding-the-ws2812/) 7. [AdaFruit NeoPixel Überguide](https://cdn-learn.adafruit.com/downloads/pdf/adafruit-neopixel-uberguide.pdf) 8. [Candle Simulation Implementation by Mark Sherman](https://github.com/carangil/candle) 9. [Lightweight Random Number Generator by Łukasz Podkalicki](https://blog.podkalicki.com/attiny13-pseudo-random-numbers/) 10. [IR Receiver Implementation](https://github.com/wagiminator/ATtiny13-TinyDecoder) 11. [TinyCandle for ATtiny13A](https://github.com/wagiminator/ATtiny13-TinyCandle)    # License  This work is licensed under Creative Commons Attribution-ShareAlike 3.0 Unported License. (http://creativecommons.org/licenses/by-sa/3.0/)