documentation & more (#63)

* documentation

* documentation

* documentation

AI.md

@@ -0,0 +1,73 @@
+# AI usage experience
+## github copilot
+I used the 30 days trial period of github copilot with VS code to find out how effectively copilot enhances / speeds up development.
+
+Github copilot made a mixed impression from extremely helpful to completely annoying.
+
+Sometimes it really worked:
+- just type a word - comment or code
+- copilot proposes just what was intended or even better
+- just a TAB and code is written
+
+Sometimes it didn't
+- proposals where completely unusable
+- the occupation of TAB can confuse
+
+Copilot worked as good with python as with C++.
+
+Since it is AI - it learns as you work with it and .. gets better.
+
+### conclusion
+
+Once I've got used to it (and it to me), it pulverizes the typing work.
+
+And yes: I pay the 10$ / month.
+
+## ChatGPT
+Later in the development - just for curiosity - I asked ChatGPT for a solutions.
+
+### sample: .sh to .cmd
+#### linux
+I had written a linux shell script (.sh) to run system tests:
+- run DSTW application in background
+- run test application
+- run stop application (which send a stop telegram to DSTW application)
+
+No big deal in bash.
+
+#### win
+Since everything also build in VS - there wa a need to have this as a Windows cmd script.
+
+For me the Windows scripting syntax is a pain in the ass.
+
+#### translate
+So I came to the idea to ask ChatGPT:
+- copied the .sh code to ChatGPT
+- asked: can you translate to cmd?
+- and I got it, not yet working, but almost
+
+#### discuss
+The thing is, that you really get to better solutions by discussion.
+
+e.g.
+- me: I don't think "call" statements are correct, because they exit the script
+- GPT: sorry, you are right
+- new code
+- took 10 minutes to have the working code
+
+Have a look at the results if you like:
+-   [source](make/runSystemTests.sh)
+-   [translation](make/runSystemTests.cmd) 
+
+### conclusion
+ChatGPT is a boost. It will make google and sites like StackOverflow more or less redundant.
+
+(The price of this is a consumption of electric energy equivalent to a town with 150000 - yes: a hundred and fifty thousand - inhabitants.)
+
+## AI conclusion
+AI has changed the approach to software development
+- less work with implementation issues
+- more concentration on issues like
+    - subject
+    - requirements
+    - collaboration

README.md

@@ -10,17 +10,21 @@ It consists of the following components:
 - SYS: commonly used system
 - COM: TCP communication to field and GUI
 
+### goals
 The project does not intend an implementation that would work in a real digital interlocking (DSTW).
 
-The aim is to apply and demonstrate techniques to meet security integrity level 4 (SIL4).
-
-It shows a completely different approach than the [model driven](Clinch.md) one I happened to experience.
+The aim is to
+- apply and demonstrate techniques to meet security integrity level 4 (SIL4).
+- show a completely different approach than the [model driven](Clinch.md) one I happened to experience.
+- use as much modern C++ as possible
+- gain AI usage experience
 
 ## components interaction overview
 ![overview](specification/doc/overview.svg)
 
 ## topics
 - [SIL4](SIL4.md)
+- [AI usage](AI.md)
 - [testing](testing/README.md)
 - [transition tables](specification/doc/transition_tables.md)
 - [code coverage](testing/coverage.md)

testing/README.md

@@ -4,7 +4,12 @@
 CppUTest is the base of testing in this project for good reasons:
 
 -   it's lean and fast
--   it runs on almost every device
+-   it runs on almost every device and platform. I have used (and customized) it with:
+    - CAD-UL
+    - IAR
+    - VS
+    - gcc
+    - eclipse / Mingw
 -   the greatest advantage to other frameworks: it natively handles unexpected calls as well as expected calls that aren't fulfilled
 
 ## module tests
@@ -15,7 +20,7 @@ In test context every module instance that realizes an interface is substituted
 
 The software compiled for production does not provide any substitution of the modules in charge.
 
-The whole thing is achieved by different include paths leading to two different [IL.h headers](##IL-headers).
+The whole thing is achieved by different include paths leading to two different IL.h headers.
 
 This concept has been SIL4 validated already.