Merge remote-tracking branch 'github/develop' into feature/119-serial-interface-connect-protocol-with-actual-data

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
@@ -13,6 +13,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+    - name: Install tools for generation of documentation
+      run: |
+        sudo apt-get install doxygen graphviz
+        sudo apt-get install texlive-base perl # necessary for citing bib files
+    
     - name: Checkout code
       uses: actions/checkout@v2
 
@@ -25,9 +30,9 @@ jobs:
         echo "DOC_OUTPUT_DIR=$output_dir" >> "$GITHUB_ENV"
 
     - name: generate documentation
-      uses: mattnotmitt/doxygen-action@v1.9.5
-      with:
-        additional-packages: texlive perl # necessary for citing bib files
+      run: |
+        wget https://github.com/plantuml/plantuml/releases/latest/download/plantuml.jar
+        (echo "PLANTUML_JAR_PATH = ."; cat Doxyfile) | doxygen -
 
     - name: deploy documentation
       uses: peaceiris/actions-gh-pages@v3

.gitignore

@@ -6,3 +6,4 @@
 .vscode/extensions.json
 doc/html/
 doc/latex/
+.vscode/settings.json

CONTRIBUTING.md

@@ -29,6 +29,10 @@ To get in touch with us you may contact a [contributor](https://github.com/Task-
 
 Before submitting to this repository, please: 
 
+* Familiarize yourself with the 
+  [software architecture documentation](<\ref software_architecture> "software architecture documentation")
+  and the
+  [design decisions](<\ref doc/decisions> "design decisions").
 * Test your contribution.
 * Make sure your code does not introduce warnings or errors.
 * Your proposition may be reviewed based on state of the art coding standards (for example [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/) or [C++ Super FAQ](https://isocpp.org/faq)).

Doxyfile

@@ -7,6 +7,7 @@ EXTRACT_STATIC         = YES
 CITE_BIB_FILES         = doc/bibliography
 INPUT                  = .
 RECURSIVE              = YES
+EXAMPLE_PATH           = doc/debouncing/
 IMAGE_PATH             = doc/
 USE_MDFILE_AS_MAINPAGE = ./README.md
 HTML_FILE_EXTENSION    = .xhtml

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/debouncing.md

@@ -0,0 +1,100 @@
+# Debouncing Approaches {#debouncing_approaches}
+
+Obtaining the state of switches and buttons generally requires to debounce the input signal because of contact bouncing.
+The waveform of an input may be smoothed physically using a low-pass filter.
+Coping with bouncing programmatically may allow a simplified circuit thus reducing complexity and material cost.
+
+Debouncing in software follows in general one of these approaches:
+
+1. steady sampling of the signals and waiting for either
+  1. an average value to cross a threshold
+  2. a sequence of continuous states to reach a minimum length
+2. observing processor interrupts triggered by state changes of digital inputs
+  1. after a state change, ignore further changes for a specified time before adopting the next change
+  2. after a state change, wait for the state to be stable for a specified time before adopting that change
+
+Steady sampling has disadvantages:
+
+- if the sample rate is too low, the reaction may be significantly delayed
+- if the number of samples is too low, a state change may be prematurely detected (state changes while still bouncing)
+- constantly polling the state
+  - may bind processing time
+  - may require context switching
+  - may be solved (more) efficiently using the processor's hardware timers and counters (availability depends on the MPU)
+
+Interrupt based sampling only consumes processing time if actual changes occur.
+This is especially advantageous with buttons, which are seldomly actuated, compared to other activities.
+
+Also interrupt based sampling is not flawless.
+The specific disadvantages depend on the chosen approach and the concrete implementation.
+
+In any case it must be considered that detecting a steady state change of a button should probably be executed with a higher priority than the execution of the processing of that event.
+For example periodically sampling or reacting on an digital input should interrupt time-insensitive processing.
+But the actual processing of a finally adopted state change may take longer and should take place with lower priority.
+Thus some kind of synchronization mechanism (or interrupt masking) will usually be necessary.
+
+Hereafter two different approaches based on hardware interrupts will be discussed.
+
+
+## Interrupt based Debouncing
+
+Interrupts called by the processor as a reaction on a change of a digital input may be used to detect state changes of switches and buttons.
+In contrast to debouncing approaches which sample with fixed periods, interrupt based debouncing usually uses the time relative the the last state change to detect steady states.
+Either by discarding changes which occur shortly after a previously adopted state change.
+Or by waiting for the last change to prevail long enough.
+
+
+### Post-change delay
+
+Approaches which ignore changes which occur in a short period after a previously accepted change are easy to implement.
+One simply has to compare the timestamp of the last accepted change with the current time.
+If that difference is below a threshold, the state change will be ignored.
+
+\include{doc} bouncing-classic-normal.puml
+
+The timing diagram above shows how, when the button is pressed, a rising edge will be detected.
+But also bouncing will occur for some time.
+A threshold defines a window (highlighted section) beginning with the first event in which following state changes will be ignored.
+After that window, if the button is released the falling edge, and therefor the state change, will immediately be detected.
+
+The debounced signal will be active for the time between button pressed and released.
+
+\include{doc} bouncing-classic-too-short.puml
+
+A problem arises in case the button press (the pulse) is too short.
+The first state change will be detected.
+But if bouncing finishes within the window for ignoring changes, the final state (released) will not be detected.
+The debounced state will remain "active" until further state changes.
+
+As the time a button bounces may differ on each actuation, defining a threshold value totally avoiding this problem may not be possible.
+
+
+### Pre-change delay
+
+A different interrupt based approach waits for the input signal to be stable before adopting its change.
+This can be achieved with a delay which will be restarted each time a state change occurs.
+If the delay elapses without further changes the state is considered as stable.
+The current state is then read to check for a state change.
+
+The duration of the delay can be much shorter than the window in which state changes will be ignored from the previous approach.
+In contrast to defining the expected time after which a signal will be stable it defines the minimum time a signal may not change to be accepted as stable.
+Thus the duration is more a requirement then a heuristic.
+
+\include{doc} bouncing-delay-normal.puml
+
+In the timing diagram above is shown that the debouncer will wait while the digital input bounces.
+After bouncings stops the delay time will elapse.
+Only then the state of the digital input is read to detect the state change.
+
+The debounced signal will be active for a duration which depends on the bouncing while releasing the button.
+If bouncing takes the same time while pressing and releasing, the active duration will be the same as the pressed duration.
+
+The debounced state will be delayed by the bouncing time and the defined startup delay.
+
+\include{doc} bouncing-delay-too-short.puml
+
+An advantage to the previous approach can be seen with short pulses.
+If the button is pressed and then released while still bouncing (or withing the delay), no state change will be adopted.
+Too short button presses do not lead to adopt only one of two (or more) state changes.
+This is the safer approach.
+

doc/debouncing/bouncing-classic-normal.puml

@@ -0,0 +1,33 @@
+@startuml
+title debouncing by post-event filtering: not too short
+caption debouncing normal pulse
+hide time-axis
+scale 1 as 250 pixels
+binary "digital input" as D
+binary "debounced signal" as B
+
+@0
+D is low
+note top of B : debounced
+B is low
+@+1
+D is {low,high}
+note bottom of D : button pressed
+D@+0 <-> @+0.8 : bouncing
+D -> B : rising edge detected
+highlight +0 to +1 : state changes ignored
+B is high
+@+0.8
+D is high
+@+0.5
+D is {low,high}
+note bottom of D : button released
+D -> B : falling edge detected
+D@+0 <-> @+0.8 : bouncing
+highlight +0 to +1 : state changes ignored
+B is low
+@+0.8
+D is low
+
+
+@enduml

doc/debouncing/bouncing-classic-too-short.puml

@@ -0,0 +1,23 @@
+@startuml
+title debouncing by post-event filtering: too short
+caption too short pulse leads to wrong state
+hide time-axis
+scale 1 as 250 pixels
+binary "digital input" as D
+binary "debounced signal" as B
+
+@0
+D is low
+note top of B : debounced
+B is low
+@+1
+D is {low,high}
+D@+0 <-> @+0.9 : bouncing
+D -> B : rising edge detected
+highlight +0 to +1 : state changes ignored
+B is high
+@+0.9
+D is low
+D -> B : state change ignored
+
+@enduml

doc/debouncing/bouncing-delay-normal.puml

@@ -0,0 +1,41 @@
+@startuml
+title debouncing based on delay: not too short
+caption debouncing normal pulse
+hide time-axis
+scale 1 as 250 pixels
+binary "digital input" as D
+binary "debouncer waiting" as W
+binary "debounced signal" as B
+
+@0
+D is low
+note top of B : debounced
+B is low
+@+1
+D is {low,high}
+W is high
+note bottom of D : button pressed
+D@+0 <-> @+0.8 : bouncing
+@+0.8
+W@+0 <-> @+0.1 : delay
+D is high
+@+0.1
+W is low
+W -> D : read state
+W -> B : rising edge detected
+B is high
+@+0.5
+note bottom of D : button released
+D is {low,high}
+W is high
+D@+0 <-> @+0.8 : bouncing
+@+0.8
+D is low
+W@+0 <-> @+0.1 : delay
+@+0.1
+W is low
+W -> D : read state
+W -> B : falling edge detected
+B is low
+
+@enduml

doc/debouncing/bouncing-delay-too-short.puml

@@ -0,0 +1,26 @@
+@startuml
+title debouncing based on delay: too short
+caption too short pulse will be completely ignored
+hide time-axis
+scale 1 as 250 pixels
+binary "digital input" as D
+binary "debouncer waiting" as W
+binary "debounced signal" as B
+
+@0
+D is low
+note top of B : debounced
+B is low
+@+1
+D is {low,high}
+W is high
+D@+0 <-> @+0.9 : bouncing
+@+0.9
+D is low
+W@+0 <-> @+0.1 : delay
+@+0.1
+W -> D : read state
+W is low
+note top of B : state has not been adopted
+
+@enduml