Title: Manual mcHF
Post by: Leo on 15. December 2016, 08:58:46
Hallo Leute ich bin wie die Jungfrau zum Kind zu einem mcHF gekommen.
Leider bin ich in Technik ziemlich unbedarft. Zum wesentlichen, laut Einschalt=
bildschirm laüft das Ding mit der Firmware 1.2.0 und Bl:2.0.0. und ich denke
das Manual zu der Ver.0.0.219.26 passt nich wirklich zu der neueren FW.
Frage dazu: gibt es was neueres?
vy 73 de Leo |
Title: Re:Manual mcHF
Post by: DF8OE on 15. December 2016, 09:09:48
Nur bruchstückhaft. Es hat sich immer noch niemand / kein Team gefunden, das diese Aufgabe übernehmen möchte ::)
Hier gibt es Infos, die neuer sind:
https://github.com/df8oe/mchf-github/wiki (https://github.com/df8oe/mchf-github/wiki)
vy 73
Andreas |
Title: Re:Manual mcHF
Post by: DC9LW on 18. December 2016, 16:00:41
Hallo Leute
Mein Vorschlag für eine Dokumentation des Menüs eines mcHF wäre ein Mindmap wie im Bild dargestellt.
Dieses Fragment habe ich mit CMAP (http://cmap.ihmc.us/) hergestellt. Die Möglichkeiten der Software scheinen mir interessant zu sein, zumal es die unterschiedlichsten Exportmöglichkeiten der Map's gibt. Auch die Bearbeitung kann im Team erfolgen, den die Map's können in eine Cloud ausgelagert werden, von wo aus sie der Allgemeinheit zu Verfügung stehen.
Andreas, ich weiß nicht was passiert wenn ich das exportierte html File hier einfüge, daher lasse ich das lieber. Ich schicke es dir im Anschluss als html.txt
vy 73 Günter |
Title: Re:Manual mcHF
Post by: DB4PLE on 18. December 2016, 16:33:03
Hallo Günter,
das geht ja hier zu wie als ob es bald Weihnachten wäre. Lauter tolle Dinge, die man sich schon so lange gewünscht hat.
So eine Mindmap ist eine tolle Idee.
Insbesondere deswegen nicht das Folgende falsch verstehen:
Aber einen Haken hat jedes Geschenk. Hier wäre es die Sprache. Die "offizielle" Wiki-Sprache ist Englisch und die Pflege mehrerer Sprachen ist aufwändig, insbesondere für die nicht des Deutschen mächtigen.
Beim Tool muss ich auch etwas rumnörglen. Das ist kein OpenSource und erstmal nur in der Betaphase kostenlos.
Ich hätte eine "offline only" full Open Source- Alternative: Freemind (www.freemind.org) . Sollte auch alles können was man braucht, bis auf die Online Kollaboration (man muss allerdings Java installiert haben).
Ob Du die Idee auf Deutsch oder Englisch weiterführst und mit welchem Tool, ist absolut deine Sache und egal wie, das sollte unterstützt werden, nur um das nochmal klar zu sagen. Ich denke auch, dass die Mindmap auch auf Deutsch ins Wiki sollte oder damit verlinkt werden, keine Frage. Die Menü-Doku im Wiki hat derzeit gerade mal einen Eintrag: https://github.com/df8oe/mchf-github/wiki/Operating-Manual---Menu , dass ist wahrlich nicht allumfassend.
Im Endzustand schwebt mir allerdings die automatische Generierung der Menüdoku aus der Software vor, sonst kommt man bei Änderungen einfach nicht mehr nach. Habe aber noch keine klare Idee, wie das technisch einfach (!) zu bewerkstelligen wäre.
73
Danilo
|
Title: Re:Manual mcHF
Post by: DC9LW on 18. December 2016, 17:05:17
Hallo Danilo
Ich habe die Map auch mit freeplane (ein Fork von freemind) erstellt, hatte die Möglichkeiten von Cmap aber als größer erachtet ohne auf die Lizenz zu achten, sorry.
Bei freemind würde ich alleine darstehen und das ist doch etwas zu umfangreich für mich, zumal es mir schwerfallen würde dies in englisch zu erstellen.
Also hoffen wir, dass das mit der automatischen Erstellung der Doku aus der Software bald klappen wird.
Vy 73 Günter |
Title: Re:Manual mcHF
Post by: DB4PLE on 18. December 2016, 21:23:20
Hallo Günter,
dann mach es doch so wie Du es kannst und willst. Die automatische generierte Doku schreibt die Beschreibungstexte auch nicht selbst und Deutsch nach Englisch ist allemal besser als "nichts" nach Englisch.
Wenn CMAP auch wieder Freemind ausspuckt, dann sollte ein plötzlicher Lizenzwandel hoffentlich durch Export nach Freemind erledigt sein.
73
Danilo |
Title: Re:Manual mcHF
Post by: HB9ocq on 22. December 2016, 10:22:49
na was soll ich sagen, ich meinte es ernst mit:Das ist DOT-Language aus dem SW-Paket Graphviz:
* <http://www.graphviz.org (http://www.graphviz.org)>
Da bin ich Fan von, und fast fluent in dieser Sprache :-)
|
|
ich hab mir .../driver/ui/ui_menu.c etwas angeschaut, dann hats mich gejuckt,
ein paar wenige ZauberZeilen bash + Python und die Menuuebersicht laesst sich programmatisch als Graph in DOT Language umformen. Der Renderer dot (aus dem SW-Paket Graphviz) ist unser Maling-Knecht.
Hier mal eine Uebersicht der C-enums um das Prinzip zu verdeutlichen.
Ich verhuebsche das noch auf die Presentation-layer-texts (MenuDescriptor.id MenuDescriptor.label in .../driver/ui/ui_menu.c), dann solls ins Makefile und wird per make docs oder aehnlich automagisch aufdatierbar.
DAS nenne ich EDV = Elektronische Datenverarbeitung - von Hand abmalen ist bloss EDV = ENDE DER VERNUNFT!
Danke fuer die Anregung!
(und waer doch C auch so schoen/einfach/praegnant wie die 3 hier verwendeten Sprachen :-P ) |
Title: Re:Manual mcHF
Post by: HB9ocq on 22. December 2016, 10:38:16
| baaah! Ich muss jetzt an den Herd... |
Title: Re:Manual mcHF
Post by: peter_77 on 22. December 2016, 11:41:05
Mmmmhhh...lecker Käsefondue ??!
Ich komm vorbei !
|
Title: Re:Manual mcHF
Post by: HB9ocq on 22. December 2016, 12:48:39
nein: wie meine ZauberZeilen oben ist auch das nur Resteverwertung gewesen :-D |
Title: Re:Manual mcHF
Post by: DB4PLE on 22. December 2016, 13:16:58
Hallo Stephan,
super! Genau so hatte ich mir das vorgestellt. Und vorallem das ich das nicht selbst machen muss 8)
Was ich jetzt noch gerne machen würde, wäre einen speziellen Kommentar für jedes Menü-Element zu haben, aus dem wir
dann die Doku generieren. Wenn Du mal dein Skript ins github bringst oder selbst eine Idee hast, wie wir das bewerkstelligen können, mach ruhig.
Ich stelle mir halt als Minimum einen einfachen Text (in Markdown-Notation, denn den versteht auch das github Wiki. Dann generieren wir statt des DOT (bleibt natürlich auch), die Wiki-Tabellen direkt aus dem Source-Code, das würde Donald Knuth (Stichwort Literate Programming, Das Programm und die Dokumentation werden in einem gemeinsamen Dokument geschrieben) freuen. Und die Hemmschwelle senken, die Menüs korrekt zu dokumentieren.
Wenn man es schöner will, kann man auch noch Infos zu Default und Wertebereich separat erfassen. Das ist aber auch nicht ohne Gefahr, dann das Wissen dazu ist nicht direkt am Menüeintrag zu finden, sondern in echtem Programmcode, also nicht so einfach auszulesen (bis garnicht). Aber schon der Text allein ist ein Bringer...
Ich freu mich drauf.
73
Danilo
|
Title: Re:Manual mcHF
Post by: DF8OE on 22. December 2016, 13:30:28
Weihnachten findet dieses Jahr schon früher statt :D
Danke für dein Engagement Stephan. Ich schaue mir auch halbfertige oder nicht lauffähige Sachen an! Also wenn Du nicht weiterkommst: wirf die Brocken einfach hier rein. Es sind genug Tauben da, die darauf warten...
vy 73
Andreas |
Title: Re:Manual mcHF
Post by: HB9ocq on 23. December 2016, 10:15:42
Title: Re:Manual mcHF
Post by: DF8OE on 23. December 2016, 10:27:48
!!!!!!!!!!!!!!!!!!!!!!!!!!!
:D
vy 73
Andreas |
Title: Re:Manual mcHF
Post by: HB9ocq on 23. December 2016, 10:50:38
Ich stelle mir halt als Minimum einen einfachen Text (in Markdown-Notation, denn den versteht auch das github Wiki.
|
|
) vor.
(Danilo, nur nicht in die Hose machen, wegen dem bisschen EDV ;-)
Etwa so? (s. Anhang) |
Title: Re:Manual mcHF
Post by: HB9ocq on 23. December 2016, 11:00:24
Ich schaue mir auch halbfertige oder nicht lauffähige Sachen an!
|
|
Aber Andreas, wo kaemen wir denn hin, wenn alle noch was dazu lernen... ;-) |
Title: Re:Manual mcHF
Post by: HB9ocq on 23. December 2016, 13:02:47
super! Genau so hatte ich mir das vorgestellt. Und vorallem das ich das nicht selbst machen muss 8)
|
|
soso...einen speziellen Kommentar für jedes Menü-Element zu haben, aus dem wir
dann die Doku generieren.
:
Dann generieren wir ... direkt aus dem Source-Code, das würde Donald Knuth (Stichwort Literate Programming, Das Programm und die Dokumentation werden in einem gemeinsamen Dokument geschrieben) freuen.
|
|
Da ja bereits DoxyGen im Einsatz ist, arbeite Dich in die DoxyGen-Syntax ein: da geht mehr customisation als einfach Doku zum Quellcode.
z.B. einfach mit dem richtigen Markup DOT-Language einleiten und kleine Diagramme (z.B. State-Machine) von hand rein Pflanzen
Sowenig wie:
"""
power_On -> STATE_A
STATE_A -> STATE_B -> STATE_C
STATE_C -> STATE_A
"""
ergibt bereits "4 beschriftete Ballone mit Pfeile untereinander" und da sind nichtmal reservierte Woerter verwendet
Wenn man es schöner will, kann man auch noch Infos zu Default und Wertebereich separat erfassen. Das ist aber auch nicht ohne Gefahr, dann das Wissen dazu ist nicht direkt am Menüeintrag zu finden, sondern in echtem Programmcode, also nicht so einfach auszulesen (bis garnicht). Aber schon der Text allein ist ein Bringer...
|
|
Gerne, aber Du erkennst es richtig: wenn ein Programm (hier die mcHF-FW) zu "Anweisungslastig" konzipiert ist, kann fast nur der Quellcode-Parser die zusammengehoerige Information zusammenbringen.
Besser ist wenn ein Programm (hier AUCH die mcHF-FW) mehr auf "Datengesteuert" umgebaut wird.
Die Menusache insbesondere, UIs im allgemeinen, geben einen hervorragenden Praxisfall ab, genau wegen dem dual use (fuer das Binary, fuer das Handbuch)
- - <BRAINSTORM state="on"> - -
Die Datei .../drivers/ui/ui_menu.c ist mit knapp 4k LOC einfach mal aus Prinzip zu lange.
mchf-eclipse/support $ cloc --by-file ../drivers/ui/*.?
7 text files.
7 unique files.
0 files ignored.
http://cloc.sourceforge.net v 1.60 T=0.09 s (76.4 files/s, 145481.1 lines/s)
---------------------------------------------------------
File blank comment code
---------------------------------------------------------
../drivers/ui/ui_driver.c 973 1306 4951
../drivers/ui/ui_menu.c 253 296 3543
../drivers/ui/ui_configuration.c 78 115 471
../drivers/ui/ui_configuration.h 23 98 415
../drivers/ui/ui_driver.h 64 128 303
../drivers/ui/ui_menu.h 10 34 226
../drivers/ui/ui.h 7 13 14
---------------------------------------------------------
SUM: 1408 1990 9923
---------------------------------------------------------
mchf-eclipse/support $
Jetzt wo ich die Extraktion der MenuDaten zwecks Diagramm gemacht habe und ein wenig in ui_menu.c hineingesehen habe, waere als erstes dran diese MenuDaten in eine eigene Datei auszulagern.
Diese duerften in eine Header-Datei z.B. ui_menu_data.h passen: alle Deklarationen (Datentypen) und Definitionen (const... Daten) welche nur mit der MenueSache zu tun haben.
ui_menu_data.h wuerde dann -fuer die mcHF-FW- AUSSCHLIESSLICH in ui_menu.c inkludiert werden.
Beim Extrahieren mit anderen Mittel (Shell, Python, ...) aus ui_menu_data.h ist dann sicherer dass man eben NUR auf Daten zu den Menus zugreift (die Suchmuster muessen nicht auch noch alfaellige "Abwehrmassnahmen" gegen unerwuenschtes enthalten).
Andererseits kann dann auch ein anderes Programm in C geschrieben werden, welche z.B. in .../support/ beheimatet ist und durch inkludieren von .../drivers/ui/ui_menu_data.h anderes anstellen kann: erstens gar nicht auf der mcHF-HW laufen sondern auf dem Entwicklungshost und direkt ohne Umweg (also ohne Shell, Python, ...) DOT/MarkDown/egalwas generieren.
Preis: ein weiteres Makefile (z.B. .../support/Makefile) welches Host-Tools baut BEVOR der ganze Build laeuft.
Der "Ganze Build[TM]" kann dann mit diesem Makefile sowohl die Werkzeuge wie auch die Dokuartefakte und anschliessend mit dem bisherigen (Target-/Cross-)Makefile die Binaerartefakte fuer die Zielplattform koordinieren.
(die genaue Zaehlung ergibt tatsaechlich: +2 zusaetzliche Makefiles oder +1 Script z.B. build.sh u. +1 Makefile)
Was ich weiter sehe:
mchf-eclipse/support $ grep -A3 -P '^const\s+MenuDescriptor\s+\w+\[\]' ../drivers/ui/ui_menu.c
const MenuDescriptor topGroup[] =
{
{ MENU_TOP, MENU_GROUP, MENU_BASE, "STD","Standard Menu"},
{ MENU_TOP, MENU_GROUP, MENU_CONF, "CON","Configuration Menu"},
--
const MenuDescriptor baseGroup[] =
{
// { MENU_BASE, MENU_ITEM, MENU_SSB_NARROW_FILT,"029","CW Filt in SSB Mode"},
{ MENU_BASE, MENU_ITEM, MENU_SSB_AUTO_MODE_SELECT,"031","LSB/USB Auto Select"},
--
const MenuDescriptor displayGroup[] =
{
{ MENU_DISPLAY, MENU_ITEM, CONFIG_LCD_AUTO_OFF_MODE,"090","LCD Auto Blank"},
{ MENU_DISPLAY, MENU_ITEM, CONFIG_FREQ_STEP_MARKER_LINE,"091","Step Size Marker"},
--
const MenuDescriptor cwGroup[] =
{
// { MENU_CW, MENU_ITEM, MENU_CW_WIDE_FILT,"028","Wide Filt in CW Mode"},
{ MENU_CW, MENU_ITEM, MENU_KEYER_MODE,"070","CW Keyer Mode"},
--
const MenuDescriptor confGroup[] =
{
// Unused in firmware: { MENU_CONF, MENU_ITEM, CONFIG_FREQ_LIMIT_RELAX,"231","Freq. Limit Disable"},
--
const MenuDescriptor powGroup[] =
{
{ MENU_POW, MENU_ITEM, CONFIG_TUNE_POWER_LEVEL,"P00","Tune Power Level"},
{ MENU_POW, MENU_ITEM, CONFIG_TUNE_TONE_MODE,"P99","Tune Tone (SSB)"},
--
const MenuDescriptor filterGroup[] =
{
{ MENU_FILTER, MENU_ITEM, MENU_FP_SSB_01,"600", "SSB Filter 1" },
{ MENU_FILTER, MENU_ITEM, MENU_FP_SSB_02,"600", "SSB Filter 2" },
--
const MenuDescriptor infoGroup[] =
{
{ MENU_SYSINFO, MENU_INFO, INFO_DISPLAY,"I01","Display"},
{ MENU_SYSINFO, MENU_INFO, INFO_DISPLAY_CTRL,"I02","Disp. Controller"},
--
const MenuDescriptor debugGroup[] =
{
{ MENU_DEBUG, MENU_ITEM, MENU_DEBUG_TX_AUDIO,"028","TX Audio via USB"},
{ MENU_DEBUG, MENU_STOP, 0, " " , NULL }
stephans@indas:~/tmp/GIT_DF8OE_mchf-github/mchf-eclipse/support$ grep -A4 -P '^const\s+MenuDescriptor\s+\w+\[\]' ../drivers/ui/ui_menu.c
const MenuDescriptor topGroup[] =
{
{ MENU_TOP, MENU_GROUP, MENU_BASE, "STD","Standard Menu"},
{ MENU_TOP, MENU_GROUP, MENU_CONF, "CON","Configuration Menu"},
{ MENU_TOP, MENU_GROUP, MENU_DISPLAY, "DIS","Display Menu"},
--
const MenuDescriptor baseGroup[] =
{
// { MENU_BASE, MENU_ITEM, MENU_SSB_NARROW_FILT,"029","CW Filt in SSB Mode"},
{ MENU_BASE, MENU_ITEM, MENU_SSB_AUTO_MODE_SELECT,"031","LSB/USB Auto Select"},
{ MENU_BASE, MENU_ITEM, MENU_DIGI_DISABLE,"030","Digital Modes"},
--
const MenuDescriptor displayGroup[] =
{
{ MENU_DISPLAY, MENU_ITEM, CONFIG_LCD_AUTO_OFF_MODE,"090","LCD Auto Blank"},
{ MENU_DISPLAY, MENU_ITEM, CONFIG_FREQ_STEP_MARKER_LINE,"091","Step Size Marker"},
{ MENU_DISPLAY, MENU_ITEM, CONFIG_DISP_FILTER_BANDWIDTH,"092","Filter BW Display"},
--
const MenuDescriptor cwGroup[] =
{
// { MENU_CW, MENU_ITEM, MENU_CW_WIDE_FILT,"028","Wide Filt in CW Mode"},
{ MENU_CW, MENU_ITEM, MENU_KEYER_MODE,"070","CW Keyer Mode"},
{ MENU_CW, MENU_ITEM, MENU_KEYER_SPEED,"071","CW Keyer Speed"},
--
const MenuDescriptor confGroup[] =
{
// Unused in firmware: { MENU_CONF, MENU_ITEM, CONFIG_FREQ_LIMIT_RELAX,"231","Freq. Limit Disable"},
{ MENU_CONF, MENU_ITEM, CONFIG_FREQ_MEM_LIMIT_RELAX,"232","Save Out-Of-Band Freq."},
--
const MenuDescriptor powGroup[] =
{
{ MENU_POW, MENU_ITEM, CONFIG_TUNE_POWER_LEVEL,"P00","Tune Power Level"},
{ MENU_POW, MENU_ITEM, CONFIG_TUNE_TONE_MODE,"P99","Tune Tone (SSB)"},
{ MENU_POW, MENU_ITEM, CONFIG_REDUCE_POWER_ON_LOW_BANDS,"P0A","Reduce Power on Low Bands"},
--
const MenuDescriptor filterGroup[] =
{
{ MENU_FILTER, MENU_ITEM, MENU_FP_SSB_01,"600", "SSB Filter 1" },
{ MENU_FILTER, MENU_ITEM, MENU_FP_SSB_02,"600", "SSB Filter 2" },
{ MENU_FILTER, MENU_ITEM, MENU_FP_SSB_03,"600", "SSB Filter 3" },
--
const MenuDescriptor infoGroup[] =
{
{ MENU_SYSINFO, MENU_INFO, INFO_DISPLAY,"I01","Display"},
{ MENU_SYSINFO, MENU_INFO, INFO_DISPLAY_CTRL,"I02","Disp. Controller"},
{ MENU_SYSINFO, MENU_INFO, INFO_SI570,"I02","SI570"},
--
const MenuDescriptor debugGroup[] =
{
{ MENU_DEBUG, MENU_ITEM, MENU_DEBUG_TX_AUDIO,"028","TX Audio via USB"},
{ MENU_DEBUG, MENU_STOP, 0, " " , NULL }
};
mchf-eclipse/support $
ist dass es redundant ist die MenuDescriptor-Eintraege alle mit dem ersten Element "menuId" zu versehen UND die MenuDesctiptor Arrays separat halten.
Derzeit ist es so dass ausnahmslos jeder Eintrag desselben Arrays auf genau dasselbe "Uebermenu" verweist - diese Information ist durch das individuelle Array jedoch implizit.
FRAGE: was spricht dagegen ALLE MenuDescriptor ine einem EINZIGEN Array vorzuhalten?
"Einspruenge" an den Anfang jeder Gruppe lassen sich durch Zeiger legen.
MENU_STOP-Eintraege werden auch bis auf der letzte ueberfluessig: jede Gruppe zeichnet sich durch gleichen menuId-Wert aus...
(also ein weiterer, neuer, erster Eintrag MENU_NONE wuerde das derzeitige MENU_STOP ersetzen:
enum MENU_GROUP_ITEM { MENU_NONE=0, MENU_TOP, MENU_... }
)
Tut mir leid, das fliesst nun weg vom Threadthema "Manual mcHF" - ist aber in Relation dazu... |
Title: Re:Manual mcHF
Post by: HB9ocq on 23. December 2016, 14:19:34
- - <BRAINSTORM state="continue"> - -
Zur Sache mit den Wertebereiche.
Als erstes alle ARTEN von Menues inventarisieren:
- nur anzeige = MENU_INFO
- weiteres Menu = MENU_GROUP
- (Ganz-)Zahlenbereiche m. allen Zwischenwerte [min..max]
- Listenbereiche (Strings)
:
enum MENU_KIND ergaenzen/umbauen, auch mit typedef
MenuDescriptor entsprechend zu union umbauen, MenuDescriptor.kind muss vom Typ enum MENU_KIND werden und als union-Diskriminator fungieren
Die union-Varianten bekommen entsprechend Felder fuer MIN, MAX, Liste (enum Typ) und was auch immer interessiert (icons anyone?).
:
Das ist jetzt nur kurz angerissen und keinesfalls Vollstaendig oder gar zu Ende gedacht; etwas in dieser Art fuehrt aber zu Konsolidierung aller Information welche fuer Menues (in der FW, im Handbuch) relevant ist.
Die Konsequenz ist natuerlich dass der Code welcher Menus "ausfuehrt" auch umgebaut werden muss.
Es muss ein Mechnanismus gefunden werden um callback-Funktionen einzubinden, vllt. ein weiterer enum zur Inventur aller cb-Funktionen und eine Funktion mit switch() um die cb-Aufrufe gemaess Signatur (=Parameterliste) auszufuehren...
Es lohnt sich bestimmt zuerst die aktuelle IST-Situation bezueglich LOCs (apt get cloc ist dein Freund *) und Binaer-kBs zu charakterisieren umd das mit dem spaeter erreichten zu vergleichen.
In allen QRL-Projekte welche ich gesehen habe (an denen ich mitgearbeitet habe) ergaben sich nach einem solchen Refactoring im UI-Bereich ausnahmslos folgende Vorteile:
- reduktion LOCs insgesamt = weniger zu testenden Code weil mehr Code wiederverwendet wird (der Code wird generischer anstatt spezifischer)
- kleinere Binaries
- Erweiterungen (mehr Menus) werden einfacher/billiger, mehr Fokus auf den funktionalen Code
- (UI-)Fehler treten wenn dann an mehreren Stellen auf, fallen schneller auf, sind schneller behoben (und ueberall gleichzeitig weg) = weniger Testaufwand
Sind alle Informationen zu den Menues zentral konsolidiert (z.B. in einem oder wenige Header-Dateien), wird das Kompilieren in Sprachvarianten OHNE alle Sprachen im Binary auch "ploetzlich ganz einfach": Build-Variable steuert welche Sprachdatei inkludiert wird.
(* Andreas, werden im Automatischen Build auch Build-Logs abgelegt?
die cloc Auswertung oder was aequivalentes waere eine sinnvolle Ergaenzung...
ja, folgende 2 Aufrufe sind nur naive Muster, es gibt sicher noch mehr auszuschliessende Dateien)
$
$ cloc --exclude-dir=mchf-eclipse/cmsis,mchf-eclipse/cmsis_boot,mchf-eclipse/cmsis_lib mchf-eclipse/ 463 text files.
438 unique files.
228 files ignored.
http://cloc.sourceforge.net v 1.60 T=2.89 s (122.0 files/s, 81794.8 lines/s)
--------------------------------------------------------------------------------
Language files blank comment code
--------------------------------------------------------------------------------
C/C++ Header 160 4059 7847 86808
C 168 12334 36672 81353
Python 10 566 727 2891
HTML 1 245 0 1012
make 2 57 59 353
Assembly 1 109 22 331
CMake 1 46 25 208
Bourne Shell 6 19 63 53
XML 1 0 0 36
C++ 1 10 8 20
Bourne Again Shell 1 5 44 18
--------------------------------------------------------------------------------
SUM: 352 17450 45467 173083
--------------------------------------------------------------------------------
$
$ cloc --exclude-dir=mchf-eclipse/cmsis,mchf-eclipse/cmsis_boot,mchf-eclipse/cmsis_lib --by-file mchf-eclipse/
463 text files.
438 unique files.
228 files ignored.
http://cloc.sourceforge.net v 1.60 T=2.92 s (120.5 files/s, 80782.2 lines/s)
------------------------------------------------------------------------------------------------------------------------------------------
File blank comment code
------------------------------------------------------------------------------------------------------------------------------------------
mchf-eclipse/drivers/freedv/noise_samples.h 2 2 60002
mchf-eclipse/drivers/audio/freedv_test_data.c 1 16016 16006
mchf-eclipse/bootloader/inc/stm32f4xx.h 756 848 5397
mchf-eclipse/drivers/ui/ui_driver.c 973 1306 4951
mchf-eclipse/drivers/freedv/codebookvq.c 4 15 4204
mchf-eclipse/drivers/freedv/golayenctable.h 1 1 4098
mchf-eclipse/drivers/ui/ui_menu.c 253 296 3543
mchf-eclipse/drivers/freedv/codebookjnd.c 4 15 3477
mchf-eclipse/drivers/fat_fs/src/ff.c 506 280 2739
:
:
mchf-eclipse/drivers/fat_fs/inc/fattime.h 3 1 4
mchf-eclipse/drivers/freedv/pilots_coh.h 1 1 4
mchf-eclipse/drivers/freedv/postfilter.h 9 20 4
mchf-eclipse/drivers/freedv/listensim.sh 3 4 2
mchf-eclipse/drivers/freedv/fq20.sh 2 4 2
------------------------------------------------------------------------------------------------------------------------------------------
SUM: 17450 45467 173083
------------------------------------------------------------------------------------------------------------------------------------------
$
|
Title: Re:Manual mcHF
Post by: DB4PLE on 23. December 2016, 14:45:57
Hallo Stephan,
Auslagerung:
Auslagerung vollkomen okay, sehr sinnvoll. Allerdings habe ich Probleme mit Header-Dateien, die "echte" Datenstrukturen beeinhalten und deswegen nur genau einmal inkludiert werden dürfen. Deswegen ist ein Paar h/c vermutlich besser. Host Tools ja, aber.
Host Tools:
Es darf nicht dazu kommen, das man mit Eclipse (oder auch CoIDE) nicht einen Build hinbekommt. D.h. die Hosttools sind nur für sekundäre Zwecke einsetzbar oder müssen in die entsprechenden Toolchains integriert werden. Makefile-Only Builds finde ich nicht akzeptabel, weil sie meinen und auch den Workflow anderer bei der Entwicklung empfindlich stören. Ich habe kein Problem, wenn jemand Eclipse beibringt direkt die Makefiles abzuarbeiten, da habe ich aber keinen Nerv dazu und mir fehlt da auch das Wissen.
Menu:
Die Struktur der Menüs habe ich mir ja überlegt. Der Sinn und Zweck der ganzen Übung war komplett statische Datenstrukturen zu erzeugen, die man nicht in Gänze durchsuchen muss sondern quasi selbstverlinkend sind und auf der anderen Seite auch Raum für die Umsetzung dynamischer Menüs lassen (dann im RAM), deswegen die Zergliederung. Und das bißchen Overhead für die Rückwärtsverlinkung ist zu verkraften.
Ich persönlich finde auch die separaten Menüs leichter zu überblicken, aber YMMV. Das war ein expliziter Design Choice, damit einfach klar ist, welche Menüeinträge ein Menü hat. Und man nicht hunderte von Einträgen durchsuchen muss ob da nicht noch einer mit der passenden Id ist.
Das kann man natürlich anders machen, die Frage ist, ob es nicht sinnvoller ist, sich auf andere Sachen zu konzentrieren.
Wenn Du einen Vorschlag hast, wie man die sich wiederholende MenuId entsorgen kann, das wäre nett. Hatte ich einfach keine Lust mehr, darüber nachzudenken, wie man das hinbekommt, da war mir die Zeit für die Lösungsfindung einfach zu schade.
Der Stop-Eintrag ist notwendig, weil C ja leider nicht verrät, wie lang die Datenarrays sind.
Länge ui_menu.c:
ui_menu.c ist eine Datei, die exterm strukuriert ist und deren Länge sich aus der hohen Anzahl der Menü-Einträge speist.
Da gibt es viel schlimmere Baustellen, ich sag nur ui_driver.c (Da bereite ich ja schon eine Weile die Auslagerung der "nicht" UI Funktionen mit dem Präfix RadioManagement vor.
Eigentliches Topic:
Für die Integration zusätzlicher Infos würde ich auch auf Makro-Magie setzen.
#ifndef MENU_DESC
#define MenuDescription(a)
#else
#define MenuDescription(a) a
#endif
...
{ MENU_TOP, MENU_GROUP, MENU_BASE, "STD","Standard Menu", MenuDescription("Das ist eine Beschreibung eines Menu-Entries")},
Warum: Weil man dann in Zukunft auch im UI die Text anzeigen kann. Das wäre doch auch nett.
Was denkst Du?
73
Danilo
|
Title: Re:Manual mcHF
Post by: DB4PLE on 23. December 2016, 15:00:10
Hallo Stephan,
Zum 2. Post bezüglich der Inventarisierung aller Infos min max etc:
Das wäre ein echter Fortschritt gegenüber dem aktuellen Stand, aber ordentlich Arbeit. Das Feld überlasse ich Dir gerne.
Da kommt dann gleich noch ui_configuration ins Blickfeld, in denen ähnliche, aber nicht identische Informationsstrukturen existieren.
Manche Menu Items kontrollieren ja direkt Konfigurationsvariablen, andere eher indirekt oder mit deutlich erweiterter Logik.
Wie auch immer, hier zu konsolidieren ist eine ordentliche Aufgabe, nur zu.
Das sollte aber abgestimmt erfolgen, wenn Du zeitweise "exclusiven" Zugriff auf den Menu-Code brauchst und die anderen eher nicht neue Einträge oder Anpassungen an der Logik vornehmen sollen. Bei solch umfangreichen Projekten und der existierenden Codestruktur gibt das auch mit git ordentlich Merge-Aufwand.
Callbacks: Idealerweise sollte der Callback direkt in der Definition des Menüeintrags referenziert werden, dann entfällt der switch Irrsin. Das geht mir schon im aktuellen Code gegen den Strich, das Beibehalten war der Unzahl von Baustellen geschuldet, die in der Software existieren...
73
Danilo
|
Title: Re:Manual mcHF
Post by: DF8OE on 23. December 2016, 15:03:14
Zur Zeit werden keine build-logs abgelegt.
Ansonsten ist folgende Tatsache wichtig:
Nicht alle, die an der Firmware arbeiten, arbeiten mit Linux. Etliche arbeiten mit Windows und nutzen Eclipse - am Makefile vorbei.
Es ist auch wichtig, dass diese Arbeitsweise so bleibt, wie sie jetzt ist. Schon der Schritt weg von CooCox CoIDE hat einigen (unter anderem dem früheren "Chef-FW-Entwickler" Clint KA7OEI und auch Chris M0NKA) die Freude so verleidet, dass sie sich völlig verabschiedet haben (Clint) oder im internationalen Forum schreiben "...I am punished by using Eclipse..." (Chris). Was ein Makefile ist und was für immense Vorteile sowas und die Shell bietet ist Ihnen weder zu vermitteln noch interessiert es sie. Sie lehnen es sogar aktiv ab, sich damit zu beschäftigen (was bei Chris, so sieht es im Moment aus, sogar darin gipfelt Open Source Software auszuschließen).
So ist es in unserer Projektgruppe auf jeden Fall nicht. Trotzdem ist ein Arbeiten jenseits von Eclipse für die meisten Windows-Nutzer weder vorstell- noch machbar.
Ich bin sehr dafür, Dinge so zu ändern, dass sie die Arbeit vereinfachen. Manuals erstellen lassen, auch spezifischere Analysen des erzeugten Codes. Aber im Moment bin ich der einzige, der aus dem Programmiererteam mit dem Makefile baut (oder liege ich falsch?) und Anpassungen müssen im Vorfeld besprochen werden.
Danilo ist der aktivste der FW-Entwickler und arbeitet unter Windows. Allerdings wirst Du feststellen, dass ein Vergleich mit Clint/Chris hier galaktische Unterschiede in der Heransgehensweise aufzeigt - und dank Danilo haben wir das jetzt vorliegende Ergebnis.
Wir werden zusammen an die weiteren Umstellungen herangehen - und die Toleranz gegenüber der Vielfalt der Arbeitsmöglichkeiten groß halten.
vy 73
Andreas |
Title: Re:Manual mcHF
Post by: HB9ocq on 24. December 2016, 02:09:33
Die Identifier sind in der User-Doku nicht so hilfreich (Spalte 1+2),
|
|
aehm.. ja in Spalte 1 sollte was anderes stehen O:-,
dafür brauchen wir die Text (was hälst du von meinen Vorschlag, das direkt in der Datenstruktur reinzucode mit Hilfe eines NOP-Makros?
|
|
Du sprichst von Text, welcher noch nicht in ui_menu.c ist, richtig?
Sollte doch für dein Skript kein Problem sein, den Text zu extrahieren.
|
|
korrekt, so ein "Macro-Markup" ist kein Problem, eher fast ein Vorteil WENN feldspezifische Macros gemacht werden.
Ich bin aber nicht sicher dass dein Beispiel-Macro vollstaendig/problemlos ist...
Oder hast Du da eine bessere Idee, um hier vorwärts zu kommen. Es muss so einfach sein, das jeder potentielle Contributor in der Lage ist, das auch zu machen. Also muss es irgendetwas mit Schema F sein.
|
|
Ich habe noch nicht fertig darueber nachgedacht: "macros are evil" hallt es in meinem Kopf ;-)
Dann haben wir noch den erzeugten Markdown Code.
Leerzeichen am Anfang gehen nicht,
|
|
ACK.
auch muss die Tabelle eine Zeile Abstand zur Überschrift haben.
|
|
ACK.
Ich würde auch eher auf Überschriften als Item List setzen,
|
|
ACK.
ACK.
Neuer Anhang: |
Title: Re:Manual mcHF
Post by: DB4PLE on 24. December 2016, 12:15:03
Hallo Stephan,
Für Italics dürfen keine Leerzeichen vor dem abschliessenden ** sein.
Id wird nicht mehr gepflegt und auch nicht angezeigt, das ist nicht notwendigerweise konsistent (Doppelungen von Ids möglich)
Ich habe mal den Menu-Code etwas umstrukturiert (in Dateien aufgeteilt und in ein Unterverzeichnis verschoben), das sollte das Parsen sicherer machen, da in ui_menu_structure.c nur noch die Struktur des Menüs definiert wird.
Außerdem habe ich einen Eintrag mit UiMenuDesc("sjjsjs") versehen, damit damit Du mal erproben kannst, den Text da rauszuziehen.
Siehe mein Repo oder den Pullrequest. Dann werde ich meine Finger vom Menu-Code lassen.
73
Danilo
|
Title: Re:Manual mcHF
Post by: HB9ocq on 25. December 2016, 20:48:07
die Scripts sind in gh, Pull-Req ist ausgeloest.
Morgen ist "Boxing Day": da packen die Bediensteten ihre Geschenke aus ;-) |
Title: Re:Manual mcHF
Post by: HB9ocq on 02. January 2017, 16:09:04
ich will versuchen den Kreis zu schliessen.
Frage an Leo (TE) und Guenter DC9lw:
nuetzen euch die neuen, seit euren Anfragen von mitte Dezenber entstandenen, automatisch generierten Dokumente (Diagramm u. Tabelle zu UI-Menu) im Sinne von "Handbuch"?
Tabelle:
* <https://github.com/df8oe/mchf-github/blob/active-devel/mchf-eclipse/support/ui/menu/ui_menu_structure_mdtable.md (https://github.com/df8oe/mchf-github/blob/active-devel/mchf-eclipse/support/ui/menu/ui_menu_structure_mdtable.md)>
Diagramm:
* <https://github.com/df8oe/mchf-github/blob/active-devel/mchf-eclipse/support/ui/menu/ui_menu_structure_graph.png (https://github.com/df8oe/mchf-github/blob/active-devel/mchf-eclipse/support/ui/menu/ui_menu_structure_graph.png)>
Natuerlich ist (noch) nicht jeder Menupunkt ausfuehrlich beschrieben.
Natuerlich ist die Gestaltung Geschmacksache.
Natuerlich fehlt noch Deutsch.
Aber immerhin sind -v.A. in den letzten paar Tagen- etliche neue Beschreibungstexte hinzugekommen, im Sinne der urspruenglichen Anfrage.
Die Sache funktioniert nun automagisch sodass nach hinzufuegen/korrigieren von Menu-Beschreibungen, quasi fast gratis die neue Fassung entsteht.
Mir waere es nun wichtig eine Rueckmeldung "aus dem Handbuch lesenden Publikum" zu bekommen, ob "die Entwickler" da wieder mal "Etwas zwar technisch korrektes, aber von zweifelhaftem praktischen Nutzen" zusammengebraut haben, oder ob sich die Sache tatsaechlich in Richtung "nuetzlichen praktischen Nutzen" bewegt oder gar das Ziel wunschgemaess erreicht hat. |
Title: Re:Manual mcHF
Post by: DD4WH on 03. January 2017, 07:56:25
Hallo Stephan,
ich möchte mich für die neue automagische Menü-Dokumentations-Maschinerie herzlich bedanken!
Für mich als Programmierer ganz hervorragend und sehr motivierend, gleich beim Programmieren die Infos einzutippeln.
Ich habe zwar keine Ahnung, wie das funktioniert und wie Ihr das macht mit der Automatik, aber sehr schönes feature!
Ich denke, so bekommen wir eine sehr gute Dokumentation hin, auch ohne ein aufwendiges dickes Dokument zum mcHF zu produzieren (welches am nächsten Tag eh schon wieder veraltet wäre).
73 de Frank
|
Title: Re:Manual mcHF
Post by: HB9ocq on 03. January 2017, 16:53:22
Ich habe zwar keine Ahnung, wie das funktioniert und wie Ihr das macht mit der Automatik, aber sehr schönes feature!
|
|
hallo Frank,
Quellcode ist nicht ausschliesslich dazu da, per Programmiersprachcompiler nach Maschineninstruktionen uebersetzt zu werden.
Quellcode kann man auch mit anderen Programmen "uebersetzten"/"bearbeiten".
Hier ist es erstens so dass gluecklicherweise alles zum UI-Menu schon mal in einer einzigen Quellcodedatei als struct[..] Daten erfasst sind: ui_menu_structure.c (das vermeidet schon mal ein querbeet zusammensuchen der UI-Menu Daten) und zweitens diese Daten-Quellcode einem einzigen homogenen (Text-)Muster entsprechen.
Also habe ich ein Textmustersuchwerkzeug drauflosgelassen: das nennt sich RE = Regular Expressions (Deutsch: Regulaere Ausdruecke).
Mit dem Richtigen Ausdruck werden genau jene Zeilen angesprochen, welche die Definition der UI-Menu Eintraege in dieser mcHF-FW-Quellcodedatei ausmachen.
In Python ist die RE-Library zudem so ausgestattet, dass (variable) Teile eines REs benannt werden koennen(-> named group) und wiederum im Ergebnisobjekt (-> match object) mit genau diesen vergebenen Namen "rausgefischt" werden keonnen: das Ergebnis verhaelt sich aehnlich einem struct wo die Komponenten Namen haben.
Als Programmierer solltest Du aus meinen Kommentaren in Datei <https://docs.python.org/3/library/re.html (https://github.com/df8oe/mchf-github/blob/active-devel/mchf-eclipse/support/ui/menu/ui_menu_structure_c2py.py]https://github.com/df8oe/mchf-github/blob/active-devel/mchf-eclipse/support/ui/menu/ui_menu_structure_c2py.py[/url]> Zeilen 83..97 mithilfe der Dokumentation zu Pythons re-Modul <[url=https://docs.python.org/3/library/re.html)> etwas verstehen koennen.
Diese "rausgefischten" Textbausteine danach in anderer Ordnung zu einer (textuellen) Tabelle anzuordnen ist eine einfache Uebung mit Schleifen.
Die "Anordnung" der einzelnen Tabellenteile als Text entspricht MarkDown, jene Syntax welche auf GitHub bei Seitenabruf mittels Webbrowser direkt nach HTML (vulgo: Webseiten) umgeformt wird, ohne dass man sich mit HTML Auszeichnungsmarken (en: tags) rumschlagen muss.
<https://github.com/df8oe/mchf-github/blob/active-devel/mchf-eclipse/support/ui/menu/ui_menu_structure_mdtable.py (https://github.com/df8oe/mchf-github/blob/active-devel/mchf-eclipse/support/ui/menu/ui_menu_structure_mdtable.py)>
Wird also der build der mcHF-FW nebst per STM32-Tool-chain AUCH mit anderen Programmen "bearbeitet", entstehen nebst den binaeren Artefakten (was wir in den mcHF laden) auch andere, eben textuelle, Artefakte (Uebersichtstabellen UI-Menu).
Die Universalitaet von make, nicht nur Compiler sondern eben beliebige, auch selbstgeschriebene, projektspezifische Werkzeuge gesteuert auf (Quellcode-)Dateien loszulassen, erlaubt die Integration zu einem Ganzen. Nachdem Quellcode erweitert/korrigiert wird, baut der build daraus nicht nur neue loadfiles fuer die zu programmierende HW-Plattform, sondern auch eine neue Fassung der Dokumentation.
Verraeumt Andreas also ein neues mcHF-binary, geht im selben Aufwisch -bei Bedarf aufgrund Aenderungen- auch ein neues UI-Menu Dokument hoch in den GitHub. Voila! (hier ist also fertig mit automagisch: den "Verraeumhandgriff" macht Andreas also ohnehin, aber wegen der Doku kommen keine weitere, schon gar nicht Zeitaufwaendige, Handgriffe hinzu)
Sowas geht sicher auch in Eclipse resp. anderen GUI-IDEs, dazu sollen sich aber Kenner dieser Umgebung(en) aeussern.
- - -
Das mit den Diagrammen habe ich fuer diese Erklaerung soweit unterschlagen; der Ablauf ist aber ganz aehnlich.
Die "rausgefischten" Textbausteine werden auch hier wiederum "in anderer Ordnung" mit wenigen Schleifen ausgegeben.
Diesmal wird jedoch die Syntax der DOT-Language eingehalten, eine textuelle Beschreibung von Graphen.
* <https://de.wikipedia.org/wiki/Graph_(Graphentheorie) (https://de.wikipedia.org/wiki/Graph_(Graphentheorie))>
Ein einfach zu durchschauendes Beispiel aus der Gallerie von GraphViz:
* <http://www.graphviz.org/Gallery/undirected/process.gv.txt (http://www.graphviz.org/Gallery/undirected/process.gv.txt)>
* <http://www.graphviz.org/Gallery/undirected/process.svg (http://www.graphviz.org/Gallery/undirected/process.svg)>
Unser Graph-beschreibenden Text ist zwar nicht kompliziert (nur 3 Menu-Stufen, strikt hierarchisch = keine "ueberkreuzungen"), aber wegen ueber 200 Menupunkte einfach gross (~1000 Zeilen netto)
* <https://github.com/df8oe/mchf-github/blob/active-devel/mchf-eclipse/support/ui/menu/ui_menu_structure_graph.gv (https://github.com/df8oe/mchf-github/blob/active-devel/mchf-eclipse/support/ui/menu/ui_menu_structure_graph.gv)>
Fuer die Umsetzung des Graphentextes in die Zeichnung (SVG, PNG, usw.) ist das Programm dot, eben aus dem SW-Paket GraphViz. Ja, DAS ist die eigentliche Magie :-)
Gluecklicherweise war es bereits so in mcHF, dass wegen DoxyGen zur Generierung von Dokumentation zum Quelltext, dot bereits in Verwendung war. Ich habe da also ein Standardwerkzeug weiter eingesetzt...
|
Title: Re:Manual mcHF
Post by: HB9ocq on 24. January 2017, 18:08:25
Danke an die Texter: wie ich soeben sehe sind fuer alle Menupunkte auch Erklaerungstexte in den Tabellen zu lesen!
* <https://github.com/df8oe/mchf-github/blob/active-devel/mchf-eclipse/support/ui/menu/ui_menu_structure_mdtable.md (https://github.com/df8oe/mchf-github/blob/active-devel/mchf-eclipse/support/ui/menu/ui_menu_structure_mdtable.md)>
Ausserdem habe ich auf meine Rueckfrage (s.o.), von DC9lw folgende Antwort als PN erhalten:Hallo Stephan
zu deiner Frage: JA !!
Ich habe mir die automatische Dokumentation im WIKI angeschaut, kann nur sagen, großartige Leistung. Gratulation.
|
|
Es freut mich dass wir "die Kundschaft" innert wenigen Wochen zur Zufriedenheit "bedienen" konnten :D |
Diskussions- und Newsboard des DARC-Ortsverbandes I40 | Powered by YaBB SE
© 2001-2003, YaBB SE Dev Team. All Rights Reserved.
|