# Some questions on internal key definitions/flags

**URL:** <https://community.keyboard.io/t/some-questions-on-internal-key-definitions-flags/1922>\
**Category:** Programming\
**Created:** [August 14, 2018, 6:27am UTC](https://community.keyboard.io/t/some-questions-on-internal-key-definitions-flags/1922 "2018-08-14T06:27:55Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![jamadagni](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jamadagni/32/2030_2.png) [@jamadagni](https://community.keyboard.io/u/jamadagni)\
**Post date:** [August 14, 2018, 6:27am UTC](https://community.keyboard.io/t/some-questions-on-internal-key-definitions-flags/1922/1 "2018-08-14T06:27:55Z")

</div>

1. The flag **`IS_INTERNAL`** defined at [key\_defs.h#L93](https://github.com/keyboardio/Kaleidoscope/blob/master/src/key_defs.h#L93) seems to be only used by **LEDControl** :

```auto
$ 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](https://github.com/keyboardio/Kaleidoscope/blob/master/src/key_defs.h#L92) read:

```auto
#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:

```auto
   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:

```auto
/* 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** :

```auto
#define HID_TYPE_NARY B00001000
#define HID_TYPE_OOC B00001100
#define HID_TYPE_SEL B00011000

```

1. [key\_defs.h#L112](https://github.com/keyboardio/Kaleidoscope/blob/master/src/key_defs.h#L112) – why two definitions:

```auto
#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](https://github.com/keyboardio/Kaleidoscope/blob/master/src/key_defs_keymaps.h#L5):

```auto
static const uint8_t LAYER_SHIFT_OFFSET = 42;

```

---

<div class="post-metadata">

**Author:** ![algernon](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/algernon/32/4404_2.png) [@algernon](https://community.keyboard.io/u/algernon)\
**Post date:** [August 14, 2018, 7:54am UTC](https://community.keyboard.io/t/some-questions-on-internal-key-definitions-flags/1922/2 "2018-08-14T07:54:00Z")

</div>

> [@jamadagni](#):
>
> Surely this wasn’t a flag for such a limited use?

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

> [@jamadagni](#):
>
> What else can this be used for?

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).

> [@jamadagni](#):
>
> seems erroneous because the second lowest bit is used for “internal” and not “consumer”? As per the first line of the comment:

This appears to be a bug, indeed. `IS_CONSUMER` and `IS_INTERNAL` were swapped as part of [Kaleidoscope#242](https://github.com/keyboardio/Kaleidoscope/pull/242). Looks like the comments weren’t updated at the time.

> [@jamadagni](#):
>
> 1. [key\_defs.h#L112](https://github.com/keyboardio/Kaleidoscope/blob/master/src/key_defs.h#L112) – why two definitions:
> 
> ```auto
> #define Key_NoKey (Key) { 0, KEY_FLAGS }
> #define Key_skip (Key) { 0, KEY_FLAGS }
> 
> ```

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.

> [@jamadagni](#):
>
> 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](https://github.com/keyboardio/Kaleidoscope/blob/master/src/key_defs_keymaps.h#L5):

That was me. 😉

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.

---

<div class="post-metadata">

**Author:** ![jamadagni](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jamadagni/32/2030_2.png) [@jamadagni](https://community.keyboard.io/u/jamadagni)\
**Post date:** [August 14, 2018, 12:58pm UTC](https://community.keyboard.io/t/some-questions-on-internal-key-definitions-flags/1922/3 "2018-08-14T12:58:39Z")

</div>

> [@jamadagni](#):
>
> ```auto
> 
> ```
> 
> … 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** :
> 
> ```auto
> #define HID_TYPE_NARY B00001000
> #define HID_TYPE_OOC B00001100
> #define HID_TYPE_SEL B00011000
> 
> ```

Looks like @merlin [already flagged](https://github.com/keyboardio/Kaleidoscope/pull/242#commitcomment-26441387) (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?

---

<div class="post-metadata">

**Author:** ![jamadagni](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jamadagni/32/2030_2.png) [@jamadagni](https://community.keyboard.io/u/jamadagni)\
**Post date:** [August 14, 2018, 1:01pm UTC](https://community.keyboard.io/t/some-questions-on-internal-key-definitions-flags/1922/4 "2018-08-14T13:01:02Z")

</div>

> [@algernon](#):
>
> > 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](https://github.com/keyboardio/Kaleidoscope/blob/master/src/key_defs_keymaps.h#L5):
> 
> That was me. 😉
> 
> 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.

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

BTW what are the `Key_Keymap0` etc codes useful for?

---

<div class="post-metadata">

**Author:** ![jamadagni](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/jamadagni/32/2030_2.png) [@jamadagni](https://community.keyboard.io/u/jamadagni)\
**Post date:** [August 14, 2018, 1:04pm UTC](https://community.keyboard.io/t/some-questions-on-internal-key-definitions-flags/1922/5 "2018-08-14T13:04:23Z")

</div>

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

```auto
#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](https://community.keyboard.io/t/is-it-safe-to-use-key-backlightdown-and-key-backlightup/1624/5) about the backlight keys but a further clarification:

do they refer to the _screen_ backlight or the _keyboard_ backlight?

---

<div class="post-metadata">

**Author:** ![algernon](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/algernon/32/4404_2.png) [@algernon](https://community.keyboard.io/u/algernon)\
**Post date:** [August 14, 2018, 1:06pm UTC](https://community.keyboard.io/t/some-questions-on-internal-key-definitions-flags/1922/6 "2018-08-14T13:06:07Z")

</div>

> [@jamadagni](#):
>
> So effectively since you have 256 values to play with, you took some leeway?

Yep!

> [@jamadagni](#):
>
> BTW what are the `Key_Keymap0` etc codes useful for?

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.

---

<div class="post-metadata">

**Author:** ![algernon](https://yyz1.discourse-cdn.com/flex031/user_avatar/community.keyboard.io/algernon/32/4404_2.png) [@algernon](https://community.keyboard.io/u/algernon)\
**Post date:** [August 14, 2018, 1:07pm UTC](https://community.keyboard.io/t/some-questions-on-internal-key-definitions-flags/1922/7 "2018-08-14T13:07:23Z")

</div>

> [@jamadagni](#):
>
> do they refer to the _screen_ backlight or the _keyboard_ backlight?

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.