19 files changed, 587 insertions, 0 deletions

diff --git a/lib/pbdrv/CMakeLists.txt b/lib/pbdrv/CMakeLists.txt
new file mode 100644
index 0000000..ca85b2b
--- /dev/null
+++ b/lib/pbdrv/CMakeLists.txt
@@ -0,0 +1,28 @@
+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)
+
+add_subdirectory(lib/mpack)
+
+# generic puzzle bus (de)serializer library
+add_library(pbdrv STATIC pb-read.c pb-write.c)
+target_link_libraries(pbdrv mpack)
+target_include_directories(pbdrv SYSTEM INTERFACE .)
+
+# puzzle bus module specific code (superset of pbdrv)
+add_library(pbdrv-mod STATIC pb-mod.c)
+target_link_libraries(pbdrv-mod pbdrv)
+target_include_directories(pbdrv-mod SYSTEM INTERFACE .)
+
+# supported puzzle bus drivers
+include(drv/arduino/cfg.cmake)
+include(drv/rp2040/cfg.cmake)
+
diff --git a/lib/pbdrv/drv/arduino/cfg.cmake b/lib/pbdrv/drv/arduino/cfg.cmake
new file mode 100644
index 0000000..36716e3
--- /dev/null
+++ b/lib/pbdrv/drv/arduino/cfg.cmake
@@ -0,0 +1,7 @@
+if(NOT DEFINED ARDUINO)
+	return()
+endif()
+
+target_sources(pbdrv-mod PRIVATE "${CMAKE_CURRENT_LIST_DIR}/mod.cpp")
+target_link_arduino_libraries(pbdrv-mod core Wire)
+
diff --git a/lib/pbdrv/drv/arduino/mod.cpp b/lib/pbdrv/drv/arduino/mod.cpp
new file mode 100644
index 0000000..8a38a5b
--- /dev/null
+++ b/lib/pbdrv/drv/arduino/mod.cpp
@@ -0,0 +1,37 @@
+#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 "../../pb.h"
+#include "../../pb-mod.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.setWireTimeout(PB_TIMEOUT_US, true);
+	Wire.setClock(PB_CLOCK_SPEED_HZ);
+	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(true);
+	Wire.setWireTimeout(PB_TIMEOUT_US, true);
+}
+
diff --git a/lib/pbdrv/drv/arduino/mod.h b/lib/pbdrv/drv/arduino/mod.h
new file mode 100644
index 0000000..079941a
--- /dev/null
+++ b/lib/pbdrv/drv/arduino/mod.h
@@ -0,0 +1,17 @@
+#pragma once
+
+#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/drv/rp2040/cfg.cmake b/lib/pbdrv/drv/rp2040/cfg.cmake
new file mode 100644
index 0000000..0fbad18
--- /dev/null
+++ b/lib/pbdrv/drv/rp2040/cfg.cmake
@@ -0,0 +1,7 @@
+if(NOT PICO_PLATFORM STREQUAL "rp2040")
+	return()
+endif()
+
+target_sources(pbdrv-mod PRIVATE "${CMAKE_CURRENT_LIST_DIR}/mod.c")
+target_link_libraries(pbdrv-mod hardware_i2c pico_i2c_slave)
+
diff --git a/lib/pbdrv/drv/rp2040/mod.c b/lib/pbdrv/drv/rp2040/mod.c
new file mode 100644
index 0000000..6becdee
--- /dev/null
+++ b/lib/pbdrv/drv/rp2040/mod.c
@@ -0,0 +1,73 @@
+#include "mod.h"
+
+#include "../../pb.h"
+#include "../../pb-types.h"
+#include "../../pb-mod.h"
+
+#include <hardware/i2c.h>
+#include <hardware/gpio.h>
+#include <pico/i2c_slave.h>
+
+#define PBDRV_I2C i2c0
+#define BUF_SIZE 256
+
+static volatile bool pbdrv_i2c_msg_avail = false;
+static uint8_t data[BUF_SIZE];
+static size_t size = 0;
+
+// TODO: create event group instead of pbdrv_i2c_msg_avail
+// TODO: create freertos task that monitors the pbdrv_i2c_msg_avail flag and
+// calls pbdrv_i2c_recv when a message is received
+
+
+/**
+ * \note this function is called from the I2C ISR, and should return as quickly
+ * as possible.
+ */
+static void recv_event(i2c_inst_t *i2c, i2c_slave_event_t event) {
+	// message needs to be handled first
+	if (pbdrv_i2c_msg_avail) return;
+
+	switch (event) {
+		case I2C_SLAVE_RECEIVE: {
+			if (size == BUF_SIZE) return;
+			data[size++] = i2c_read_byte_raw(PBDRV_I2C);
+			break;
+		}
+		case I2C_SLAVE_FINISH: {
+			// TODO: handle this w/ queue mechanism instead?
+			// pbdrv_i2c_recv(data, size);
+			pbdrv_i2c_msg_avail = true;
+			size = 0;
+			break;
+		}
+		default: break;
+	}
+}
+
+void pbdrv_setup() {
+	i2c_init(PBDRV_I2C, PB_CLOCK_SPEED_HZ);
+	i2c_slave_init(PBDRV_I2C, PBDRV_MOD_ADDR, &recv_event);
+}
+
+/**
+ * While the RP2040's datasheet claims it supports multi-master configurations
+ * by implementing bus arbitration, it does not natively support a mode where
+ * it is configured as a (multi-)master with a slave address, such that it can
+ * be addressed by other multi-masters. This function includes a hacky
+ * workaround that teporarily sets the RP2040 to I2C master mode to send a
+ * message, and then restores it back to slave mode.
+ *
+ * This approach results in some received frames being (partially) dropped in
+ * the time period between the invocation of this function and the bus becoming
+ * idle (and the message is sent).
+ */
+__weak void pbdrv_i2c_send(i2c_addr_t addr, const uint8_t * buf, size_t sz) {
+	i2c_set_slave_mode(PBDRV_I2C, false, PBDRV_MOD_ADDR);
+
+	// false to write stop condition to i2c bus
+	i2c_write_timeout_us(PBDRV_I2C, addr, buf, sz, false, PB_TIMEOUT_US);
+
+	i2c_set_slave_mode(PBDRV_I2C, true, PBDRV_MOD_ADDR);
+}
+
diff --git a/lib/pbdrv/drv/rp2040/mod.h b/lib/pbdrv/drv/rp2040/mod.h
new file mode 100644
index 0000000..0cf2e63
--- /dev/null
+++ b/lib/pbdrv/drv/rp2040/mod.h
@@ -0,0 +1,13 @@
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+//! puzzle bus driver setup
+void pbdrv_setup();
+
+#ifdef __cplusplus
+}
+#endif
+
diff --git a/lib/pbdrv/lib b/lib/pbdrv/lib
new file mode 120000
index 0000000..58677dd
--- /dev/null
+++ b/lib/pbdrv/lib
@@ -0,0 +1 @@
+../../lib
\ No newline at end of file
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..7a6f0df
--- /dev/null
+++ b/lib/pbdrv/pb-read.h
@@ -0,0 +1,10 @@
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+
diff --git a/lib/pbdrv/pb-types.h b/lib/pbdrv/pb-types.h
new file mode 100644
index 0000000..96ffc37
--- /dev/null
+++ b/lib/pbdrv/pb-types.h
@@ -0,0 +1,98 @@
+#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_REQ_SET_STATE, //!< request to overwrite module global state
+	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_REQ_SET_STATE data
+typedef struct {
+	const pb_msg_header_t header;
+	const pb_global_state_t state; //!< new global state
+} pb_cmd_req_set_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..752a4ac
--- /dev/null
+++ b/lib/pbdrv/pb-write.c
@@ -0,0 +1,35 @@
+#include <mpack.h>
+
+#include "pb-write.h"
+
+typedef struct {
+	mpack_writer_t writer;
+	pbdrv_buf_t buf;
+} pbdrv_writer_t;
+
+static pbdrv_writer_t pbdrv_write_init() {
+	pbdrv_writer_t writer;
+	mpack_writer_init_growable(&writer.writer, &writer.buf.data, &writer.buf.size);
+	return writer;
+}
+
+static pbdrv_buf_t pbdrv_write_finish(pbdrv_writer_t * writer) {
+	if (mpack_writer_destroy(&writer->writer) != mpack_ok) {
+		writer->buf.data = NULL;
+		writer->buf.size = 0;
+	}
+	return writer->buf;
+}
+
+static void pbdrv_write_msg_header(pbdrv_writer_t * writer, pb_msg_header_t header) {
+	mpack_write_u8(&writer->writer, header.type);
+	mpack_write_u16(&writer->writer, header.sender);
+}
+
+pbdrv_buf_t pbdrv_write_cmd_req_set_state(pb_cmd_req_set_state_t data) {
+	pbdrv_writer_t writer = pbdrv_write_init();
+	pbdrv_write_msg_header(&writer, data.header);
+	mpack_write_u8(&writer.writer, data.state);
+	return pbdrv_write_finish(&writer);
+}
+
diff --git a/lib/pbdrv/pb-write.h b/lib/pbdrv/pb-write.h
new file mode 100644
index 0000000..3245898
--- /dev/null
+++ b/lib/pbdrv/pb-write.h
@@ -0,0 +1,26 @@
+#pragma once
+
+#include "pb-types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+//! binary buffer struct
+typedef struct {
+	char * data; //! pointer to data
+	size_t size; //! size of data
+} pbdrv_buf_t;
+
+pbdrv_buf_t pbdrv_write_cmd_req_read(pb_cmd_req_read_t data);
+pbdrv_buf_t pbdrv_write_cmd_res_read(pb_cmd_res_read_t data);
+pbdrv_buf_t pbdrv_write_cmd_req_write(pb_cmd_req_write_t data);
+pbdrv_buf_t pbdrv_write_cmd_req_state(pb_cmd_req_state_t data);
+pbdrv_buf_t pbdrv_write_cmd_res_state(pb_cmd_res_state_t data);
+pbdrv_buf_t pbdrv_write_cmd_req_set_state(pb_cmd_req_set_state_t data);
+pbdrv_buf_t pbdrv_write_cmd_magic(pb_cmd_magic_t data);
+
+#ifdef __cplusplus
+}
+#endif
+
diff --git a/lib/pbdrv/pb.h b/lib/pbdrv/pb.h
new file mode 100644
index 0000000..b6efed0
--- /dev/null
+++ b/lib/pbdrv/pb.h
@@ -0,0 +1,22 @@
+#pragma once
+
+#define PB_CLOCK_SPEED_HZ 100000
+#define PB_TIMEOUT_MS 10
+#define PB_TIMEOUT_US (1e3 * PB_TIMEOUT_MS)
+
+// Adafruit NeoTrellis modules
+#define PB_ADDR_ADA_NEO_1 0x2E
+#define PB_ADDR_ADA_NEO_2 0x2F
+#define PB_ADDR_ADA_NEO_3 0x30
+#define PB_ADDR_ADA_NEO_4 0x32
+
+// TODO: ???
+#define PB_ADDR_MOD_NEOTRELLIS 0
+#define PB_ADDR_MOD_SOFTWARE 0
+#define PB_ADDR_MOD_HARDWARE 0
+#define PB_ADDR_MOD_VAULT 0
+// #define BUSADDR_MOD_AUTOMATION 0
+
+// main controller
+#define PB_ADDR_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;
+}
+```
+