From b6abd84b9930ab398f0402058e56a480e80799cc Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Tue, 28 May 2024 11:53:06 +0200 Subject: update readmes --- client/CMakeLists.txt | 3 +++ client/cmd.cpp | 1 + client/cmd.h | 14 ++++++++------ client/readme.md | 22 ++++++++++++++++++++++ readme.md | 39 +++++++++++++++++++++++++++------------ 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[] = { { @@ -35,11 +35,6 @@ static const struct cmd cmds[] = { .name = "help", .info = "show this help", }, - { - .handle = cmd_send, - .name = "send", - .info = "[debug] send raw message", - }, { .handle = cmd_status, .name = "status", @@ -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 I2C 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`|I2C 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/`|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. + + +## 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) + -- cgit v1.2.3