diff --git a/nametag8_V003/user/device/btn.c b/nametag8_V003/user/device/btn.c
index feb03b7..d97efb7 100644
--- a/nametag8_V003/user/device/btn.c
+++ b/nametag8_V003/user/device/btn.c
@@ -2,6 +2,29 @@
  * Created on: Jul 27, 2024
  *
  * generic button handler like I do on most of my projects
+ *
+ *
+ * to use the buttons:
+ *
+ * - set REG_BTN_DEBOUNCE_TIME to desired debounce time in 5ms increments
+ *   (default is set in BTN_DEBOUNCE)
+ *
+ * - set button flags for the buttons you want the interrupt line to respond
+ *   to in REG_BTNx_INT_ENABLE for each button
+ *   flags are BTN_PUSH / BTN_HOLD / BTN_RELEASE bits
+ *
+ * - enable button line interrupt if you want the interrupt line to go high
+ *   when a button interrupt happens
+ *   this is INT_BTN bit in REG_INTR_FLAGS
+ *
+ * - if using interrupts, check flag; clear the flag by writing BTN_INT bit
+ *   to REG_INTR_FLAGS_CLEAR
+ *
+ * - read the button states from REG_BTN_PUSHED, REG_BTN_HELD, REG_BTN_RELEASED
+ *   these registers are clear-on-read so will always have fresh information
+ *
+ * - alternatively, work the mask directly by reading REG_BTNx_MASK
+ *
  */
 
 #include "btn.h"
@@ -121,12 +144,12 @@ void btn_poll()
         pushed = 0;
 
         ignore = btn[i]._mask & BTN_IGNORE;
-        r = BTN_PORT->INDR & (1 << (btn[i]._pintype & BTN_PIN_MASK));
+        r = BTN_PORT->INDR & (1 << (btn[i]._pintype & BTN_PINTYPE_MASK));
 
         // active low type buttons
-        if (!r && (btn[i]._pintype & BTN_ACTIVE_LO)) pushed = 1;
+        if (!r) pushed = 1;
         // active high type buttons
-        if (r && !(btn[i]._pintype & BTN_ACTIVE_LO)) pushed = 1;
+        // if (r && !(btn[i]._pintype & BTN_ACTIVE_LO)) pushed = 1;
 
         if (pushed) {
             // hold counter
@@ -175,6 +198,7 @@ void btn_poll()
         }
     }
 
+    // any button event with enabled interrupt flags will set button interrupt flag
     if (set_interrupt) {
         i2cs_append_flag(INT_BTN);
         set_interrupt = 0;
diff --git a/nametag8_V003/user/device/btn.h b/nametag8_V003/user/device/btn.h
index 37ec08f..d8d52ab 100644
--- a/nametag8_V003/user/device/btn.h
+++ b/nametag8_V003/user/device/btn.h
@@ -14,37 +14,38 @@
 
 
 
-#define BTN_COUNT       4
-#define BTN_DEBOUNCE    (12 >> 1)   // debounce time in 2ms
+#define BTN_COUNT           5
+#define BTN_DEBOUNCE        (30 / 5)   // debounce time in 5ms increments
 
-#define BTN_PORT        GPIOC
-#define BTN_MODE        0x80
+#define BTN_PORT            GPIOC
+#define BTN_MODE            0x80
 
-#define BTN_PULL_UP     (1 << 0)
-#define BTN_PULL_DOWN   (1 << 16)
+#define BTN_PULL_UP         (1 << 0)
+#define BTN_PULL_DOWN       (1 << 16)
 
-#define BTN_ACTIVE_LO   0xf1
-#define BTN_PIN_MASK    0xf1
+#define BTN_ACTIVE_LO       0xf1
+#define BTN_PIN_MASK        0xf1
+#define BTN_PINTYPE_MASK    0x0f
 
-#define BTN1_PIN        4
-#define BTN1_PUPD       BTN_PULL_UP
+#define BTN1_PIN            4
+#define BTN1_PUPD           BTN_PULL_UP
 
-#define BTN2_PIN        5
-#define BTN2_PUPD       BTN_PULL_UP
+#define BTN2_PIN            5
+#define BTN2_PUPD           BTN_PULL_UP
 
-#define BTN3_PIN        6
-#define BTN3_PUPD       BTN_PULL_UP
+#define BTN3_PIN            6
+#define BTN3_PUPD           BTN_PULL_UP
 
-#define BTN4_PIN        7
-#define BTN4_PUPD       BTN_PULL_UP
+#define BTN4_PIN            7
+#define BTN4_PUPD           BTN_PULL_UP
 
-#define BTN5_PIN        0       // side button
-#define BTN5_PUPD       BTN_PULL_UP
+#define BTN5_PIN            0       // side button
+#define BTN5_PUPD           BTN_PULL_UP
 
-#define BTN_PUSH        (1 << 0)
-#define BTN_HOLD        (1 << 1)
-#define BTN_RELEASE     (1 << 2)
-#define BTN_IGNORE      (1 << 3)
+#define BTN_PUSH            (1 << 0)
+#define BTN_HOLD            (1 << 1)
+#define BTN_RELEASE         (1 << 2)
+#define BTN_IGNORE          (1 << 3)