summaryrefslogtreecommitdiffhomepage
path: root/src/srp/fw-ec/index.html
blob: f528ab9be4253f54d95b3ca2034b19afc4dca11f (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
<!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&nbsp;apply</code>.
				</p>
			</aside>

			<figure>
				<figcaption>
					<code>~/board/hx20/led.c</code>
				</figcaption>
				<pre>m4_fmt_code(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_fmt_code(fn-lock-1.diff.html)</pre>
			</figure>

			<figure>
				<figcaption>
					<code>~/board/hx20/keyboard-customization.c</code>
				</figcaption>
				<pre>m4_fmt_code(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_fmt_code(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_fmt_code(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>