Flashing HHKB Jp Controller Mac Layout Hex

Having recently received Hasu’s fantastic HHKB JP Bluetooth Controller, I noticed one irksome thing: the alt and command keys were reversed on the left hand side, and the kana key that I typically remap to right command was reverted.

This is normal: the keyboard targets Windows users primarily, but one thing you lose when upgrading to the Hasu controller are the dip switches that allow changing the role of caps lock, the arrow keys and setting it to macOS mode.

The default HHKB layout without Hasu controller
The default HHKB JP OSX layout without Hasu controller – link

Of course it’s a pretty easy change to fix: you simply need to head over to the TMK Keymap Editor and edit the current layout, then download the hex file and flash it, but I’ve done the work, so I might as well share!

HHKB Hasu Jp OSX Layout
A layout that reverses alt and command and sets the kana key to right command for use with macOS computers
HHKB Hasu Jp Alternative Controller Layer 2
An overview of the second layer (layer1, counting from 0) used in the Hasu HHKB JP default layout

First off, as in other tutorials, you’ll need the DFU/AVR tools installed in OSX. This is accomplished by using Homebrew.

The code to get these installed is as follows:

brew tap osx-cross/avr
brew install avr-libc dfu-programmer

Next up, you’ll need to download the layout hex file that I have compiled here: “mac_version.hex“. If, for whatever reason, you need to go back to the default firmware, I have that compiled as well: default.hex. Remember to unzip these files prior to using them if Safari doesn’t automatically unzip your downloads.

Finally, put the keyboard in DFU mode by pressing the button on the back of the controller, where the dip switches used to reside. You may need to remove the cover to do so, and note that you can use the cover if you have short fingernails.

Once in DFU mode, this one-liner will erase the firmware, load the new hex layout and reset the keyboard so that you can use it once again. Note that I’m assuming your hex file will be in the Downloads folder in your home directory, and I’d also recommend having a spare keyboard handy in case anything goes wrong.

Bash script:

sudo dfu-programmer atmega32u4 erase --force && \
sudo dfu-programmer atmega32u4 flash ~/Downloads/mac_version.hex && \
sudo dfu-programmer atmega32u4 reset

Finally, if your layout is still a bit odd (underscore and pipe not working), you may have set the keyboard to the wrong layout. In Apple OSX this can be done by opening the keyboard section of the settings and changing the keyboard layout. Note that it doesn’t really matter that ANSI is suggested when you hit shift+z, shift+?, but that you select JIS once completed, like so:

Open the keyboard panel in System Preferences, then click “Change Keyboard Type…” on the bottom left
Click continue (or press return) to start the detection wizard
Press shift+z, then shift+? as instructed
Select the JIS radio button, even though it defaults to ANSI

Getting Started with Salt Stack Windows Minions

Windows Salt Minions

This how-to on Windows Salt minions will just scratch the surface of the power behind Salt, and will cover remote execution, installation and management.

Please note: I’m new to Salt, and I’m a recovering Windows syasdamin from the 2000-2013 era. This means I probably have a bunch of out-moded ways of working with Windows.

To this end, this first question would be: why? Active Directory and associated policies do a good job of managing Wintel already. I’ve had luck in the past managing hundreds, thousands of servers, desktops and laptops using the tools Microsoft provides without too much issue, and I’ve heard things only got better since I left for greener pastures.

The easy answer is that many organisations may now find themselves with a combination of Linux and Windows servers, Windows and macOS workstations, coupled with the odd BSD system here and there, Linux desktops and Unix servers.

What Salt allows for is a management platform that covers all of these platforms with a common language that is easy to read and hack away at (YAML) and very extensible using a programming language with a relatively gentle learning curve (Python).

In my case, most things running at home are either running OSX or some version of Linux/BSD, but there are a few of oddball Windows 10 computers doing things Microsoft-based computers do pretty well; gaming, spreadsheets, touchscreen-enabled full-desktops.

The idea of managing Windows computers with Salt came to me pretty late into the journey through the docs, but hit me like a freight-train as these are often the computers that require the most maintenance for me personally, meaning reinstalls, reconfiguration and general “care and feeding”. Having gone down the path of running my own Active Directory at home a few times and finally settling on a couple of Apple “servers”, this seemed like a pretty good work-around that wouldn’t introduce much pain.

The first caveat, however, was that I was unable to get Windows-based Salt minions to be accepted by OSX-based Salt masters. Not the end of the world, but it meant running Docker or a Vagrant box to handle the Windows 10 computers. I ended up simply installing Salt on an Ubuntu-based storage server I already had running that had recently been upgraded to Xenial instead, but I’m most likely going to be revisiting this architecture in the long-term.

Now that we have that out of the way, here’s the general architecture of what I’ll be going over:

Windows Salt Minions
A simple Windows Salt Minions example with one Salt Stack master running Ubuntu Linux

The Nitty Gritty – Deploying Salt Minion Services to All of Your Windows Nodes

I’ll come right out and say that I cheated when it came to installing the Minion service on the nodes at home in that I already had Chocolatey installed, and that I simply used the default salt hostname for the master by adding it the the static DNS entries on my DNS server.

This last bit, the part about the DNS server, might be a luxury depending on your install location. I also can’t expect that Chocolatey is installed everywhere, but just quickly, here’s how that scenario works:

  1. Install Salt Master and start the service on a computer in your network
  2. Ensure that there is a DHCP reservation for the IP of this node
  3. Add a DNS entry salt for that DHCP-reserved IP
  4. Install the Salt minions via choco install -y saltminion on the Windows hosts
  5. Accept the keys on the Linux master via salt-key -A

Should you have to go about this a different way, you can point an alias (CNAME) to the hostname in your network, OR add a manual host entry to your nodes (I’ve used Group Policy to do this in the past, with network scripts), or finally, you can simply change the Salt Minion config to point to the new hostname.

As for the deployment of the Salt Minion service and binaries, you could do this over RDP for a few hosts, Group Policy, or via psexec:

Salt-Minion-2016.11.5-x64-Setup.exe /S /master=SALTMASTER

This snippet will install the Salt Minion service, configure it to point at `SALTMASTER` (replace this with the hostname you’d prefer) then start the service. Note: as mentioned above, I haven’t tested this myself!

The most up-to-date Salt Minion binaries can be found here: https://docs.saltstack.com/en/latest/topics/installation/windows.html Should the version change, you’ll want to update that one-liner as well.

Accepting the Minions

Assuming you’ve got your minions now sending requests to the Salt master node, you need to approve them.

On the master node running Linux, this can be done like so:

sudo salt-key -A

You’ll be greeted with a list of nodes to be accepted, and you can take a moment to note the names and accept them:

user@ubuntu:/srv/salt# sudo salt-key -A
[sudo] password for user: 
The following keys are going to be accepted:
Unaccepted Keys:
Proceed? [n/Y] 
Key for minion WINDOWSGAMES accepted.

Testing the Minions

Now that you have minions installed and working, let’s run a quick test that proves we can run remote commands on them. Note that this is just scratching the surface, and that “push commands” are just one way of working with Salt Stack, you can also have the nodes “pull” from the Salt master on a regular basis.

Sample run command:

sudo salt -G 'os:windows` cmd.run 'dir'

This should give you a directory listing on each of the nodes, like so:

 Volume in drive C has no label.
 Volume Serial Number is 3FF7-A973
 Directory of C:\Windows\system32\config\systemprofile
 07/16/2016 04:47 AM <DIR> .
 07/16/2016 04:47 AM <DIR> ..
 07/16/2016 04:47 AM <DIR> AppData
 0 File(s) 0 bytes
 3 Dir(s) 66,483,965,952 bytes free

Package Management on the Master Node

You’ve got a few options for package management for Windows Salt minions:

  • Chocolatey packages
  • Cygwin Packages
  • Master-shared packages (WinRepo)

Personally, I’m currently using Chocolatey package management because it’s what I’m used to, but I certainly do still use Cygwin for development purposes from time-to-time since Windows Bash mode has still yet to become commonplace. The third option, however, is probably the most scalable, and more user-friendly.

To get started with Windows repositories on the Linux Salt master, you’ll need to run:

sudo salt-run winrepo.update_git_repos

This means that you now have a repository for Windows packages on the Master node, but also note that these don’t come with binaries – they will fetch and send them as needed. I can see this as both good and bad, in a corporate setting you’ll want to create your own SLS files and point them to known-good sources.

To install a package on all of your Windows remote nodes using the Linux Salt master repository:

sudo salt -G 'os:windows' package.install 'firefox'

Note that if ever you want to specify a specific action for a node in particular, that’s done like so:

sudo salt 'WINDOWSGAMES' pkg.install 'firefox'

I’m trying to follow the “pets vs cattle” paradigm here, though you can also use -G to specify groups of servers/workstations/laptops which can overlap in order to manage things in a more granular approach (bit of a pun here, the G is for Grains).

Useful Commands for Windows Salt Minions

In no particular order, here’s a quick dump of the commands I used during my first weekend managing Salt minions at home running Windows 10.

Show installed applications:

sudo salt -G 'os:windows' pkg.list_pkgs

List current Salt minion keys:

sudo salt-key -L

Delete an old Salt minion key:

sudo salt-key -d WINDOWSGAMES

Check if a service is available:

sudo salt -G 'os:windows' service.available 'salt-minion'

Restart a service:

sudo salt -G 'os:windows' service.restart 'salt-minion'

Building Zeal60 Keymaps on OSX

Before starting, this guide requires Homebrew, which you can install from here: https://brew.sh

Open Terminal, and paste in the following. It will take a while to build, but you should be able to get it all done in one fell swoop:

git clone https://github.com/Wilba6582/qmk_firmware.git
cd qmk_firmware
git branch zeal60
cd keyboards/zeal60
git submodule update --init --recursive
brew tap osx-cross/avr
brew install avr-gcc avr-libc dfu-programmer

You can then make your keymap, like so:

  • make keymap=default
  • make keymap=poker2_ansi
  • make keymap=poker2_iso
  • make keymap=hhkb_ansi

You can run them all if you want, but you’ll probably only need one 🙂

Once you have your firmware, you can flash like so (for HHKB ANSI):

sudo dfu-programmer atmega32u4 erase --force
sudo dfu-programmer atmega32u4 flash hhkb_ansi.hex
sudo dfu-programmer atmega32u4 reset