3 files changed, 50 insertions, 14 deletions

diff --git a/lib/pbdrv/drv/arduino/include.cmake b/lib/pbdrv/drv/arduino/include.cmake
index 1e2ff08..5ec1124 100644
--- a/lib/pbdrv/drv/arduino/include.cmake
+++ b/lib/pbdrv/drv/arduino/include.cmake
@@ -3,7 +3,7 @@ if(NOT DEFINED ARDUINO)
 endif()
 
 target_sources(pbdrv-mod PRIVATE "${CMAKE_CURRENT_LIST_DIR}/mod.cpp")
-target_link_arduino_libraries(pbdrv-mod core Wire)
+target_link_arduino_libraries(pbdrv-mod PRIVATE core Wire)
 
 # freertos is used to defer the handling of i2c messages outside the receive
 # interrupt service routine
diff --git a/lib/pbdrv/drv/arduino/index.dox b/lib/pbdrv/drv/arduino/index.dox
new file mode 100644
index 0000000..03510dd
--- /dev/null
+++ b/lib/pbdrv/drv/arduino/index.dox
@@ -0,0 +1,25 @@
+// vim:ft=doxygen
+/**
+\ingroup pb_drv
+\defgroup pb_drv_arduino Arduino
+\brief Arduino ATmega (w/ Arduino-CMake-Toolchain) driver
+
+This driver is known to work with the following MCUs:
+- ATmega328P (Arduino Uno)
+- ATmega2560 (Arduino Mega)
+
+\par Usage
+- Link the \c pbdrv-mod library with your main executable
+
+\note This driver is automatically enabled if the variable \c ARDUINO is
+defined in your CMakeLists.txt (it is by default when using
+Arduino-CMake-Toolchain).
+
+\note This driver automatically includes the \ref pb_ext_freertos
+"FreeRTOS extension" for deferring calls to \c pb_i2c_recv() from the I2C ISR.
+
+A complete example for this driver is available in the \ref puzzle/dummy
+folder.
+
+*/
+
diff --git a/lib/pbdrv/drv/arduino/mod.cpp b/lib/pbdrv/drv/arduino/mod.cpp
index 9130334..c381077 100644
--- a/lib/pbdrv/drv/arduino/mod.cpp
+++ b/lib/pbdrv/drv/arduino/mod.cpp
@@ -1,7 +1,3 @@
-#ifndef ARDUINO
-#error This driver only works on the Arduino platform!
-#endif
-
 #include <Arduino.h>
 #include <Wire.h>
 #include <avr/delay.h>
@@ -42,7 +38,17 @@ static void pb_setup() {
 	Wire.onReceive(recv_event);
 }
 
+/**
+ * \ingroup pb_drv_arduino
+ * \warning This function includes a hard-coded 10ms delay before sending. This
+ * is to work around a weird issue where the Arduino pulls both SDA and SCL low
+ * while attempting to initiate an I2C transmission. We were able to verify
+ * that the Arduino correctly handles bus arbitration under a test scenario
+ * with 2 Uno's, but ran into issues while integrating the Arduino's with the
+ * RP2040.
+ */
 __weak void pb_i2c_send(i2c_addr_t addr, const uint8_t * buf, size_t sz) {
+	vTaskDelay(10 / portTICK_PERIOD_MS); // prevent bus collisions
 	Wire.beginTransmission((int) addr);
 	Wire.write(buf, sz);
 	Wire.endTransmission(true);
@@ -64,7 +70,20 @@ void loop_task() {
 	}
 }
 
-//! Application entrypoint
+/**
+ * \ingroup pb_drv_arduino
+ * \brief Application entrypoint
+ *
+ * This function overrides the default (weak) implementation of the \c main()
+ * function in the Arduino framework. No additional setup is required to use
+ * this driver.
+ *
+ * \note I should really be able to use Arduino's initVariant function for
+ * this, but I can't seem to get it to link properly using the CMake setup in
+ * this repository. Overriding the main() function seems to work, and the
+ * USBCON thing in the default Arduino main() function isn't needed because
+ * puzzle modules are likely not using USB.
+ */
 int main(void) {
 	init(); // call arduino internal setup
 	setup(); // call regular arduino setup
@@ -74,11 +93,3 @@ int main(void) {
 	return 0;
 }
 
-/**
- * \note I should really be able to use Arduino's initVariant function for
- * this, but I can't seem to get it to link properly using the CMake setup in
- * this repository. Overriding the main() function seems to work, and the
- * USBCON thing in the default Arduino main() function isn't needed because
- * puzzle modules are likely not using USB.
- */
-