<!DOCTYPE html>
<html lang="en">
<head>
m4_include(head.html)
</head>
<body>
<header>
<div>
<h1>Framework is Awesome</h1>
m4_include(nav.html)
</div>
<figure class="quote">
<blockquote>
<p>UNIX was not designed to stop its users from doing stupid
things, as that would also stop them from doing clever
things.</p>
</blockquote>
<figcaption>
Doug Gywn
</figcaption>
</figure>
</header>
<main>
<h2>Framework and the <abbr class="ec">EC</abbr></h2>
<p>
<a href="https://frame.work" target="_blank">
Framework
</a>
— for those unaware — is the coolest laptop manufacturer ever.
Their whole <em>shtick</em> is producing laptops that give the
user the ability to easily and effortlessly disassemble, repair,
and modify their hardware. I highly suggest checking them out if
you’re interested in computer hardware at all. The laptops even
have hotswappable I/O!
</p>
<p>
Anyways getting back on topic, Framework has also been giving
power to the user on the software-side of things too! A good
while ago they open-sourced the
<a href="https://github.com/FrameworkComputer/EmbeddedController">
code for the embedded controller
</a>
of their laptops, which offers all sorts of possibilities for
customization of the keyboard,
<abbr class="led">LED</abbr>
lights, and more.
</p>
<h2><abbr class="led">LED</abbr> Fun!</h2>
<p>
This is an area of the
<abbr class="ec">EC</abbr>
which I have not really looked at or touched much. I do want to
play around with this a lot more in the coming future though! So
far just for shits-and-giggles, I’ve patched the
<abbr class="ec">EC</abbr>
to make the power-button
<abbr class="ec">LED</abbr>
green instead of the normal boring white:
</p>
<aside>
<p>
Just a tip: if you want to try any of these patches out,
simply copy the diffs and paste them
into <code>git apply</code>.
</p>
</aside>
<figure>
<figcaption>
<code>~/board/hx20/led.c</code>
</figcaption>
<pre>m4_include(led.diff.html)</pre>
</figure>
<p>
As you can see, it’s all fairly simple. I just had to change our
<code>EC_LED_COLOR_WHITE</code> for
<code>EC_LED_COLOR_GREEN</code>. The codebase defines a few
colors, but they’re defined as <abbr class="rgb">RGB</abbr>
tuples which is awesome, because it opens the door to
custom <abbr class="rgb">RGB</abbr> effects in the future!
</p>
<h2>There’s More Than One <abbr class="led">LED</abbr>!?</h2>
<p>
That’s right! The Framework laptop I own (13″; the 16″ releases
soon though!) has 3 more <abbr class="led">LED</abbr> lights.
One on the left of the chassis, one on right of the chassis, and
one on the capslock key. The capslock
<abbr class="led">LED</abbr> acts as an indicator of whether or
not you’ve got capslock enabled. This is useless to me though,
because my custom keyboard layout doesn’t even support capslock
(see the next section) — so I patched it to be a function-lock
indicator instead!
</p>
<p>
Here’s the diff — but do take care if you want to apply similar
patches to your laptop! The files I’m editing are under
<code>board/hx20</code> since I’m on an 11th Gen Intel
<abbr class="cpu">CPU</abbr>. If you have a different
<abbr class="cpu">CPU</abbr>, you will probably need to fuck with
different code:
</p>
<figure>
<figcaption>
<code>~/board/hx20/board.h</code>
</figcaption>
<pre>m4_include(fn-lock-1.diff.html)</pre>
</figure>
<figure>
<figcaption>
<code>~/board/hx20/keyboard-customization.c</code>
</figcaption>
<pre>m4_include(fn-lock-2.diff.html)</pre>
</figure>
<p>
As you can see, toggling the capslock
<abbr class="led">LED</abbr> is as simple as
invoking <code>gpio_set_level()</code>. Not only that, but
disabling its functionality with the capslock key is as easy as
undefining the <code>CONFIG_CAPSLOCK_SUPPORT</code> macro.
Figuring out if the function key is locked is also really easy.
The <code>Fn_key</code> global variable is a bit-field containing
information pertaining to the function key, and we also
conveniently already have the <code>FN_LOCKED</code> constant
defined that we can bitwise-AND with <code>Fn_key</code> to check
the locked state!
</p>
<p>
We also setup some hooks with the <code>DECLARE_HOOK()</code>
macro. These just ensure that we are behaving properly on system
resume and -suspend.
</p>
<h2>The Hybrid Key</h2>
<p>
Wouldn’t it be cool if a physical key could represent two keys at
the same time? I thought so too. Like all Emacs users, I suffer
from a distinct lack of easily-accessible modifier keys. I need
escape because I use Vim bindings; I need left-control because
all the Emacs bindings use it; I need super for my
window-managers’ bindings; I need left-alt so I can type
characters that don’t come on a standard American keyboard (such
as <em>ß</em>, <em>€</em>, and <em>é</em>), and now I have a
problem. All my modifiers are taken, but Emacs still needs a
meta key to work!
</p>
<figure>
<figcaption>
<cite>Workflow</cite> by Randall Munroe
</figcaption>
<img alt="XKCD Comic 1172" src="1172.png">
</figure>
<p>
What will I ever do!? Well thanks to Framework making
the <abbr class="ec">EC</abbr> open-source, and conveniently
giving me a file called <code>keyboard_customization.c</code>,
I’m going to take two keys and stick them in one! The basic
premise is this: the capslock key is arguably the easiest
modifier key to hit, and it’s currently bound to the escape key
on my system. This is inefficient though, because nobody makes
key-bindings that chord the escape-key with another key; chords
are always done with a modifier like control, and Emacs is no
different. So my plan was to make it so that the capslock key
when used on its own mimics an escape-key, while instead
mimicking the left-control-key when used in a chord with another
key.
</p>
<p>
It took me a little longer this time to figure out how to
implement what I wanted since the code isn’t as clear, but it was
still a surprisingly easy feature to patch into the
<abbr class="ec">EC</abbr>! I basically just updated the
scancode table, swapping out the capslock scancode for my own
random one that I called <code>SCANCODE_CTRL_ESC</code>. I then
created a new function called <code>try_ctrl_esc()</code> which
is called in the on-keyup and -down callback function. The
<code>try_ctrl_esc()</code> function handles all of the logic as
you can see in the following diff; it’s basically just a state
machine:
</p>
<aside>
<p>
If you’re confused by what I mean by a “key-chord”, I am
simply referring to pressing multiple keys in conjunction,
such as when you press “<kbd>Ctrl + C</kbd>” to copy text.
</p>
</aside>
<figure>
<figcaption><code>~/board/hx20/keyboard_customization.c</code></figcaption>
<pre>m4_include(hybrid.diff.html)</pre>
</figure>
<p>
One thing that’s good to take note of is what I return from
<code>try_ctrl_esc()</code>. The general pattern for handling a
keyup or -down event is to stick the following code into
<code>keyboard_scancode_callback()</code>:
</p>
<figure>
<figcaption>
<code>keyboard_scancode_callback()</code> in
<code>~/board/hx20/keyboard_customization.c</code>
</figcaption>
<pre>m4_include(kbd-sc-cb.c.html)</pre>
</figure>
<p>
In <code>my_handler_function()</code> (or whatever you decide to
name it), you attempt to handle the event. If you don’t want to
handle a particular event and instead want to pass it on to the
next handler, you need to return <code>EC_SUCCESS</code>. If you
managed to successfully handle the event though, then you need to
return an error such as <code>EC_ERROR_UNIMPLEMENTED</code>.
It’s pretty stupid and makes very little sense from a naming
perspective, but oh well…
</p>
<h2>What’s Next?</h2>
<p>
<abbr class="rgb">RGB</abbr>
<abbr class="led">LED</abbr>s
maybe.
</p>
</main>
<hr>
<footer>
m4_footer
</footer>
</body>
</html>