update readmes

5 files changed, 61 insertions, 18 deletions

diff --git a/client/CMakeLists.txt b/client/CMakeLists.txt
index 73c703d..57a2447 100644
--- a/client/CMakeLists.txt
+++ b/client/CMakeLists.txt
@@ -3,7 +3,10 @@ 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(puzzlebox_client C CXX)
 
diff --git a/client/cmd.cpp b/client/cmd.cpp
index a26de13..ab101e9 100644
--- a/client/cmd.cpp
+++ b/client/cmd.cpp
@@ -91,3 +91,4 @@ void cmd_ls(char*) {
 	};
 	i2c_send(BUSADDR_MAIN, msg, sizeof(msg));
 }
+
diff --git a/client/cmd.h b/client/cmd.h
index 30bcbeb..932f3a2 100644
--- a/client/cmd.h
+++ b/client/cmd.h
@@ -14,10 +14,10 @@ struct cmd {
 cmd_fn_t cmd_exit;
 cmd_fn_t cmd_test;
 cmd_fn_t cmd_help;
-cmd_fn_t cmd_send;
 cmd_fn_t cmd_status;
 cmd_fn_t cmd_reset;
 cmd_fn_t cmd_ls;
+cmd_fn_t cmd_send;
 
 static const struct cmd cmds[] = {
 	{
@@ -36,11 +36,6 @@ static const struct cmd cmds[] = {
 		.info = "show this help",
 	},
 	{
-		.handle = cmd_send,
-		.name = "send",
-		.info = "[debug] send raw message",
-	},
-	{
 		.handle = cmd_status,
 		.name = "status",
 		.info = "show global puzzle box state (main controller state)",
@@ -55,6 +50,13 @@ static const struct cmd cmds[] = {
 		.name = "ls",
 		.info = "list connected puzzle modules",
 	},
+#ifdef DEBUG
+	{
+		.handle = cmd_send,
+		.name = "send",
+		.info = "[debug] send raw message",
+	},
+#endif
 };
 static const size_t cmds_length = sizeof(cmds) / sizeof(cmds[0]);
 
diff --git a/client/readme.md b/client/readme.md
index 1b4cc34..ea3e034 100644
--- a/client/readme.md
+++ b/client/readme.md
@@ -1,5 +1,27 @@
 # puzzle box client
 
+This folder contains the source code for the puzzle box client (pbc). This is a
+desktop application that communicates with the main controller over TCP to
+send/receive I<sup>2</sup>C messages. This application is not only used by a
+game operator to control and monitor the state of a puzzle box, but is also a
+useful debugging tool when developing puzzle modules, as it allows you to send
+arbitrary data over the puzzle bus.
+
+## Features
+
+- List detected puzzle modules
+- Reset puzzle modules (individually or all to reset the box)
+- Skip puzzle modules (individually or all)
+- Request puzzle box state
+
+Debug only:
+- Send arbitrary messages
+
+## Building
+
+PBC is a standard CMake project, but a [makefile](./makefile) is provided for
+convenience (still requires CMake and Ninja are installed).
+
 ## Send data
 
 ```
diff --git a/readme.md b/readme.md
index 7802f5c..ac703b7 100644
--- a/readme.md
+++ b/readme.md
@@ -1,25 +1,34 @@
-# puzzle box
+# Puzzle box
 
-Avans University of Applied Sciences project puzzle box.
+This repository contains the source code for the puzzle framework designed and
+implemented during the 2023-2024 run of the Puzzlebox project. This year's run
+of the project consists of only software students, and was developed using the
+hardware from the 21-22 run of the project.
 
-## tidyness
+Improved hardware was designed but not realised during the 22-23 run of the
+project. This hardware is recommended for future groups participating in the
+project. The software in this repository should be easily portable to various
+other microcontrollers, and a recommendation is made in the [design
+document](docs/design.adoc).
+
+## Tidyness
 
 Please keep this repository tidy by being aware of the following conventions!
 
-### folder structure
+### Folder structure
 
 |folder|contains|
 |-|-|
 |`/client`|Desktop PC application for controlling the puzzle box
 |`/docs`|Project documentation in AsciiDoc(tor) format
+|`/i2ctcp`|I<sup>2</sup>C over TCP protocol functions (used by main and client)
 |`/lib`|Libraries (tracked as [submodules](#submodules))
 |`/main`|Main controller (RPi pico) software
-|`/proto`|Puzzle bus TCP protocol functions (used by main and client)
 |`/puzzle/<name>`|Puzzle sources, each puzzle has its own subdirectory
-|`/shared`|Auxiliary shared code
+|`/shared`|Shared code
 |`/test`|Unit test framework (currently unutilized)
 
-### code style
+### Code style
 
 An `.editorconfig` file is provided in this repository. Please install the
 [EditorConfig](https://editorconfig.org/) plugin for your text editor of choice
@@ -28,7 +37,7 @@ to automatically use these.
 Currently, no linter/formatter is configured for maintaining consistent code
 style.
 
-## submodules
+## Submodules
 
 This repository tracks (most) dependencies via git submodules.
 
@@ -40,6 +49,7 @@ git submodule update --init --recursive --depth 1
 
 until your problems go away.
 
+<!--
 ## Tests
 
 ```
@@ -49,10 +59,15 @@ cmake ..
 make
 make test
 ```
+-->
+
+## ESP SDK setup
 
-## ESP
-1. Install ESP-IDF extension in vscode
+1. Install ESP-IDF extension in Visual Studio Code
 2. Install using 'express' option
 3. Install ESP-IDF v5.2.1 (release version)
-4. For windows: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/windows-setup.html#get-started-windows-first-steps
-5. For Linux: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/linux-macos-setup.html#get-started-linux-macos-first-steps
+
+   Additional help:
+   - [For windows](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/windows-setup.html#get-started-windows-first-steps)
+   - [For Linux](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/linux-macos-setup.html#get-started-linux-macos-first-steps)
+