From cdd1034144da2f606d8f2a57061f694cdaa96cc1 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Wed, 26 Jun 2024 14:44:04 +0200 Subject: more important documentation --- client/readme.md | 2 -- lib/pbdrv/pb.h | 21 +++++++++------------ main/readme.md | 2 -- puzzle/neo/index.dox | 19 +++++++++++++++++++ puzzle/smoketest/index.dox | 15 ++++++++++----- puzzle/smoketest/main.cpp | 2 ++ 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 I2C 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; -- cgit v1.2.3