Some questions on internal key definitions/flags

Programming
1
  1. The flag IS_INTERNAL defined at key_defs.h#L93 seems to be only used by LEDControl:
$ rgrep IS_INTERNAL .
./Kaleidoscope/src/key_defs.h:#define IS_INTERNAL                B00000010
./Kaleidoscope/src/key_events.cpp:  } else if (mappedKey.flags & IS_INTERNAL) {
./Kaleidoscope-LEDControl/src/Kaleidoscope-LEDControl.h:#define Key_LEDEffectNext (Key) { 0,  KEY_FLAGS | SYNTHETIC | IS_INTERNAL | LED_TOGGLE }
./Kaleidoscope-LEDControl/src/Kaleidoscope-LEDControl.h:#define Key_LEDEffectPrevious (Key) { 1,  KEY_FLAGS | SYNTHETIC | IS_INTERNAL | LED_TOGGLE }
./Kaleidoscope-LEDControl/src/Kaleidoscope-LEDControl.cpp:  if (mappedKey.flags != (SYNTHETIC | IS_INTERNAL | LED_TOGGLE))

Surely this wasn’t a flag for such a limited use? What else can this be used for?

  1. Lines starting key_defs.h#L92 read:
#define IS_SYSCTL                  B00000001
#define IS_INTERNAL                B00000010
#define SWITCH_TO_KEYMAP           B00000100
#define IS_CONSUMER                B00001000

/* HID types we need to encode in the key flags for system and consumer control hid controls
   Each key can only have one, so we don't need to use a bit vector.
   We need to keep the top two bits clear for defining the keys as synthetic
   We need to keep the bottom two bits clear for defining the keys as sysctl / consumerctl
*/

However the line:

   We need to keep the bottom two bits clear for defining the keys as sysctl / consumerctl

seems erroneous because the second lowest bit is used for “internal” and not “consumer”? As per the first line of the comment:

/* HID types we need to encode in the key flags for system and consumer control hid controls

… the part about consumer control seems important, but this means that the following additional HID type markers conflict with the existing marker for consumer control B00001000:

#define HID_TYPE_NARY  B00001000
#define HID_TYPE_OOC   B00001100
#define HID_TYPE_SEL B00011000
  1. key_defs.h#L112 – why two definitions:
#define Key_NoKey (Key) { 0,  KEY_FLAGS }
#define Key_skip (Key) { 0, KEY_FLAGS }
  1. I’d like to know the secret (of the universe) behind the number 42 (LOL what a coincidence, or wasn’t it?) in the line key_defs_keymaps.h#L5:
static const uint8_t LAYER_SHIFT_OFFSET = 42;
2

It used to be used for more, way back when.

Technically, you could use it for a lot of things. But stuff that does not have the RESERVED flag are by convention off-limits to anything non-core (excluding stuff like LEDControl, which used to be part of the core firmware).

This appears to be a bug, indeed. IS_CONSUMER and IS_INTERNAL were swapped as part of Kaleidoscope#242. Looks like the comments weren’t updated at the time.

Historical reasons. In the very beginning, keymaps were defined in a text file, and a Perl script processed them into a C++ header file. skip and NoKey was used there to convey two slightly different things (skip being “don’t care about this now, maybe later”, NoKey being “this is definitely not going to do a thing”), that happened to map to the same action: nothing.

That was me. :wink:

We support 32 layers, so to distinguish between momentary and toggled layers, we made momentary layers have a higher number, well above our 32-layer limit. I chose 42, because obviously, that’s the right answer to the question. (Just don’t ask me about the question, ok?)

I could have chosen 32 too, would have worked just as well. But since we had plenty of numbers available, I went for the funny one.

3

Looks like @merlin already flagged (pun intended) this problem but there seems to be no reply to his comment other than his own which says that those type markers don’t seem to be used anywhere.

I am not whether he means they aren’t used anywhere in the Kaleidoscope code or anywhere in the outside world? If they aren’t used in the outside world then what were they added for in the first place?

Since the reversal of the internal vs consumer codes which you point out effectively render the type markers useless (as they conflict with them) shall we create a PR to totally eradicate them if they aren’t used?

4

So effectively since you have 256 values to play with, you took some leeway? :blush:

BTW what are the Key_Keymap0 etc codes useful for?

5

While we’re at it, what are these useful for:

#define KEY_BACKLIGHT_DOWN 0xF1
#define KEY_BACKLIGHT_UP 0xF2
#define Key_BacklightDown (Key) { KEY_BACKLIGHT_DOWN,  KEY_FLAGS }
#define Key_BacklightUp (Key) { KEY_BACKLIGHT_UP,  KEY_FLAGS }
#define KEY_RIGHT_FN2 0xfe
#define Key_RFN2 (Key) { KEY_RIGHT_FN2,  KEY_FLAGS }
#define KEY_LEFT_FN2 0xff
#define Key_LFN2 (Key) { KEY_LEFT_FN2,  KEY_FLAGS }

I had previously asked this about the backlight keys but a further clarification:

do they refer to the screen backlight or the keyboard backlight?

6

Yep!

Historical artifacts. Before we had LockLayer and ShiftToLayer, Key_KeymapN and Key_KeymapN_Momentary could be used instead. Key_Keymap0 is exactly the same as LockLayer(0). They are (were?) there to be a friendlier way to switch to a particular layer (then called keymap).) An interesting tidbit is that at that time, we did not have transparency, so you could only have one keymap active at a time, and it completely replaced whatever was active previously.

7

That’s something I’d love to know as well. A lot of these keycodes were copied out from the USB spec, which sometimes fails to give a meaningful description.