menelaus/README.md -rw-r--r-- 3.2 KiB
71e98173Phil Hagelberg Fix reset function. 8 months ago


A firmware for the Atreus keyboard, written in Microscheme.

Atreus keyboard

See this article about how it works.


  • 6KRO (6 simultaneous keys, plus 4 modifiers)
  • Software debouncing
  • Multiple layers, momentary and sticky (limited only by memory)
  • Combo keys (a single keystroke can send a modifier and a non-modifier)
  • Bind arbitrary Microscheme functions to a key
  • ~300 lines of code
  • Qwerty and Dvorak layouts; easy to add more


Install microscheme from source; place microscheme executable on your $PATH. Version 3bc5611 from March 2020 is known to work.

Requires avrdude for uploading to the controller on the keyboard; install with your package manager of choice.

Replace /dev/ttyACM0 with the path your OS assigns to the USB bootloader of the microcontroller (on Mac OS X sometimes it is /dev/cu.usbmodem1411 or similar):

$ make upload USB=/dev/ttyACM0

Once you run that, put the device in bootloader mode; sometimes this can be invoked by a key combo and sometimes a hard reset is necessary. On the A-star Micro used in the Atreus kits, this is done by shorting GND and RST twice in under a second, which causes the onboard LED to pulse. The Keyboardio Atreus has a reset button you can press with a pin to the bottom of the board. On linux-based systems you can monitor for the bootloader activation using sudo dmesg --follow.

Some linux-based systems will need a udev rule to grant permissions to the USB device for uploading firmware. If you get permission denied on /dev/ttyACM0 or whatever it is, try running sudo make udev.


If you use dual-role keys, one-shot modifiers, or mouse keys, you may be happier with QMK or Kaleidoscope. Likewise if you need more than 6 regular keys and 4 modifiers at once.



By default you get the qwerty layout. You can copy qwerty.scm to mylayout.scm and make changes, (you can see a list of available keycodes in keycodes.scm) then upload with:

$ make upload USB=/dev/ttyACM0 LAYOUT=mylayout

There is also a multidvorak layout which is designed to send the right keycodes with the assumption that the OS is set to use Dvorak, but it also includes layers for "hard Dvorak".

The default layout is based on the Keyboardio Atreus, except that for older 42-key builds, the percent key is replaced with backtick, and backslash is fn+semicolon.


The firmware can also be run on a PC rather than on the microcontroller in the keyboard using test.rkt which loads it up into Racket and simulates the GPIO functions with a test harness:

$ make test
racket test.rkt


Copyright © 2014-2020 Phil Hagelberg and contributors

Released under the GNU GPL version 3 or any later version.

Uses PJRC USB Keyboard library which is Copyright © 2009 PJRC.COM, LLC and released under the MIT/X11 license.