firmware
Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
parent directory.. | ||||
########################### ## XMAS-ICETUBE FIRMWARE ## ########################### The xmas-icetube firmware is a complete reimplementation of the Adafruit Ice Tube Clock firmware and runs on *both* the Adafruit Ice Tube Clock v1.1 and the xmas-icetube hardware revision. Since most users will be using the xmas-icetube firmware on the Adafruit Ice Tube Clock v1.1, the default firmware configuration is set for the Adafruit clock. The xmas-icetube firmware is discussed in the following Adafruit thread, which is a good place to post questions and comments: http://forums.adafruit.com/viewtopic.php?f=41&t=34924 ############## ## FEATURES ## ############## Many of the features in the xmas-icetube firmware were first implemented in other firmware projects; see the CREDITS file for details. This firmware boasts the following improvements over the official Adafruit firmware: - animated display transitions - multiple time and date formats - optionally pulse display during alarm and snooze - three alarm times for selectable days of the week - functional alarm during power outage - adjustable alarm volume (from 0 to 10) - progressive alarm option (gradually increasing volume) - selectable alarm sound (high frequency beeps, low frequency beeps, high frequency three beep pulse, low frequency three beep pulse, Merry Christmas, Big Ben, Reveille, or For He's a Jolly Good Fellow) - adjustable snooze duration - DST support (USA, EU, or manual) - fully automatic correction for time drift - time-from-GPS support* - temperature compensated timekeeping* - no beeping or time loss after external power failure - 4-fold or 25-fold* increase in backup battery life - low battery warning before battery failure - larger range for user-configured display brightness - per-digit brightness adjustment for uneven displays - automatic brightness control by ambient light* - optionally disable display during specified time periods - optionally disable display at night (when dark)* - IV-18 VFD tube driven to specifications* * For the Adafruit Ice Tube Clock v1.1, these hacks require hardware modification and support must be enabled by uncommenting macros in config.h. See the HACKS AND MODS section of this file as well as the comments in config.h for more information. For clock hackers, this firmware has (1) compatibility with the ATmega328p, (2) a pseudo object-oriented design, (3) good source code documentation, and (4) display/menus by finite state machine. ################## ## INSTALLATION ## ################## Installation requires GNU Make, avr-libc, avr-gcc, and avrdude; the instructions below presume proficiency with these tools. This firmware requires the ATmega328p, not the ATmega168v included with the Adafruit kit. Due to the many features, xmas-icetube currently requires around 30 kB of program memory, but the ATmega168v only has 16 kB. The ATmega328p also supports Atmel picoPower features that are used to extend battery life by 4-fold (and 25-fold with a minor hardware modification). The ATmega168v does not support picoPower. Note that if your ATmega328p has an Arduino bootloader installed, it will not work without reconfiguration. See the TROUBLESHOOTING section for reconfiguration instructions. To program the chip, any avrdude-compatible ISP programmer should work, but programming has been tested with the Adafruit USBtinyISP, the Atmel AVR Dragon, and an Arduino programed with the ArduinoISP sketch. Compilation and installation has been tested under (a) Ubuntu Linux 12.04 with the avr-gcc and avrdude packages, (b) MacOS 10.14.5 with CrossPack for AVR Development, and (c) Windows 10 with WinAVR and Cygwin's perl and bash packages. To compile and install this firmware, first configure compile-time options by editing the Makefile and config.h. Then build and install the project using the included Makefile: (1) Edit the Configuration Variables First, review the macro definitions in config.h, changing definitions as needed to enable support for various hardware hacks. The default values in config.h are suitable for the Adafruit Ice Tube Clock v1.1 and includes support for the autodimmer and GPS mods. For the xmas-icetube hardware revision, it may be more convenient to copy the config.h file from the hardware directory and edit that as desired: % cp ../hardware/config.h config.h Next, review the Makefile to ensure that configuration variables are reasonable given your hardware. In particular, AVRISP and AVRDUDEOPT seem most likely to require attention. (2) Compile the Firmware Build icetube_fuse.hex, icetube_flash.hex, icetube_eeprom.hex, and icetube_lock.hex which contain the fuse bits, program memory (flash), EEPROM data, and lock bits: % make (3) Connect the Programmer Ensure the clock has an ATmega328p installed and not an ATmega168v. Unplug and disassemble the clock. Remove the side PCB with VFD tube. Make sure that the AVR programmer will not provide power to the clock. (For the Adafruit USBtinyISP, this means ensuring that the power jumper is not installed.) Connect the AVR programmer to the clock's ISP header, ensuring that pin one on the cable and the marked pin on the clock's ISP header match. Finally, power the clock board with the external power adaptor. (4) Install the Firmware Install this firmware to an ATmega328p by setting the fuse bits, writing the flash program, writing the EEPROM data, and setting the lock bits: % make install-all Alternatively, this firmware may be installed or upgraded in separate steps. If you wish not to set lockbits or not to overwrite the EEPROM (clock settings), simply skip those commands below. % make install-fuse % make install-flash % make install-eeprom % make install-lock (5) Verify Successful Programming (Optional, but Recommended) To ensure that the chip has been successfully programmed, one may check the chip data against what should have been installed in the previous step: % make verify-all One may also verify the individual sections of programmed memory. The following commands are equivalent to "make verify-all": % make verify-fuse % make verify-flash % make verify-eeprom % make verify-lock ##################### ## USING THE CLOCK ## ##################### The USAGE file contains an overview of how to use the clock. #################### ## HACKS AND MODS ## #################### Development of the various hacks and mods supported by this firmware have been discussed extensively on the Adafruit discussion board. Options requiring hardware changes can be enabled by uncommenting macros in the config.h file. Comments in the config.h describe each optional feature in detail. :: Automatic Display Dimming :: http://forums.adafruit.com/viewtopic.php?f=41&t=12932 http://forums.adafruit.com/viewtopic.php?p=219736#p219736 :: Temperature Compensated Timekeeping :: http://forums.adafruit.com/viewtopic.php?f=41&t=14941 http://forums.adafruit.com/viewtopic.php?f=41&t=43998 :: GPS Timekeeping :: http://forums.adafruit.com/viewtopic.php?f=41&t=36873 http://learn.adafruit.com/ice-tube-clock-kit/mods http://forums.adafruit.com/viewtopic.php?f=41&t=32660 :: Extended Battery Life :: http://forums.adafruit.com/viewtopic.php?f=41&t=36697 :: IV-18 To-Spec Hack :: http://forums.adafruit.com/viewtopic.php?f=41&t=41811 :: Reliably Sleeping During Power Failure :: http://forums.adafruit.com/viewtopic.php?f=41&t=22515 :: Automatic Drift Correction :: http://forums.adafruit.com/viewtopic.php?f=41&t=12720 :: Per-Digit Brightness Adjustment :: http://forums.adafruit.com/viewtopic.php?f=41&t=23586 ##################### ## TROUBLESHOOTING ## ##################### :: General Troubleshooting :: For many hardware issues, the Adafruit FAQs are quite helpful: http://forums.adafruit.com/viewtopic.php?f=41&t=27032 http://learn.adafruit.com/ice-tube-clock-kit/faq The Adafruit Clocks forums is an excellent place to ask for help: http://forums.adafruit.com/viewforum.php?f=41 :: Reset and Diagnostic Messages :: After a reset, the microcontroller will examine MCUSR (microcontroller unit status register) to determine the reason for the reset, and the display will alternate between the restored time and a message showing the cause of the reset. Reset messages can be dismissed by setting the time, as the time is usually wrong after a reset. "bod rset" (brown out detection reset): The clock was reset due to insufficient voltage. This usually happens when power is lost and the backup battery is nearly dead. "pin rset" (external reset): The clock was reset by an external signal to the microcontroller reset pin (pin 1). Programming the clock through the ISP header will trigger an external reset. Accidently shorting the reset pin to ground will do the same. This message used to read "ext rset", but the "x" looked more like an "H". "pwr rset" (power reset): The clock started up after a complete power loss. This usually happens if the clock loses external with without a backup battery or with a completely dead backup battery. "wdt rset" (watchdog timer reset): During normal operation the clock will periodically reset the watchdog timer. If this timer expires, the clock is behaving abnormally and will reset itself in an attempt to fix the problem. Usually watchdog timer resets are caused by problems with the crystal oscillator; see the troubleshooting entry on crystal oscillator problems. "oth rset" (other reset): If no flags were set in MCUSR to indicate the cause of the reset, the display will flash "oth rest". In theory, this should never happen. The clock might also flash one of the following status messages: "bad batt" (low battery warning): The microcontroller checks the system voltage whenever the clock sleeps for more than ten minutes. When the battery is low, the display will flash "bad batt" after the clock wakes, and the message can be dismissed by pressing any button. "gps lost" (GPS signal lost; only applies if GPS_TIMEKEEPING was defined in config.h): The clock is receiving data from the GPS, but the GPS has been unable to acquire a signal for at least three minutes. "temp err" (temperature sensor error; only applies if TEMPERATURE_SENSOR was defined in config.h): If the microcontroller is unable to communicate with the temperature sensor, the display will flash "temp err". :: Programming Fails with an Arduino Chip :: The Arduino Uno chip is an ATmega328p, but will not work in an Ice Tube Clock without reconfiguration. Arduino chips have their fuse settings configured to use an external 16 MHz oscillator for the system clock. The Ice Tube Clock does not provide a suitable external oscillator, and without an external oscillator, an Arduino chip will not function--not even to be reconfigured. To provide an external oscillator for reconfiguration, insert the Arduino chip into an Arduino board. Next, connect a programmer to the ISP on the Arduino board and reprogram the fuses with the xmas-icetube Makefile: "make install-fuse". The ATmega328p's fuse settings are now configured to use the 8 MHz internal oscillator and can be installed and programmed as described in the INSTALLATION section. This method is also described in the following thread: http://forums.adafruit.com/viewtopic.php?p=184722#p184722 :: Other Programming Failures :: First, ensure that the hardware is connected properly, as described in the installation instructions above. Second, double check the Makefile configuration section, paying particular attention to the AVRISP and AVRDUDEOPT macros. Third, try programming the chip at a lower bit rate by changing the "-B 2" option to "-B 25" in the AVRDUDEOPT macro: AVRDUDEOPT ?= -B 25 -P usb -c $(AVRISP) -p $(AVRMCU) Fourth, if the chip cannot be programmed in the clock, try programming it in a development board such as the Arduino Uno. Finally, it's possible that the chip is somehow damaged or bricked; usually, the simplest solution is to simply replace the ATmega328p with a new chip and try again. :: Dim Digits :: The per-digit brightness control in the xmas-icetube firmware provides one way to increase the brightness of dim digits. With Adafruit clocks, a dim initial or final digit is almost invariably due to insufficient filament current. In those cases, increasing filament current usually produces better results, but increasing current may also introduce a brightness gradient across the display when the menu-configured brightness level is low. To find the optimal current for a given clock, a good approach is to gradually increase current across the filament until all digits have consistent brightness at the highest menu-configured brightness setting: First, upgrade Q3 to a FET capable of supplying more current. One such FET is the ZVP2110A available from Digi-Key or Mouser.** If the digit remains dim after upgrading Q3, replace R3 with an 11 ohm resistor to further increase current. And if the digit is still dim, replace R3 with a jumper. Note that Q3 provides power to both the filament and VFD driver chip. Replacing R3 with a jumper or smaller resistor without first upgrading Q3 will increase filament current, but might also result in an insufficient logic supply voltage to the VFD driver chip. That, in turn, could cause faulty display operation. **UPDATE: For anyone who purchased an official Adafruit kit, Adafruit will now provide a free ZVP2110A to resolve the issue: http://forums.adafruit.com/viewtopic.php?p=340772#p340772 :: Flaky Segments :: On some Adafruit clocks, display segments are flaky. The exact symptoms vary depending on the particular clock, but most commonly, the clock will start normally and segments will quickly stop working until few or no segments are active. Also common is a display that only shows one or two blinking segments. But occasionally the symptoms are more bizarre such as a display with all digits and segments continuously lit or a single digit going blank at a certain time. The following threads describe the flaky segment problem and several solutions in more detail: http://forums.adafruit.com/viewtopic.php?f=41&t=47733 http://forums.adafruit.com/viewtopic.php?f=41&t=49619 http://forums.adafruit.com/viewtopic.php?f=41&t=50823 http://forums.adafruit.com/viewtopic.php?f=41&t=51207 The flaky segment problem can be solved by replacing Q3. Although Adafruit will provide a free replacement for Q3, I recommend replacing Q3 with a better FET, such as the ZVP2110A available from Digi-Key or Mouser.** By providing additional current across the VFD filament, the ZVP2110A will also eliminate the dim digit problem described in the previous entry as well as extending tube life by slowing cathode poisoning. **UPDATE: For anyone who purchased an official Adafruit kit, Adafruit will now provide a free ZVP2110A to resolve the issue: http://forums.adafruit.com/viewtopic.php?p=340772#p340772 :: Nonfunctional Drift Correction :: Initially the clock will not perform drift correction. Use the clock normally and the automatic drift correction will eventually enable itself. Accuracy will improve over time. The clock estimates time drift when users change the time by more than 15 seconds. The fastest way to enable drift correction is to (1) set the correct time, (2) wait for the clock to drift by more than 15 seconds, and (3) set the correct time. Occasionally setting an incorrect time will not have much effect on drift correction, and changing time for different timezones or daylight saving is similarly unproblematic. The automatic drift correction method is quite robust: http://forums.adafruit.com/viewtopic.php?p=178611#p178611 :: Crystal Oscillator Problems ("wdt rset") :: The ATmega328p is more prone to oscillator issues than the ATmega168v, and users occasionally encounter oscillator problems after upgrading. Oscillator problems usually result in inconsistent timekeeping; the clock may keep accurate time one day, but not on another. When oscillator problems are severe, the microcontroller's watchdog circuit will detect that time is not advancing and reset the clock in an attempt to fix the problem. After such a reset, the clock will beep and display "wdt rset" to indicate possible time loss due to a watchdog reset. Fixing oscillator issues requires some trial and error, but following the procedure below will likely fix the problem. First, excess flux or burnt flux can cause oscillator problems. Sometimes cleaning the board thoroughly with flux cleaner--or simply alcohol and a toothbrush--will solve the problem. Second, the 20 pF oscillator capacitors included in the Adafruit kit are a bit large. Replacing C8 and C9 with with 10 pF caps will sometimes fix the oscillator. Even if the clock is functioning normally, installing 10 pF caps will increase timekeeping accuracy. Finally, replacing the crystal will sometimes resolve the issue. The replacement should be another 32.768 kHz crystal with a 12.5 pF load capacitance and equivalent series resistance of 30 kOhm or less. The AB38T-32.768KHZ is a good choice and is available from Digi-Key or Mouser. When installing and soldering the crystal, gently push the crystal through the circuit board until there is 2-3 mm of space between the bottom of the crystal and the circuit board. Leaving this space prevents undue stress on the leads which could damage the crystal; it also ensures solder will not make unwanted electrical contact with the metallic crystal housing. The following threads provide more information on oscillator issues after upgrading to the ATmega328p: http://forums.adafruit.com/viewtopic.php?p=189366#p189366 http://forums.adafruit.com/viewtopic.php?f=41&t=51960 ############# ## LICENSE ## ############# The xmas-icetube firmware may be used as described in the LICENSE file.