Skip to content

Map VT User Defined Keys for the K95 terminal type - #580

Merged
davidrg merged 23 commits into
masterfrom
k95-udk
Nov 2, 2026
Merged

davidrg merged 23 commits into
masterfrom
k95-udk

Conversation

@davidrg

@davidrg davidrg commented Oct 26, 2026 •

Copy link
Copy Markdown
Owner

Now that UDKs can be locked and are locked by default, its safe to have them mapped by default for the K95 terminal type. All 20 UDKs are supported, and for the K95 terminal type they're automatically initialized with what xterm sends for Shift+F1...F10 and Alt+Shift+F1...F10.

This branch also has a fix for UDKs being reset on soft-reset, and the UDK lock not being reset to the users preference on hard reset, and a pile of other very long standing deviations from hardware behaviour as well just plain bugs.

…ift+F10 mapped to K_UDKF1...K_UDKF10 by default for the K95 terminal type.

And for compatibility with xterm, UDKs are now initialised to what xterm sends for the K95 type.
@davidrg davidrg linked an issue Oct 26, 2026 that may be closed by this pull request
@davidrg

davidrg commented Oct 26, 2026

Copy link
Copy Markdown
Owner Author

@j4james I hope this should fix the outstanding (known) issues with UDKs in the K95 terminal type!

@j4james

j4james commented Oct 27, 2026

Copy link
Copy Markdown

@davidrg If you're interested in looking into other UDK issues at the same time, these are a few edge cases that showed up in my conformance tests:

  • DECUDK with invalid first parameter aborts the sequence
  • DECUDK with invalid second parameter aborts the sequence
  • DECUDK ignores null key definitions in the list
  • DECUDK resets keys which have a blank definition
  • DECUDK ignores unexpected characters in the definition

Those are just the failed test case names that come from the logs, so I'm not sure how useful they are to you without more context - I'm afraid the system isn't very well suited for bug reporting. But if any of those sound like issues you want to address, just let me know and I can try and provide you with more detailed test cases.

@j4james

j4james commented Oct 27, 2026

Copy link
Copy Markdown

Some feedback regarding this PR in particular:

  1. When testing keys F11 to F20, I use the actual keys rather than Alt+Shift+F1 to F10. So to get those test to pass on Kermit I still have to set them up with set key \890 \Kudkf11, etc. Not a big deal, but you may want to consider supporting both key combinations for people that actually have the full function key range.
  2. There are a quite a few more test cases failing now that didn't fail previously, because when a key definition is reset, you now remap it to the Xterm sequence rather than a blank value (which is what would be expected on a real terminal). I suspect that may be intentional, so I'm not sure there's anything that can be done about that.

@davidrg

davidrg commented Oct 27, 2026

Copy link
Copy Markdown
Owner Author

I'm not too surprised there are other things not quite right with DECUDK - seems like whenever look into some new part of the terminal emulator new issues pop up! I'll try to sort those out too as it would be nice to be able to call that function "done" as much as possible for the VT220/320 emulations accuracy-wise. When I eventually get to VT420 and VT520 emulations DECUDK will require further work as they seem to support extra parameters for specifying modifiers and direction.

As for which key sequences the UDKs are bound to and what they send by default, that was intended as an xterm-compatibility compromise. Until the host sends a DECUDK, the function keys will just do as xterm does for the K95 terminal type; VT220 and VT320 will reset to blank as the real terminals do (or at least as the VT220 does - looking forward to the day when something can run the VT320 firmware!).

Though I've just fired up my VT520 and it seems to behave the same way - it doesn't initialize UDKs to blank:

  • F6 sends CSI 17 ~
  • Shift+F6 sends CSI 17 ; 2 ~
  • Alt+F6 sends CSI 17 ; 4 ~
  • After sending printf '\x1bP0;1|17/414243\x1b\\' , Shift+F6 sends ABC, all other sequences are unmodified.

So looks like xterm sends DECFNK for the function keys, and the VT520 initializes the UDKs to send DECFNK too rather than do nothing. The Shift+Alt+F6 -> F16 (or UDK F16) is perhaps an xtermism though. The LK401 of course has a real F16 key (Do) so programming key 29 alters Shift+Do rather than Shift+Alt+F6. Looking at the manual, I suspect with a PC keyboard the terminal just won't give you F13+ and so DECUDK won't let you modify what those keys send. I'll have to dig out a PS/2 keyboard and do some more tests to confirm.

@j4james

j4james commented Oct 27, 2026

Copy link
Copy Markdown

As for which key sequences the UDKs are bound to and what they send by default, that was intended as an xterm-compatibility compromise.

That much I understood, and that makes sense for VT5xx compatibility too I think. What was confusing me was how UDKs were cleared.

After sending printf '\x1bP0;1|17/414243\x1b\\' , Shift+F6 sends ABC, all other sequences are unmodified.

So I was assuming the erase control being set to "Clear all UDKs" would actually erase them, rather than resetting them back to a default mapping, although this makes sense in retrospect. I guess I'm just going to have to treat "level 5" terminals differently in my tests, which is a bit annoying. I haven't actually done much of anything at level 5, though, so there's a lot more keyboard work required there anyway.

And just to be clear, on your VT520, if you did printf '\x1bP0;1|17/414243\x1b\\' and then followed that up with printf '\x1bP0;1|18/414243\x1b\\', does Shift+F6 actually go back to CSI 17 ; 2 ~? It's not just leaving the default unchanged?

The Shift+Alt+F6 -> F16 (or UDK F16) is perhaps an xtermism though.

That is actually documented in the VT520/VT525 manual (it may not apply to the VT510 though). All I was suggesting was that you could possibly support both, i.e. Shift+Alt+F6 should just be an alias for Shift+F16. I don't know about other platforms, but Windows is at least capable of supporting keyboards with all 20 function keys (it actually has virtual key codes up to F24).

However, note that Shift+Alt+F1 and Shift+Alt+F2 are not intended to be aliases for Shift+F11 and Shift+F12. They're distinct key combinations as far as I understand. The table I'm referencing is on page 5-166 of EK-VT520-RM.A01.

@j4james

j4james commented Oct 27, 2026

Copy link
Copy Markdown

FYI, I've now updated my test suite to accept the erase control resetting the key definitions as an alternative to clearing them, so those tests are passing in Kermit again.

@davidrg

davidrg commented Oct 28, 2026

Copy link
Copy Markdown
Owner Author

And just to be clear, on your VT520, if you did printf '\x1bP0;1|17/414243\x1b\\' and then followed that up with printf '\x1bP0;1|18/414243\x1b\\', does Shift+F6 actually go back to CSI 17 ; 2 ~? It's not just leaving the default unchanged?

I can confirm that's how it works - after the second DECUDK, Shift+F6 goes back to CSI 17 ; 2 ~. Looks like like its just tied in with the whole key mapping system - when DECUDK defines a key it updates the keymap, and when it clears the definition it just resets that slot in the keymap to default. These show the before and after of firing off a DECUDK. Using DECUDK to clear definitions returns the keymap to the before state:
image
image

The Shift+Alt+F6 -> F16 (or UDK F16) is perhaps an xtermism though.

That is actually documented in the VT520/VT525 manual (it may not apply to the VT510 though). All I was suggesting was that you could possibly support both, i.e. Shift+Alt+F6 should just be an alias for Shift+F16. I don't know about other platforms, but Windows is at least capable of supporting keyboards with all 20 function keys (it actually has virtual key codes up to F24).

Ah yes, that makes sense. The keymap does actually cover the LK450 (and I assume LK250) keyboard, so F13-F20 on one of those ought work as expected. I guess unsurprisingly the LK450 uses different scancodes though - I'll add PC F13-F20 to the keymap too.

@j4james

j4james commented Oct 29, 2026

Copy link
Copy Markdown

Thanks for double checking that. I love seeing what the editor UI looks like on the actual device. But now I'm very curious to know how they achieved the "Define Key Editor" title. That surely can't just be a double-width line, because then the borders on that line would also be double-width, and out of alignment. Did they have the ability to control the width on individual cells, but just not expose that as an escape sequence?

@davidrg

davidrg commented Oct 29, 2026

Copy link
Copy Markdown
Owner Author

Yeah, that's interesting. I can't find any any other screens in the firmware that do something like this which makes it more surprising. Would be a bit of a waste of an attribute bit if double-width was really a per-cell thing. Unless perhaps they had plans to do more there but ran out of time. Would be interesting to see a disassembly of the firmware - perhaps there might be some undocumented modes or control sequences.

@j4james

j4james commented Oct 29, 2026

Copy link
Copy Markdown

Yeah, now that I think about it, it can't be an attribute bit, because I'm fairly certain I know what all the cell bits are used for from the DECRQCRA reports. 10 bits were needed for the glyph index, 5 bits for the rendition attributes, and 1 bit for the protected attribute.

Maybe they render the border directly onto the screen, similar to way the screen frame is done when framed mode is enabled (DECFWM)?

My other thought was that it could have been a separate glyph that exactly matched the single-width border glyph once it was scaled, but I think I would have noticed that when I was dumping the glyph tables from the ROM.

Not that it matters - just curious. And we might find out more if Blaze ever does a VT520 disassembly.

… a partial hex code was encountered.

STD 070 says the key definition and the rest of the DECUDK sequence should be ignored in this scenario. It doesn't say the rest of the DECUDK sequence should be dumped to the terminal. And the VT220, VT420 and VT520 I have access to don't behave in this way at all - they just ignore the partial hex code and continue on.

As the old behaviour was at least partially consistent with the standard I can't rule out some DEC terminal out there behaving in the same way as past K95 releases, so for now the behaviour is just commented out.
Previously K95 would abort the DECUDK sequence dumping the remainder of the DCS buffer to the terminal in this scenario. This behaviour is commented out for now in case one of the other terminals K95 emulates really did behave this way.
@j4james

j4james commented Oct 31, 2026

Copy link
Copy Markdown

I've just tested with the latest changes, and I've only got two test cases failing now. I've extracted the actual test definitions below in case that's helpful. They use the Given/When/Then syntax which I'm hoping is reasonably understandable.

The "terminal is ready" step is just an operating status DSR, to make sure the terminal has actually received the keyboard definitions before attempting to type anything.

  • DECUDK resets keys which have a blank definition

    Given string is output "\033P0;1|17/626164\033\\" 
    And string is output "\033P1;1|18/676F6F64\033\\" 
    And string is output "\033P1;1|17/\033\\" 
    And terminal is ready  
    When keys are pressed Shift+F6,Shift+F7           
    Then response should be "good" or "\033[17;2~good"
    
    >>> Expected "good"
    >>> Actual   "goodgood"
  • DECUDK ignores unexpected characters in the definition

    Given string is output "\033P0;1|17/54j484+95Z320$49 532&04G649|4Ew45\033\\" 
    And terminal is ready  
    When key is pressed Shift+F6 
    Then response should be "THIS IS FINE" 
    
    >>> Expected "THIS IS FINE"
    >>> Actual   "T\x04\x84\x09P2"

… processed as DCS regardless of the set type.

And also fix a larger issue: apcrecv is only reset on terminal reset. This means that once an APC has been received, *all* subsequent string-type escape sequences will be interprted as APC until terminal reset. This bug has existed since at least v1.1.11 (February 1997) and is now described as bug 845.
… causes a DCS (or any other escape sequence) to be aborted.

So when emulating a VT220, translate SOS and PM into CAN rather than their two-byte representations.

This also introduces a new 'strict emulation' setting which, when set, causes OSC and APC to be translated to CAN as well. This setting is hidden for now as it doesn't do much, but someday it should be extended to suppress all other extensions.
…CDLD.

Someday we need to switch to processing DCS one byte at a time as the real terminals do, rather than accumulating it all into a string which would remove the need for hacks like this.

Also fix escape sequences that caused an abort not being processed correctly.
…a...f respectively in the DECUDK command string.
@davidrg

davidrg commented Nov 1, 2026

Copy link
Copy Markdown
Owner Author

Those two should be fixed now! And I think K95s current DECUDK implementation should now match the VT220, VT420 and VT520 except for those VT420/520 features not currently implemented (support for up to 768 bytes on a single key, key modifiers, and direction).

xterm behaves as the VT520 does, and Alt+Shift+F1..10 is mapped to K_UDF10...20, not 1...10.
@j4james

j4james commented Nov 1, 2026

Copy link
Copy Markdown

The unexpected character test passes now, but the reset test is still failing for me. I've checked I'm on commit 95a1334, and I've run clean.bat before the build, so I don't think I've messed up the build.

I've also tried running the test manually to make sure it wasn't an issue with my test framework - I tried three separate echo statements from a bash shell. Still failed although in a slightly different way - the Shift+F6 got reset to some random bytes rather than good. I'm assuming it's just random memory that happened to have good in it from the previous Shift+F7 definition when all three statement were executed in rapid succession.

@davidrg

davidrg commented Nov 1, 2026

Copy link
Copy Markdown
Owner Author

That last one should be fixed now! Not sure why it worked for me when I first tried it, but it was certainly broken!

@j4james

j4james commented Nov 1, 2026

Copy link
Copy Markdown

That's done it! All my DECUDK tests are passing now.

If it was random memory, it could have just ended up with null bytes some of the time, which may be why it initially seemed to work for you.

@j4james

j4james commented Nov 1, 2026

Copy link
Copy Markdown

Btw are you intentionally resetting to blank in this case, rather than original CSI 17;2~ definition? I accept either as correct, because the earlier terminals expected it to be blank, but I thought you might be returning the original definition the same way the other resets worked on the VT520. Is this one a special case?

@davidrg

davidrg commented Nov 1, 2026 •

Copy link
Copy Markdown
Owner Author

Nope, that was just me trying to fix a bug before my morning coffee! I was testing using the VT320 emulation, so completely missed that it should go back to sending DECFNK for the K95 terminal type (I've just confirmed the VT520 does do this too - you can't map a UDK to send nothing via DECUDK). Should be fixed now.

Though the fix is probably going to be a temporary solution - I think when I get around to doing all the other VT420/VT520 keyboard stuff I'll have to change how this works a bit. Because a bunch of other keys can be programmed too, I think rather than defaulting the UDKs to some particular value instead I need to insert an extra layer into the key map system somewhere:

                   [Special Keyboard Modes]
             +-----------+----------+----------+
             |           |          |          |
           EMACS      HEBREW     RUSSIAN   WORDPERFECT
             |           |          |          |
             +-----------+-----+----+----------+
                               |
                      [SET KEY Definitions]
                               |
[New layer for VT420/500 - DECUDK, DECPFK, DECPAK, DECPKA, DECCKD, etc, map keys here perhaps?]
                               |
           [Terminal-Emulation-Specific Definitions]
    +--------+--------+--------+--------+--------+--------+
    |        |        |        |        |        |        |
  VT52     VT100    VT220     WYSE    DG200     TVI      etc...
    |        |        |        |        |        |        |
    +--------+--------+--------+--------+--------+--------+

@davidrg
davidrg merged commit a09cd1a into master Nov 2, 2026
32 checks passed
@davidrg

davidrg commented Nov 2, 2026

Copy link
Copy Markdown
Owner Author

Thanks for all your help in getting DECUDK all fixed up! As seems to be usual with these things, a lot of other bugs were uncovered in the process so its great to get all of that sorted and be able to call this function done for the time being!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

DECUDK doesn't seem to work when terminal type is k95

2 participants