The UI toolkit is called Spaghetti Monster, or FSM for short.

(pictured: the [insert your preferred F-word] Spaghetti Monster)

FSM implements an event-driven finite state machine for cooperative multitasking, and attempts to abstract out most of the hardware-specific details so the main code can focus entirely in the interface.

The basic idea is that you #define some options, #include a single file, and then start writing a UI. The UI consists of one or more State objects for the finite state machine, a setup() function, a loop() function, and whatever else you need for the particular UI.

State objects are actually just callback functions. They take an Event type and a 16-bit integer parameter, and they are expected to return "EVENT_HANDLED" or "EVENT_NOT_HANDLED" depending on whether they do anything with the Event they're given. States can be stacked, so if the top-most State doesn't handle an Event, an underlying State gets a chance to handle it instead. The stacking also means it's possible to have utility States which do common tasks like "ask the user to enter a number, then return to the previous state". It can just pop() itself off the stack and return to the previous State without having to care what that State was.

The setup() function runs once every time power is connected. It should do things like loading eeprom and then pushing a default State onto the stack.

The loop() function runs repeatedly, whenever the MCU is otherwise idle. It's for doing long-running tasks, like blinking out a SOS pattern... or for tasks which shouldn't happen until the system is idle, like going into standby mode.

It can also have a low_voltage() function which runs whenever LVP activates, or this can be implemented by handling the EV_voltage_low Event on a per-state basis. Similar story for thermal regulation.

Otherwise most of the UI code ends up fairly similar to how I usually describe UIs. It's a list of States, and each State has a list of Events it accepts and the corresponding actions to take for each Event.

For example, let's say we wanted the following UI, similar to an Olight Baton:

• From off:
  • 1 click: Go to lowest level.
• While on:
  • 1 click: Turn off.
  • Hold: Ramp up one step. At highest level, loop back to lowest level.
  • When voltage is low, ramp down in steps then turn off.

The code would look something like this:

uint8_t off_state(Event event, uint16_t arg) {
    if (event == EV_enter_state) {
        go_to_standby = 1; // sleep while off
        return EVENT_HANDLED;
    }
    // 1 click: go to lowest level
    else if (event == EV_1click) {
        set_state(ramp_state, 1);
        return EVENT_HANDLED;
    }
    return EVENT_NOT_HANDLED;
}

uint8_t ramp_state(Event event, uint16_t arg) {
    // turn LED on when we first enter the mode
    if (event == EV_enter_state) {
        set_level(arg);
        return EVENT_HANDLED;
    }
    // 1 click: off
    else if (event == EV_1click) {
        set_state(off_state, 0);
        return EVENT_HANDLED;
    }
    // hold: change brightness every HOLD_TIMEOUT ticks
    else if (event == EV_click1_hold) {
        if ((arg % HOLD_TIMEOUT) == 0) {
            set_level((actual_level+1) % (MAX_LEVEL));
        }
        return EVENT_HANDLED;
    }
    return EVENT_NOT_HANDLED;
}

void low_voltage() {
    // step down by one level or turn off
    if (actual_level > 1) {
        set_level(actual_level - 1);
    }
    else {
        set_state(off_state, 0);
    }
}

void setup() {
    // turn on at lowest level when battery is connected
    push_state(ramp_state, 1);
}

void loop() {
}

That's pretty much all it takes to implement a very basic Baton-like stepped ramping UI.

This example is only missing a couple small things to make it actually compile and run, like the config #defines and #include at the top, some declarations, and a ramp table for PWM values.  It's intended as a simple introduction to how FSM works.  Or for a more complete version which has more features, here is one which actually compiles.

I hope it's fairly easy to read, as far as C code goes, and easy to modify.  The point of all this is to take the "spaghetti code" normally involved in writing firmware...  and lock it in a box where you don't have to see it or care about it.  All the spaghetti bits are hidden away under the hood.

The code is available in two branches...  "trunk" for the stable version, or the "fsm" branch for more up-to-date development:

http://bazaar.launchpad.net/~toykeeper/flashlight-firmware/fsm/files/head:/ToyKeeper/spaghetti-monster/

Here’s a summary of FSM-based interfaces created so far.

Momentary

A simple on-off interface.

• Hold the button: Light is on.
• Release the button: Light is off.

Mostly added as an example.

Baton

Similar to the Olight Baton series.

From off:

• 1 click: Turn on at last-ramped level.
• Hold: Lowest level, then ramp up in steps.
• 2 clicks: Highest level.
• 4 clicks: Soft lockout.

While on:

• 1 click: Off.
• Hold: Ramp up in steps. Loops back from highest level to lowest.
• 2 clicks: Go to/from highest level.

Soft lockout:

• 4 clicks: Turn on at “low” level.

Includes LVP and thermal regulation.

DarkHorse

Nearly exact clone of Zebralight’s UI from 2016.

From off:

• 1 click: High mode.
• 2 clicks: Med mode.
• 3 clicks: Blinky mode.
• 4 clicks: Battcheck mode.
• Hold: Low mode, then ramp up.

Low/med/high modes:

• 1 click: Off.
• Hold: Ramp through low, med, and high… always starting at low.
• 2 clicks: Toggle between H1/H2, M1/M2, or L1/L2 levels.
• Click, hold: Change the brightness of current mode’s secondary (H2/M2/L2) level.

Battcheck mode:

• Blinks 1 to 4 times then turns itself off. (0 blinks for less than 3.0V, 5 blinks for more than 4.2V)

Blinky mode:

• 1 click: Off.
• 2 clicks: Go to next blinky mode. The sequence is:
  • 0.2 Hz beacon at L1
  • 0.2 Hz beacon at H1
  • 4 Hz tactical strobe at H1
  • 19 Hz tactical strobe at H1

Remembers a few things after battery change:

• Primary or secondary toggle for high/med/low.
• H2/M2/L2 levels.
• Which blinky was last used.

Includes LVP and thermal regulation.

Andúril

Fancy all-in-one UI inspired by Tom E’s fantastic Narsil. It’s still a work in progress, so it’s expected to change.

I should probably mention that the smooth and discrete ramps have independent floor/ceiling values. You can have one with the ceiling all the way up, and one with the ceiling at a comfortable safe level. Or you can have one with moon and one without.

Discrete ramp mode has anywhere from 2 to 150 steps, spaced evenly (or as close to “even” as possible with integers).

A “hold” always ramps up, and a “click-release-hold” always ramps down.

Sorry about the 5-click action for momentary mode. Too many states available from “off”.

Beacon and momentary mode use the last-ramped brightness level.

Momentary mode is permanent until power is disconnected.

“Good night” mode starts at low and slowly ramps down for an hour, then shuts itself off. Intended for tail-standing next to a bed at night.

I set the PWM levels to start at 1/255. Depending on the hardware, this may be too low to make any light. However, the ramp floor can be set to whatever level you think looks good.

Config modes are similar to bistro — they blink out a number, pause, then “buzz” for a while. Click during the “buzz” to set a new value. It’ll keep buzzing as long as you keep clicking. If you want to skip an option, just wait without clicking.

Settings which are remembered after a battery change:

• Smooth ramp floor / ceiling.
• Discrete ramp floor / ceiling / steps.
• Beacon timing.
• Temperature limit.
• Which strobe mode was last used.
• Bike flasher brightness.
• Party strobe speed.
• Tactical strobe speed.

Includes LVP and smooth thermal regulation.

Werner Dual-Switch

Since it’s a thing people might want, and since I think Lexel may have been requesting it, I took a moment to make a Werner-style momentary UI, side e-switch plus tail clicky-switch.

https://code.launchpad.net/~toykeeper/flashlight-firmware/fsm

The short version is:

While completely off (power disconnected):

• Click tail to turn on at memorized level.
• Hold e-switch and click tail to enter utility mode.

While on (regular “on” mode):

• Click tail switch to turn off.
• Click side switch to go brighter.
• Hold side switch to go dimmer.

In utility mode:

• Click side switch to go to regular “on” mode.
• Hold side switch to go turn on at lowest level.
• Double click side switch to turn on at highest level.
• 3 clicks: Battcheck.
• 4 clicks: Ramp config.

Battcheck mode: Blinks out battery voltage.

• Click to go back to utility mode.
• 2 clicks for tempcheck mode.

Tempcheck mode: Blinks out current temperature in C.

• Click to go back to utility mode.
• 2 clicks for battcheck mode.
• 4 clicks for thermal config mode.

Ramp config:

• During first “buzz”, click N times to set floor level to N out of 150 total levels.
• During second “buzz”, click N times to set ceiling level to 151 minus N.
• During third “buzz”, click N times to set number of total brightness steps.
• Each “buzz” can be skipped to leave the value as-is.

Thermal config:

• During first “buzz”, click N times to calibrate current temperature to N degrees C.
• During second “buzz”, click N times to set thermal ceiling to 30 C + N.
• Each “buzz” can be skipped to leave the value as-is.

Includes LVP and smooth thermal regulation, copied directly from Anduril.

I filled in the “reserved” posts #2 and #3 with a summary of the toolkit and a summary of what has been made with it so far.

Lexel wrote:

I think NarsilM is close to be perfect,

I agree that NarsilM is pretty dang spiffy, to use some awkwardly mild words for it. I always wanted to change a few things though, which is how I ended up with the unnamed UI in comment #3.

I don’t know what to call it though. Maybe I should call it “Supafly”.

djozz wrote:

If the BLF-A6 driver was available in just ramp up/ramp down with background safety stuff, …

I’m not sure if it would interest you, but have you looked at Crescendo? It runs on a BLF-A6 driver and does smooth ramp up/down with background safety stuff like LVP and thermal regulation.

Also a bunch of blinkies, but those can be compiled out or avoided.

The “good night” mode starts at “low” and slowly ramps down for an hour, then shuts itself off.

It’s not really a blinky, but there wasn’t a more appropriate place to put it. And I like to do battcheck on the way to goodnight, so that puts them right next to each other. Perhaps I should call that group “specials” or something instead of “blinkies”.

I decided to try cloning the Meteor M43 UI tonight.

First I cloned UI1 — no problem.

Cloned UI2 — no problem.

Started on UI3 and then I noticed… it has different actions defined for “short click”, “long click”, and “hold”. And different actions for “two short clicks”, “short click then long click”, and “short click, then hold”.

No wonder I could never get some of the actions to work reliably.

Otherwise it’s going well though. I’ll continue later when I get my palm unstuck from my forehead.

joechina wrote:

In SM: Unnamed

what is the difference between
from OFF: 2 fast clicks
from OFF: click, then hold ?

If you double-click from off, it goes to the ramp ceiling level and stays there.

If you click, release, then hold from off, it goes to the ramp ceiling level and ramps down. It’s like a double click, except you hold the second click and it ramps until you let go.

Basically, it lets you navigate from the top or bottom from off. So, there isn’t really any need to configure whether modes are in low-to-high vs high-to-low order, because you get both.

patmurris wrote:

Regarding the question “what is the best single side switch UI”, i share djozz comments.

In general terms, I agree. The tricky part is translating that to specific implementation details — especially if the UI is intended to satisfy both enthusiasts and muggles.

The common 3-mode SK-68 UI (high, low, strobe) is very muggle-friendly but enthusiasts usually hate it. Or the HiveLD driver has lots of features for enthusiasts, but it requires a 9-page manual to operate, and setting config options requires a soldering iron and a metronome.

Getting both power and simplicity at the same time is somewhat tricky. The “unnamed” UI definitely errs more toward power and less toward simplicity. That’s kind of the point of it though — to be fancy and full of features that I want on my personal lights.

Tixx wrote:

Since this is the proper place for it, my suggestion was to turn the double blink when installing a new battery to moonlight instead of something bright like now. Reason: If you unscrew the cap for lockout and use the light in the middle of the night, you have to see 2 bright flashes first.

That was a thing I left alone in the D4 interface. On my custom UIs though, I generally do a single very-quick blink when power is connected. Very very quick. Unless it’s intended for a dual-switch light (e-switch and power cut switch), in which case it definitely shouldn’t blink at power-on.

The quick blink can be just as bright, but it doesn’t look as bright because it’s so short. Regardless, if you don’t want to be seen, it’s a good idea to cover the front of the light while tightening the tailcap.

It could perhaps be made optional, or I could maybe add a lockout config option to specify whether lockout blinks on exit or not. With soft lockout on 4 clicks, I usually go for that instead of unscrewing the tailcap. Perhaps it could have two or three modes: blink on exit, moon on exit, or no feedback at all.

allcool wrote:

better Thermal regulation sampling system and smooth hiccup free ramp. …

I have some ideas for improving thermal regulation, and plan to try them soon. It won’t take the entire rest of the ROM though.

About the ramp blinks, those are there because people requested it. Before, the ramp was actually too smooth and left people feeling lost, with no idea how bright it was or how long it would run.

But if the space isn’t needed for other things, it would be relatively easy to add an option to toggle the ramp blinks.

allcool wrote:

individual heat sensors for each led to show/control its individual performance … until a dedicated circuit/chip is used, maybe with a remote sensor soldered on the dtp, then all the software in the world won’t help..?

Bingo. That’s not a software thing. The software has access to only one pixel, one button, and one poorly-placed thermal sensor.

mozart.f wrote:

Is it possible to share the unnamed firmware?

Yes, but not quite yet. I’m still working out a few details. Mostly trying to coordinate with other people, which takes time.

dave1010 wrote:

The “good night” mode sounds great. If the timer in a flashlight is good enough for that kind of thing then I wonder if you could make an alarm clock mode that slowly ramps up the light after a programmed (with clicks) time.

The timer is pretty good (in my test, it timed an hour to a precision of less than a second), but waiting 8 hours before turning on is a little tricky. It would mean one of the following:

• Leaving the MCU on all night, at about 5 mA, so ~40 mAh power used each night just waiting.
• Implementing a special “twilight” half-sleep mode specifically for things like this alarm clock mode. (like standby, but the WDT would wake up every couple seconds and send a “tick” to the current State handler, with ADC turned off so it can’t sense low voltage)

I don’t like that first one, because 5mA is really high for a mode where it isn’t doing anything. I may be able to make the second one happen though, and it might be kind of nice for other things too (like controlling an indicator LED during standby mode).

In any case, if you want a light to blast in your face each morning, that might be do-able.
(it’s just going to need a bit of plumbing work first)
(OTOH, timers exist which plug into wall outlets and turn on whatever they’re connected to at a specified time, so that’s probably a cheaper and easier way to do it)

I have a SRK with Q8 driver, and a D4, and hopefully soon a D1, to test on. If I can make the thermal regulation “just work” on all those, it’ll probably be flexible enough for most purposes with no need to fine-tune anything. Hopefully the physical traits (like power level and thermal mass) will give the regulation enough feedback to adjust itself. Like, a big light heats up slower so it can react slower or in smaller steps.

However, that said, at a firmware level there are quite a few knobs to tweak, to make sure it reacts at the right speed and intensity without oscillating. And I need to test with tail-standing and no fan, since that was a scenario where the D4’s regulation would over-shoot and then take a long time to recover. It did fine with a hand to sink heat to, or with moving air, but the stagnant air case didn’t behave very well.

Sure, it would be easy to add heart beacon and SOS. I’m not sure it would add much though… It already has a beacon with adjustable frequency and brightness, and the momentary mode is good for sending Morse code.

Does anyone actually use SOS?