added documentation comments and led map

5 files changed, 40 insertions, 5 deletions

diff --git a/software/animation.h b/software/animation.h
index 2626291..feab14d 100644
--- a/software/animation.h
+++ b/software/animation.h
@@ -2,4 +2,5 @@
 
 #include "consts.h"
 
+/** @brief round time to nearest frame */
 unsigned long clamp_time(unsigned long unclamped_time);
diff --git a/software/consts.h b/software/consts.h
index 2598d29..b0b7075 100644
--- a/software/consts.h
+++ b/software/consts.h
@@ -1,11 +1,41 @@
 #pragma once
 
+// pinouts
 #define PINOUT_SCK 4
 #define PINOUT_SER 2
 #define PINOUT_LCK 3
 
+// animation framerate
 #define CONFIG_FRAMERATE 60
-#define CONFIG_PWM_FREQ 1000
 
-#define CONFIG_SERIAL_BAUD 115200
-#define DEBUG
+// debug options
+// #define CONFIG_SERIAL_BAUD 115200
+// #define DEBUG
+
+/**
+ * @brief map 3D cube coordinates to `led_state` indices
+ *
+ * usage: `led_state[led_map[x + 4*y + 16*z]]`
+ */
+const unsigned int led_map[64] = {
+	0x31, 0x21, 0x11, 0x01,
+	0x33, 0x23, 0x13, 0x03,
+	0x35, 0x25, 0x15, 0x05,
+	0x37, 0x27, 0x17, 0x07,
+                  
+	0x30, 0x20, 0x10, 0x00,
+	0x32, 0x22, 0x12, 0x02,
+	0x34, 0x24, 0x14, 0x04,
+	0x36, 0x26, 0x16, 0x06,
+                  
+	0x38, 0x28, 0x18, 0x08,
+	0x3a, 0x2a, 0x1a, 0x0a,
+	0x3c, 0x2c, 0x1c, 0x0c,
+	0x3e, 0x2e, 0x1e, 0x0e,
+                  
+	0x39, 0x29, 0x19, 0x09,
+	0x3b, 0x2b, 0x1b, 0x0b,
+	0x3d, 0x2d, 0x1d, 0x0d,
+	0x3f, 0x2f, 0x1f, 0x0f,
+};
+
diff --git a/software/scan.h b/software/scan.h
index 0c19763..82dccb0 100644
--- a/software/scan.h
+++ b/software/scan.h
@@ -1,13 +1,17 @@
 #pragma once
 
+// utility
 #define SCAN_HOR 0
 #define SCAN_VER 1
 extern unsigned char scan_direction;
 extern unsigned char scan_index;
 extern unsigned char scan_order[8];
 
+/** @brief fetch horizontal or vertical row from led_state */
 unsigned char get_state_row(unsigned char row, unsigned char direction);
 
+/** @brief scan through the 8x8 wiring matrix and display led_state */
 void scan();
+/** @brief optimize brightness by pruning empty lines */
 void optimize_scan();
 
diff --git a/software/shift.h b/software/shift.h
index 2b4f7fd..27170c5 100644
--- a/software/shift.h
+++ b/software/shift.h
@@ -1,7 +1,5 @@
 #pragma once
 
-#define SR_ROW 0
-#define SR_COL 1
 extern unsigned char shift_state[2];
 
 /** @brief update physical state of shift registers with shift_state */
diff --git a/software/util.h b/software/util.h
index 077fd68..654fa95 100644
--- a/software/util.h
+++ b/software/util.h
@@ -1,7 +1,9 @@
 #pragma once
 #ifdef DEBUG
 
+/** @brief [DEBUG] print binary number padding with 0 */
 void print_binary_number(unsigned char data);
+/** @brief [DEBUG] print led_state in 8x8 grid */
 void print_led_state();
 
 #endif