← Back to branch summary

~toykeeper/flashlight-firmware/fsm

« back to all changes in this revision

Viewing changes to ToyKeeper/spaghetti-monster/anduril/anduril-manual.txt

  • Committer: Selene Scriven
  • Date: 2019-01-09 06:50:47 UTC
  • Revision ID: bzr@toykeeper.net-20190109065047-102wcw9xhovcxhi3
Wrote up a basic user manual for Anduril.

Show diffs side-by-side

added added

removed removed

Lines of Context:
ToyKeeper/spaghetti-monster/anduril/anduril-manual.txt
 
1
Anduril User Manual
 
2
-------------------
 
3
 
 
4
Anduril is an open-source firmware for flashlights, distributed under 
 
5
the terms of the GPL v3.  The sources can be obtained here:
 
6
 
 
7
  http://FIXME
 
8
 
 
9
 
 
10
Quick Start
 
11
-----------
 
12
 
 
13
After putting a battery in the light and tightening the parts together, 
 
14
the light should quickly blink once to confirm it has power and is now 
 
15
operational.  After that, basic usage is simple:
 
16
 
 
17
  - Click to turn the light on or off.
 
18
  - Hold the button to change brightness.
 
19
  - Release and hold again to change brightness the other way.
 
20
 
 
21
That is all the user needs to know for basic use, but there are many 
 
22
more modes and features available for people who want more.
 
23
 
 
24
Before reading the rest of this manual, it is recommended that users 
 
25
look at the Anduril UI diagram, which should be provided along with the 
 
26
flashlight.
 
27
 
 
28
 
 
29
Ramping / Stepped Ramping Modes
 
30
-------------------------------
 
31
 
 
32
Anduril's normal operation mode uses a smooth ramp or a stepped ramp, 
 
33
depending on which style the user prefers.
 
34
 
 
35
Each ramp has its own settings -- floor (lowest level), ceiling (highest 
 
36
level), and the stepped ramp can also have a configurable number of 
 
37
steps.
 
38
 
 
39
There are four ways to access this mode when the light is off:
 
40
 
 
41
  - Click: Turn on at the memorized brightness.
 
42
  - Hold: Turn on at the floor level.  The light should give a very 
 
43
    subtle dark blink when the user can let go of the button to stay at 
 
44
    the floor, or keep holding the button to ramp up.
 
45
  - 2 clicks: Turn on at the ceiling level.
 
46
  - Click, hold: Turn on at the ceiling level, then ramp down.
 
47
 
 
48
While the light is on, a few basic actions are available:
 
49
 
 
50
  - Click: Turn off.
 
51
  - 2 clicks: Go to or from turbo (full power).
 
52
  - Hold: Change brightness (up).  If the button was released less than 
 
53
    1 second ago, or if it's already at the ceiling, it goes down 
 
54
    instead.
 
55
  - Click, hold: Change brightness (down).
 
56
  - 3 clicks: Switch to the other ramp.
 
57
  - 4 clicks: Go to ramp config mode.
 
58
 
 
59
 
 
60
Other Modes
 
61
-----------
 
62
 
 
63
Anduril has several other modes too.  To access these, press the button 
 
64
more than 2 times when the light is off:
 
65
 
 
66
  - 3 clicks: Access the blinky / utility modes.
 
67
  - Click, click, hold: Access the strobe modes.
 
68
  - 4 clicks: Lockout mode.
 
69
  - 5 clicks: Momentary mode.
 
70
  - 6 clicks: Muggle mode.
 
71
 
 
72
 
 
73
Blinky / Utility Modes
 
74
----------------------
 
75
 
 
76
Click 3 times from Off to access Anduril's blinky / utility modes.  This 
 
77
always starts at battery check and the user can proceed to other blinky 
 
78
modes from there.  The sequence is:
 
79
 
 
80
  1. Battery check.
 
81
  2. Sunset mode.
 
82
  3. Beacon mode.
 
83
  4. Temperature check.
 
84
 
 
85
In all of these modes, some basic actions are available:
 
86
 
 
87
  - Click: Turn off.
 
88
  - 2 clicks: Next blinky mode.
 
89
 
 
90
Additionally, in beacon and temperature check modes:
 
91
 
 
92
  - 4 clicks: Go to the beacon config mode or thermal config mode.
 
93
 
 
94
In more detail, this is what each blinky / utility mode does:
 
95
 
 
96
  1. Battery check.
 
97
 
 
98
     Blinks out the battery voltage per cell.  Full is 4.2V, empty is 
 
99
     about 3.0V.  The light blinks the whole-number digit first, pauses, 
 
100
     then blinks out the "tenths" digit.  Then a longer pause, and it 
 
101
     repeats.
 
102
     So for 4.2V, it would be "blink-blink-blink-blink .. blink-blink".
 
103
 
 
104
     A "zero" digit is represented by a very quick blink.
 
105
 
 
106
  2. Sunset mode.
 
107
 
 
108
     This starts at a low level, then dims gradually for an hour, and 
 
109
     then shuts off.  It is intended for use when going to bed.
 
110
 
 
111
  3. Beacon mode.
 
112
 
 
113
     Blinks at a slow speed.  The light stays on for half a second, and 
 
114
     then stays off until the next blink.  The brightness and the number 
 
115
     of seconds between pulses is configurable:
 
116
 
 
117
       - Brightness is the user's last-ramped level, so set this in 
 
118
         ramping mode before starting beacon mode.
 
119
 
 
120
       - Speed is configured in beacon config mode.  Click 4 times to 
 
121
         enter beacon config mode, wait for the light to stutter, then 
 
122
         click to enter the number of seconds per blink.  For example, 
 
123
         to do a 10-second alpine beacon, click 10 times.
 
124
 
 
125
  4. Temperature check.
 
126
 
 
127
     Blinks out the current temperature in degrees C.  This number 
 
128
     should be pretty close to what a real thermometer says.  If not, it 
 
129
     would be a good idea to click 4 times to enter thermal config mode, 
 
130
     and calibrate the sensor.
 
131
 
 
132
     Thermal config mode has two settings:
 
133
 
 
134
     - Current temperature.  Click once per degree C to calibrate the 
 
135
       sensor.  For example, if the ambient temperature is 21 C, then 
 
136
       click 21 times.
 
137
 
 
138
     - Temperature limit.  This sets the maximum temperature the light 
 
139
       can reach before it will start doing thermal regulation to keep 
 
140
       itself from overheating.  Click once per degree C above 30.  For 
 
141
       example, to set the limit to 50 C, click 20 times.  The default 
 
142
       is 45 C.
 
143
 
 
144
 
 
145
Strobe / Mood Modes
 
146
-------------------
 
147
 
 
148
Anduril includes a few extra modes for a variety of purposes:
 
149
 
 
150
  - Candle mode
 
151
  - Bike flasher
 
152
  - Party strobe
 
153
  - Tactical strobe
 
154
  - Lightning storm mode
 
155
 
 
156
Click 3 times from Off to access these, but hold the third click for a 
 
157
moment.  Click, click, hold.  The last-used strobe mode is remembered, 
 
158
so it will return to whichever one you used last.
 
159
 
 
160
In all of these modes, a few actions are available:
 
161
 
 
162
  - Click: Turn off.
 
163
  - 2 Clicks: Next strobe / mood mode.
 
164
  - Hold: Increase brightness, or strobe faster.  (except lightning)
 
165
  - Click, hold: Decrease brightness, or strobe slower.  (except lightning)
 
166
 
 
167
Additionally, candle mode has one more action:
 
168
 
 
169
  - 3 clicks: Add 30 minutes to the timer.
 
170
 
 
171
In more detail, here is what each mode does:
 
172
 
 
173
  - Candle mode
 
174
 
 
175
    Brightness changes randomly in a pattern resembling a candle flame.  
 
176
    If a timer is set, it will run until the timer expires, then get 
 
177
    dimmer for one minute, then sputter and turn itself off.  Without a 
 
178
    timer, candle mode runs until the user turns it off.  Brightness is 
 
179
    configurable.
 
180
 
 
181
  - Bike flasher
 
182
 
 
183
    Runs at a medium level, but stutters to a brighter level once per 
 
184
    second.  Designed to be more visible than a normal ramping mode, but 
 
185
    otherwise works mostly the same.  Brightness is configurable.
 
186
 
 
187
  - Party strobe
 
188
 
 
189
    Motion-freezing strobe light.  Can be used to freeze spinning fans 
 
190
    and falling water.  Speed is configurable.
 
191
 
 
192
  - Tactical strobe
 
193
 
 
194
    Disorienting strobe light.  Can be used to irritate people.  Speed 
 
195
    is configurable, and the duty cycle is always 33%.
 
196
 
 
197
  - Lightning storm mode
 
198
 
 
199
    Flashes at random brightness and random speed to simulate lightning 
 
200
    strikes during a busy lightning storm.  Do not look directly at the 
 
201
    flashlight when this mode is running, because it may suddenly go to 
 
202
    full power without warning.
 
203
 
 
204
 
 
205
Lockout Mode
 
206
------------
 
207
 
 
208
Click 4 times from Off to enter Lockout mode.  This makes the light safe 
 
209
to carry in a pocket or a bag or anywhere else the button might be 
 
210
pressed by accident.
 
211
 
 
212
To exit lockout mode, click 4 times.  The light should blink briefly and 
 
213
then return to the regular "off" mode.
 
214
 
 
215
Lockout mode also doubles as a momentary moon mode, so the user can do 
 
216
quick tasks without having to unlock the light.  The brightness in 
 
217
lockout mode is determined by the floor setting of the current ramp.
 
218
 
 
219
 
 
220
Momentary Mode
 
221
--------------
 
222
 
 
223
Click 5 times from Off to enter Momentary mode.  This locks the 
 
224
flashlight into a single-mode interface where the LEDs are only on when 
 
225
the button is held down.  It is intended for Morse code and other 
 
226
signalling tasks.
 
227
 
 
228
Brightness is the last-ramped level, so adjust that before entering 
 
229
momentary mode.
 
230
 
 
231
To exit this mode, physically disconnect power by unscrewing the tailcap 
 
232
or battery tube.
 
233
 
 
234
 
 
235
Muggle Mode
 
236
-----------
 
237
 
 
238
Click 6 times from Off to enter Muggle mode.  This is a simpler and 
 
239
less-bright interface which makes the light relatively safe to lend to 
 
240
children or other people who could use the light unsafely.
 
241
 
 
242
In Muggle mode, there are only a few available actions:
 
243
 
 
244
  - Click: Turn the light on or off.
 
245
  - Hold: Change brightness.
 
246
  - 6 clicks: Exit Muggle mode.
 
247
 
 
248
The brightness in this mode usually goes from about 10 lm to 300 lm.
 
249
 
 
250
Muggle mode is remembered even after changing the battery.  This helps 
 
251
prevent children from exiting the mode by unscrewing the tailcap.  
 
252
However, be sure to supervise children whenever they are using any 
 
253
powerful tools, including a bright flashlight.
 
254
 
 
255
 
 
256
Configuration Modes
 
257
-------------------
 
258
 
 
259
Every config mode has the same interface.  The menu has one or more 
 
260
options the user can configure, and it will go through them in order.  
 
261
For each menu item, the light will follow the same pattern:
 
262
 
 
263
  - Blink one or more times, corresponding to the item number.
 
264
 
 
265
  - Stutter or "buzz" quickly between two brightness levels for a few 
 
266
    seconds.  This indicates that the user can click one or more times 
 
267
    to enter a number.  It will keep buzzing until the user stops 
 
268
    clicking, so there is no need to hurry.
 
269
 
 
270
  - Pause, and then go to the next option.
 
271
 
 
272
After the light has gone through all of the menu options, it should 
 
273
return to whatever mode the light was in before entering the config 
 
274
mode.
 
275
 
 
276
If the user doesn't press a button during a menu item's "buzz" phase, 
 
277
that item remains unchanged from its previous value.
 
278
 
 
279
 
 
280
Ramp Config Mode
 
281
----------------
 
282
 
 
283
While the light is on in a ramping mode, click 4 times to enter the 
 
284
config mode for the current ramp.
 
285
 
 
286
For smooth ramping mode, there are two menu options:
 
287
 
 
288
  1. Floor.  (default = 1/150)
 
289
  2. Ceiling.  (default = 120/150)
 
290
 
 
291
For the stepped ramping mode, there are three menu options:
 
292
 
 
293
  1. Floor.  (default = 20/150)
 
294
  2. Ceiling.  (default = 120/150)
 
295
  3. Number of steps.  (default = 7)
 
296
 
 
297
To configure the floor level, click the button equal to the number of 
 
298
ramp levels (out of 150) at which the floor should be.  To set the 
 
299
lowest possible level, click once.
 
300
 
 
301
To configure the ceiling level, each click goes one level lower.  So 1 
 
302
click sets the highest possible level, 2 clicks is the 2nd-highest, 3 
 
303
clicks is the 3rd-highest level, etc.  To set the default of 120/150, 
 
304
click 31 times.
 
305
 
 
306
When configuring the number of steps, the value can be anything from 2 
 
307
to 150.
 
308
 
 
309
 
 
310
Protection Features
 
311
-------------------
 
312
 
 
313
Anduril includes low voltage protection (LVP) and thermal regulation.
 
314
 
 
315
LVP makes the light step down to a lower level when the battery is low, 
 
316
and if the light is already at the lowest level, it shuts itself off.  
 
317
This activates at 2.8V.  LVP adjustments happen suddenly, in large 
 
318
steps.
 
319
 
 
320
Thermal regulation attempts to keep the light from overheating, and 
 
321
otherwise adjusts output to stay as close as possible to the 
 
322
user-configured temperature limit.  Thermal adjustments happen 
 
323
gradually, in steps so small they are difficult for humans to perceive.
 
324
 
 
325
 
 
326
Aux LEDs / Button LEDs
 
327
----------------------
 
328
 
 
329
Some lights have aux LEDs or button LEDs.  These can be configured to do 
 
330
different things while the main emitters are off.  There is one aux LED 
 
331
mode for the regular "off" mode, and another aux LED mode for "lockout" 
 
332
mode.  This allows the user to see at a glance whether the light is 
 
333
locked.
 
334
 
 
335
Aux LED modes typically include:
 
336
 
 
337
  - Off
 
338
  - Low
 
339
  - High
 
340
  - Blinking
 
341
 
 
342
To configure the aux LEDs, go to the mode you want to configure and then 
 
343
click the button a few times:
 
344
 
 
345
  - Off mode: 7 clicks.
 
346
  - Lockout mode: 3 clicks.
 
347
 
 
348
This should change the aux LEDs to the next mode supported on this 
 
349
light.