Proffie OS8.10 Features

saber_BC_buttons.h

  http://fredrik.hubbe.net/lightsaber/proffieos.html

  Copyright (c) 2016-2019 Fredrik Hubinette

  Copyright (c) 2023-2025 Brian Conner with contributions by:

  Fredrik Hubinette, Fernando da Rosa, Matthew McGeary, and Scott Weber.

  Distributed under the terms of the GNU General Public License v3.

  http://www.gnu.org/licenses/

Includes 1 or 2 button controls. (3rd button for power control of Dual Blades supported as well).

Incorporates an intuitive control scheme so button actions are consistant

whether blade is on or off.

** This prop version REQUIRES a V2 ProffieOS Voicepack for menus to work right.

** Menus will have no sounds if the contents are not somewhere in the font search path.

** Typically, that is a folder named "common" on the root level of the SD card.

Download your choice of language and variation here:

http://fredrik.hubbe.net/lightsaber/sound/

Also, a large variety of FREE in-universe character Voicepacks available here:

https://crucible.hubbe.net/t/additional-voicepacks/4227

If you'd care to make a donation for my time:

https://www.buymeacoffee.com/brianconner

Features:

- Live preset changing while blade is running (skips font.wav and preon).

- Battle Mode, gesture ignitions, and multi-blast based on fett263's work.

- Auto enter/exit multi-blaster block mode.

- Spoken Battery level in volts OR percentage. Both always available.

- Dedicated Quote sounds - Always available, blade ON or OFF. Force.wavs can remain as force.

                           Add quote.wav files to font to use.

                           Live toggle between sequential or random quote play.

                           Quotes can be triggered while blade is off.

- Play / Stop track control while blade is OFF OR ON.

- Force Push is always available, not just in Battle Mode.

- Melt is always available as no button, with pull-away or button to end.

- Drag is always clash with button pressed while pointing DOWN.

- No gestures if No blade is inserted - available option if Blade Detect is used.

- Custom Volume menu with Quick MIN and MAX levels.

- Bypass preon and/or postoff based on blade angle.

- Spam Blast - Enter this mode to make the button super sensitive for

                            multiple blaster blocks. Presses are prioritized over

                            other features. No limits, no lag when "rapid firing".

- No inadvertant effects during preon.

- Rotary control of Volume and Scroll Presets. (Rotate hilt like turning a dial)

- * NEW for OS8 *

  - Dual blade independent ignition and retraction control with a single Proffieboard. (Such as for a staff saber)

  - Scroll Presets mode.

  - Quotes play with blade ON or OFF, and will not overlap / interrupt one another.

  - Mute sound plays before igniting muted.(optional mute.wav used)

  - Blade Length editing menu.

  - OS System Menu system available with a #define.

* Deprecated features:

- No Volume UP/DOWN with buttons. Use rotary control instead (see above),

  but QuickMinVolume and QuickMaxVolume are still available.

- swap and monoforce features of yore are now just assignable User Effects.

- #define NO_VOLUME_MENU removed.

---------------------------------------------------------------------------

Optional Blade style elements:

On-Demand battery level - A layer built into the blade styles that reacts

                          as the battery gets weaker, changing blade color

                          from Green to Red, and the blade length shortens.

User Effects:

These equate to Fett263 "Special Abilities" 1-8.

- Can be built into blade style code to trigger anything that takes an EFFECT_XXXXX argument.

EFFECT_USER1 through 4 work when blade is ON.

EFFECT_USER5 through 8 work when blade is OFF.

USER 3, 4, 7, 8 are done "while pointing up" on 1 button setups, or the AUX button for 2 button sabers.

EFFECT_POWERSAVE        - PowerSave Dim Blade. Blade style should use a Mix or an AlphaL that applies

                          a transparent amount of Black to the base blade color.

                          Layer example: 50% brightness reduction

                          EffectSequence<EFFECT_POWERSAVE,AlphaL<Black,Int<16384>>,AlphaL<Black,Int<0>>>

---------------------------------------------------------------------------

Optional #defines:

#define BC_ENABLE_AUTO_SWING_BLAST - Multi-blast initiated by simply swinging

                                     within 1 second of last blast.

                                     Exit by not swinging for 1 second.

#define FEMALE_TALKIE_VOICE        - To use a female voice version of onboard Talkie.

* NEW as of OS8:

#define MENU_SPEC_TEMPLATE         - BC Volume Menu, Scroll Presets, ColorChange, and BC Blade Length adjust are used by default.

                                     Use this define to override and add access the the OS System Menu for editing presets, colors etc...

                                     Several template choices are available to set how the menus are used. See https://pod.hubbe.net/howto/menus.html.

#define DYNAMIC_BLADE_LENGTH       - This is required for onboard menu driven blade length adjustments.

                                     The blade length maximum should be set in the user config file's BladeConfig section.

// Adding the following define activates Dual Blade code in the prop.

#define BC_DUAL_BLADES             - Use Dual Blades mode for a staff saber setup.

                                     Defaults are BLADE 1 and BLADE 2 as MAIN and SECOND blades respectively.

                                     BLADE # corresponds to the blades list in the BladeConfig section of the config file,

                                     and therefore the position of the blade styles in a preset.

                                     If your MAIN and SECOND blades are not in position 1 and 2, you can use the following

                                     optional defines to manually set BLADE # to the appropriate blade from the BladeConfig list.

#define BC_MAIN_BLADE                * Example: #define BC_MAIN_BLADE 2

#define BC_SECOND_BLADE              * Example: #define BC_SECOND_BLADE 4

---------------------------------------------------------------------------

Gesture Controls:

- There are three gesture types: swing, thrust and twist.

  For simplicity, using gesture ignition will automatically skip the preon effect.

  * NOTE * If using Dual Blades, Swing and Twist ignitions will turn on all blades.

  Below are the options to add to the config to enable the various gestures.

#define BC_SWING_ON

#define BC_THRUST_ON

#define BC_TWIST_ON

#define BC_TWIST_OFF

#define NO_BLADE_NO_GEST_ONOFF

- If using Blade Detect, this define disables gesture ignitions or retractions when no blade is inserted.

  * Only works when a BLADE_DETECT_PIN is defined.

#define BC_FORCE_PUSH

- This gesture plays a force sound (or force push sound if the font contains push.wav) with

  a controlled pushing gesture, and is always available, not just in Battle Mode.

#define BC_FORCE_PUSH_LENGTH

- Used for adjustment to the Push gesture length in millis needed to trigger

  Force Push. Recommended range 1 ~ 10,

  1 = shortest, easiest to trigger, 10 = longest. Default value is 5.

#define BC_NO_BM

- Disable battle mode features.

#define BC_GESTURE_AUTO_BATTLE_MODE

- Makes gesture ignition ALSO enter battle mode automatically on ignition.

- *Note* - Cannot be used if #define BC_NO_BM is active.

"Battle Mode 1.0" by fett263, BC modified version:

- Once you enter battle mode, buttons are not used for lockup.

  Clashing the blade against something will automatically do lockup and then end

  when you pull away.

- Automatic lockup and grazing clash (swinging through) detection works

  by measuring delay of the saber blade pulling back from the clash.

  If you clash the blade and do not pull away during the delay period,

  it is assumed to be a lockup and the lockup effect will show on the blade.

  If you clash the blade and pull away, only the bgn/end lockup effects will show.

  You can adjust the threshold of this detection by using:

  #define BC_LOCKUP_DELAY (insert number here)

  Default value is 200.

  If you don't rebound off the object (opponent's blade) but instead clash while

  swinging through, clash will automatically trigger.

- To manually override the auto-lockup temporarily and get a regular clash,

  hold any button while clashing.

- Automatic clash/lockup uses the bgnlock and endlock effects

  so your blade style and font MUST have those capabilities to support

  battle mode.

- Melt will automatically trigger with no buttons when you physically

  stab something, and end when you pull away or click any button.

- Stab will trigger with no buttons and thrusting forward.

------------------------ GENERAL RULES ------------------------

Pointing the blade UP during ignition or retraction will bypass preon and postoff effects.

Gesture Ignitions bypass preon.

Rotation gestures LEFT and RIGHT are single direction "twists".

TWIST gesture is a 2-direction rotation, like revving a motorcycle. Either direction first works.

OS8 System Menus:

System menu will allow for editing of presets, colors and styles, similar to way the ProffieOS Workbench webpage and Edit mode work.

There's also an Edit Settings mode that has a volume level menu, blade length editing and more.

In this BC prop, the default mode is direct entry to BC Volume and BC Blade Length mode menus.

If you want to use the OS System Menu instead, you need to define a Menu Spec Template such as `#define MENU_SPEC_TEMPLATE DefaultMenuSpec`

While in any menu mode the following controls apply:

Save                - Click POW

Cancel / Exit       - Click AUX or Double Click POW

For more info, see https://pod.hubbe.net/howto/menus.html

Each section for controls have a descriptive version listed by feature and somwhat in the order

of using the saber, and a second summary list that is sorted by button clicks.

====================== 1 BUTTON CONTROLS ========================

| Sorted by ON or OFF state: (what it's like while using saber) |

=================================================================

* See below for modifications to these controls if BC_DUAL_BLADES is used.

-------- When blade is OFF -------

Turn Blade ON             - Short Click POW, or use a Gesture Ignition (see Gesture Controls above).

                            * Gesture ignitions will bypass preon, and optional fastout.wav can be used instead of out.wav.

Turn ON without Preon     - Short Click POW (while pointing UP), or use a Gesture Ignition.

                            * Uses fastout.wav if available.

Turn Blade ON Muted       - Hold POW then Twist.

                            or

                            Double Click POW.

                            * Muted ignitions will bypass preon.

                              Optional mute.wav will play before silent ignition and operation.

                              Saber unmutes when blade shuts off.

Scroll Presets            - Hold POW. Beeps will be heard when entering mode, and font.wav will play.

                            Rotate hilt to cycle through presets. Right = Next, Left = Previous.

                            Click POW to ignite with chosen preset, or Click and Hold POW again to Exit.

                            * TWIST_ON not available in this mode.

Next Preset               - Long Click then release POW (NOT pointing UP or DOWN).

Prev Preset               - Long Click then release POW (while pointing DOWN).

Jump to First Preset      - Long Click then release POW (while pointing UP).

Play/Stop Track           - 4x Click POW.

BC Volume Menu:

        Enter Menu        - Hold POW and Clash.

        Volume UP         - Rotate Right.

        Volume DOWN       - Rotate Left.

        Quick MAX Vol     - Hold POW while in Volume Menu.

        Quick MIN Vol     - Double Click and Hold POW while in Volume Menu.

        Save and Exit     - Click POW.

        Cancel and Exit   - Double Click POW.

BC Blade Length Edit:

        Enter Mode        - Double Click and Hold POW.

        Adjust            - Rotate Right or Left

        Save and Exit     - Click POW.

        Cancel and Exit   - Double Click POW.

** OS System Menu           * To use the OS menu system instead of the default BC Volume and BC Blade Length options,

                              use #define MENU_SPEC_TEMPLATE

Spoken Battery Level

        in percentage     - 3x Click and Hold POW.

        in volts          - 3x Click and Hold POW (while pointing DOWN).

                            * Will show On-blade display if EFFECT_BATTERY_LEVEL is used in blade style.

On-Demand Batt Level      - 3x Click and Hold POW, release after a second. (Double Click then Long Click)

                            * Requires EFFECT_BATTERY_LEVEL to be in blade style.

                            * Plays battery.wav sound effect if it exists in font or common folder,

                              otherwise a familiar tune of beeps 🙂

Quote Player              - 3x Click POW.

                            * Does Force effect if no quote(s) exist.

Toggle Sequential or

       Random quotes      - 3x Click POW (while pointing DOWN).

User Effect 5             - Hold POW then Rotate Left 60 degrees. (keep holding POW until executed)

User Effect 6             - Hold POW then Rotate Right 60 degrees. (keep holding POW until executed)

                            * Requires EFFECT_USER in blade style.

                            * Note the same controls when blade is ON are USER 1 and 2.

Trigger Blade ID Scan     - 4x Click POW and Hold, release after one second (3x Click then Long Click)

Next Blade Array          - 4x Click POW and Hold.

                            * Cycles to the next blade array in BladeConfig

-------- When blade is ON -------

Play/Stop Track           - 4x Click POW.

Next Preset Fast          - Hold POW and Twist (NOT pointing UP or DOWN).

                            * Fast switching presets bypasses preon and font.wav.

Previous Preset Fast      - Hold POW and Twist (while pointing DOWN).

First Preset Fast         - Hold POW and Twist (while pointing UP).

Clash                     - No button, just hit the blade against something.

Stab                      - Thrust forward with a stabbing motion. Works in Battle Mode.

Blaster Deflection        - Click or Double click POW.

Spam Blaster Blocks       - 4x Click and Hold POW (while pointing DOWN). Toggles SPAM BLAST mode ON/OFF.

                            * This makes the POW button super sensitive for multiple blaster blocks,

                              but gets in the way of controls for some other features, so deactivate when you're done spamming.

                              Plays mzoom.wav for activating/deactivating this mode.

                              Exits automatically when blade shuts OFF in case you leave it active.

Auto Swing Blast          - Swinging within 1 second of doing a button activated Blaster Block will start this timed mode.

                              To trigger auto blaster blocks, swing saber within 1 second of last block.

                              To exit, stop swinging for 1 second.

                              * Requires #define BC_ENABLE_AUTO_SWING_BLAST.

Toggle Battle Mode        - Double Click and Hold POW, release after a second (while pointing UP). (Click then Long Click)

                            * Power OFF is disabled while in Battle Mode. YOU MUST EXIT THE MODE FIRST.

Force Effect              - Double Click and Hold POW, release after a second (while NOT pointing UP). (Click then Long Click)

Lockup                    - Hold POW + Clash. Release button to end.

                            * In Battle Mode:

                              Just Clash and stay there to Lockup.

                              Holding POW while Clashing will do regular Clash without Locking up.

                              Pull away or press POW to end Lockup.

Drag                      - Hold POW + Clash (while pointing DOWN). Release button to end.

Melt                      - No button, just stab something. Rotate hilt to modify melting. Pull away or press POW to end.

Lightning Block           - Double Click and Hold POW. Release button to end.

Color Change Mode         - 3x Click and Hold POW.

                              Rotate hilt to cycle through all available colors.

                              Click POW to save color selection and Exit.

                              Double Click POW to Exit without saving.

Revert ColorChange        - 3x Click and Hold POW, release after a second. (Double Click then Long Click)

                              Reverts ColorChanged blade color back to the uploaded config color.

                              * This is done outside ColorChange Mode

        ColorChange explained:

          If RotateColorsX<Variation,COLOR> is used in the blade style:

              Rotate hilt to cycle through all available colors,

              Hold POW to save color selection and exit.

          If ColorChange<> is used in the blade style:

              There are up to 12 colors per rotation with a ccchange.wav sound at each step.

              If also using #define COLOR_CHANGE_DIRECT in the config,

              simply entering Color Change Mode will select the next color in the list and exit Color Change Mode.

Quote Player              - 3x Click POW.

                            * Does Force effect if no quote(s) exist.

Toggle Sequential or

       Random quotes      - 3x Click POW (while pointing DOWN).

Force Push                - Push hilt perpendicularly from a stop.

                            Plays push.wav if it exists, otherwise force.wav.

PowerSave Dim Blade       - 4x Click and Hold POW (while pointing UP).

User Effect 1             - Hold POW then Rotate Left 60 degrees. (keep holding POW until executed)

User Effect 2             - Hold POW then Rotate Right 60 degrees. (keep holding POW until executed)

                            * Require EFFECT_USER in blade style.

                            * Note the same controls when blade is OFF are USER 5 and 6.

Turn OFF blade            - Hold POW until off -or - Twist if using #define BC_TWIST_OFF.

Turn OFF bypass postoff   - Turn OFF (while pointing UP).

---------------------------------------

      1 button summary by clicks

---------------------------------------

--------- When blade is OFF ---------

twist                   - turn both blades ON (requires Gesture defines)

stab

swing

1 click                 - turn blade ON

                          turn blade ON bypass preon (pointing up)

1 click long            - first preset (pointing up)

                          next preset

                          previous preset (pointing down)

1 click held            - enter/exit scroll presets

    then twist          - turn blade ON muted (back and forth twist)

    then clash          - enter BC volume menu

    then rotate left    - user effect 5 (keep holding POW until executed)

    then rotate right   - user effect 6 (keep holding POW until executed)

2 clicks                - turn blade ON muted

2 clicks held           - blade length edit, or

                          OS system menu instead (requires #define MENU_SPEC_TEMPLATE)

3 clicks                - quote

                          toggle sequential or random quotes (pointing down)

3 clicks long           - on-demand battery level

3 clicks held           - spoken battery level in percentage

                          spoken battery level in volts (pointing down)

4 clicks                - play / stop track

4 clicks long           - manually trigger blade ID scan

4 clicks held           - manually switch to next blade array

twist                   - turn blade ON (requires #define BC_TWIST_ON)

- BC volume menu:

    rotate right        - volume UP

    rotate left         - volume DOWN

    1 click held        - quick MAX volume

    2 clicks held       - quick MIN volume

- OS system menu:

    rotate right/left   - choose options / adjust

    1 click             - select / save

    2 clicks            - exit / cancel

--------- When blade is ON ---------

1 click                 - blaster deflection

1 click long

1 click held            - turn blade OFF

                          turn blade OFF bypass postoff (pointing up)

    then twist          - first preset fast (pointing up)

                          next preset fast

                          previous preset fast (pointing down)

    then clash          - lockup

                          drag (pointing down)

    then rotate left    - user effect 1 (keep holding POW until executed)

    then rotate right   - user effect 2 (keep holding POW until executed)

2 clicks                - blaster deflection

2 clicks long           - force (not pointing up)

                        - toggle battle mode (pointing up)

2 clicks held           - lightning block (release to end)

3 clicks                - quote

                          toggle sequential or random quotes (pointing down)

3 clicks long           - revert colorchange to config

3 clicks held           - color change mode

4 clicks                - play / stop track

4 clicks long

4 clicks held           - dim (pointing up)

                          toggle spam blasts (pointing down)

hit object              - clash

twist                   - turn blade OFF (requires #define BC_TWIST_OFF)

thrust (air)            - stab

stab object             - melt

push                    - force push