3 files changed, 62 insertions, 9 deletions
diff --git a/lib/pbdrv/drv/arduino/index.dox b/lib/pbdrv/drv/arduino/index.dox
new file mode 100644
index 0000000..4c74222
--- /dev/null
+++ b/lib/pbdrv/drv/arduino/index.dox
@@ -0,0 +1,19 @@
+// vim:ft=doxygen
+/**
+\ingroup pb_drv
+\defgroup pb_drv_arduino Arduino
+\brief Arduino (Arduino-CMake-Toolchain) driver
+
+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.
+
+This driver is known to work with the following MCUs:
+- ATmega328P (Arduino Uno)
+- ATmega2560 (Arduino Mega)
+
+*/
+
diff --git a/lib/pbdrv/drv/arduino/mod.cpp b/lib/pbdrv/drv/arduino/mod.cpp
index 9130334..2eef8d5 100644
--- a/lib/pbdrv/drv/arduino/mod.cpp
+++ b/lib/pbdrv/drv/arduino/mod.cpp
@@ -42,6 +42,7 @@ static void pb_setup() {
 	Wire.onReceive(recv_event);
 }
 
+/// \ingroup pb_drv_arduino
 __weak void pb_i2c_send(i2c_addr_t addr, const uint8_t * buf, size_t sz) {
 	Wire.beginTransmission((int) addr);
 	Wire.write(buf, sz);
@@ -64,7 +65,16 @@ void loop_task() {
 	}
 }
 
-//! Application entrypoint
+/**
+ * \ingroup pb_drv_arduino
+ * \brief Application entrypoint
+ *
+ * \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 +84,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.
- */
-
diff --git a/lib/pbdrv/drv/index.dox b/lib/pbdrv/drv/index.dox
new file mode 100644
index 0000000..1fe09e2
--- /dev/null
+++ b/lib/pbdrv/drv/index.dox
@@ -0,0 +1,32 @@
+// vim:ft=doxygen
+/**
+\ingroup pbdrv-mod
+\defgroup pb_drv Drivers
+\brief Platform-specific \ref pbdrv-mod implementations
+
+Like \ref pb_ext "extensions", drivers provide platform-specific
+implementations for various functions used in \ref pbdrv-mod.
+
+Drivers are automatically included based on your build configuration, and you
+only need to ensure \c pbdrv-mod is linked with your final executable in order
+to use one of the available drivers:
+
+```cmake
+# include pbdrv
+add_subdirectory(lib/pbdrv)
+
+# link pbdrv-mod
+target_link_libraries(main pbdrv-mod)
+
+```
+
+If there is no existing driver for your target, you may implement the following
+in order to use \ref pbdrv-mod:
+
+- The \c pb_i2c_recv() function must be **called** for every received I2C
+	message
+- The \c pb_i2c_send() function must be **implemented** using the
+	platform/device-specific I2C write function
+
+*/
+