Merge branch 'develop' into feature/generic-menu-and-lvgl-implementation

Author: dhebbeker

.github/workflows/generate-documentation.yml

@@ -1,9 +1,9 @@
 name: generate and deploy documentation
 
 on:
-  push:
-    branches-ignore:
-      - 'gh-pages'
+  workflow_run:
+    workflows: [Cleanup GitHub Pages Branch Workflow]
+    types: [completed]
 
 permissions:
   contents: write

README.md

@@ -71,10 +71,30 @@ Since version 2.1.0 it uses VS Code's built-in terminal instead.
 That terminal does not provide a prompt for entering, reviewing and modifying a message before sending it.
 See also [this issue report](https://github.com/wokwi/wokwi-features/issues/698).
 
-Serial port forwarding is enabled for the simulator.
-Thus a Telnet client can be used to connect to the serial port of the simulator.
+The simulator also [provides a RFC2217 TCP server](https://docs.wokwi.com/vscode/project-config#serial-port-forwarding) as an alternative.
+Serial port forwarding is enabled for the simulator per configuration.
+This can be used to connect via a Telnet client to the serial port of the simulated device.
 
-For example one can use the [PuTTY](https://www.putty.org/) SSH Client in Telnet mode with `localhost` as host and `4000` as port.
+For example one may use a [PuTTY](https://www.putty.org/) SSH Client with the following settings:
+
+- Host Name: `localhost`
+- Port: `4000`
+- Connection type: Telnet
+
+For testing with the Task Tracker App (or any other programm which supports a serial interface),
+one can forward the RFC2217 TCP connection to a pseudo terminal.
+For example using [socat](http://www.dest-unreach.org/socat/):
+
+    socat -d -d pty,raw,echo=0,link=/tmp/tcp_tty tcp:localhost:4000
+
+Now you can connect to the serial terminal using these settings:
+
+- path to serial line: `/tmp/tcp_tty`
+- speed: `115200` baud
+- data bits: `8`
+- stop bits: `1`
+- parity: none
+- flow control: none
 
 ### Debugging
 

doc/hardware-architecture.md

@@ -0,0 +1,23 @@
+Hardware Architecture {#hardware_architecture}
+=====================
+
+The Task-Tracker-Device consists of hardware which is described in this chapter.
+
+The coarse structure of the hardware is sketched in the following diagram:
+
+![diagram showing the hardware structure](hardware-structure.svg)
+
+- The **microcontroller** block represents the used microcomputer including its immediate external components which are necessary for general operation.
+  This block is realized by a the development board [ESP32-S3-DevKitC-1](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/hw-reference/esp32s3/user-guide-devkitc-1.html).
+  It includes a UART to USB transciever for convenient connection to a host system.
+  A DC voltage converter from 5V to 3.3V is also included.
+- The **power and battery charger** provides an integrated limited power source.
+  It is capable to provide uninterrupted power for the other components while charging or disconnected.
+- A **USB** connector is used for power and data.
+  Serial communication is transported over USB data.
+  The microcontroller also acts as a USB mass storage device to a USB host.
+- A OLED **display** is connected via I2C to the microcontroller.
+  It has 124x64 monochrome pixels.
+- A real-time clock (**RTC**) provides the current wall-clock time to the microcontroller.
+- **LEDs** and a **buzzer** are use to advertise states or events to the user.
+- **Buttons** can be used by the user to directly interact with the device.

doc/hardware-structure.svg

@@ -44,12 +44,7 @@ void setCallbackForLineReception(const StringHandler &callback)
 
 } // namespace serial_port
 
-/*
-  SerialEvent occurs whenever a new data comes in the hardware serial RX. This
-  routine is run between each time loop() runs, so using delay inside loop can
-  delay response. Multiple bytes of data may be available.
-*/
-void serialEvent()
+void serial_port::readAndHandleInput()
 {
     while (Serial.available() > 0)
     {

lib/3rd_party_adapters/Arduino/serial_port.cpp

@@ -33,7 +33,7 @@ void initialize();
 /**
  * Reads a line from serial port.
  * 
- * Interprets the end of line as `\n`.
+ * Expects the end of line to be `\n`.
  * It will wait for data for the duration of the timeout.
  * \returns an empty string in case no data is read
  */
@@ -42,7 +42,7 @@ String readLine();
 /**
  * Gets a line from serial port.
  * 
- * Interprets the end of line as `\n`.
+ * Expects the end of line to be `\n`.
  * \returns an object that does not contain a value in case no data is already available.
  */
 std::optional<String> getLine();
@@ -58,6 +58,8 @@ typedef std::function<void(const String &)> StringHandler;
  */
 void setCallbackForLineReception(const StringHandler &callback);
 
+void readAndHandleInput();
+
 } // namespace serial_port
 
 /**

lib/application_business_rules/serial_interface/serial_port.hpp

@@ -32,6 +32,8 @@ void loop()
     static Presenter presenter(singleMenu, board::getStatusIndicators());
     static ProcessHmiInputs processHmiInputs(presenter, board::getKeypad());
 
+    serial_port::readAndHandleInput();
+
     for (auto task : device::tasks)
     {
         serial_port::cout << task.second.getLabel() << " : " << std::boolalpha << task.second.isRunning()