@@ 9,7 9,7 @@ build: $(LAYOUT).hex
 
 upload: $(LAYOUT).hex
 	@echo "Put your device in bootloader mode now..."
-	@echo "Classic Atreus: connect GND pin to RST pin twice in under a secod."
+	@echo "Classic Atreus: press reset key (usually fn+esc -> B)."
 	@echo "Keyboardio Atreus: press the button on the underside of the board."
 	while [ ! -r $(USB) ]; do sleep 1; done; \
 	avrdude -p $(MCU) -c avr109 -U flash:w:$(LAYOUT).hex -P $(USB)

@@ 46,10 46,12 @@ 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`.
 
-## Known bugs
+## Limitations
 
-The reset function in the firmware has no effect; hard-reset must be
-used to flash a new firmware once this is uploaded.
+If you use dual-role keys, one-shot modifiers, or mouse keys, you may
+be happier with [QMK](https://docs.qmk.fm/) or
+[Kaleidoscope](https://github.com/keyboardio/Kaleidoscope). Likewise
+if you need more than 6 regular keys and 4 modifiers at once.
 
 ## Layout
 

@@ 105,3 105,6 @@
 (define mod-super (modify 4))
 
 (define (sft keycode) (combo mod-shift keycode)) ; shorthand
+
+;; Enter the bootloader in preparation for flashing.
+(define (reset _) (call-c-func "reset"))

@@ 25,9 25,16 @@
 ;; steps thru a vector/list with the initial arguments calculated by its
 ;; non-aux equivalent. The -aux function is never called directly.
 
-;; This file should be loaded by your main layout code; see qwerty.scm
+;; This file should be loaded by your main layout file; see qwerty.scm
 ;; for an example. It assumes that keycodes, layouts, and pinout have already
-;; been defined.
+;; been defined. In particular, it needs these definitions:
+
+;; * everything in keycodes.scm
+;; * momentary-layer: either false (when not active) or a vector of keycodes
+;; * current-layer: a vector of keycodes for when momentary-layer is inactive
+
+;; The keycodes in these vectors can be numbers, lists, or procedures;
+;; for details see the "Layout lookup" section below.
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 

@@ 1,10 1,16 @@
 ;;; This is the multidvorak layout.
 
-;; It will work for the 44-key Atreus 2 or the 42-key Atreus 1.
+;; It is written with the assumption that the host OS is set to dvorak mode, so
+;; it sends keycodes with the assumption that the OS will apply the dvorak
+;; mapping; for instance it sends [ as -, which the OS then turns back into [.
+;; There is also a "hard dvorak" layer you can activate when you plug into
+;; a computer that isn't set to dvorak in the OS.
+
+;; It will work for the 44-key Keyboardio Atreus or the 42-key Atreus Classic.
 
 (include "keycodes.scm")
 
-;; What are the rows and columns we care about?
+;; What are the rows and columns we care about? (Atreus Classic pinout)
 (define rows (list 0 1 2 3))
 (define columns (list 0 1 2 3 4 5 6 7 8 9 10))
 


@@ 35,11 41,8 @@
 (define (set-layer n)
   (lambda (_) (set! current-layer (vector-ref layers n))))
 
-;; This will reset the board but fails to enter the bootloader for some reason.
-(define (reset _) (call-c-func "reset"))
-
-;; On the Atreus 1, we need to expose backtick on the fn layer, but on
-;; the Atreus 2 it has its own key, so we put percent there instead.
+;; On the Atreus Classic, we need to expose backtick on the fn layer, but on
+;; the Keyboardio Atreus it has its own key, so we put percent there instead.
 (define backtick-or-percent
   ;; (sft key-5)
   key-backtick)


@@ 123,7 126,7 @@
           key-space fn key-quote key-left-bracket key-enter))
 
 (define hard-dvorak-fn-layer
-  (vector (sft key-1) (sft key-2) key-up (sft key-4) (sft key-5) (sft key-6)
+  (vector (sft key-1) (sft key-2) key-up (sft key-4) backtick-or-percent (sft key-6)
           key-page-up key-7 key-8 key-9 (sft key-backspace)
 
           (sft key-3) key-left key-down key-right (sft key-4) 0

@@ 33,10 33,8 @@
 (define (set-layer n)
   (lambda (_) (set! current-layer (vector-ref layers n))))
 
-(define (reset _) (call-c-func "reset"))
-
-;; On the Atreus 1, we need to expose backtick on the fn layer, but on
-;; the Atreus 2 it has its own key, so we put percent there instead.
+;; On the Atreus Classic, we need to expose backtick on the fn layer, but on
+;; the Keyboardio Atreus it has its own key, so we put percent there instead.
 (define backtick-or-percent
   ;; (sft key-5)
   key-backtick)

@@ 604,9 604,6 @@ ISR(USB_COM_vect)
   UECONX = (1<<STALLRQ) | (1<<EPEN);  // stall
 }
 
-// this fails to enter the bootloader.
-// it is unknown why the same code fails here but works fine in
-// https://github.com/technomancy/atreus-firmware/blob/master/atreus.c#L230
 void reset(void) {
   UDCON = 1; USBCON = (1<<FRZCLK); UCSR1B = 0;
   _delay_ms(5);


@@ 616,4 613,5 @@ void reset(void) {
   PORTB = 0; PORTC = 0; PORTD = 0; PORTE = 0; PORTF = 0;
   *(uint16_t *)0x0800 = 0x7777;
   wdt_enable(WDTO_120MS);
+  asm volatile("jmp 0x7E00");
 };