3
As this is my first micro controller project, please don't expect perfect
4
code. Hints on where I went wrong and how to do things right are always
5
welcome. Please send all constructive criticism, questions, feature
6
requests, patches, fan mail, hate mail, legal threats etc. to tido@4gh.eu
7
or join the discussion on the Budget Light Forum: http://budgetlightforum.cz.cc
9
This is the third alpha release of the BLF-VLD. It can be built in three
10
configurations, namely simple, fixed and programmable modes. In simple mode,
11
the user can only use the standard modes configured at compile time. In fixed
12
and programmable mode, the user can switch from the main mode group to the
13
extended group by repeatedly switching modes for a certain count of times
16
In extended mode the user can cycle through all mode lines defined
17
in EEPROM. After staying in one mode for more than two seconds, the light
18
will return to the standard mode group the next time it is switched on. The
19
light will give a short visual feed back (two short blinks) upon entering and
20
leaving the extended mode group.
22
In programmable mode, the user may assign any mode from the extended mode
23
group to any mode slot in the standard mode group. See the instructions below
24
on how to perform mode programming
26
What to do with the source
27
==========================
29
To build the driver, you will need the gcc-avr tool-chain (gcc, binutils,
30
avr-libc) plus other standard development tools. Since this program is
31
entirely useless to anyone without the necessary hardware to flash it
32
into the ATtiny and anyone in possession of said hardware can reasonably
33
be expected to be knowledgeable enough on where to get and how to use this
34
tools, I will not go into details on how to build and install. Just look
35
at the source and you will know what to do. I have developed and tested
36
this on an ATtiny13, running off the internal oscillator at 4.8MHz.
38
The archive contains an Eclipse C/C++ AVR project and can be imported as such.
40
The driver can also be built from the command line, just cd into one of the
41
configuration dirs ("Default", "Fixed Modes", "Programmable", "Simple") and
42
type 'make'. If your tool chain is set up correctly, this should build, among
43
other things, the files BLF-VLD.hex and BLF-VLD.eep, which are the flash and
44
eeprom images that need to be flashed into the ATtiny.
46
The archive contains prepared images in each configuration directory. "Simple"
47
is a simple 3-mode driver with just low, medium and high modes.
49
"Fixed Modes" has the same modes in the standard mode group, but the extended
50
mode group can be accessed by switching modes six times in a row.
52
With the "Programmable" driver, any mode of the extended mode group can be
53
assigned to any mode slot in the standard group. See below on how to do this.
57
How to program the modes
58
========================
60
To enter programming mode, first choose the mode slot you wish to reassign and
61
stay in that mode for more than two seconds. Now change mode NUM_EXT_CLICKS
62
times in a row. The light will give a short blink and enter the extended
63
mode group. Choose the mode you wish to assign and stay in it for more than
64
two seconds, then switch the light off. When switched on again, the light
65
will give a short blink and you will have to lock in the new mode.
67
To acknowledge the programming, you will have to follow a timed sequence of
68
"taps". "Tapping" means turning the light on for only a short period of time.
69
A short tap is less than 1 second, a long tap is between 1 and 2 seconds. To
70
lock in the programming, you will have to tap short-short-long-short. If the
71
driver has been compiled with the proghelper enabled, the light will signal
72
the appropriate moment to switch off by briefly rising or lowering the light
73
level, depending on the current light mode.
75
Setting up battery monitoring
76
=============================
78
Battery voltage monitoring is configured via the following #defines:
81
If defined, battery monitoring will be compiled into the driver.
84
Battery voltage is monitored via the analog-to-digital converter, which
85
returns a value in the range of 0 to 255. Low battery voltage handling
86
will be activated if the measured value is smaller than the one given here.
87
The actual threshold to use here depends on how the monitoring circuitry
88
is set up. See below for an explanation on how to calculate this value.
89
For most variants of the NANJG-101-AK, a threshold value of 130 will
93
Enable gradual lowering of the light level. If the driver detects a low battery
94
level, it starts halving the output level every five seconds until the voltage
95
stabilizes or LOWBAT_MIN_LVL is reached. If not defined, light will switch to
96
LOWBAT_MIN_LVL immediately.
99
PWM level to fall back to if a low battery situation is detected. If
100
LOWBAT_RAMPDOWN is not defined, LOWBAT_MIN_LVL is compared to the current
101
PWM level and the smaller one is set. If LOWBAT_RAMPDOWN is defined, the ramping
102
down will not go below this level.
105
If LOWBAT_RAMPDOWN is defined, the light will lower the PWM level to
106
LOWBAT_MAX_LVL (if current PWM level is higher) and start ramping down until
107
the battery's voltage stabilizes.
110
ADC channel to use, depending on which pin of the ATtiny13 is connected.
117
To make sure the ADC works correctly, the digital input for pin used for
118
measuring is explicitly disabled.
125
The ADC has to be clocked between 50kHz and 200kHz. The clock is generated
126
from the system clock and needs to be scaled down. For systems running at
127
4.8MHz or 9.6MHz a prescaler value of 64 is adequate, systems running at
128
1.2MHz will need a prescale factor of 32.
132
How to compute the low voltage threshold:
133
==========================================
135
Most driver PCBs sold by DX and KD contain the necessary circuitry to monitor
136
the battery's voltage (V_bat). This is done by using the ATtiny13's
137
analog-to-digital converter (ADC) and the internal 1.1V reference (V_ref).
138
To measure the battery's voltage, which is usually in the 3V-4V range, V_cc is
139
connected to the measuring pin via a voltage divider. This is necessary
140
because the ADC can only measure voltages smaller or equal to the reference.
142
As there usually is a diode in front of the µC to provide reverse polarity
143
protection, V_cc is 200mV to 600mV lower than V_bat. We will call this voltage
146
The voltage divider consists of two resistors in series, connecting V_cc to
147
ground. The voltage between the resistors is measured by the ADC and can be
148
expressed by the following formula:
150
V_adc = V_cc * (R2 / (R1 + R2))
152
The ADC is set to measure with 8 bit resolution in the range from 0V to V_ref.
153
The value returned by the ADC can be expressed by this formula:
155
val = 255 * (V_adc / V_ref);
157
By subsequently substituting V_adc and V_cc, we get the following formula:
159
val = ((V_bat - V_diode) * R2 * 255) / ((R1 + R2) * V_ref)
161
Now we can substitute the component values and the desired target voltage
162
to get the ADC value at which the battery alert should be triggered.
164
Example 1 (older NANJG-101-AK):
167
V_bat = 3V <= target voltage
171
val = ((3.0V - 0.6V) * 3kOhm * 255) / ((10kOhm + 3kOhm) * 1.1V) = 128
173
Example 2 (newer version):
180
val = ((3.0V - 0.2V) * 4.7kOhm * 255) / ((18kOhm + 4.7kOhm) * 1.1V) = 134
182
In conclusion, a value of 130 is usually a good compromise for PCBs with usable
189
There are two types of mode switching. The standard one uses only the
190
resources available in the MCU and works by measuring how long the light
191
has been switched on to determine if the mode should be changed on start up.
192
If the light is switched off within two seconds after being turned on, it will
193
switch mode the next time it is started. As this way does not depend an any
194
external hardware, it will work with every driver PCB.
196
The second method samples an I/O pin on startup and switches modes if it is
197
in a certain state (high or low). Some PCBs connect a capacitor to an I/O pin,
198
which will keep it above a certain voltage level for some time after the power
199
has been cut. This way, the MCU can read the pin on start up and determine,
200
if the power was off for only a short time (usually less than 2 seconds). In
201
this case, the light switches to the next mode.
203
Pin state based mode switching may be enabled and configured via the following
207
Enable pin state mode switching.
210
Define the pin to query, e.g. PB4.
213
If defined, a high level indicates mode switch, otherwise a low level is used.
216
If defined, the pin is set to high or low (depending on PS_HIGH) while the
217
light is switched on. This way, a capacitor connected to the pin can be
218
charged or discharged.
added
removed
Tido/BLF-VLD/docs/README
