update readmes

1 files changed, 27 insertions, 12 deletions

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)
+