Shift function description and help needed

[Rappelbox]

Currently i'm a bit lost with the "shiftmode" function for my buttons.

I want to set my Startbutton (key 1) to also act as a shift button.
but honestly i can't figure it out how that actually works...
do i have to use the shiftbits description on all other buttons that would have a 2nd function?

it would be really helpful if someone could post a working example of maybe 2-3 buttons, so i get an idea of how it works.
tbh, the config helper is not very helpful at that special case, or i simply didn't get it :(

[mjrgh]

I've been meaning to add some examples to the config reference.

If you just want to cut to the chase, there's an example at the bottom that you should be able to crib from without having to get into all of the technical details. But I'll start with an explanation of how this works, in case you want to be able to extend the example beyond just the one shift button. The system is pretty technical, in that it requires understanding a little bit about binary arithmetic and Boolean logic functions, but once you have those basics down, the core rule that makes it work is really pretty simple.

The key to how this whole scheme works is "bit masking", which is another term for the "bitwise AND" operation, where you perform the AND operation on two binary numbers, bit by bit. For a single bit, the AND function is pretty straightforward: A AND B = 1 if both A and B are 1, and 0 for every other case - in other words, it's TRUE (1) if BOTH A AND B are both TRUE, and FALSE (0) otherwise. Extending this idea to integer values, you write out the binary version (that is, the base 2 arithmetic representation) of the two numbers, and you apply the AND operation to each digit position in the number. For example, to calculate 2 AND 3, you write the binary versions - 2 = 10, 3 = 11 - and then you AND each bit: so the first (left) bit is "1 AND 1 = 1", and the second (right) bit is "0 and 1 = 0". Then you string the bits together again and make it into a new binary number so 2 AND 3 (decimal) = 10 AND 11 (binary) = 10 (binary) = 2 (decimal).

The other important bit operation is OR. A OR B is TRUE when EITHER A OR B is TRUE: 0 OR 0 = 0, 0 OR 1 = 1, 1 OR 0 = 1, 1 OR 1 = 1. This extends to larger numbers in the same way as AND, writing the two numbers in binary, and applying it bit-by-bit. So 2 OR 3 (decimal) = 10 OR 11 (binary) = 11 (binary) = 3 (decimal).

Note that JSON lets you write numbers in binary format explicitly, which might make this easier to follow in the config file. To write a number in binary, start it with a "0b" (zero, lower-case B) prefix: 0b10 is the same as decimal 2, 0b11 is decimal 3, 0b1000 is decimal 8 etc.

The Pinscape shift key scheme uses the bit masking/bitwise AND operation to determine when a key is affected by shifting. Here's the core rule:

A button activates when the "Global Shift State" AND the button's shiftMask equals the button's shiftBits.

The "Global Shift State" is the OR combination of the shiftBits values for all of the type: "shift" buttons that are currently pressed.

If you just want to create a single SHIFT button, bringing all of this binary arithmetic to bear is a lot of overkill in terms of learning curve, but fortunately it ends up pretty simple in terms of what you actually have to put in the JSON.

For just one SHIFT button, we just need one bit for the "Global Shift State" business, so let's use the first bit, 1 (binary), which we write in JSON as 0b1. (We could also write it as just 1, since the decimal representation of 0b1 also happens to be decimal 1, or 0x1, since it's also 1 in hexadecimal.)

buttons: [
   { type: "shift", shiftBits: 0b1, source: { type: "gpio", gp: 5 }, },   // shift button
]

Okay, so that gives us our shift button, on GPIO port GP5. Press that button, and the Global Shift State value - the bitwise OR combination of the shifrtBits values of the pressed type: "shift" buttons - takes on the value 0b1, from the shiftBits of that button. Don't press the button, and the Global Shift State is 0, since the bitwise combination of nothing at all (no buttons pressed) is 0.

Now we just need to define a button with a shifted function. This requires TWO new button entries, one for the SHIFTED function of the button, and one for the UNSHIFTED function of the button.

In both cases, we want this button to be sensitive to the shiftBits of the shift button we just defined, so we need to set its shiftMask to 0b1. Remember the overarching rule that a button activates when "Global Shift State AND shiftMask equals shiftBits" - this is why we have to define shiftMask for these buttons that are affected by the shift button. It's the only way to make it sensitive to that bit (0b1) that we defined in the shift button. If shiftMask is 0 for any given button, which is the default if you don't define it, then "Global Shift State AND shiftMask" for that button is ALWAYS zero that button, and that button won't be affected at all by the shift button. And that's a cool feature of this scheme, because it means that BY DEFAULT, NOTHING is affected by shift buttons. So if you have a setup that you like, and you want to add a new shift button, nothing that's already defined will be affected by the new shift button - you don't have to go through your whole setup and redefine everything around the new change. It just naturally keeps working the way it did before. For buttons that you DO want to put under the influence of the new shift button, you just add the new shift button's shiftBits bit to the shiftMask in the affected buttons.

The other thing we have to add to each affected button is a shiftBits value. Again, we go back to the master rule, that a button activates when "Global Shift State AND shiftMask equals ShiftBits" - we've defined shiftMask for each button, now we just have to add shiftBits. When the shift button ISN'T pressed, Global Shift State will be zero, so the UNSHIFTED version of our button needs have shiftBits: 0. That will make the master rule activate that button when the shift button isn't pressed. When the shift button IS pressed, Global Shift State will be 0b1, so we define the SHIFTED version of the button with shiftBits: 0b1. That makes the button activate when the shift button IS pressed.

Putting that all together, here's the basic outline of what you need to define when there's a single shift button in your system:

• For the SHIFT button itself, define it as type: "shift" with shiftBits: 0b1
• For the UNSHIFTED version of any button that you want to be affected by the shift button, include shiftMask: 0b1 and shiftBits: 0
• For the SHIFTED version of any button that you want to be affected by the shift button, include shiftMask: 0b1 and shiftBits: 0b1
• For buttons that you DON'T want to be affected by the shift, simply omit shiftMask

Now to the example! This should define one shift button on GP5, and a two-function button on GP6, which acts as the Volume Down key when the shift ISN'T pressed, and the Volume Up key when the shift IS pressed:

buttons: [
   { type: "shift", shiftBits: 0b1, source: { type: "gpio", gp: 5 }, },   // shift button
   { 
      shiftMask: 0b1,           // sensitive to shift bit 1
      shiftBits: 0,             // operates when shift ISN'T pressed (Global Shift State AND shiftBits = 0b1 AND 0b0 = 0)
      source: { type: "gpio", gp: 6 }, 
      action: { type: "key", key: "voldown" },
   },
   { 
      shiftMask: 0b1,           // sensitive to shift bit 1
      shiftBits: 0b1,           // operates when shift IS pressed (GlobalShiftState AND shiftBits = 0b1 AND 0b1 = 0b1)
      source: { type: "gpio", gp: 6 }, 
      action: { type: "key", key: "volup" },
   },
]

You should be able to follow the pattern for the Volume Down/Volume Up buttons above to create any number of other shifted buttons. All you have to do to make them shifted is put in the shiftMask and shiftBits values as shown.

[Rappelbox]

Thank you for your detailed explanation.
i managed to get it to work, in some way.

issue 1:
as per your example, it is handled as a shift AND operation. this leads to the behavior that the button ("1" in my case) is triggered immediately. it still acts as a shift button, noticeable when pressing another button that has a shifted state configured.
In my example i have "enter" and shifted "o" on the same port.
If i open notepad or similar, i can see both "1" and "o" appear.

If i recall correct, on the original pinscape it was handled as OR operation, meaning the "1" was only triggered when no other button was pressed while "1" was active.

{
	    type: "shift", shiftBits: 0b1,
            source: { type: "74hc165", chip: 0, port: "H", debounceTimeOff: 1000, debounceTimeOn: 1000, lowPassFilterRiseTime: 50, lowPassFilterFallTime: 50 },
            action: { type: "key", key: "1" },
        },
        {
            source: { type: "74hc165", chip: 0, port: "D", debounceTimeOff: 1000, debounceTimeOn: 1000 },
	    action: { type: "key", key: "enter" },
        },
        {
            source: { type: "74hc165", chip: 0, port: "D", debounceTimeOff: 1000, debounceTimeOn: 1000 },
	    action: { type: "key", key: "o" },
	    shiftMask: 0b1,
	    shiftBits: 0b1,
        },

issue 2:
only little related to this topic, but "key" Volup/VolDown have no effect, whereas "media" works as expected.

Anyways, this project is a great new experience with ultra high versatility, which sometimes causes a little confusion and feeling overwhelmed.

[Rappelbox]

nevermind... "tPulse:100" solved the issue

so for everyone interested:

{
	    type: "shift", shiftBits: 0b1, tPulse: 100,
            source: { type: "74hc165", chip: 0, port: "H", debounceTimeOff: 1000, debounceTimeOn: 1000, lowPassFilterRiseTime: 50, lowPassFilterFallTime: 50 },
            action: { type: "key", key: "1" },
        },
        {
            source: { type: "74hc165", chip: 0, port: "D", debounceTimeOff: 1000, debounceTimeOn: 1000 },
	    action: { type: "key", key: "enter" },
        },
        {
            source: { type: "74hc165", chip: 0, port: "D", debounceTimeOff: 1000, debounceTimeOn: 1000 },
	    action: { type: "key", key: "o" },
	    shiftMask: 0b1,
	    shiftBits: 0b1,
        },

does the following:
press Start button = "1"
waits for 100ms after release and only then types the actual key
press Fire Button = "Enter"
press Start + Fire Button = "o"

[mjrgh]

I should have mentioned the SHIFT-AND and SHIFT-OR option - tPulse is the way to get the SHIFT-OR version, as you figured out.

You're right that Windows ignores the Keyboard Volume Up and Keyboard Volume Down keys, whereas it does have built-in handling for the Media Volume Up and Down keys, so those would have made a better example.