Wo Dokumentation für weitere Hardware ablegen?

[dokape]

Das Projekt wird größer und immer wieder tauchen Fragen zum Anschluss von Sensoren und Displays an. Nicht immer ist alles aktuell und an einem Ort dokumentiert.

Ich sehe da Verbesserungsbedarf. Im Meta-Wiki steht vieles, eine "Verkabelungsliste" der inzwischen zahlreichen unterstützten Sensoren wäre sinnvoll. Das könnte ich auch gerne zusammentragen. Die Frage wäre nur: Wo legt man so eine Dokumentation am besten an?

Hier im META-WIKI eine weitere Unterseite mit "Anschluss von weiterer Hardware"? https://github.com/opendata-stuttgart/meta/wiki

[pathmapper]

Ein Ort an dem alles zu Diplays und Sensoren steht, wäre praktisch. Habe gerade diverse Seiten nach Informationen zu Displays (https://github.com/opendata-stuttgart/meta/issues/73) abgesucht. Die Informationen sind derzeit ziemlich verstreut.

Ich finde den Vorschlag mit einer eigenen Seite zum Thema im META-WIKI gut. Das META-WIKI beinhaltet derzeit schon einige weitergehende Informationen. Außerdem könnte dort jeder zu dieser Seite beitragen und helfen diese aktuell zu halten.

Von anderen Stellen wie z.B. den FAQ unter http://luftdaten.info/faq/ könnte auf diesen Sammelbereich im META-WIKI verlinkt werden.

[pathmapper]

Hier findet sich jetzt Dokumentation für weitere Hardware:

https://github.com/opendata-stuttgart/sensors-software/blob/master/airrohr-firmware/Readme.md

Und airrohr-firmware.ino enthält jetzt einen Hinweis auf diese Readme.md:

https://github.com/opendata-stuttgart/sensors-software/blob/master/airrohr-firmware/airrohr-firmware.ino#L68

[dokape]

Bin mir nicht sicher, ob das in die Readme soll. Wäre es nicht im META-WIKI besser aufgehoben? Weiterhin ´wäre das über das Wiki besser, da man dort auch Bilder der Sensoren und Hardware besser verknüpfen und ablegen könnte. Das würde "Einsteigern" möglicherweise das etwas schneller näher bringen und weniger doppelte issues produzieren.

Bei der Dokumentation hat sich ein Fehler eingeschlichen: Der DS18B20 hängt am selben Anschluss D7/GPIO13 wie der DHT22. In der Doku steht aber D6 und GPIO13. Ich habe dort keine Schreibrechte. Bitte ändern. Ebenfalls sollte dann dort erwähnt werden, dass dann nur DHT22 ODER DS18B20 angeschlossen werden kann.

https://github.com/opendata-stuttgart/sensors-software/blob/master/airrohr-firmware/Readme.md#ds18b20-onewire-interface

Issue zu DS18B20 Integration: https://github.com/opendata-stuttgart/sensors-software/pull/108

[dokape]

Weiterhin ist die Beschreibung zum OLED-Display etwas irreführend. Unter dem Punkt wird auf die API und die Funktionsweise der PINS für die API eingegangen Anschluss und Typ/Anzeigewerte für das Display fehlen.

[dokape]

Fehlt ebenfalls in der Readme.md Der Anschluss vom NEO6M (seriell) an zweiten Seriellen Port des nodeMCU: RX-Pin vom NEO an D5 TX-Pin vom NEO an D6

[pathmapper]

Unabhängig davon, ob die Readme.md der geeignete Platz ist: Auch wenn man an der readme.md keine Schreibrechte hast, kann man Korrekturen/Ergänzungen mit einem Pull Request übermitteln, den jemand mit entsprechenden Rechten nur noch zu mergen braucht. Damit nimmt man auch Arbeit an der Pflege der readme.md ab

Die Informationen in der readme.md abzulegen hat gegenüber dem Meta-Wiki den Vorteil, dass hier eine Kontrolle der Änderungen stattfinden und nicht jeder frei editieren kann (falsche Informationen, Vandalismus). Das kann man natürlich auch als Nachteil sehen, insbesondere wenn auf Pull Requests nicht zeitnah reagiert werden sollte.

[dokape]

Dann wäre das Vorgehen folgendermaßen (ich habe noch keine größeren Erfahrungen mit Github) Ich editiere die readme. Beim Speichern wird meine editierte Kopie in meinem user-bereich abgelegt. Dann kann ich von dort aus einen Pull-Request schicken. Gibts noch irgendwelche Hürden?

[pathmapper]

Am Besten forkst du das repository, in dem Fall der readme.md von der wir hier sprechen: https://github.com/opendata-stuttgart/sensors-software. Der Knopf zum Forken befindet sich oben rechts. Anschließend hast du eine Kopie des Repository in deinem Github Account. Dort kannst du die readme.md bearbeiten und danach einen Pull Request an https://github.com/opendata-stuttgart/sensors-software senden. Das geht alles über die Benutzeroberfläche von Github.

Falls es irgendwo hakt, bitte melden.

Edit: Hast ja selber schon einen Weg gefunden :-)

[dokape]

Danke. Ausprobiert. Bin gespannt.

Update: klappt :-)

[dokape]

Meiner Meinung nach sollte die Dokumentation dringend überarbeitet werden.

Derzeit gibt es Dokumentation an zahlreichen Orten: z.b. die Readme, die vor allem technisch ausgerichtet ist: https://github.com/opendata-stuttgart/sensors-software/blob/master/airrohr-firmware/Readme.md

Dann gibt es den Meta-Wiki, der schon länger nicht mehr gepflegt wurde, aber durchaus wichtige Infos parat hält. https://github.com/opendata-stuttgart/meta/wiki

Auf der Luftdaten.info-Seite gibt es ebenfalls zahlreiche Infos.

Bei der Durchsicht der Issue sind mir ebenfalls einige Fragen bzgl. Dokumentation aufgefallen. Z.b. Datensatzbeschreibung. Es fehlt IMHO irgendwie ein klares Konzept für eine Dokumentation.

Hier sollte nach Skills und Verständnis der unterschiedlichen Nutzer unterschieden werden. Da sind zum einen die Menschen, die ohne größeres Verständnis für Technik einen Sensor zusammenbauen wollen und das eigentlich auch können. Für diese benötigt man eine einfache Anleitung. Das ist bereits auf der Luftdaten.info-Webseite erfolgt. @riedelwerk macht dazu auch tolle Veranstaltungen. Dann gibt es die Anwender mit Vorkenntnissen, die mehr Infos benötigen. Anschluss weiterer Sensoren, eigene Auswertungen von Daten. Hier wären vor allem technische Infos nötig: PIN-Funktionen (ist wohl derzeit in der Readme aktuell) Datenformat (dazu gibt es wohl nur rudimentäre Dokumentation) Übertragung zu weiteren Anbietern wie opensensebox mit entsprechenden Hürden (hPa/Pa für Luftdruck)

Dann natürlich eine Beschreibung der Firmware mit den zahlreichen Einstellmöglichkeiten. z.b. Konfiguration und deren Löschung, auch manuell.

Meiner Meinung nach ist das im Meta-Wiki am besten aufgehoben, auch wenn Befürchtungen bzgl. Vandalismus und ich eine zweite Instanz zur Prüfung/Verifikation nicht schlecht fände.

Irgendwelche Vorschläge?

[ricki-z]

Ich würde gern die Infos zur Hardware und zur Firmware selbst gern in der Readme lassen. Während des Entwickelns ist das einfacher und schneller aktuell zu halten. Github war zu Beginn des Projekts noch ganz gut. Mit der wachsenden Zahl an Interessenten ist aber eigentlich die Luftdaten.info der erste Anlaufpunkt.

[dokape]

Also die technische Infos in der Readme, dicht an der Entwicklung. Ist sinnvoll.

Und Infos für die "normalen Endanwender" optisch und sprachlich verständlich aufgearbeitet unter Luftdaten.info. (Sensor bauen und FAQ reichen wohl den meisten)

Dazwischen gibt es aber auch eine Reihe von "Power-Usern", die Infos irgendwo dazwischen benötigen. Sie stellen ihre Anfragen teils im META-Issue Bereich, andere stellen ihre Anfragen im Sensor-Issue Bereich. Vieles davon könnte man per Doku frühzeitig abfangen oder darauf verweisen. Bringt wertvolle Zeit für Weiterentwicklung statt einzeln zu antworten.

Sollte man dann evtl. einen weiteren Menüpunkt: "Dokumentation" auf Luftdaten.info einbauen und dort auf die Details eingehen? Basis dazu bildet die readme.md Dort könnte man auch einen Newsletter (ist das noch zeitgemäß?) anbieten oder über Facebook/twitter eine neue Software/Update mit den Änderungen ankündigen? Wie: Seit 19 Uhr wird die neue Software NRZ-2017-121 ausgeliefert. Änderungen: Support Sensor xxx, Fehlerbehebung zzz. Neue Displayinfos ...

Programmierer programmieren. Tester testen die Betas und Änderungen Tester und Andere dokumentieren und fangen Anfragen/Issues ab.

Ich denke, eine klare strukturierte und dokumentierte Vorgehensweise wird auch die Akzeptanz der Erhebung und Auswertung der Daten insbesondere in der Öffentlichkeit deutlich erhöhen.

[ricki-z]

@dokape Erst mal DANKE fürs Mithelfen bei den Issues. Bei mir reicht es inzwischen meist nur noch für kurze Antworten. Für die Power-User sollten die Infos wohl wirklich am Besten ins Meta-Wiki. Dort kann schnell geändert und ergänzt werden. Für die Dokumentation könnte dafür unterhalb der Protokolle (die mal zurecht gekürzt werden sollten) ein neuer Abschnitt eingefügt werden. Also ein neuer Block 'Dokumentation', darunter dann eine grobe Themen-Unterteilung und die entsprechenden Infos dann auf der entsprechenden Seite. Auf diese kann dann in den Issues entsprechend verwiesen werden. Die Benachrichtigung über Updates könnte über Twitter und Facebook erfolgen. Ich baue mal einen Textbaustein. Leider haben wir keinen Account, über den mehrere Leute posten können. Mal sehen, zu welchem Jan mir Zugriff gibt.

[dokape]

Doku sehe ich auch so. Sollte man das als Block oder gleich als Link zu einer eigenen (Unter) Seite Dokumentation mit Unterstrukturen/Seiten ausführen?

Update/Facebook Twitter muss ja nicht manuell sein. Kann man das per Oauth etc. Mit github/Wiki oder Blog Luftdaten verknüpfen? Sehe ich aber derzeit als niedrige prio

[dokape]

Ich hab nun den von @ricki-z angelegten Stub im Wiki etwas ausgebaut.

https://github.com/opendata-stuttgart/meta/wiki/Anschluss-weiterer-Sensoren-und-Hardware

[dokape]

FRAGE: Was sagen diese Werte aus? (aus /data.json )

{"value_type":"samples","value":"588824"}, {"value_type":"min_micro","value":"243"}, {"value_type":"max_micro","value":"27694"}

Dokumentation Datenformat: https://github.com/opendata-stuttgart/meta/wiki/Beschreibung-Datenformat

[ricki-z]

Vielleicht sollten wir zunächst ein paar der Punkte aus der 'Anleitung' in die Dokumentation verschieben. Z.B. APIs, weitere Projekte, Studien, Datenblätter, ... Dann kann der Doku-Block vielleicht auch oben unter die Anleitung.

[dokape]

Ich sehe, da ist im rechten Bereich schon ein Block Dokumentation entstanden. https://github.com/opendata-stuttgart/meta/wiki

Und einige Unterpunkte sind schon drin. Das kann man nun schrittweise ausbauen. :-)

[dokape]

Thema API, Konfigurationsseite Feinstaubsensor: Unterschied zwischen "API Luftdaten.info" (erster Punkt) und ganz unten "Weitere APIs"; InfluxxDB mit ebenfalls api.luftdaten.info als Server?

[ricki-z]

Ich werde den Default-Eintrag in einer der nächsten Versionen ändern. Aber es steht ja eigentlich weiter oben 'Ab hier nur ändern, wenn Sie wirklich wissen, was Sie tun'. Und da sollte man eigentlich wissen, was InfluxDB ist und wie das funktioniert... ;-)

[dokape]

Man lernt immer noch dazu. Und weiss dann, was man tut ;-)

[ricki-z]

Stimmt schon. Aber alles können wir wirklich nicht erklären. Sonst würden wir ja Wikipedia heißen ... Erklärungen an den Stellen, die Sinn machen. Sonst Hinweis auf andere Seiten, so wie du das bei OpenSenseMap ja auch gemacht hast. Ich gehe ja davon aus, das Power-User wissen, wie Suchmaschinen funktionieren ;-)

[dokape]

Nun weiß ich auch, was InfluxDB ist und macht. So schnell lernt man. Ein interessantes Konzept. Diese Art DB kannte ich noch nicht.

[ricki-z]

InfluxDB ist zwar schnell, hat aber auch so ein paar Einschränkungen. Und es ist ziemlich Beta. Wir müssen unsere InfluxDB täglich neu starten, weil sie sonst nach spätestens 3 Tagen stehen bleibt.

[dokape]

Gibt es bei der Anlieferung der Daten zur InfluxDB noch Infos? Sind das die selben Bezeichnungen/values wie bei der Ausgabe der data.json Werte? Zeitstempel wird keiner mitgeliefert, nehme ich an?