14 files changed, 420 insertions, 0 deletions

diff --git a/lib/pbdrv/CMakeLists.txt b/lib/pbdrv/CMakeLists.txt
new file mode 100644
index 0000000..08894cc
--- /dev/null
+++ b/lib/pbdrv/CMakeLists.txt
@@ -0,0 +1,40 @@
+cmake_minimum_required(VERSION 3.29)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_EXPORT_COMPILE_COMMANDS 1)
+
+# enable debug features
+set(CMAKE_BUILD_TYPE Debug)
+add_compile_definitions(DEBUG)
+
+project(pbdrv C CXX)
+
+if(DEFINED ARDUINO)
+	set(PBDRV_ARDUINO true)
+endif()
+
+include_directories(.)
+add_library(pbdrv STATIC
+	pb-read.c
+	pb-write.c
+	)
+target_include_directories(pbdrv SYSTEM INTERFACE .)
+
+list(APPEND PBDRV_SRCS pb-mod.c)
+
+if(PBDRV_ARDUINO)
+	list(APPEND PBDRV_SRCS drv/arduino/mod.cpp)
+endif()
+
+add_library(pbdrv-mod STATIC ${PBDRV_SRCS})
+target_link_libraries(pbdrv-mod pbdrv)
+# add_dependencies(pbdrv-mod pbdrv)
+
+if(PBDRV_ARDUINO)
+	target_link_arduino_libraries(pbdrv-mod
+		core
+		Wire
+		)
+endif()
+
diff --git a/lib/pbdrv/drv/arduino/mod.cpp b/lib/pbdrv/drv/arduino/mod.cpp
new file mode 100644
index 0000000..c7bbe45
--- /dev/null
+++ b/lib/pbdrv/drv/arduino/mod.cpp
@@ -0,0 +1,33 @@
+#ifndef ARDUINO
+#error This driver only works on the Arduino platform!
+#endif
+
+#include <Arduino.h>
+#include <Wire.h>
+
+#include <stdlib.h>
+#include <stdint.h>
+
+#include "mod.h"
+
+static void recv_event(int bytes) {
+	uint8_t * data = (uint8_t *) malloc(bytes);
+	size_t size = 0;
+	while (Wire.available()) {
+		data[size++] = Wire.read();
+	}
+
+	pbdrv_i2c_recv(data, size);
+}
+
+void pbdrv_setup() {
+	Wire.begin((int) PBDRV_MOD_ADDR);
+	Wire.onReceive(recv_event);
+}
+
+__weak void pbdrv_i2c_send(i2c_addr_t addr, const uint8_t * buf, size_t sz) {
+	Wire.beginTransmission((int) addr);
+	Wire.write(buf, sz);
+	Wire.endTransmission();
+}
+
diff --git a/lib/pbdrv/drv/arduino/mod.h b/lib/pbdrv/drv/arduino/mod.h
new file mode 100644
index 0000000..e545d9b
--- /dev/null
+++ b/lib/pbdrv/drv/arduino/mod.h
@@ -0,0 +1,19 @@
+#pragma once
+
+#include "../../pb-mod.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * \brief puzzle bus driver setup
+ *
+ * This function should be called from the Arduino \c setup() function.
+ */
+void pbdrv_setup();
+
+#ifdef __cplusplus
+}
+#endif
+
diff --git a/lib/pbdrv/makefile b/lib/pbdrv/makefile
new file mode 100644
index 0000000..c87d1af
--- /dev/null
+++ b/lib/pbdrv/makefile
@@ -0,0 +1,4 @@
+TARGET = $(BUILD_DIR)/libpbdrv.a
+
+include ../../lazy.mk
+
diff --git a/lib/pbdrv/mod/main.h b/lib/pbdrv/mod/main.h
new file mode 100644
index 0000000..535ce06
--- /dev/null
+++ b/lib/pbdrv/mod/main.h
@@ -0,0 +1,13 @@
+#pragma once
+
+#include "../types.h"
+
+typedef struct {
+	const i2c_addr_t mod_addr;
+	const pb_global_state_t mod_state;
+} pb_mod_main_mod_t;
+
+enum {
+	PB_MOD_MAIN_ADDR_MODS = 0x01, //!< connected puzzle modules
+};
+
diff --git a/lib/pbdrv/pb-mod.c b/lib/pbdrv/pb-mod.c
new file mode 100644
index 0000000..740f2a5
--- /dev/null
+++ b/lib/pbdrv/pb-mod.c
@@ -0,0 +1,26 @@
+#include "pb-types.h"
+#include "pb.h"
+
+//! fallback module name
+__weak const char * PBDRV_MOD_NAME = "???";
+
+//! [private] placeholder global state variable
+static pb_global_state_t _global_state = PB_GS_NOINIT;
+
+//! [private] main controller global state
+static pb_global_state_t _main_state = PB_GS_NOINIT;
+
+// __weak enum pb_state pbdrv_hook_mod_state_read() {
+// 	return _global_state;
+// }
+
+// __weak void pbdrv_hook_mod_state_write(enum pb_state state) {
+// 	_global_state = state;
+// }
+
+__weak void pbdrv_i2c_recv(const uint8_t * buf, size_t sz) {
+	return;
+}
+ 
+__weak void pbdrv_hook_main_state_update(pb_global_state_t state) { }
+
diff --git a/lib/pbdrv/pb-mod.h b/lib/pbdrv/pb-mod.h
new file mode 100644
index 0000000..fa290bf
--- /dev/null
+++ b/lib/pbdrv/pb-mod.h
@@ -0,0 +1,34 @@
+#pragma once
+
+/**
+ * \file puzzle bus driver implementation
+ *
+ * Most \c pbdrv_* functions have a weak implementation, which may be
+ * overwritten by a custom implementation. This allows you to use the default
+ * implementation where possible, and only implement extensions required for
+ * your puzzle module. Please see spec.adoc for more information about how to
+ * use the puzzle bus driver library.
+ */
+
+#include <stdint.h>
+#include <stddef.h>
+#include <stdbool.h>
+
+#include "pb-types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+//! puzzle module name (optional, default = "???")
+extern const char * PBDRV_MOD_NAME;
+//! puzzle module bus address (required)
+extern const i2c_addr_t PBDRV_MOD_ADDR;
+
+void pbdrv_i2c_recv(const uint8_t * buf, size_t sz);
+void pbdrv_i2c_send(i2c_addr_t i2c_addr, const uint8_t * buf, size_t sz);
+
+#ifdef __cplusplus
+}
+#endif
+
diff --git a/lib/pbdrv/pb-read.c b/lib/pbdrv/pb-read.c
new file mode 100644
index 0000000..843420d
--- /dev/null
+++ b/lib/pbdrv/pb-read.c
@@ -0,0 +1,3 @@
+#include "pb-read.h"
+
+
diff --git a/lib/pbdrv/pb-read.h b/lib/pbdrv/pb-read.h
new file mode 100644
index 0000000..3f59c93
--- /dev/null
+++ b/lib/pbdrv/pb-read.h
@@ -0,0 +1,2 @@
+#pragma once
+
diff --git a/lib/pbdrv/pb-types.h b/lib/pbdrv/pb-types.h
new file mode 100644
index 0000000..3c1314f
--- /dev/null
+++ b/lib/pbdrv/pb-types.h
@@ -0,0 +1,91 @@
+#pragma once
+#include <stdint.h>
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifdef __GNUC__
+#define __weak __attribute__((weak))
+#endif
+#ifndef __weak
+#error Could not determine weak attribute for current compiler
+#define __weak
+#endif
+
+typedef uint16_t i2c_addr_t;
+
+//! puzzle bus command types
+enum pb_cmd_id {
+	PB_CMD_REQ_READ, //!< request a puzzle module property
+	PB_CMD_RES_READ, //!< respond to a puzzle module property request
+	PB_CMD_REQ_WRITE, //!< request to write a puzzle module property
+	PB_CMD_REQ_STATE, //!< request global state
+	PB_CMD_RES_STATE, //!< respond to a global state request
+	PB_CMD_MAGIC, //!< magic message (regular i2c command)
+};
+typedef enum pb_cmd_id pb_cmd_id_t;
+
+//! magic sent from main controller to puzzle module
+static const char pb_cmd_magic_msg[] = { 0x70, 0x75, 0x7a, 0x62, 0x75, 0x73 };
+//! magic reply from puzzle module back to main controller
+static const char pb_cmd_magic_res[] = { 0x67, 0x61, 0x6d, 0x69, 0x6e, 0x67 };
+
+//! puzzle bus global states
+enum pb_global_state {
+	PB_GS_NOINIT, //!< uninitialized (only used by puzzle modules)
+	PB_GS_IDLE, //!< puzzle not started yet
+	PB_GS_PLAYING, //!< puzzle actively being solved
+	PB_GS_SOLVED, //!< puzzle completed
+};
+typedef enum pb_global_state pb_global_state_t;
+
+//! puzzle bus message header (shared by all commands)
+typedef struct {
+	const pb_cmd_id_t type; //!< command type
+	const i2c_addr_t sender; //!< i2c address of sender
+} pb_msg_header_t;
+
+//! PB_CMD_REQ_READ data
+typedef struct {
+	const pb_msg_header_t header;
+	const uint8_t propid; //!< state property id to return
+} pb_cmd_req_read_t;
+
+//! PB_CMD_RES_READ data
+typedef struct {
+	const pb_msg_header_t header;
+	const uint8_t propid; //!< id of returned state property
+	const uint8_t value[];
+} pb_cmd_res_read_t;
+
+//! PB_CMD_REQ_WRITE data
+typedef struct {
+	const pb_msg_header_t header;
+	const uint8_t propid; //!< state property id to write
+	const uint8_t value[]; //!< new value of property
+} pb_cmd_req_write_t;
+
+//! PB_CMD_REQ_STATE data
+typedef struct {
+	const pb_msg_header_t header;
+	const pb_global_state_t state; //!< global state of sender
+} pb_cmd_req_state_t;
+
+//! PB_CMD_RES_STATE data
+typedef struct {
+	const pb_msg_header_t header;
+	const pb_global_state_t state; //!< global state of sender
+} pb_cmd_res_state_t;
+
+//! PB_CMD_MAGIC data
+typedef struct {
+	const pb_msg_header_t header;
+	const char magic[]; //!< magic value
+} pb_cmd_magic_t;
+
+#ifdef __cplusplus
+}
+#endif
+
diff --git a/lib/pbdrv/pb-write.c b/lib/pbdrv/pb-write.c
new file mode 100644
index 0000000..65a2932
--- /dev/null
+++ b/lib/pbdrv/pb-write.c
@@ -0,0 +1 @@
+#include "pb-write.h"
diff --git a/lib/pbdrv/pb-write.h b/lib/pbdrv/pb-write.h
new file mode 100644
index 0000000..45dcbb0
--- /dev/null
+++ b/lib/pbdrv/pb-write.h
@@ -0,0 +1,3 @@
+#pragma once
+
+
diff --git a/lib/pbdrv/pb.h b/lib/pbdrv/pb.h
new file mode 100644
index 0000000..e37d785
--- /dev/null
+++ b/lib/pbdrv/pb.h
@@ -0,0 +1,18 @@
+#pragma once
+
+// Adafruit NeoTrellis modules
+#define BUSADDR_ADA_NEO_1 0x2E
+#define BUSADDR_ADA_NEO_2 0x2F
+#define BUSADDR_ADA_NEO_3 0x30
+#define BUSADDR_ADA_NEO_4 0x32
+
+// TODO: ???
+#define BUSADDR_MOD_NEOTRELLIS 0
+#define BUSADDR_MOD_SOFTWARE 0
+#define BUSADDR_MOD_HARDWARE 0
+#define BUSADDR_MOD_VAULT 0
+// #define BUSADDR_MOD_AUTOMATION 0
+
+// main controller
+#define BUSADDR_MOD_MAIN 0x00
+
diff --git a/lib/pbdrv/spec.adoc b/lib/pbdrv/spec.adoc
new file mode 100644
index 0000000..3172e84
--- /dev/null
+++ b/lib/pbdrv/spec.adoc
@@ -0,0 +1,133 @@
+= Puzzle module specification
+
+This folder contains an implementation of the puzzle bus protocol
+specification, and is targeted at puzzle module developers. This document
+describes the required implementation steps for integrating a new game into the
+puzzle module framework.
+
+== The bus
+
+The puzzle bus carries data over a standard I^2^C bus. Additional details about
+this bus can be found in the link:../../docs/design.adoc[Design document].
+
+The following details are important to puzzle module developers, as they may
+cause unexpected behavior:
+
+- *Addresses influence the puzzle box's behavior*. The order of puzzles is
+	determined by the puzzle module address. Two puzzle modules may use the same
+	address, but this will mean that they cannot be used simultaniously in the
+	same puzzle box. Known addresses are documented in link:bus.h[].
+- *The read/write bit of an I^2^C frame determines how it's handled*. I^2^C
+	*read* frames are treated as requests, while *write* frames are treated as
+	responses.
+
+== Puzzle bus driver (pbdrv)
+
+The library in this folder is a partial implementation of the puzzle bus
+specification *for puzzle modules*. Most functions in the driver are marked
+with the 'weak' attribute, which allows you to override them by providing an
+implementation.
+
+In order to utilize this driver, the following must be done:
+
+- The ``pbdrv_i2c_recv`` function must be *called* for every received *I^2^C
+	read* frame
+- The ``pbdrv_i2c_send`` function must be *implemented* with the
+	platform-specific *I^2^C write* function
+
+This is enough to get the puzzle module registered. You may also want to
+implement some of the following integrations:
+
+- If your game uses the global state variable, you should implement the
+	<<sec:state-global,global state hooks>> to point the driver to your own
+	global state variable, and be notified of reads/writes to it.
+- If you want to expose additional game state variables over the puzzle bus,
+	you should implement the <<sec:state-aux,auxiliary state hooks>>.
+- If you want to implement custom puzzle bus commands, you can implement the
+	<<sec:cmd,command hook>>.
+
+All other kinds of integrations/hooks can likely be realized by overriding the
+default implementations, but this is discouraged.
+
+[[sec:state-global]]
+== Global state
+
+If your puzzle module defines its own global ``enum pb_state``, you can tell
+the driver to use it by implementing the ``pbdrv_hook_state_read`` and
+``pbdrv_hook_state_write`` functions. These functions are also used by the
+default implementation of the read/write commands to address 0 (global state).
+
+Example:
+
+```c
+pb_state_t global_state = PB_GS_NOINIT;
+
+pb_state_t pbdrv_hook_mod_state_read() {
+	return global_state;
+}
+
+void pbdrv_hook_mod_state_write(pb_state_t state) {
+	global_state = state;
+}
+```
+
+[[sec:state-aux]]
+== Auxiliary state
+
+You can expose additional state variables by implementing the
+``pbdrv_hook_read`` and ``pbdrv_hook_write`` functions. These functions should
+return ``true`` for state addresses you want to override.
+
+Example:
+
+```c
+#define CUSTOM_VAR_ADDR 0x01
+uint8_t my_custom_variable = 10;
+
+bool pbdrv_hook_read(uint16_t i2c_addr, uint8_t addr) {
+	switch (addr) {
+		case CUSTOM_VAR_ADDR: {
+			char res[] = { PB_CMD_READ, addr, my_custom_variable };
+			pbdrv_i2c_send(i2c_addr, res, sizeof(res));
+			break;
+		}
+		default: return false;
+	}
+
+	return true;
+}
+
+bool pbdrv_hook_write(uint16_t i2c_addr, uint8_t addr, const char * buf, size_t sz) {
+	switch (addr) {
+		case CUSTOM_VAR_ADDR: {
+			if (sz != 1) return false;
+			my_custom_variable = buf[0];
+			break;
+		}
+		default: return false;
+	}
+
+	return true;
+}
+```
+
+[[sec:cmd]]
+== Custom commands
+
+Similar to the auxiliary state, custom commands can be added by implementing
+the ``pbdrv_hook_cmd`` function, which should return ``true`` for the
+command(s) that you want to overwrite.
+
+Example:
+
+```c
+bool pbdrv_hook_cmd(uint16_t i2c_addr, enum pb_cmd cmd, const char * buf, size_t sz) {
+	if (cmd == 0x54) {
+		printf("custom command received!\n");
+		return true;
+	}
+
+	return false;
+}
+```
+