64 Bit Soarer's Tools for Mac

User avatar
Muirium
µ

25 Feb 2021, 12:36

As we all know: Soarer's Converter is awesome for bringing your vintage boards up to speed with USB and adding deep programmability. I've been using them myself for years and years.

The Problem
One problem, though: Apple dropped 32 bit compatibility a wee while ago on the Mac, and Soarer's configuration tools are 32 bit.

Soarer's original .hex files are still fine. Teensies are still the same and run the same code just great. The only updating necessary is the software running on the Mac.

The Solution
So I rebuilt them in 64 bit. Here they are:
Soarer's Tools x86_64.zip
(69.77 KiB) Downloaded 109 times
Note: these are 64 bit Intel. They work great on Intel Macs running Catalina and Big Sur *and* they work the same on M1 Macs in Big Sur! I have tested both. Eventually Apple will kill Rosetta, and these tools will break again. But it's probably many years away. PowerPC backwards compatibility lasted a long time back in the Intel transition, and they're following much the same path again.

Why not build them in ARM? Well… uh… building these was hard! Soarer made them open source which is great. (All the good stuff is in his original thread.) But if you open the source code in Xcode on a modern Mac, you're faced with loads of dependency issues I'm not technical enough to resolve. How I did it was go back to Mavericks and build in 64 bit Intel there. Mavericks is way too old to know about ARM Macs. So this is a patch, not an ultimate solution. Works though!

Handy Tools
As for hid_listen and getting Soarer's .hex files onto your Teensy, I find QMK Toolbox does the trick on modern Macs. Version 0.0.21 is fully native on both Intel and Apple Silicon. Remember to open it with Control+click to get around any code signing problems on first run. Oh, Gatekeeper, you dizzy bugger! Amusingly, no such problems with my simple command line tools. Good job, because I've no idea how to sign them. They just work.

Don't forget Soarer's Controller
Oh, one more thing: I also gave Soarer's Controller some love. It uses the same tools as his converter but needs separate versions of scas and scdis. I built those and threw them into the zip. They're called scascontroller and scdiscontroller. (Something about that last name really appeals to me…) The rest of the tools—scwr, scrd, scinfo and scbootloader—build identically and work identically on both Soarer's Converter and Soarer's Controller.

And the Docs
For ease of access, I'm just uploading Soarer's original documentation files here, extracted from his combined zip file. (DT won't accept .html attachments, or .txt!? so I've pasted them in as text files right here.) This way I can open them on my phone next time I need them, too!

All of these apply to both Soarer's converter and controller.

config quick ref
Spoiler:
XT/AT/PS2/Terminal to USB Converter with NKRO
Config Quick Reference v0.997+
Comments begin with a '#' and continue to the end of the line.

# This is a comment.
The force command disables the auto-detection of keyboard type.

force {set1|set2|set3|set2ext}
The include command processes another file, exactly as if it was copy-pasted to where the include command is.

include <file_name>
Conditionals stay in effect until the conditional is repeated with different argument(s).
The blocks following a conditional are only applied if...

ifselect {<select_num> | any} # specified select is active.
ifset [set1] [set2] [set3] [set2ext] [any] # using one of the specified sets.
ifkeyboard {<keyboard_id> | any} # keyboard has the specified ID.
Layerblocks define combinations of function keys to access different layers.
(Function keys are defined by remapping one or more keys to pseudo-HID codes FN1 to FN8).

layerblock
<fn_key_combo> <layer_num>
...
endblock
Remapblocks define remappings either for the base layer, or for the specified layer if a layer command is given inside the block.

remapblock
[layer <layer_num>]
<from_hid> <to_hid>
...
endblock
Macroblocks define one or more macros. Macros are triggered by a single HID key with any combination of metas, and can have command blocks that execute on either or both of make and break of the HID key.

macroblock
macro <hid> [[-][{l|r}]shift] [[-][{l|r}]ctrl] [[-][{l|r}]alt] [[-][{l|r}]gui] ...
[
<command> [<value>]
...
]
[onbreak [norestoremeta]
<command> [<value>]
...
]
endmacro
...
endblock
config
Spoiler:
XT/AT/PS2/Terminal to USB Converter with NKRO

Config v0.997+
Overview
Initial Translation
Command Reference
force
include
ifselect
ifset
ifkeyboard
remapblock
layerblock
macroblock
Macro Commands
Macro trigger matching

Overview
========

This diagram gives an simplified view of the processing stages inside the converter:


The first stage is a fixed initial translation into HID codes, that cannot be modified by the config. The goal of this stage is to map into a reasonable base set of codes for further remapping, and to try and ensure that each key on the keyboard results in a unique HID code after this stage.

The second stage combines remapping and layer functions, since layers are simply alternate remappings.

The third stage is macro expansion.

The final stage separates out the internal commands such as SELECTn and BOOT etc. and routes them appropriately, and also converts the HIDX codes back into standard HID codes for the keyboard, media, and power code pages.

Initial Translation
For most keys it's fairly obvious which codes are produced after the fixed initial translation. However, for some keys on a 122-key keyboard, and the normally unused extra keys on various keyboards, the codes don't follow an obvious pattern.

To find out which code a key is producing after the fixed initial translation, you can use hid_listen to examine the Diagnostic Output.

When you press a key, a set of codes is sent by the converter to hid_listen. For example, pressing the centre key in the 122-key's cursor block results in:

r62 +93 d93 rE2 -93 u93
Note the code prefixed by '+', then look it up in the HID code list. For the example, looking up 93 reveals that the identifier to use for remapping or triggering a macro would be LANG_4.


Command Reference
=================

force
The force command disables the auto-detection of keyboard type. It is only very rarely needed!

force {set1|set2|set3|set2ext}
Example:

force set2
include
The include command processes another file, exactly as if it was copy-pasted to where the include command is.

include <file_name>
Quotation marks are optional unless the file name contains spaces.

Example:

include "colemak.sc"
ifselect
Groups of settings can be toggled by using the ifselect command and defining remaps or macros that output the SELECT_0 to SELECT_7 codes.

ifselect {<select_num> | any}
When any of the SELECT codes are output the entire config is reloaded, and the ifselect commands choose which blocks will be applied.
When the converter powers-up, all selects, except select 0, are inactive.
Multiple selects can be active at a time.
Select 0 is special - it is always active, and when SELECT_0 is output it resets all the other selects.

Blocks following ifselect <select_num>, up to the next ifselect, are applied only if the specified select is active.

Blocks following ifselect any, up to the next ifselect, are applied regardless of which selects are active.

Example:

# toggle between qwerty and colemak by pressing scroll lock

ifselect 1
include colemak.sc

ifselect any
remapblock
SCROLL_LOCK SELECT_1
endblock
ifset
Blocks following the ifset command are only applied if using one of the specified sets.

ifset [set1] [set2] [set3] [set2ext] [any]
Example:

ifset set1 set2
ifkeyboard
Blocks following the ifkeyboard command are only applied if the keyboard has the specified ID.

ifkeyboard {<keyboard_id> | any}
The keyboard ID is given in hexadecimal.

See the Troubleshooting section for details of how to find out the ID of your keyboard.

Example:

ifkeyboard BABA


Layers
======

layerblock
Layerblocks define combinations of function keys to access different layers.

layerblock
<fn_key_combo> <layer_num>
...
endblock
Function keys are defined by remapping keys to codes FN1 to FN8.

Example:

layerblock
FN1 1
FN2 1
FN1 FN2 2
endblock

remapblock
LGUI FN1
RGUI FN2
endblock
remapblock
Remapblocks define remappings either for the base layer, or for the specified layer if a layer command is given inside the block.

remapblock
[layer <layer_num>]
<from_hid> <to_hid>
...
endblock
Example:

# swap capslock and backspace

remapblock
CAPS_LOCK BACKSPACE
BACKSPACE CAPS_LOCK
endblock


Macros
======

macroblock
Macroblocks define one or more macros. Macros are triggered by a single HID key with any combination of metas, and can have command blocks that execute on make and/or break of the HID key.

macroblock
macro <hid> [[-][{l|r}]shift] [[-][{l|r}]ctrl] [[-][{l|r}]alt] [[-][{l|r}]gui] ...
[
<command> [<value>]
...
]
[onbreak [norestoremeta]
<command> [<value>]
...
]
endmacro
...
endblock
Example:

macroblock
macro SCROLL_LOCK LSHIFT LCTRL -ALT
PUSH_META CLEAR_META all # save and clear all metas
PRESS p # press some keys...
PRESS i
PRESS N # case is ignored - this results in lowercase 'n'
SET_META lshift # you have to set modifiers yourself
PRESS g # results in a capital 'G', since shift is set
POP_ALL_META # restore metas that were active before
endmacro
endblock

Macro Commands
==============

Command Description
NOP Does nothing
PRESS <hid> Shorthand for MAKE <hid> then BREAK <hid>
MAKE <hid> Set keystate to 'down'
BREAK <hid> Set keystate to 'up'
ASSIGN_META <metas> Set all metas to the state specified
SET_META <metas> Set specified metas to down state
CLEAR_META <metas> Set specified metas to up state
TOGGLE_META <metas> Set specified metas to inverse of current state
POP_META Restore metas from the time of the last PUSH_META
POP_ALL_META Restore metas from the time of the first PUSH_META
DELAY <delay_in_ms> Delay by the specified number of milliseconds
CLEAR_ALL (internal use e.g. when buffer overrun is received)
BOOT Cause the converter to jump to the bootloader v1.0+
PUSH_META <cmd> <value> Save metas for later. Combines with other commands
Macro trigger matching

Macros are triggered only when the state matches for all of the the specified metas.
If a particular meta is not specified, its state is not matched.

Meta Trigger condition
LSHIFT LSHIFT is pressed
RSHIFT RSHIFT is pressed
SHIFT Either LSHIFT or RSHIFT is pressed
-LSHIFT LSHIFT is not pressed
When looking for a match, macros are checked in the order they appear in the config file.
The first matching macro found (if any) is executed, so you sometimes need to take of what order the macros are in.

macroblock
macro SCROLL_LOCK LSHIFT # this macro will execute even if LCTRL is down, so...
...
endmacro
macro SCROLL_LOCK LSHIFT LCTRL # ... this macro will never execute!
...
endmacro
endblock
The correct order would be:

macroblock
macro SCROLL_LOCK LSHIFT LCTRL
...
endmacro
macro SCROLL_LOCK LSHIFT
...
endmacro
endblock
See the HID code list for HID and META values.
codes
Spoiler:

Code: Select all

XT/AT/PS2/Terminal to USB Converter with NKRO

Codes
Modified HID Code Set
Deprecated Code Names
Modifiers
Modified HID Code Set
Mainly HID page 7, with additions to support internal features, media keys, and power keys.
Codes in italics are used internally by the converter, and are not output.
Codes with highlight are output, but may not be supported by all OS (notably Windows).
Media and Power codes are translated to the correct code page before being output.

Name              HID Code        Description
UNASSIGNED          0x00          No Event
OVERRUN_ERROR       0x01          Overrun Error
POST_FAIL           0x02          POST Fail
ERROR_UNDEFINED     0x03          ErrorUndefined
A                   0x04          a A
B                   0x05          b B
C                   0x06          c C
D                   0x07          d D
E                   0x08          e E
F                   0x09          f F
G                   0x0A          g G
H                   0x0B          h H
I                   0x0C          i I
J                   0x0D          j J
K                   0x0E          k K
L                   0x0F          l L
M                   0x10          m M
N                   0x11          n N
O                   0x12          o O
P                   0x13          p P
Q                   0x14          q Q
R                   0x15          r R
S                   0x16          s S
T                   0x17          t T
U                   0x18          u U
V                   0x19          v V
W                   0x1A          w W
X                   0x1B          x X
Y                   0x1C          y Y
Z                   0x1D          z Z
1                   0x1E          1 !
2                   0x1F          2 @
3                   0x20          3 #
4                   0x21          4 $
5                   0x22          5 %
6                   0x23          6 ^
7                   0x24          7 &
8                   0x25          8 *
9                   0x26          9 (
0                   0x27          0 )
ENTER               0x28          Return
ESC                 0x29          Escape
BACKSPACE           0x2A          Backspace
TAB                 0x2B          Tab
SPACE               0x2C          Space
MINUS               0x2D          - _
EQUAL               0x2E          = +
LEFT_BRACE          0x2F          [ {
RIGHT_BRACE         0x30          ] }
BACKSLASH           0x31          \ |
EUROPE_1            0x32          Europe 1 (use BACKSLASH instead)
SEMICOLON           0x33          ; :
QUOTE               0x34          ' "
BACK_QUOTE          0x35          ` ~
COMMA               0x36          , <
PERIOD              0x37          . >
SLASH               0x38          / ?
CAPS_LOCK           0x39          Caps Lock
F1                  0x3A          F1
F2                  0x3B          F2
F3                  0x3C          F3
F4                  0x3D          F4
F5                  0x3E          F5
F6                  0x3F          F6
F7                  0x40          F7
F8                  0x41          F8
F9                  0x42          F9
F10                 0x43          F10
F11                 0x44          F11
F12                 0x45          F12
PRINTSCREEN         0x46          Print Screen
SCROLL_LOCK         0x47          Scroll Lock
PAUSE               0x48          Pause
INSERT              0x49          Insert
HOME                0x4A          Home
PAGE_UP             0x4B          Page Up
DELETE              0x4C          Delete
END                 0x4D          End
PAGE_DOWN           0x4E          Page Down
RIGHT               0x4F          Right Arrow
LEFT                0x50          Left Arrow
DOWN                0x51          Down Arrow
UP                  0x52          Up Arrow
NUM_LOCK            0x53          Num Lock
PAD_SLASH           0x54          Keypad /
PAD_ASTERIX         0x55          Keypad *
PAD_MINUS           0x56          Keypad -
PAD_PLUS            0x57          Keypad +
PAD_ENTER           0x58          Keypad Enter
PAD_1               0x59          Keypad 1 End
PAD_2               0x5A          Keypad 2 Down
PAD_3               0x5B          Keypad 3 PageDn
PAD_4               0x5C          Keypad 4 Left
PAD_5               0x5D          Keypad 5
PAD_6               0x5E          Keypad 6 Right
PAD_7               0x5F          Keypad 7 Home
PAD_8               0x60          Keypad 8 Up
PAD_9               0x61          Keypad 9 PageUp
PAD_0               0x62          Keypad 0 Insert
PAD_PERIOD          0x63          Keypad . Delete
EUROPE_2            0x64          Europe 2
APP                 0x65          App (Windows Menu)
POWER               0x66          Keyboard Power
PAD_EQUALS          0x67          Keypad =
F13                 0x68          F13
F14                 0x69          F14
F15                 0x6A          F15
F16                 0x6B          F16
F17                 0x6C          F17
F18                 0x6D          F18
F19                 0x6E          F19
F20                 0x6F          F20
F21                 0x70          F21
F22                 0x71          F22
F23                 0x72          F23
F24                 0x73          F24
EXECUTE             0x74          Keyboard Execute
HELP                0x75          Keyboard Help
MENU                0x76          Keyboard Menu
SELECT              0x77          Keyboard Select
STOP                0x78          Keyboard Stop
AGAIN               0x79          Keyboard Again
UNDO                0x7A          Keyboard Undo
CUT                 0x7B          Keyboard Cut
COPY                0x7C          Keyboard Copy
PASTE               0x7D          Keyboard Paste
FIND                0x7E          Keyboard Find
MUTE                0x7F          Keyboard Mute
VOLUME_UP           0x80          Keyboard Volume Up
VOLUME_DOWN         0x81          Keyboard Volume Dn
LOCKING_CAPS_LOCK   0x82          Keyboard Locking Caps Lock
LOCKING_NUM_LOCK    0x83          Keyboard Locking Num Lock
LOCKING_SCROLL_LOCK 0x84          Keyboard Locking Scroll Lock
PAD_COMMA           0x85          Keypad comma (Brazilian Keypad .)
EQUAL_SIGN          0x86          Keyboard Equal Sign
INTERNATIONAL_1     0x87          Keyboard Int'l 1 (Ro)
INTERNATIONAL_2     0x88          Keyboard Intl'2 (Katakana/Hiragana)
INTERNATIONAL_3     0x89          Keyboard Int'l 2 (Yen)
INTERNATIONAL_4     0x8A          Keyboard Int'l 4 (Henkan)
INTERNATIONAL_5     0x8B          Keyboard Int'l 5 (Muhenkan)
INTERNATIONAL_6     0x8C          Keyboard Int'l 6 (PC9800 Keypad comma)
INTERNATIONAL_7     0x8D          Keyboard Int'l 7
INTERNATIONAL_8     0x8E          Keyboard Int'l 8
INTERNATIONAL_9     0x8F          Keyboard Int'l 9
LANG_1              0x90          Keyboard Lang 1 (Hanguel/English)
LANG_2              0x91          Keyboard Lang 2 (Hanja)
LANG_3              0x92          Keyboard Lang 3 (Katakana)
LANG_4              0x93          Keyboard Lang 4 (Hiragana)
LANG_5              0x94          Keyboard Lang 5 (Zenkaku/Hankaku)
LANG_6              0x95          Keyboard Lang 6
LANG_7              0x96          Keyboard Lang 7
LANG_8              0x97          Keyboard Lang 8
LANG_9              0x98          Keyboard Lang 9
ALTERNATE_ERASE     0x99          Keyboard Alternate Erase
SYSREQ_ATTN         0x9A          Keyboard SysReq/Attention
CANCEL              0x9B          Keyboard Cancel
CLEAR               0x9C          Keyboard Clear (use DELETE instead)
PRIOR               0x9D          Keyboard Prior
RETURN              0x9E          Keyboard Return
SEPARATOR           0x9F          Keyboard Separator
OUT                 0xA0          Keyboard Out
OPER                0xA1          Keyboard Oper
CLEAR_AGAIN         0xA2          Keyboard Clear/Again
CRSEL_PROPS         0xA3          Keyboard CrSel/Props
EXSEL               0xA4          Keyboard ExSel
SYSTEM_POWER        0xA8          System Power
SYSTEM_SLEEP        0xA9          System Sleep
SYSTEM_WAKE         0xAA          System Wake
AUX1                0xAB          Auxiliary key 1
AUX2                0xAC          Auxiliary key 2
AUX3                0xAD          Auxiliary key 3
AUX4                0xAE          Auxiliary key 4
AUX5                0xAF          Auxiliary key 5
EXTRA_LALT          0xB1          AT-F extra pad lhs of space
EXTRA_PAD_PLUS      0xB2          Term extra pad bottom of keypad +
EXTRA_RALT          0xB3          AT-F extra pad rhs of space
EXTRA_EUROPE_2      0xB4          AT-F extra pad lhs of enter
EXTRA_BACKSLASH     0xB5          AT-F extra pad top of enter
EXTRA_INSERT        0xB6          AT-F extra pad lhs of Insert
EXTRA_F1            0xB7          122-key Terminal lhs F1
EXTRA_F2            0xB8          122-key Terminal lhs F2
EXTRA_F3            0xB9          122-key Terminal lhs F3
EXTRA_F4            0xBA          122-key Terminal lhs F4
EXTRA_F5            0xBB          122-key Terminal lhs F5
EXTRA_F6            0xBC          122-key Terminal lhs F6
EXTRA_F7            0xBD          122-key Terminal lhs F7
EXTRA_F8            0xBE          122-key Terminal lhs F8
EXTRA_F9            0xBF          122-key Terminal lhs F9
EXTRA_F10           0xC0          122-key Terminal lhs F10
EXTRA_SY            0xC2          Sys Req (AT 84-key)
FN1                 0xD0          Function layer key 1
FN2                 0xD1          Function layer key 2
FN3                 0xD2          Function layer key 3
FN4                 0xD3          Function layer key 4
FN5                 0xD4          Function layer key 5
FN6                 0xD5          Function layer key 6
FN7                 0xD6          Function layer key 7
FN8                 0xD7          Function layer key 8
SELECT_0            0xD8          Select reset
SELECT_1            0xD9          Select 1 toggle
SELECT_2            0xDA          Select 2 toggle
SELECT_3            0xDB          Select 3 toggle
SELECT_4            0xDC          Select 4 toggle
SELECT_5            0xDD          Select 5 toggle
SELECT_6            0xDE          Select 6 toggle
SELECT_7            0xDF          Select 7 toggle
LCTRL               0xE0          Left Control
LSHIFT              0xE1          Left Shift
LALT                0xE2          Left Alt
LGUI                0xE3          Left GUI (Left Windows)
RCTRL               0xE4          Right Control
RSHIFT              0xE5          Right Shift
RALT                0xE6          Right Alt
RGUI                0xE7          Right GUI (Right Windows)
MEDIA_NEXT_TRACK    0xE8          Scan Next Track
MEDIA_PREV_TRACK    0xE9          Scan Previous Track
MEDIA_STOP          0xEA          Stop
MEDIA_PLAY_PAUSE    0xEB          Play/ Pause
MEDIA_MUTE          0xEC          Mute
MEDIA_BASS_BOOST    0xED          Bass Boost
MEDIA_LOUDNESS      0xEE          Loudness
MEDIA_VOLUME_UP     0xEF          Volume Up
MEDIA_VOLUME_DOWN   0xF0          Volume Down
MEDIA_BASS_UP       0xF1          Bass Up
MEDIA_BASS_DOWN     0xF2          Bass Down
MEDIA_TREBLE_UP     0xF3          Treble Up
MEDIA_TREBLE_DOWN   0xF4          Treble Down
MEDIA_MEDIA_SELECT  0xF5          Media Select
MEDIA_MAIL          0xF6          Mail
MEDIA_CALCULATOR    0xF7          Calculator
MEDIA_MY_COMPUTER   0xF8          My Computer
MEDIA_WWW_SEARCH    0xF9          WWW Search
MEDIA_WWW_HOME      0xFA          WWW Home
MEDIA_WWW_BACK      0xFB          WWW Back
MEDIA_WWW_FORWARD   0xFC          WWW Forward
MEDIA_WWW_STOP      0xFD          WWW Stop
MEDIA_WWW_REFRESH   0xFE          WWW Refresh
MEDIA_WWW_FAVORITES 0xFF          WWW Favorites

Deprecated Code Names v1.0+
The following code names are deprecated, and should no longer be used.
They are included for compatibility with older config files written for v0.997.
Replacements for these names have been added beginning 'EXTRA_'.
(As in, the change is just in the names of these codes).

Name              HID Code        Description
FAKE_01             0xB0          extra
FAKE_02             0xB1          AT-F extra pad lhs of space
FAKE_03             0xB2          Term extra pad bottom of keypad +
FAKE_04             0xB3          AT-F extra pad rhs of space
FAKE_05             0xB4          AT-F extra pad lhs of enter
FAKE_06             0xB5          AT-F extra pad top of enter
FAKE_07             0xB6          AT-F extra pad lhs of Insert
FAKE_08             0xB7          Term F1
FAKE_09             0xB8          Term F2
FAKE_10             0xB9          Term F3
FAKE_11             0xBA          Term F4
FAKE_12             0xBB          Term F5
FAKE_13             0xBC          Term F6
FAKE_14             0xBD          Term F7
FAKE_15             0xBE          Term F8
FAKE_16             0xBF          Term F9
FAKE_17             0xC0          Term F10
FAKE_18             0xC1          extra
FAKE_19             0xC2          Sys Req (AT 84-key)

Modifiers
For most uses, either a single key or a combination can be specified.
Depending on context, a combination might mean 'any' or 'all' of the specified modifiers.

Name         Description
LCTRL        Left Control
LSHIFT       Left Shift
LALT         Left Alt
LGUI         Left GUI (Left Windows)
RCTRL        Right Control
RSHIFT       Right Shift
RALT         Right Alt
RGUI         Right GUI (Right Windows)
CTRL         Either/Both Control (shorthand for LCTRL RCTRL)
SHIFT        Either/Both Shift (shorthand for LSHIFT RSHIFT)
ALT          Either/Both Alt (shorthand for LALT RALT)
GUI          Either/Both GUI (shorthand for LGUI RGUI)
ALL          Any/All (shorthand for CTRL SHIFT ALT GUI)
tools
Spoiler:

Code: Select all

XT/AT/PS2/Terminal to USB Converter with NKRO
Command Line Tools v0.997+
Introduction
Tools
scas
scdis
scwr
scrd
scboot
scinfo
scaswr
Building
Windows
Linux
Mac OS-X


Introduction
============

The main tools are scas and scwr.

Typically, you edit your config file(s), assemble them with scas, then load them onto the converter with scwr.

As long as it says 'device: complete' at the end, scwr has succeeded.

C:\sctools> scas foo.sc foo.scb
No errors. Wrote: foo.scb

C:\sctools> scwr foo.scb
Looking for Soarer's Converter: found
...
device: complete
On Windows, you may find scaswr more convenient. It simply combines the two steps.

Tools
=====

Tool	Description
scas	Assembles one or more config text files to a config binary file
scdis	Dissassembles a config binary file to a config text file
scwr	Writes a config binary file to the converter
scrd	Reads a config binary file from the converter
scboot	Causes the converter to jump to the bootloader v1.0+
scinfo	Displays converter's version and memory information v1.0+
scaswr	Combination of scas and scwr (Windows only) v1.1+

scas
Assembles one or more config text files to a config binary file.

Usage:

scas <text_config> [<text_config> ...] <binary_config>
Output, if everything is fine:

No errors. Wrote: foo.scb
Output, if there's an error:

error at line 4: invalid argument
Output, if there's an error in an included file in an included file:

error at line 4: error at line 5: error at line 5: invalid argument
To find the error, start with the last line number given, which will be an include command.
Then look in that file for the next to last line number given, and so on.
The first line number given is where the actual error is.

Only the first error found is reported.

Alternatively, check that included files assemble successfully on their own, before including into another config.

scdis
Dissassembles a config binary file to a config text file.

Usage:

scdis <binary_config> [<text_config>]
There is no output unless an error occurs.

This tool might be useful to validate that your config assembles as you expected (it was very useful while I was writing scas).

scwr
Writes a config binary file to the converter.

Usage:

scwr <binary_config>
Output:

scwr: looking for Soarer's Converter: found
scwr: reading file: 139 bytes: ok
scwr: sending info request: ok
device: ok
protocol version check: converter=1.00, scwr=1.00: ok
settings version check: converter=1.01, file=1.01: ok
settings length check: max=1018, file=137 bytes: ok
scwr: sending write request for 137 bytes: ok
device: ok
device: ready
scwr: sending 60 bytes: ok
device: ok
device: ready
scwr: sending 60 bytes: ok
device: ok
device: ready
scwr: sending 17 bytes: ok
device: ok
device: complete
scrd
Reads a config binary file from the converter.

Usage:

scrd <binary_config>
Output:

scrd: looking for Soarer's Converter: found
scrd: sending read request: ok
device: has 137 bytes: ok
scrd: ready
device: sent 64 bytes: ok
scrd: ok
scrd: ready
device: sent 64 bytes: ok
scrd: ok
scrd: ready
device: sent 9 bytes: ok
scrd: ok
scrd: complete
scrd: writing file: 139 bytes: ok
scboot v1.0+
Causes the converter to jump to the bootloader.

Usage:

scboot
After running this command, the converter should be ready to have new firmware loaded into it. Note that, at this point, the converter will not be working as a keyboard any more! To cancel the bootloader mode, simply disconnect the converter from the computer and reconnect it.

Output:

scboot: looking for Soarer's Converter: found
scboot: sending boot request: ok
device: ok
scinfo v1.0+
Displays converter's version and memory information.

Usage:

scinfo
Output:

Code Version: v1.00
Max Settings Version: v1.01
Current Settings Version: v1.01
SRAM Size: 2560 bytes
SRAM Free: 1817 bytes
EEPROM Size: 1024 bytes
EEPROM Free: 883 bytes
scaswr.bat (Windows only) v1.1+
A combination of scas and scwr, designed so you can simply drag'n'drop a config file onto it (or a shortcut to it). It will assemble the text config and then write the resulting binary config to the converter, in a single step.

Of course, it can also be used from the command line...

Usage:

scaswr <text_config>

Building
========

Source code is provided, along with makefiles etc., to natively build on Windows, Linux and OS-X.
Additionally, a mingw32 cross-compile can be used to build the Windows tools on Linux.

To rebuild the tools, change directory to the sub-directory of build that's right for your OS, and type make.

Windows
The tools are built for Windows using MS Visual Studio 2003. Porting to later versions should be trivial.

scwr, scrd, scboot and scinfo rely on a small library of RAWHID routines from PJRC.
For Windows, this library was compiled to a DLL using the Microsoft DDK.

Linux v1.0+
The tools are built for Linux using gcc etc.

Mac OS-X v1.0+
The tools are built for Mac OS-X on Snow Leopard using Xcode 3.2.6 and the version 10.6 SDK.
hardware
Spoiler:
Hardware
Parts List
Wiring Info
Connectors
Pull-up resistors
LEDs
Auxiliary Key Inputs
Connection Summary for Teensy
Parts List
Essential items:

Teensy, or similar AVR breakout board
Connector to suit your keyboard
Some wire
Optional items, as desired:

3x LEDs
3x Resistors for LEDs (value depends on the LEDs)
2x 1k Resistors (for pull-ups)
Box (optional, but recommended!)
You could, of course, mount the Teensy inside your keyboard and not even need a connector or a box!

See the firmware section for details of supported AVR processors and breakout boards.

Wiring Info
Connector Breakout board
GND GND
Vcc/+5V VCC
Data PD0
Clock PD1
Keyboard Reset v1.1+ PB7

See PJRC for Teensy pinouts, or the documentation that came with your chosen breakout board.

'Keyboard Reset' is only required for certain PC/XT-like keyboards, such as the Leading Edge DC-2014.

Connectors
I wired mine to a PS/2 socket, and then use adapters to connect the others.

kbdbabel has masses of connector info. So much, that it can be hard to find the one you want!

So I've included the most common connectors used with this converter here.

Note that all the connectors are shown looking into the socket.


PC/XT keyboards use a 5 pin, 180 degree, DIN connector. It is the same as the AT connector shown later, except that pin 3 is defined as a reset signal...


(from the IBM PC Technical Reference Manual, with correction!)


Terminal keyboards usually have a 5 pin, 270 degree, DIN connector...


...or sometimes this 8P5C connector...


PC, XT and AT keyboards use the same 5 pin, 180 degree, DIN connector and pinout, while PS/2 keyboards use a 6 pin mini-DIN connector...


RT keyboards have this connector...


Pull-up resistors
In nearly all cases, these resistors are not needed.

But, if the keyboard has a very long cable (3m+), I recommend adding two pull-up resistors of 1Kohm - one between Clock and +5V, the other between Data and +5V. These can really help to clean up a dirty signal (see here).

LEDs
Optionally, lock LEDs can be wired up. Useful if your keyboard doesn't have them!
The outputs are active high (each pin puts out +5V when it wants to light the LED).
A resistor is needed inline with each LED. (The value needed depends on the type of LED, 1Kohm is a good starting point for modern high-brightness types).

Here's an example circuit for hooking up an LED, taken from ladyada.net:

They also have a more in-depth tutorial.


The pins used differ between CPUs.

ATMEGA32U4 (Teensy 2.0) and ATMEGA16U4:

LED CPU Pin
CapsLock PF5
NumLock PF6
ScrollLock PF7
AT90USB1286 (Teensy++ 2.0) and AT90USB646:

LED CPU Pin
CapsLock PD3
NumLock PD4
ScrollLock PD5
Auxiliary Key Inputs v1.1+
Five inputs are provided for auxiliary keys, buttons, or footswitches, which generate codes that can be remapped in your config:

Auxiliary Key Code CPU Pin
1 AUX1 PB0
2 AUX2 PB1
3 AUX3 PB2
4 AUX4 PB3
5 AUX5 PB4
Inputs cause key presses when grounded, so you can simply connect the switch between the pin and ground:



Inputs have the internal pull-up enabled, so an external resistor won't be required in most cases. But it might be necessary to use one, for example with footswitches where the wires are long. Here's how you would wire one up:



Connection Summary for Teensy
The GND and Vcc pins at the end of the Teensy can be used instead of the marked GND and Vcc, if you prefer. Or you might choose to wire the connector to one GND and the LEDs using the other.

Of course, not all connections are required! The minimum and still fairly typical setup would be to connect just Ground, +5V, Data and Clock to the connector (or keyboard).
firmware
Spoiler:
XT/AT/PS2/Terminal to USB Converter with NKRO
Firmware
CPUs
Loading
CPUs
The firmware has been compiled for the following CPUs, listed roughly in order of preference:

CPU Known breakout board(s)
ATmega32U4 Teensy 2.0, Adafruit Atmega32u4 Breakout Board
AT90USB1286 Teensy++ 2.0
AT90USB646 Teensy++ (no longer available)
ATmega16U4 ???

Make sure you pick the right .hex file for your dev board!

ATmega32U4 breakout boards are usually the best choice, on a price basis.

AT90USB1286 boards work equally as well, and have more memory (which can be essential if you want to set up a very large number of layers and/or macros), but cost more.

Note: the ATmega16U4 build is very close to 16KB in size, and probably does not leave room for a USB bootloader on the chip.
So, ATmega16U4 based breakout boards are not recommended for novices!

Loading
The Teensy family have the PJRC bootloader installed and are programmed using PJRC's Teensy Loader, available for all common OS.

Other breakout boards usually have the Atmel DFU bootloader installed and can be programmed using FLIP.
FLIP is available for Windows and Linux. For Mac OS-X, see this guide on how use DFU-programmer.

Arduino Leonardo can be programmed using avrdude, or the Arduino IDE.
controller config
Spoiler:

Code: Select all

Controller Config v1.20+
Overview
Command Reference
led
matrix
scanrate
debounce
debounce_method
blocking
strobe_mode
sense_delay
sense_polarity
muxstrobe_port
muxstrobe_enable
muxstrobe_gate
sense
muxstrobe
strobe
unstrobed

Overview
This brief page describes the new commands added to support Controller functionality.
All of the remapping, layer, select and macro commands of the Converter config are also supported.

A matrix is a grid of switches arranged in rows and columns.
To make clear which is driven by the controller and which is read, I mainly use the terms strobe and sense instead.
Depending on the matrix (and the orientation of the diodes, if it has them) you might strobe the rows and sense the columns, or you might strobe the columns and sense the rows.

Command Reference
led
Lock LEDs can be connected to any pin, and the polarity of each pin can be individually configured.

led <lock> [-]<pin>
Example:

led caps PD3     # for when the other end of the LED/resistor combination is 0V
led num -PD4     # for when the other end of the LED/resistor combination is +5V
led scroll -PD5
matrix
Syntax:

matrix
    [scanrate <milliseconds>]
    [debounce <scans>]
    [debounce_method <method_num>]
    [blocking <flag>]
    [strobe_mode <mode>]
    [sense_delay <microseconds>]
    [sense_polarity <polarity>]
    [muxstrobe_port <port_pin_range>]
    [muxstrobe_enable [-]<pin>]
    [muxstrobe_gate [-]<pin>]
    [sense <pin> ...]
    [muxstrobe <number> <hid> ...]
    ...
    [strobe <pin> <hid> ...]
    ...
    [unstrobed [-]<pin> <hid>]
    ...
end
All options have default values, so often hardly any need to be used.

The sense, muxstrobe, strobe and unstrobed options, when used, must be given in that order!

Full example for my mini keyboard, which has 8 rows and 8 columns, and diodes fitted to each switch:

matrix
    blocking 0

    sense           PB0         PB1 PB2         PB3 PD0 PD1         PD2         PD3

    strobe  PF0     ESC         2   4           5   7   9           MINUS       LCTRL
    strobe  PF1     1           3   UNASSIGNED  6   8   0           BACKSPACE   LGUI
    strobe  PF4     TAB         W   R           T   U   O           LEFT_BRACE  LALT
    strobe  PF5     Q           E   BACKSPACE   Y   I   P           RIGHT_BRACE UNASSIGNED
    strobe  PF6     CAPS_LOCK   S   F           G   J   L           ENTER       RALT
    strobe  PF7     A           D   SPACE       H   K   SEMICOLON   UNASSIGNED  MENU
    strobe  PB6     LSHIFT      Z   C           V   N   COMMA       FN2         RCTRL
    strobe  PB7     FN1         X   UNASSIGNED  B   M   PERIOD      RSHIFT      UNASSIGNED
end
scanrate

Scan rate is set in milliseconds, in other words it's actually the interval between scans.
The default is 1ms, giving a scan rate of 1000Hz.
Valid values are from 1 to 8, allowing scan rates between 1000Hz and 125Hz.
There's little reason to change this unless scanning is unreliable, or you need to extend the debounce time.

debounce

Debounce time is set as a number of scans. Multiply by the scan interval to get a debounce time in milliseconds.
The default is 5, which, along with the default scan rate, would give a debounce time of 5ms.
Valid values are from 1 to 7.
To get a higher debounce time than 7ms, the scan interval should be increased.

debounce_method

Two debounce methods are supported, both of which debounce each key individually.
Method 0 is a standard debounce, to handle both noisy switch contacts and electro-magnetic interference (EMI).
Method 1 is a turbo debounce, which adds no lag to your inputs unlike the standard debounce. It does not handle EMI.

blocking

Specify whether to activate the ghost key blocking function, which is required when the matrix does not have diodes (or equivalent such as capacitive sensing).
Valid values are 0 (off) and 1 (on).
The default is on.

strobe_mode

Various strobe modes can be selected, although it will be quite unusual to need anything other than the default, which is 0.

WARNING: exercise caution when using modes 1 or 5, since errors in the connections or lack of diodes can easily damage the Teensy!

Mode  Active  Inactive
0     low     pullup
1     low     high
2     low     float
3     float   high
4     pullup  low
5     high    low
6     float   low
7     high    float

sense_delay

A delay of at least 1 microsecond (µs) is inserted between setting a strobe and reading the senses, to allow the signals across the matrix to settle.
Valid values are from 1 to 64 µs.
The default is 1 µs.

sense_polarity

This setting should normally match the strobe mode, with 0 being used for strobe_modes 0 to 3, and 1 being used for strobe_modes 4 to 7.
Valid values are 0 (active low) or 1 (active high).
The default is 0.

muxstrobe_port

For multiplexed strobes, muxstrobe_port defines the port and range of pins used to select the strobe.
Currently this is restricted to a contiguous set of pins on a single port.

Example:

muxstrobe_port PF7:4
muxstrobe_enable

External decoding logic may require an enable signal. This option assign a pin to that function.
The pin will be made active before scanning muxstrobes and inactive after - i.e. it remains active for the entire scan of all muxstrobes.
If the pin name is preceded with '-', the signal will be active low.

Example:

muxstrobe_enable -PD4
muxstrobe_gate

External decoding logic may require a gate signal. This option assign a pin to that function.
The pin will be made active and then inactive for each muxstrobe.
If the pin name is preceded with '-', the signal will be active low.

Example:

muxstrobe_gate -PD3
sense

Specifies a list of pins to read every time the matrix is strobed by either strobe or muxstrobe.

Example:

sense PB3 PB7 PD0 PD1 PD2 PD3 PC6 PC7
strobe

Specifies a pin to strobe, and the HID codes corresponding to each sense pin.
If fewer HID codes are given than there are sense lines, the remainder are assumed to be UNASSIGNED.

Example:

strobe PF0 ESC 2 4 5 7 9 MINUS LCTRL
muxstrobe

As strobe, except that instead of a pin to strobe, this specifies a code to send to the external decoding logic.

Example:

muxstrobe 7 ESC 2 4 5 7 9 MINUS LCTRL
unstrobed

Specifies a single pin to read and the corresponding HID code.
This is intended for a single switch which can be wired with the other side of the switch permanently connected to either ground or +5V. If the other side of the switch is at +5V, a pull-down resistor must be added between the pin and ground.

Example:

unstrobed -PF1 LSHIFT
That last one is specific to the controller, which can do everything Soarer's converter can do, wile driving a matrix too! Enjoy.
Last edited by Muirium on 27 Feb 2021, 01:01, edited 2 times in total.

User avatar
sharktastica

25 Feb 2021, 13:18

Oh, this is awesome!

I'll spread the news since I know a lot of people who would be interested in this. Cheers, Mu!

User avatar
Muirium
µ

25 Feb 2021, 14:33

You're welcome, folks! I finally got around to building it because I really needed it myself. Soarer did all the real work, I simply did some mopping up afterwards. :D

User avatar
UnscrambledEggs

25 Feb 2021, 19:40

:D This is absolutely amazing! Shark shared this and I had to come here to thank you, it's been a real hassle to get it Soarer's converters programmed 'til now.

User avatar
Muirium
µ

25 Feb 2021, 22:05

You’re telling me! I was borrowing a Windows friend (hey, uh, now it’s this keyboard… I already wrote the config file!) but then lockdown put them out of reach. Besides, I was getting on their nerves, and mine.

Building this took winding back my 2013 MacBook Pro to its original OS, Mavericks, and building against the Snow Leopard SDK as I remember. Which may be inaccurate! I know I installed and included several older SDKs before it worked.

Pretty sure the tools will need rewritten for different libraries to be able to build on modern Macs. Fortunately Rosetta runs them perfectly on M1. (For now…)

edlee

27 Feb 2021, 17:26

Did you uncomment the following 2 lines? There is a bug in the, "hid_tokens.cpp", source file. For some reason, Soarer commented out two lines for:

//{ "EXTRA_UNUSED_1", 0xB0 }, // extra
//{ "EXTRA_UNUSED_2", 0xC1 }, // extra

This causes the hid_token_list[] array indexes for the HID codes greater than 0xB0 to be decremented by 1 and the array indexes for the HID codes greater than 0xC1 to be decremented by another 1. This causes the lookup_hid_token(int value) function to return the wrong HID name (token) for the HID values that are equal to or greater than 0xB0. This potentially affects the, "scdis.cpp", program which uses the lookup_hid_token(int value) function to disassemble a binary *.scb file.

If the lookup_hid_token(int value) function is used in other source files which Soarer did not release, then those source files might be affected as well.

I uncommented these lines and recompiled the, "scas.exe", and, "scdis.exe", programs with MinGW for Windows using static libraries, which is why the files are larger than the originals.

User avatar
Muirium
µ

02 Mar 2021, 14:56

edlee wrote:
27 Feb 2021, 17:26
Did you uncomment the following 2 lines? There is a bug in the, "hid_tokens.cpp", source file. For some reason, Soarer commented out two lines for…
No, I did not. And no: it works perfectly as is, for me on Mac.

I've just hooked up a keyboard to test this just now. I juggled the modifier keys around in the configuration file, compiled it with scas, upped them to the board, and they work fine: all with HID codes greater than 0xC1. Also tried the round-trip with scrd and scdis. It's all working as it always did before.

This is on an M1 Mac, running the tools through Rosetta, in Big Sur. So it's definitely my recompiled versions! 32 bit won't even run here.

I used these rebuilt tools quite a bit a few months back when I first recompiled them. You had me second guessing myself! But no, they're fine. I don't know Soarer's reason for commenting out those lines, but it definitely works on Mac, even in 64 bit.

crypto_sloth

12 Apr 2021, 13:56

These tools worked perfect for me, thanks Muirium!
Flashed a Teensy++ for a IBM 5140 board with this 64 bit soarer's controller.
Also using a M1 Mac, and had to do it from a Rosetta Terminal as described.

User avatar
Muirium
µ

12 Apr 2021, 14:03

You're welcome. :D

Rosetta's perfectly seamless. You just run them exactly the same on M1 as on Intel.

User avatar
darkcruix

12 Apr 2021, 18:54

Man - great work !!!

Just saw it now and I have no idea, how I could have missed this..... Do you mind, if I use some of it in the Technical Manual around Soarer's?

Thanks,

Roland

User avatar
Muirium
µ

12 Apr 2021, 19:54

Go ahead, my man. Spread the gift of Soarer’s! :lol:

Be sure to give us a link, too. I wanna see this.

User avatar
darkcruix

12 Apr 2021, 20:09

Muirium wrote:
12 Apr 2021, 19:54
Go ahead, my man. Spread the gift of Soarer’s! :lol:

Be sure to give us a link, too. I wanna see this.
Will all be in the Technical Manual: https://www.bucklingspring.com/technica ... downloads/.

User avatar
Muirium
µ

12 Apr 2021, 21:13

Impressive file sizes! Are you sending blueprints? Maybe high res geospatial imagery for replicators, once future generations figure out how to order those.

User avatar
darkcruix

13 Apr 2021, 21:17

I couldn't resist ... find attached the compiled tools in ARM64 binary as well ....
I used: https://github.com/Kreeblah/sctools_macos as basis and changed the architecture and minimum OS accordingly (arm64 and 11.1)

Code: Select all

SDK = /Library/Developer/CommandLineTools/SDKs/MacOSX11.1.sdk
ARCH = -mmacosx-version-min=11.1 -arch arm64
Screen Shot 2021-04-13 at 9.15.07 PM.png
Screen Shot 2021-04-13 at 9.15.07 PM.png (160.24 KiB) Viewed 1755 times
Tools included:

Code: Select all

scas
scboot
scdis
scinfo
scrd
scwr
Archive.zip
(47.28 KiB) Downloaded 33 times

ps: I am waiting for a SDL to USB cable for my SSK and I am using one of those new MacBooks ... hence I played with it. Hope it helps others as well. Thanks Mu!!!!!
Last edited by darkcruix on 13 Apr 2021, 21:28, edited 1 time in total.

User avatar
darkcruix

13 Apr 2021, 21:23

Muirium wrote:
12 Apr 2021, 21:13
Impressive file sizes! Are you sending blueprints? Maybe high res geospatial imagery for replicators, once future generations figure out how to order those.
Yeah, I know. I kept the quality of the pictures nearly native, so I can pass this to a professional printer to get some books done at some point. Not that books are something desirable anymore ;). I still enjoy them, so ...

User avatar
Muirium
µ

14 Apr 2021, 12:12

Nice work on the Arm binaries! Naturally, I'd never heard of Kreeblah's modernised port. Looks like they did the plumbing required to get these to build again. I couldn't get modern Xcode versions to play ball on the original source at all.

Anyway, one issue: MacOS's built in Gatekeeper does indeed block running these new builds on first install. Those of us downloading the binaries must run this command in their download / extraction folder:

Code: Select all

xattr -cr *
I learned this trick with Mini vMac, explained here. The files have an extended attribute added to them, which must be stripped off; or you need to build them with a developer certificate supplied by Apple.

My x86_64 builds escaped this because I built them on an ancient Xcode, so they were grandfathered in. :roll:

lukebpalmer

24 Oct 2021, 22:48

HELP REQUESTED
(2019 imac, MacOS Big Sur, IBM Model F AT 1986)
My keyboard is not responding to your code and I'm not really sure why.
My keyboard is running just normally and the Esc key is functioning normally.

I downloaded the zip & opened it in my terminal window.

I created this bare-bones FAT_1.sc file:
# test

# Some quality of life remaps
ifselect any
remapblock
ESC NUM_LOCK
endblock

# Macros for automating Windows shortcuts
macroblock
endblock
Heres some code and ouput:

$ ./scinfo

"scinfo v1.10
scinfo: looking for Soarer's Converter: found
scinfo: sending info request: ok
device: ok

Protocol Version: v1.00
Code Version: v1.12
Max Settings Version: v1.01
Current Settings Version: v1.01
SRAM Size: 2816 bytes
SRAM Free: 1806 bytes
EEPROM Size: 1024 bytes
EEPROM Free: 1007 bytes"

$ ./scas FAT_1.sc FAT_1.scb

"scas v1.10
No errors. Wrote: FAT_1.scb"

$ ./scwr FAT_1.scb

"scwr v1.10
scwr: looking for Soarer's Converter: found
scwr: reading file: 15 bytes: ok
scwr: sending info request: ok
device: ok
protocol version check: converter=1.00, scwr=1.00: ok
settings version check: converter=1.01, file=1.01: ok
settings length check: max=1018, file=13 bytes: ok
scwr: sending write request for 13 bytes: ok
device: ok
device: ready
scwr: sending 13 bytes: ok
device: ok
device: complete"

User avatar
Muirium
µ

29 Oct 2021, 12:36

The logs you pasted say it worked fine.

On Soarer, the key remap syntax works like this: Keycode you want to remap *from* (space) Keycode you want to remap *to*. So, depending on what you're actually trying to do, maybe try reversing your single remap? The Mac platform itself doesn't support Num Lock like PCs do. Macs consider it the "Clear" key.

Here's my own AT.sc for an example. I modified my AT, though, so its numpad is laid out differently in hardware, and won't match yours. Try assembling and flashing this to your converter. Then, if it works, delete all the complex stuff you don't want and get editing!

Code: Select all

#	Modded IBM AT with internal Teensy

layerblock
	fn1 1
endblock

#	Fair old bit of remapping for that vintage layout and shifted numpad

remapblock
layer 0
	BACK_QUOTE		ESC
	LALT			LGUI
	F9				RCTRL
	F10				LALT
	BACKSPACE		BACK_QUOTE
	EXTRA_BACKSLASH	BACKSPACE
	CAPS_LOCK		FN1
	ESC				select_1	# Toggle numpad navigation mode
	PAD_7			DELETE
	PAD_4			PAGE_UP
	PAD_1			PAGE_DOWN
	PAD_2			UP
	EXTRA_INSERT	LEFT
	PAD_0			DOWN
	PAD_PERIOD		RIGHT
	PAD_5			PAD_1
	PAD_6			PAD_2
	PAD_MINUS		PAD_3
	PAD_8			PAD_4
	PAD_9			PAD_5
	PAD_ASTERIX		PAD_6
	NUM_LOCK		PAD_7
	SCROLL_LOCK		PAD_8
	EXTRA_SYSRQ		PAD_9
	PAD_PLUS		PAD_0
	F11				PAD_PERIOD
endblock

#	Lots of HHKB goodness

remapblock
layer 1
	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
	I				PRINTSCREEN
	O				SCROLL_LOCK
	P				PAUSE
	A				MEDIA_VOLUME_DOWN
	S				MEDIA_VOLUME_UP
	D				MEDIA_MUTE
	ESC				SYSTEM_POWER
	1				F1
	2				F2
	3				F3
	4				F4
	5				F5
	6				F6
	7				F7
	8				F8
	9				F9
	0				F10
	MINUS			F11
	EQUAL			F12
	BACKSLASH		INSERT
	BACKSPACE		DELETE
	ENTER			PAD_ENTER
	EXTRA_BACKSLASH	DELETE
	TAB				CAPS_LOCK
	PAD_5			END
	PAD_6			DOWN
	PAD_MINUS		PAGE_DOWN
	PAD_8			LEFT
	PAD_9			DOWN
	PAD_ASTERIX		RIGHT
	PAD_PERIOD		ENTER
	NUM_LOCK		HOME
	SCROLL_LOCK		UP
	EXTRA_SYSRQ		PAGE_UP
endblock


macroblock

#	App window cycling, HHKB style

macro ESC -lalt lgui -ralt
	PRESS BACK_QUOTE
endmacro

#	Quick Ctrl + Number access to System Menus etc.

macro 2 lctrl
	PRESS F2
endmacro
macro 3 lctrl  # 01 01
	PRESS F3
endmacro
macro 4 lctrl  # 01 01
	PRESS F4
endmacro
macro 8 lctrl  # 01 01
	PRESS F8
endmacro

#	Shift + Shift = Caps Lock

macro LSHIFT rshift  # 20 20
	PRESS CAPS_LOCK
endmacro
macro RSHIFT lshift  # 02 02
	PRESS CAPS_LOCK
endmacro
endblock

#	Numpad nav block - toggle with Num Lock (marked Escape)

ifselect 1
remapblock
layer 0
	pad_5		end
	pad_6		down
	pad_minus	page_down
	pad_8		left
	pad_9		pad_5
	pad_asterix	right
	num_lock	home
	scroll_lock	up
	extra_sysrq	page_up
	pad_plus	pad_enter
	f11			pad_enter
endblock
If you want to make a Num Lock mode, you can do it by a select function like this:

Code: Select all

remapblock
layer 0
	num_lock	select_1	#	Toggle numpad to navigation block
endblock

#	Numpad nav block - toggle with Num Lock
ifselect 1
remapblock
layer 0
	pad_1		end
	pad_2		down
	pad_3		page_down
	pad_4		left
	pad_5		pad_5
	pad_6		right
	pad_7		home
	pad_8		up
	pad_9		page_up
	pad_0		ralt
endblock
That's the code I use in my general purpose Soarer's converter, for Model M and later layouts. You may need to tweak it a bit for the original AT keyboard.

Selects are Soarer's most advanced feature. So if you're new to this, learn basic remaps first. Unless you like splashing straight into the deep end!

lukebpalmer

03 Nov 2021, 19:49

SOLUTION

Yeah it seems my test case wasnt a very good one! Thanks for all of the help! That was genious to turn the NUM_LOCK key into a function key to swap the numpad!

Heres my current code that I used to remap and change keys for my keyboard. Not finalized but it may help somebody.

Code: Select all


# at_f_remaps_modded
ifset set2
remapblock
	F1			SYSTEM_SLEEP
	F2			ESC
	
	F3			F1 # Brightness-
	F4			F2 # Brightness+
	F5			MEDIA_VOLUME_DOWN
	F6			MEDIA_VOLUME_UP
	F7			MEDIA_MUTE
	F8			MEDIA_PLAY_PAUSE
	F9			MEDIA_PREV_TRACK
	F10			MEDIA_NEXT_TRACK
	
	ESC			DELETE
	SCROLL_LOCK		PAD_SLASH
	FAKE_19			PAD_ASTERIX
	PAD_ASTERIX		PAD_MINUS
	PAD_MINUS		PAD_PLUS
	PAD_PLUS		PAD_ENTER

	CLEAR			DOWN
	
	LCTRL			CAPS_LOCK
	CAPS_LOCK		RCTRL
endblock


# NUM LOCK FOR MAC

remapblock
layer 0
	num_lock	select_1
endblock

ifselect 1
remapblock
layer 0
	pad_1		end
	pad_2		down
	pad_3		page_down
	pad_4		left
	pad_5		down
	pad_6		right
	pad_7		home
	pad_8		up
	pad_9		page_up
	pad_0		insert
	pad_period	delete
endblock

This code implements this layout that I put together.

Image

I'm sure everybody knows about these guys but for those who dont i'm getting the keycaps from https://www.modelfkeyboards.com/product ... d-keycaps/ and probably ebay.

I havent anci modded it yet so that should be fun and terrifying preforming open heart surgery with this piece of history.
cheers!

ALTERNATIVE SOLUTION
Soarers converter is universal for macs and pcs. So you can compile on windows10 using the original win32 code and then plug the keyboard into imac after. Note if you detach the converter from the keyboard it resets the code and you have to scwr the code again.

Compiling on my wife's windows10 computer and typing on my imac worked like a charm!
Last edited by lukebpalmer on 04 Nov 2021, 06:25, edited 7 times in total.

lukebpalmer

03 Nov 2021, 19:56

Spoiler:
Muirium wrote:
29 Oct 2021, 12:36
The logs you pasted say it worked fine.

On Soarer, the key remap syntax works like this: Keycode you want to remap *from* (space) Keycode you want to remap *to*. So, depending on what you're actually trying to do, maybe try reversing your single remap? The Mac platform itself doesn't support Num Lock like PCs do. Macs consider it the "Clear" key.

Here's my own AT.sc for an example. I modified my AT, though, so its numpad is laid out differently in hardware, and won't match yours. Try assembling and flashing this to your converter. Then, if it works, delete all the complex stuff you don't want and get editing!

Code: Select all

#	Modded IBM AT with internal Teensy

layerblock
	fn1 1
endblock

#	Fair old bit of remapping for that vintage layout and shifted numpad

remapblock
layer 0
	BACK_QUOTE		ESC
	LALT			LGUI
	F9				RCTRL
	F10				LALT
	BACKSPACE		BACK_QUOTE
	EXTRA_BACKSLASH	BACKSPACE
	CAPS_LOCK		FN1
	ESC				select_1	# Toggle numpad navigation mode
	PAD_7			DELETE
	PAD_4			PAGE_UP
	PAD_1			PAGE_DOWN
	PAD_2			UP
	EXTRA_INSERT	LEFT
	PAD_0			DOWN
	PAD_PERIOD		RIGHT
	PAD_5			PAD_1
	PAD_6			PAD_2
	PAD_MINUS		PAD_3
	PAD_8			PAD_4
	PAD_9			PAD_5
	PAD_ASTERIX		PAD_6
	NUM_LOCK		PAD_7
	SCROLL_LOCK		PAD_8
	EXTRA_SYSRQ		PAD_9
	PAD_PLUS		PAD_0
	F11				PAD_PERIOD
endblock

#	Lots of HHKB goodness

remapblock
layer 1
	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
	I				PRINTSCREEN
	O				SCROLL_LOCK
	P				PAUSE
	A				MEDIA_VOLUME_DOWN
	S				MEDIA_VOLUME_UP
	D				MEDIA_MUTE
	ESC				SYSTEM_POWER
	1				F1
	2				F2
	3				F3
	4				F4
	5				F5
	6				F6
	7				F7
	8				F8
	9				F9
	0				F10
	MINUS			F11
	EQUAL			F12
	BACKSLASH		INSERT
	BACKSPACE		DELETE
	ENTER			PAD_ENTER
	EXTRA_BACKSLASH	DELETE
	TAB				CAPS_LOCK
	PAD_5			END
	PAD_6			DOWN
	PAD_MINUS		PAGE_DOWN
	PAD_8			LEFT
	PAD_9			DOWN
	PAD_ASTERIX		RIGHT
	PAD_PERIOD		ENTER
	NUM_LOCK		HOME
	SCROLL_LOCK		UP
	EXTRA_SYSRQ		PAGE_UP
endblock


macroblock

#	App window cycling, HHKB style

macro ESC -lalt lgui -ralt
	PRESS BACK_QUOTE
endmacro

#	Quick Ctrl + Number access to System Menus etc.

macro 2 lctrl
	PRESS F2
endmacro
macro 3 lctrl  # 01 01
	PRESS F3
endmacro
macro 4 lctrl  # 01 01
	PRESS F4
endmacro
macro 8 lctrl  # 01 01
	PRESS F8
endmacro

#	Shift + Shift = Caps Lock

macro LSHIFT rshift  # 20 20
	PRESS CAPS_LOCK
endmacro
macro RSHIFT lshift  # 02 02
	PRESS CAPS_LOCK
endmacro
endblock

#	Numpad nav block - toggle with Num Lock (marked Escape)

ifselect 1
remapblock
layer 0
	pad_5		end
	pad_6		down
	pad_minus	page_down
	pad_8		left
	pad_9		pad_5
	pad_asterix	right
	num_lock	home
	scroll_lock	up
	extra_sysrq	page_up
	pad_plus	pad_enter
	f11			pad_enter
endblock
If you want to make a Num Lock mode, you can do it by a select function like this:

Code: Select all

remapblock
layer 0
	num_lock	select_1	#	Toggle numpad to navigation block
endblock

#	Numpad nav block - toggle with Num Lock
ifselect 1
remapblock
layer 0
	pad_1		end
	pad_2		down
	pad_3		page_down
	pad_4		left
	pad_5		pad_5
	pad_6		right
	pad_7		home
	pad_8		up
	pad_9		page_up
	pad_0		ralt
endblock
That's the code I use in my general purpose Soarer's converter, for Model M and later layouts. You may need to tweak it a bit for the original AT keyboard.

Selects are Soarer's most advanced feature. So if you're new to this, learn basic remaps first. Unless you like splashing straight into the deep end!
Another question,
Do you know how to get the NUM LOCK light to turn on and off when pressing the NUM_LOCK button using your code..?

User avatar
Muirium
µ

05 Nov 2021, 13:28

The Mac does not maintain a Num Lock state. Caps Lock gets a working LED because Macs do that just the same as every other platform. My code uses Soarer's "select" feature to swap the numpad around with a toggle key, but the Mac knows nothing about it. Your Mac just sees you pressing those keys directly.

Years ago, when he was still around, I did ask Soarer for Num Lock and Scroll Lock LED controls. They were on his todo list, as I remember. But they were never implemented, so no, there is no way to control them with Soarer's converter.

Post Reply

Return to “Workshop”