more important documentation

6 files changed, 40 insertions, 21 deletions

diff --git a/client/readme.md b/client/readme.md
index 375e8c1..f92c94d 100644
--- a/client/readme.md
+++ b/client/readme.md
@@ -1,8 +1,6 @@
 \defgroup pbc pbc
 \brief Puzzle box client
 
-# puzzle box client
-
 This folder contains the source code for the puzzle box client (pbc). This is a
 desktop application that communicates with the main controller over TCP to
 send/receive I<sup>2</sup>C messages. This application is not only used by a
diff --git a/lib/pbdrv/pb.h b/lib/pbdrv/pb.h
index e9c803d..6f84d10 100644
--- a/lib/pbdrv/pb.h
+++ b/lib/pbdrv/pb.h
@@ -15,34 +15,31 @@
 //! I2C bus timeout delay in microseconds
 #define PB_TIMEOUT_US (1e3 * PB_TIMEOUT_MS)
 
-//! Null address (used by client)
-#define PB_ADDR_NULL 0x00
-
-//! Adafruit NeoTrellis module 1 I2C address
+//! Adafruit NeoTrellis module 1 I2C address \ingroup puz_neo
 #define PB_ADDR_ADA_NEO_1 0x2E
-//! Adafruit NeoTrellis module 2 I2C address
+//! Adafruit NeoTrellis module 2 I2C address \ingroup puz_neo
 #define PB_ADDR_ADA_NEO_2 0x2F
-//! Adafruit NeoTrellis module 3 I2C address
+//! Adafruit NeoTrellis module 3 I2C address \ingroup puz_neo
 #define PB_ADDR_ADA_NEO_3 0x30
-//! Adafruit NeoTrellis module 4 I2C address
+//! Adafruit NeoTrellis module 4 I2C address \ingroup puz_neo
 #define PB_ADDR_ADA_NEO_4 0x32
 
-//! Main controller I2C address
+//! Main controller I2C address \ingroup main
 #define PB_ADDR_MOD_MAIN 0x08
 
-//! NeoTrellis puzzle module I2C address
+//! NeoTrellis puzzle module I2C address \ingroup puz_neo
 #define PB_ADDR_MOD_NEOTRELLIS 0x21
 //! Software puzzle module I2C address
 #define PB_ADDR_MOD_SOFTWARE 0x22
 //! Hardware puzzle module I2C address
 #define PB_ADDR_MOD_HARDWARE 0x23
-//! Vault puzzle module I2C address
+//! Vault puzzle module I2C address \ingroup puz_vault
 #define PB_ADDR_MOD_VAULT 0x24
 //! Automation puzzle module I2C address
 #define BUSADDR_MOD_AUTOMATION 0x25
-//! Smoketest puzzle module I2C address
+//! Smoketest puzzle module I2C address \ingroup puz_smoketest
 #define PB_ADDR_MOD_SMOKETEST 0x26
-//! Dummy puzzle module I2C address
+//! Dummy puzzle module I2C address \ingroup puz_dummy
 #define PB_ADDR_MOD_DUMMY 0x69
 
 /// \}
diff --git a/main/readme.md b/main/readme.md
index 2a50fd1..b73305c 100644
--- a/main/readme.md
+++ b/main/readme.md
@@ -1,8 +1,6 @@
 \defgroup main main
 \brief Main controller software
 
-# main controller firmware
-
 This directory contains the software for the main controller of the Puzzle Box.
 The main controller target is a Raspberry Pi Pico W.
 
diff --git a/puzzle/neo/index.dox b/puzzle/neo/index.dox
index 87822e0..002ab47 100644
--- a/puzzle/neo/index.dox
+++ b/puzzle/neo/index.dox
@@ -4,6 +4,25 @@
 \defgroup puz_neo Neo
 \brief NeoTrellis puzzle module
 
+\warning **This puzzle module does not work.**
+
+\warning The NeoTrellis boards from Adafruit sometimes pull both the SDA and
+SCL lines low after being addressed. This seems to consistently happen during
+the first iteration of the main controller's state exchange loop after the
+handshake wave has completed successfully.
+
+\warning We have been unable to find the root cause of the issue, but suspect
+the Adafruit boards themselves, as the I2C lines remain low even when the main
+controller and Arduino are both disconnected. We did find that the \ref
+puz_dummy "dummy puzzle module" produced similar behavior (pulling the I2C low
+indefinitely) when attempting to write to the I2C bus from an I2C receive ISR
+directly. The Adafruit boards use a different microcontroller and run
+closed-source firmware, which made verifying whether this was the issue
+impossible.
+
+\warning We recommend future project groups design a custom button/LED matrix
+board instead of using the NeoTrellis boards.
+
 \par Setup
 - Use the Arduino IDE library manager to install the "Adafruit seesaw Library"
 	library and its dependencies
diff --git a/puzzle/smoketest/index.dox b/puzzle/smoketest/index.dox
index 15eae1f..78ff702 100644
--- a/puzzle/smoketest/index.dox
+++ b/puzzle/smoketest/index.dox
@@ -1,11 +1,16 @@
 // vim:ft=doxygen
 /**
 \ingroup puz
-\defgroup puz_vault Vault
-\brief Vault puzzle module
+\defgroup puz_smoketest Smoketest
+\brief Smoketest puzzle module
 
-\par Setup
-- Use the Arduino IDE library manager to install the "TM1637" library (by
-	Avishay Orpaz) and its dependencies
+This puzzle module was used as a substitute for the \ref puz_neo
+"NeoTrellis puzzle module" during the 23-24 assessment due to the I2C issues
+encountered with the Adafruit NeoTrellis modules.
+
+This puzzle module turns on an on-board LED when it is in the \ref
+PB_GS_PLAYING "playing" state, and sets itself to the \ref PB_GS_SOLVED
+"solved" state when an external button is pressed.
 
 */
+
diff --git a/puzzle/smoketest/main.cpp b/puzzle/smoketest/main.cpp
index 6b4d7d0..3169ed5 100644
--- a/puzzle/smoketest/main.cpp
+++ b/puzzle/smoketest/main.cpp
@@ -2,7 +2,9 @@
 #include "lib/pbdrv/pb-types.h"
 #include "lib/pbdrv/pb-mod.h"
 
+//! LED pin (on-board LED on Arduino Uno board) \ingroup puz_smoketest
 #define EXTERNAL_LED_PIN 13
+//! External button pin (button shorts this pin to ground) \ingroup puz_smoketest
 #define BUTTON_PIN 10
 
 pb_global_state_t state = PB_GS_NOINIT;