KPP (keyboard programmming protocol)

[Daniel Beardsmore]

Does this seem reasonable to anyone?

Code: Select all

> HELO MOTO
< 200+MODEL Poker III, ISO, 62
< 200+REVISION 1.2
< 200+PROTOCOL 1.0
< 200+FEATURES Delay_Keys/1.1
< 200+LAYERS "Normal", "Fn"=0xFFFF
< 200+BUFFER 14
< 200 Ready
> READ 0xFFFF+x042
< 210 DEFAULT
> BIND 0xFFFF+0x42 = 0x99
< 220 Binding set
> READ 0xFFFF+0x42
< 210 0x99

A shamelessly SMTP-based keyboard discovery and programming protocol. Allows anyone to read off the keyboard's specifications and bindings, and apply new bindings.

It's not OS specific, it's not even software specific, as you can use a plain old serial client (Hyperterminal, PuTTY etc), to program it if there isn't (yet) a programming application for your system.

I am suspecting (I'm not at my work PC right now, so I can't check) that the "broken" Pn layer on my Poker II is a result of me not realising how the Pn layer was set in the factory. I was setting bindings to the empty list to remove my tests, and that's probably what's killed off most modifiers in Pn mode.

"Solution": Programming software on your PC.

Problem: what if I don't have Windows, or the developer doesn't have Windows?

Solution: Make the keyboard's programming independent of any specific programming software.

What it means also is that any program can bring up a schematic of any keyboard's programming, so I'd actually see from the outset what's on my Poker's Pn layer and realise that I'm making a hash out of it.

It also means that you don't need to waste a whole Pn key for programming ;-)

One thing it would require, is standardisation of additional scancodes for meta keys.

I've used 0xFFFF to represent Fn, and maybe use the 0xF000-0xFFFE range for meta keys, e.g. macro delay keys, backlight control, dedicated macro keys etc. Additional layer keys can go from 0xFFFE down.

Feasible? Am I just plain nuts/asking way too much? Are the odds too high that keyboard firmware implementers are just going to screw it all up like with any other protocol? Too complicated? I don't want this to be another of the horrible mistakes the IT industry has been making for years.

[CJNE]

Interesting idea
Just thinking about how the bindings would be stored, on a Teensy 2.0 you only have 1024 bytes of EEPROM available, not sure if that would be enough?

[Muirium]

Programming via text editor on the computer is how Soarer's converter / controller already works. For instance, here's my (very much work in progress) config for that homemade 60% of mine I'm forever showing off. No Pn key required.

Code: Select all

# Muirium's Shiny 60%

# Todo:
# Better layout of function and media keys, where my fingers expect them to be.
# Integrate full numpad around I key on some layer for keyboard mouse control.

matrix
	blocking 0

	sense			PF7			PB6		PB5		PB4			PD7			PC7		PC6			PD3			PD2			PD1		PD0			PB7			PB3			PB2			PB1				PB0
	strobe	PF0		esc			1		2		3			4			5		6			7			8			9		0			minus		equal		backslash	back_quote		unassigned
	strobe	PF1		tab			q		w		e			r			t		y			u			i			o		p			left_brace	right_brace	unassigned	backspace		unassigned
	strobe	PF4		fn1			a		s		d			f			g		h			j			k			l		semicolon	quote		unassigned	enter		unassigned		unassigned
	strobe	PF5		lshift		z		x		c			v			b		n			m			comma		period	slash		unassigned	rshift		unassigned	fn2				unassigned
	strobe	PF6		lctrl		lalt	lgui	unassigned	unassigned	space	unassigned	unassigned	unassigned	rgui	ralt		unassigned	rctrl		unassigned	pad_enter		unassigned
end

layerblock
	fn1 		1
	fn2 		1		# One for each hand, where available
	fn1 fn2		2		# Press them both for a hard to reach second layer
endblock

# Layerin' time
remapblock
layer 1

	# 	HHKB Arrows
	LEFT_BRACE 	UP
	SEMICOLON 	LEFT
	SLASH 		DOWN
	QUOTE 		RIGHT
	L 			PAGE_UP
	PERIOD 		PAGE_DOWN
	K 			HOME
	COMMA 		END
	H 			PAD_ASTERIX
	J 			PAD_SLASH
	N			PAD_PLUS
	M			PAD_MINUS
	
# 	ESDF Arrows	
	E			UP
	S			LEFT
	D			DOWN
	F			RIGHT
	R			PAGE_UP
	V			PAGE_DOWN
	A			HOME
	G			END

	# 	Media keys across the number row	
	1			F14					# Decrease Display Brightness 
	2			F15					# Increase Display Brightness
	3			F10					# Exposé: All App Windows
	4			F12					# Dashboard
	5			F11					# Exposé: Show Desktop
	6			F9					# Exposé: All Windows in All Apps
	7			MEDIA_PREV_TRACK	# iTunes / media playback controls
	8			MEDIA_PLAY_PAUSE
	9			MEDIA_NEXT_TRACK
	0			MEDIA_MUTE			# Volume controls
	MINUS		MEDIA_VOLUME_DOWN
	EQUAL		MEDIA_VOLUME_UP

#	Maybe use the two function layer keys differently to resolve this clash.
		
#	Specifically Shiny
	Esc			EUROPE_2		# Our old friend §	
	backspace		delete
# 	ralt			left			# The sneaky inerted T arrow cluster  
# 	rshift			up				# Perhaps put this on layer zero?  
# 	rctrl			down  			# Retired for now.
#	pad_enter		right
	back_quote		f24
	backslash		system_power
endblock

remapblock	
layer 2
	# 	Don't forget the media keys. Contention here on what goes on layer 1.	

	# 	Function row across the number row
	Esc			EUROPE_2
	1			F1
	2			F2
	3			F3
	4			F4
	5			F5
	6			F6
	7			F7
	8			F8
	9			F9
	0			F10
	minus		F11
	equal		F12
	back_quote	F13
endblock

# If I ever figure out how to engage it!
remapblock
layer 3
	7			pad_7		# Numpad / mouse movement keys
	8			pad_8
	9			pad_9
	u			pad_4
	i			pad_5
	o			pad_6
	j			pad_1
	k			pad_2
	l			pad_3
	m			pad_0
	comma		pad_period
	minus		pad_minus
	equal		pad_plus
endblock

#	Engage the macros!

macroblock
	# Command + Escape = Command + Section break (for app window cycling)
	macro ESC gui -ctrl -alt
	press EUROPE_2
	endmacro
	
	# Soarer's Double Shift Caps Lock
	macro lshift rshift
	press caps_lock
	endmacro
	
	macro rshift lshift
	press caps_lock
	endmacro
	
	# Apple style Control + Corner Arrow shortcuts for Shiny
	
	# Page Up
	macro up lctrl
	press page_up
	endmacro
	
	# Page Down
	macro down lctrl
	press page_down
	endmacro
	
	# Home
	macro left lctrl
	press home
	endmacro
	
	# End
	macro right lctrl
	press end
	endmacro
	
	# Fn + Backtick = Ctrl + Cmd + Opt + 8 (Negative / night colours mode)  
 	macro f24 -shift  
 	push_meta set_meta rgui ralt rctrl  
 	press 8  
 	pop_meta  
 	endmacro  
 	  
 	# Shift + Fn + Backtick = Ctrl + Cmd + Opt + I (Isolator darkness mode)  
 	macro f24 shift  
 	push_meta set_meta rgui ralt rctrl  
 	push_meta clear_meta lshift rshift  
 	press I  
 	pop_all_meta    
 	endmacro
 	
 	# Shift + Fn + Backslash = Numlock for Mouse Keys
 	macro system_power shift
 	push_meta set_meta rshift
 	press scroll_lock
 	pop_meta
 	endmacro

	# Swap # and £ so I can keep UK layout in software but match legends
 	# Pound = Hash
 	macro 3 shift -alt
 	push_meta set_meta lalt
 	push_meta clear_meta lshift rshift
 	press 3
 	pop_all_meta
 	endmacro
 	
 	# Hash = Pound
 	macro 3 -shift alt
 	push_meta set_meta lshift
 	push_meta clear_meta lalt ralt
 	press 3
 	pop_all_meta
 	endmacro
 	
 	# Quick Ctrl+F-keys for menu navigation
 	# Ctrl 2 = Ctrl + F2 = Enter main app menu
 	macro 2 ctrl -alt -gui -shift
 	press f2
 	endmacro

 	# Ctrl 8 = Ctrl + F8 = Enter system menus
	macro 8 ctrl -alt -gui -shift
 	press f8
 	endmacro
 	
endblock

The software to actually get it on the Teensy wasn't available for my platform (PowerPC Mac OS X), but fortunately Soarer's tools are open source and a little makefile coercion and I compiled them fine. Can't say I'd ever expect to be able to pull off such a trick with commercial software.

Now I know this isn't directly comparable to (everything) that you propose, but I can speak from experience with this style of keyboard customisation: it's good stuff. Can't see it coming to anything other than our own builds, though. And CJNE is quite right about the Teensy's very teensy indeed confines.

[CJNE]

Yeah, i think we need to use program space to store the mappings which means compiling and programming is required...
AVR programmers and cross compilers are available on all platforms though, so maybe it would be possible to get somewhere along the line of the original idea, but instead of talking to the keyboard directly to do the mapping you'd have a little program that then compile and burn the firmware for you.

I've been tinkering with something like that for the tmk firmware, haven't had so much time for it lately but i plan to finish and share it sometime soon.

mapper.jpg (219.01 KiB) Viewed 3748 times

[Daniel Beardsmore]

Compilers and makefiles? Sorry mate, I forgot we hadn't left the 20th century yet … I'll get my coat/time machine …

Maybe it won't work with a Teensy. I can't watch YouTube videos on my BBC Micro.

14 keystrokes per key binding is the Poker II limit. In ISO, that's 60 keys (not Pn or Fn) × 14 keystrokes max per key; with null terminators/length bytes, that's 900 bytes as an array. How the Poker actually stores the macros, I don't know, as it combines consecutive matching delays, but doesn't combine delays of different quantities.

In fact, the Poker II allows you to program both the Pn and Pn+Fn layers, so that's really 2 × 60 × 15 = 1800 bytes for keystrokes alone, plus state (backlight toggle and intensity).

How a keyboard wants to store bindings isn't relevant (it's an implementation issue that will differ between keyboards), only that communication is open and transparent, incremental updates are possible (change one key without having to rebuild the entire firmware from scratch, and we already have the Poker II as an example of on-the-fly reprogrammable, saved to internal memory), existing definitions can be retrieved for display, and that no special software of any kind is required (just serial communications). I'm not seriously suggesting that people would use serial communications, only that there's no dependence on any black art program/secret protocols etc, and that slowly, newer firmwares would (be able to) take advantage of standard reprogramming tools.

[scottc]

If you think that compilers and makefiles are unusual then you'd better wrap up warm, it'll take quite a while to travel that far into the future.

CJNE, that tool looks fantastic. I was thinking of writing something similar myself, but probably more on the level of $SOME_MARKUP_LANG --> outputs layout.h. Do I see that it's written in Node?

[CJNE]

Sounds like the Poker have more EEPROM than a teensy then Don't know much about the Poker controller, is it even possible to flash it with a custom firmware?

I'm not quite sure what you had in mind here, to get all manufacturers to agree on a standard protocol?
That would be nice, but the chances for that to happen might not be that great, not even if you increase the year knob in your time machine

[scottc]

Great Scott!

[CJNE]

CJNE, that tool looks fantastic. I was thinking of writing something similar myself, but probably more on the level of $SOME_MARKUP_LANG --> outputs layout.h. Do I see that it's written in Node?

Thanks
Yeah it's Node alright, trying to keep up with the trends
And it would be trivial to add on a web frontend instead of the curses one.

A markup parser that can output a C header file sounds like a nice idea!

Almost on topic, it would be nice if we could agree on a common markup for keymaps that could work across different firmwares, then have specific converters to make them into header files...

[matt3o]

color me interested, but... how could you have manufactures using your protocol?

[Daniel Beardsmore]

Sounds like the Poker have more EEPROM than a teensy then :) Don't know much about the Poker controller, is it even possible to flash it with a custom firmware?

The firmware is upgradeable, yes.

color me interested, but... how could you have manufactures using your protocol?

What do you mean by "manufactures"? Cherry? Vortex aren't exactly a huge impenetrable organisation — they already build keyboards for KBT, and the KBC/iKBC ones are built for a keyboard community.

Now, I understand that no good idea goes unpunished. I expect nothing any more.

If you think that compilers and makefiles are unusual then you'd better wrap up warm, it'll take quite a while to travel that far into the future. :roll:

I hope for your sake that you are not serious in your scorn. I have had enough personal experiences with creating things even I can't understand to realise the importance of product quality. Unfortunately too many people, especially hobbyists, have an all-consuming mindset that, so long as they can understand something, it's ready to be shared with the world. Whether anyone else can figure it out is never relevant.

It's the same lack of empathy that gives you the poisonous "users suck" attitude when in reality users are thrown headfirst into a world full of computers from which they have no escape, and which never work, never make any sense, and never behave consistently from one day to the next. Impenetrable jargon, user interfaces that are utterly inconsistent from one program to the next, error messages that don't mean anything to anyone on the planet — why are we so willing to to inflict such pain on people and then ridicule them for failing to cope with it? How exactly do you expect users to understand something when you vomit such filth in their faces every day?

Even something as simple as asking a Linux program its version depends on the program. If you just type the program name it usually shouts at you for being so stupid as to not give it instructions, and if you try the wrong version argument it still shouts at you for not making any sense. Utter hostility, everywhere.

So no, I hope you are not serious.

[jeffkoch]

How do you keep track of what is programmed on each key? The factory keycaps for some keyboards have 3 or more legends printed.

[Daniel Beardsmore]

How do you keep track of what is programmed on each key? The factory keycaps for some keyboards have 3 or more legends printed.

No better than I can keep track of the factory assignments on a backlit Poker II with its dark, unlit front-printed Fn layer legends! :(

That's the snag with keyboards that use different angled keycaps instead of a curved backplane: no keycap rearrangement. If flat keycaps aren't an issue, you can also print out legends and use relegendable keycaps.

Some will of course argue that they're more likely to remember their own assignments, as they chose them. I can't remember anything …