diff options
Diffstat (limited to 'main')
| -rw-r--r-- | main/blink.h | 12 | ||||
| -rw-r--r-- | main/config.def.h | 54 | ||||
| -rw-r--r-- | main/i2c.h | 14 | ||||
| -rw-r--r-- | main/index.dox | 6 | ||||
| -rw-r--r-- | main/init.h | 12 | ||||
| -rw-r--r-- | main/pbdrv.h | 56 | ||||
| -rw-r--r-- | main/readme.md | 3 | ||||
| -rw-r--r-- | main/sock.h | 15 | ||||
| -rw-r--r-- | main/tasks.h | 9 |
9 files changed, 134 insertions, 47 deletions
diff --git a/main/blink.h b/main/blink.h index 51c5f32..f8262d0 100644 --- a/main/blink.h +++ b/main/blink.h @@ -1,4 +1,16 @@ #pragma once +/** + * \ingroup main_tasks + * \{ + */ + +/** + * \brief Status LED blink task + * + * This task is started after initialization is complete, and blinks the + * on-board LED to indicate the Pico has completed initialization successfully. + */ void blink_task(); +/// \} diff --git a/main/config.def.h b/main/config.def.h index e9503ed..0dae608 100644 --- a/main/config.def.h +++ b/main/config.def.h @@ -3,31 +3,44 @@ #include <cyw43_country.h> /** + * \ingroup main + * \defgroup main_config config + * \brief Configuration options + * \{ + */ + +/** * \name Network (Wi-Fi) configuration * \{ */ #ifndef CFG_NET_SSID -//! network name (SSID) +/** + * \brief Network name (SSID) + * \note Not defining \c CFG_NET_SSID will implicitly enable \c CFG_NET_DISABLE + */ #define CFG_NET_SSID "" #ifndef CFG_NET_DISABLE -//! disable network communication +/** + * \brief Disable network communication completely + * \note Enabling this option will implicitly enable \c CFG_SRV_DISABLE + */ #define CFG_NET_DISABLE #warning No SSID defined! Disabling network communication! #endif #endif #ifndef CFG_NET_PASS -//! network password +//! Network password #define CFG_NET_PASS "" #endif #ifndef CFG_NET_AUTH -//! network security type +//! Network security type #define CFG_NET_AUTH CYW43_AUTH_OPEN #endif #ifndef CFG_NET_CONN_TIMEOUT -//! max duration (milliseconds) for establishing wifi connection +//! Max duration (milliseconds) for establishing Wi-Fi connection #define CFG_NET_CONN_TIMEOUT 10e3 #endif @@ -36,47 +49,52 @@ #define CFG_NET_COUNTRY CYW43_COUNTRY_WORLDWIDE #endif #ifndef CFG_NET_COUNTRY -//! radio communications country +//! Radio communications country #define CFG_NET_COUNTRY CYW43_COUNTRY_NETHERLANDS #endif -/** \} */ +/// \} /** - * \name i2ctcp server configuration + * \name TCP server configuration * \{ */ #ifndef CFG_SRV_PORT -//! i2ctcp server port +//! TCP server port #define CFG_SRV_PORT 9191 #endif - #ifdef CFG_NET_DISABLE -//! disable the i2ctcp server +//! Disable the TCP server #define CFG_SRV_DISABLE #endif -/** \} */ +/// \} /** * \name I2C configuration * \{ */ #ifndef CFG_SDA_PIN -//! I^2^C SDA pin +//! I2C SDA pin #define CFG_SDA_PIN 16 #endif #ifndef CFG_SCL_PIN -//! I^2^C SCL pin +//! I2C SCL pin #define CFG_SCL_PIN 17 #endif -/** \} */ +/// \} +/** + * \name Auxiliary options + * \{ + */ #ifndef CFG_LED_PIN -//! status LED pin +//! Status LED pin #define CFG_LED_PIN CYW43_WL_GPIO_LED_PIN #endif - #ifndef CFG_PB_MOD_MAX -//! maximum number of simultaniously connected puzzle modules +//! Maximum number of simultaniously connected puzzle modules #define CFG_PB_MOD_MAX 8 #endif +/// \} + +/// \} @@ -1,5 +1,17 @@ #pragma once -//! looking for slave addresses and requesting updates +/** + * \ingroup main_tasks + * \{ + */ + +/** + * \brief I2C bus activity task + * + * This function does an initial bus scan for puzzle modules, and then goes + * into an infinite loop that periodically polls all puzzle modules for their + * global state. + */ void bus_task(); +/// \} diff --git a/main/index.dox b/main/index.dox new file mode 100644 index 0000000..aa2d07a --- /dev/null +++ b/main/index.dox @@ -0,0 +1,6 @@ +// vim:ft=doxygen +/** +\ingroup main +\defgroup main_tasks tasks +\brief Tasks +*/ diff --git a/main/init.h b/main/init.h index 73d2773..a24977d 100644 --- a/main/init.h +++ b/main/init.h @@ -1,11 +1,17 @@ #pragma once /** - * \brief initialize the main controller + * \ingroup main + * \{ + */ + +/** + * \brief Initialize the main controller * * This function only synchronously initializes the standard input/output (used - * for `printf` and `panic`), and queues all other types of initialization in - * the `init` task using FreeRTOS. + * for \c printf() and \c panic()), and queues all other types of + * initialization in the \c async_init() task using FreeRTOS. */ void init(); +/// \} diff --git a/main/pbdrv.h b/main/pbdrv.h index a751000..9496aa9 100644 --- a/main/pbdrv.h +++ b/main/pbdrv.h @@ -3,35 +3,41 @@ #include "pb-types.h" /** - * This is the RP2040 puzzle bus driver. This file is no longer inside - * lib/pb//rp2040 as it is tightly coupled to both the pico-sdk and - * freertos functions. I have tried to get FreeRTOS to play nicely with the - * CMake subproject layout, but the pico-sdk and the rp2040 port of freertos - * both rely on CMake's import() functionality, which makes using FreeRTOS in a - * libary context extremely messy. + * \ingroup pb_drv + * \defgroup pb_drv_rp2040 RP2040 + * \brief Raspberry Pi Pico and Pico W driver * - * The workaround implemented in this driver was already kind of messy, and a - * different microcontroller should be used for the main controller instead. + * \note This file is no longer inside `lib/pbdrv/drv/rp2040` as it is tightly + * coupled to both the pico-sdk and FreeRTOS functions. I have tried to get + * FreeRTOS to play nicely with the CMake subproject layout, but the pico-sdk + * and the RP2040 port of FreeRTOS both rely on CMake's import() functionality, + * which makes using FreeRTOS in a libary context extremely messy. + * + * \warning The workaround implemented in this driver was already kind of + * messy, and **a different microcontroller should be used for the main + * controller instead**. Please see the handover document for more details. + * + * \{ */ #ifdef __cplusplus extern "C" { #endif -//! puzzle bus driver setup +//! Puzzle bus driver setup void pb_setup(); /** - * 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. + * \note 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). + * \warning 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). */ void pb_i2c_send(i2c_addr_t addr, const uint8_t * buf, size_t sz); @@ -39,13 +45,19 @@ void pb_i2c_send(i2c_addr_t addr, const uint8_t * buf, size_t sz); * \brief Scan the bus for I2C slaves, and send handshake messages to ACK-ing * slaves. * - * As a result of the RP2040 hardware limitations detailed at the top of this - * file, this function is also implemented in this file, even through it does - * not belong to the puzzle bus driver. In order to not miss any handshake - * responses, the bus should remain busy during the entire scan. + * \note As a result of the RP2040 hardware limitations, this function is also + * implemented in this file, even though it does not belong to the puzzle bus + * driver. + * + * \warning In order to not miss any handshake responses, the bus should remain + * busy during the entire scan. The \c nostop parameter of the \c + * i2c_write_timeout_us() function from the pico-sdk does not seem to keep the + * bus busy. */ void bus_scan(); +/// \} + #ifdef __cplusplus } #endif diff --git a/main/readme.md b/main/readme.md index 28fcfad..85a3fca 100644 --- a/main/readme.md +++ b/main/readme.md @@ -1,3 +1,6 @@ +\defgroup main main +\brief Main controller software + # main controller firmware This directory contains the software for the main controller of the Puzzle Box. diff --git a/main/sock.h b/main/sock.h index 38fca01..a151973 100644 --- a/main/sock.h +++ b/main/sock.h @@ -1,8 +1,17 @@ #pragma once -#include <stdint.h> -#include <stddef.h> +/** + * \ingroup main_tasks + * \{ + */ -//! start listening for TCP socket requests +/** + * \brief Listen for TCP socket messages + * + * This task starts a TCP server that listens for messages using \ref i2ctcp, + * and sends any received I2C messages (also using \ref i2ctcp). + */ void serve_task(); +/// \} + diff --git a/main/tasks.h b/main/tasks.h index 002f830..ac77a9e 100644 --- a/main/tasks.h +++ b/main/tasks.h @@ -1,4 +1,13 @@ #pragma once +/** + * \ingroup main + * \{ + */ + +/** + * \brief Register \ref main_tasks "all tasks" in FreeRTOS + */ void init_tasks(); +/// \} |