the large library cleanup

22 files changed, 616 insertions, 0 deletions

diff --git a/lib/i2ctcp/CMakeLists.txt b/lib/i2ctcp/CMakeLists.txt
new file mode 100644
index 0000000..b47b1d7
--- /dev/null
+++ b/lib/i2ctcp/CMakeLists.txt
@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 3.29)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_EXPORT_COMPILE_COMMANDS 1)
+
+project(i2ctcp C CXX)
+
+add_subdirectory(../mpack ${CMAKE_CURRENT_BINARY_DIR}/mpack)
+
+add_library(i2ctcp STATIC ./i2ctcpv1.c)
+target_link_libraries(i2ctcp mpack)
+target_include_directories(i2ctcp SYSTEM INTERFACE .)
+
diff --git a/lib/i2ctcp/i2ctcpv1.c b/lib/i2ctcp/i2ctcpv1.c
new file mode 100644
index 0000000..944df3a
--- /dev/null
+++ b/lib/i2ctcp/i2ctcpv1.c
@@ -0,0 +1,52 @@
+#include <mpack.h>
+#ifndef MIN
+#define MIN(a,b) (((a) < (b)) ? (a) : (b))
+#endif
+
+#include "i2ctcpv1.h"
+
+int i2ctcp_read(i2ctcp_msg_t * target, const char * buf, size_t buf_sz) {
+	mpack_reader_t reader;
+	mpack_reader_init_data(&reader, buf, buf_sz);
+
+	// at start of message
+	if (target->_rdata == 0) {
+		target->addr = mpack_expect_u16(&reader);
+		target->length = target->_rdata = mpack_expect_bin(&reader);
+		if (mpack_reader_error(&reader) != mpack_ok) return -1;
+		target->data = (char *) malloc(target->length);
+
+		// seek forward in buf to where binary data begins (to avoid having to read
+		// from private member reader.data in the memcpy below)
+		buf += buf_sz - mpack_reader_remaining(&reader, NULL);
+	}
+
+	// continue reading chunks of target->data until the amount of bytes
+	// specified in target->length
+	size_t to_read = MIN(mpack_reader_remaining(&reader, NULL), target->_rdata);
+	char * data = target->data + target->length - target->_rdata;
+	memcpy(data, buf, to_read);
+	target->_rdata -= to_read;
+	// NOTE: memcpy is used here because mpack_read_bytes requires that a tag was
+	// opened, which is not the case for the chunks following the initial mpack
+	// header
+
+	// if rdata = 0, the message was completely read
+	return target->_rdata;
+}
+
+void i2ctcp_read_reset(i2ctcp_msg_t * target) {
+	target->_rdata = 0;
+}
+
+bool i2ctcp_write(const i2ctcp_msg_t * target, char ** buf, size_t * buf_sz) {
+	mpack_writer_t writer;
+	mpack_writer_init_growable(&writer, buf, buf_sz);
+
+	mpack_write_u16(&writer, target->addr);
+	mpack_write_bin(&writer, target->data, target->length);
+
+	// finish writing
+	return mpack_writer_destroy(&writer) == mpack_ok;
+}
+
diff --git a/lib/i2ctcp/i2ctcpv1.h b/lib/i2ctcp/i2ctcpv1.h
new file mode 100644
index 0000000..799b668
--- /dev/null
+++ b/lib/i2ctcp/i2ctcpv1.h
@@ -0,0 +1,71 @@
+#pragma once
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** \brief I2C over TCP message (v1) */
+struct i2ctcp_msg {
+	uint16_t addr; //!< I^2^C address
+	char * data;   //!< message content
+	size_t length; //!< message size
+	size_t _rdata; //!< \private remaining bytes to read until message is complete
+};
+typedef struct i2ctcp_msg i2ctcp_msg_t;
+
+/**
+ * \brief Read chunk of input stream, and store resulting message in \p target
+ *
+ * This function is called for each chunk of data from an input stream, and
+ * will parse the next puzzle bus message into \p target. The input stream is
+ * assumed to only contain messages encoded by \p i2ctcp_write()
+ *
+ * \param target  pointer to struct that will contain the finished message data
+ * \param buf     pointer to input stream data chunk
+ * \param buf_sz  size of \p buf
+ *
+ * \returns Integer representing amount of bytes required to finish message, or
+ * -1 if the message header could not be read. If this function returns 0, the
+ *  message in \p target is complete.
+ *
+ * \note target->data will automatically be allocated by this function, even if
+ * the message is not fully parsed. This variable must be `free()`d by the
+ * caller after each complete message to prevent memory leaks.
+ */
+int i2ctcp_read(i2ctcp_msg_t * target, const char * buf, size_t buf_sz);
+
+/**
+ * \brief reset the remaining message data counter
+ *
+ * Calling this function has the effect of forcing \c i2ctcp_read() to parse
+ * the next buffer chunk as the start of a new message. This function may be
+ * called before reading a TCP frame's data to mitigate any synchronization
+ * issues arising from earlier corrupt or otherwise malformed messages.
+ */
+void i2ctcp_read_reset(i2ctcp_msg_t * target);
+
+/**
+ * \brief Allocate and write a msgpack-formatted message to \p buf
+ *
+ * This function allocates a buffer large enough to fit the message specified
+ * in \p target, and encodes the data in \p target in a format that can be
+ * decoded later using \p i2ctcp_read()
+ *
+ * \param target  pointer to struct that contains the message data
+ * \param buf     pointer to \c char* that will contain the formatted message
+ * \param buf_sz  pointer to \c size_t that will represent the final size of \p buf
+ *
+ * \returns boolean true if a the message could be encoded successfully, false
+ * if there was some kind of error
+ *
+ * \note the pointer stored in \p buf must be `free()`d by the caller afterwards
+ */
+bool i2ctcp_write(const i2ctcp_msg_t * target, char ** buf, size_t * buf_sz);
+
+#ifdef __cplusplus
+}
+#endif
+
diff --git a/lib/i2ctcp/makefile b/lib/i2ctcp/makefile
new file mode 100644
index 0000000..5ca3fd1
--- /dev/null
+++ b/lib/i2ctcp/makefile
@@ -0,0 +1,4 @@
+TARGET = $(BUILD_DIR)/libi2ctcp.a
+
+include ../../lazy.mk
+
diff --git a/lib/i2ctcp/readme.md b/lib/i2ctcp/readme.md
new file mode 100644
index 0000000..d5bfe6d
--- /dev/null
+++ b/lib/i2ctcp/readme.md
@@ -0,0 +1,25 @@
+# i2ctcp (I<sup>2</sup>C over TCP)
+
+This folder includes protocol (de)serialization functions for sending and
+receiving I<sup>2</sup>C messages over TCP. These functions are used by the
+[main controller](../main) and the [puzzle box client (pbc)](../client). This
+folder does not include any puzzle bus specific code, and the headers for
+puzbus are in the [shared](../shared) folder instead.
+
+[MessagePack][msgpack] (specifically the [mpack][mpack] implementation) is used
+for the actual serialization/deserializtion, and the functions in this folder
+act as helpers for parsing from chunked data streams.
+
+To use these functions, include the following statement in your CMakeLists.txt:
+```cmake
+include(../i2ctcp/include.cmake)
+```
+
+The functions are available by `#include`ing the `i2ctcpv1.h` header, and are
+extensively documented using Doxygen-style comments.
+
+[msgpack]: https://msgpack.org/
+[mpack]: https://github.com/ludocode/mpack/
+
+
+
diff --git a/lib/mpack/CMakeLists.txt b/lib/mpack/CMakeLists.txt
new file mode 100644
index 0000000..0a904b0
--- /dev/null
+++ b/lib/mpack/CMakeLists.txt
@@ -0,0 +1,26 @@
+if(TARGET mpack)
+	return()
+endif()
+
+cmake_minimum_required(VERSION 3.29)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_EXPORT_COMPILE_COMMANDS 1)
+
+project(mpack C)
+
+add_library(mpack STATIC
+	src/src/mpack/mpack-common.c
+	src/src/mpack/mpack-expect.c
+	src/src/mpack/mpack-node.c
+	src/src/mpack/mpack-platform.c
+	src/src/mpack/mpack-reader.c
+	src/src/mpack/mpack-writer.c
+	)
+target_include_directories(mpack SYSTEM INTERFACE
+	src/src/mpack
+	)
+
+# causes some wild crashes, please leave off
+add_compile_definitions(MPACK_READ_TRACKING=0)
+
diff --git a/lib/mpack/makefile b/lib/mpack/makefile
new file mode 100644
index 0000000..e96794a
--- /dev/null
+++ b/lib/mpack/makefile
@@ -0,0 +1,4 @@
+TARGET = $(BUILD_DIR)/libmpack.a
+
+include ../../lazy.mk
+
diff --git a/lib/mpack b/lib/mpack/src
-Subproject 79d3fcd3e04338b06e82d01a62f4aa98c7bad5f
+Subproject 79d3fcd3e04338b06e82d01a62f4aa98c7bad5f
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;
+}
+```
+