From e53f00ecd39a47bc0f063716a99a79043f032de2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Anian=20B=C3=BChler?= <anian.buehler@reutlingen-university.de> Date: Thu, 22 Jul 2021 15:22:48 +0000 Subject: [PATCH] Readme updated --- README.md | 134 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 121 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index acea258..dd7b8e8 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,130 @@ # didacticNetwork -Library for implementing networks on Arduino boards. -The functionalities correspond to state of the art technologies, which are didactically reduced. +Bibliothek zur Implementierung von vereinfachten Netzwerken auf Arduino-Boards. +Die Funktionalitaeten entsprechen dem Stand der Technik, die Umsetzung ist didaktisch reduziert. -## Supported so far: +## Bisher unterstuetzt: publish/subscribe network -### usage +### Beispiele -```Arduino +**Broker:** +- sPSN_Broker.ino **->** Broker Applikation (muss nicht angepasst werden) + +**Clients:** +- sPSN_Client1(2).ino **->** Client Applikationen die sich gegenseitig einen analogen bzw. digtalen Wert senden +- sPSN-ClientMinimal.ino **->** Minimal-Code für den einfachen Einstieg +- sPSN-Chat.ino **->** Chat-Applikation die Nachrichten unter eigenem Namen austauschen lässt + +## Funktionen und Parameter + +### Client +```cpp +#Anlegen der Client-Instanz didacticPSNetClient psnClient; -psnClient.begin(stream, callback); -psnClient.handleNetwork(); -psnClient.subscribe(topic); -psnClient.unsubscribe(topic); -psnClient.publish(topic); +#Starten der Client-Instanz +void psnClient.begin(Stream& sSerial, fcn callback); +//Param1: Schnittstelle (Serial | SoftSerial); param2: Callback-Funktion + +#Netzwerkverwaltung Client (Daten senden und Empfangen, Zugriffsregelung) +bool psnClient.handleNetwork(); +// return: true wenn Daten versendet / false wenn nicht + +#Topic eines anderen Clients abbonieren +int psnClient.subscribe(char* topic); +// param: Topic String/char-Array ("example" / char topic[n]) +int psnClient.subscribe(char* topic, int length); +// param1: Topic String/char-Array; param2: Anzahl Zeichen des Topics +// return ERROR-Wert: DN_ERROR_NOERROR, DN_ERROR_TOPIC_LEN (Topic zu lang - wird abgeschnitten) + +#Topic eines anderen Clients entfernen +bool psnClient.unsubscribe(char* topic); +// param: Topic String/char-Array +bool psnClient.unsubscribe(char* topic, int length); +// param1: Topic String/char-Array; Param2: Param2: Anzahl Zeichen des Topics +// return true wenn Daten versendet / false wenn nicht + +#Daten unter Topic veroeffentlichen +int psnClient.publish(char* topic,char* payload); +// param1: Topic String/char-Array; param2: payload-char-Array +int psnClient.publish(char* topic, int topicLength,char* payload, int payloadLength); +// param1: Topic String/char-Array; param2: Anzahl Zeichen des Topics, param3: payload-char-Array; param4: Anzahl Zeichen der Payload +// return: ERROR-Wert: DN_ERROR_NOERROR, DN_ERROR_TOPIC_LEN, DN_ERROR_PAYLOAD_LEN (Payload zu lange - wird abgeschnitten) + +#Callback-Funktion (wird bei neuen Daten aufgerufen) +void clientCallback(char* topic, int topicLength, char* payload, int payloadLength){...} +//param1: Topic der Nachricht, param2: Lange des Topics; param3: Nutdaten der Nachricht; param4: Laenge der +``` + +### Broker +```cpp +#Anlegen der Broker-Instanz +didacticPSNetBroker psnBroker; + +#Starten der Broker-Instanz +void psnBroker.begin(Stream& sSerial); +// param: Schnittstelle (Serial | SoftwareSerial) + +#Netzwerkverwaltung Broker (Daten senden und Empfangen, Zugriffsregelung) +bool psnBroker.handleNetwork(); +``` + +### Hilfreiche Funktionen +Wichtiger Hinweis: +Diese Funktionen koennen derzeit nur einmal pro Programm/Client-Instanz eingesetzt werden. +Werden diese an verschiedenen Stellen mit verschiedenen Werten verwendet, werden Werte u. U. ueberschrieben. + +```cpp +#Flankenerkennung z.B. fuer Taster +int psnClient.edgeDetected(bool currentState); +// param: aktueller binärer Zustand +// return: 0 -> keine Flanke, RISING, FALLING + +#Auf Wertaenderung groeßer Schwellwert pruefen +bool psnClient.valueChanged(int currentvalue, int threshold); +// param: aktueller Wert; param2: Schwellwert +// return: true -> Aenderung groeßer als Schwellwert; sonst false + +#Nicht blockierendes Warten +bool psnClient.timeElapsed(long); +// param: zu wartende Zeit in Millisekunden +// return: true, wenn Zeit Wartezeit abgelaufen; sonst false + +#Einlesen von Text ueber Serialle Schnittstelle bis Endezeichen empfangen wird +int psnClient.readSerialData(Stream&, char*, char); +// param1: Schnittstelle (Serial | SoftSerial); param2: Array in das die Zeichen eingelesen werden; param3: Endezeichen (char) +// return: Anzahl der eingelesenen Zeichen (0 wenn noch kein Endezeichen) +``` + +### Konstanten +Konstanten aus der Library die fuer die Programmierung genutzt werden und teilweise angepasst werden koennen. +```cpp +#ASCII Endezeichen +DN_ASCII_CR -> 'CR' -> (int) 13 +DN_ASCII_NL -> 'NL' -> (int) 10 + +#Laenge Topics und Payload (Client und Broker) +MAX_LEN_TOPICS default: 10 +MAX_LEN_PAYLOAD default: 20 + +#Anzahl Topics +MAX_NR_TOPICS_CLIENT default: 5 +MAX_NR_TOPICS_BROKER default: 20 + +#ERRORs +DN_ERROR_NOERROR 0 +DN_ERROR_TOPIC_LEN -1 +DN_ERROR_PAYLOAD_LEN -2 + +#Frame +MSG_PRELIMITER '<' +MSG_DELIMITER '>' +MSG_SEPARATOR '|' -didacticPSNetBroker psnBroker; -psnBroker.begin(stream, callback); -psnBroker.handleNetwork(); +#Dienste +MSG_PUBLISH '@' +MSG_SUBSCRIBE '?' +MSG_UPDATE '#' +MSG_TOPIC_MULTI '*' +``` -- GitLab