One Wire Buszugriff

Ausführliche Beschreibung

#include <avrhal/ow.h> 

Diese Headerdatei deklariert einen einfachen Low-Level Zugang zum Eindrahtkommunikationssystem One Wire von Dallas. Mit dessen Hilfe können daran angeschlossene Sensoren, Speicher oder sonstige I/O-Bausteine angesprochen werden. Der One Wire Bus ist an PORTD Bit 4 angeschlossen. Zur Zeit sind folgende One Wire Geräte über ein eigenes API ansprechbar:

• Temperatursensor DS1820/DS1822

Für die Erstellung dieses Codes wurden folgende Referenzen benutzt: [1], [2], [3],

Zu beachten:

[1] Dallas Semiconductor Application Note 159 "Ultra-Reliable 1-Wire Communications"

[2] Dallas Semiconductor Application Note 187 "1-Wire Search Algorithm"

[3] Dallas Semiconductor Application Note 126 "1-Wire Communications Through Software"

Noch zu erledigen:

Überführung von Teilen der Initialisierung nach Sektion .init1

Integration einer One Wire ALARM Ereignisbehandlung.

Code-Optimierung bei Eingerätebenutzung (Wegfall der Umfangreichen ROM Code Suche, Wrapper Macros).

Dokumentation der benutzerdefinerten Typen

ow_device_st

Typvereinbarung für einen One Wire Geräteeintrag. Siehe auch: ow_device_s

ow_rom_code_st

Typvereinbarung für einen One Wire ROM Code. Siehe auch: ow_rom_code_s

Dokumentation der Funktionen

unsigned char ow_buf_read (  unsigned char *    buf, size_t    buf_size, unsigned char    crc_included )

Bytes vom One Wire Bus in einen Puffer lesen. Mit dieser Funktion können unter Zuhilfenahme von ow_byte_read() so viele Bytes hintereinander vom One Wire Bus in den über buf referenzierten Puffer gelesen werden, wie über buf_size angegeben sind. Auf Wunsch erfolgt zusätzlich mit crc8_ow() ein Test der im letzten Byte enthaltenen CRC Summe, wenn crc_included ungleich Null ist. Das jeweilige One Wire Gerät, von dem gelesen werden soll, muß zuvor durch andere Funktionen entsprechend vorbereitet werden (z.B. mit ow_function()). Parameter: buf  Zeiger auf den Anfang des Puffers. buf_size  Anzahl der Bytes im Puffer (Größe). crc_included  Anzeige über enthaltene CRC Summe. Rückgabe: Die Funktion ow_buf_read() gibt bei fehlerhafter Übertragung eine Null(0) Zurück. Ansonsten wird eine Eins(1) zurückgegeben.

unsigned char ow_buf_write (  unsigned char *    buf, size_t    buf_size, unsigned char    crc_included )

Bytes aus einem Puffer zum One Wire Bus schreiben. Mit dieser Funktion können unter Zuhilfenahme von ow_byte_write() so viele Bytes hintereinander aus den über buf referenzierten Puffer zum One Wire Bus geschrieben werden, wie über buf_size angegeben sind. Auf Wunsch erfolgt zusätzlich mit crc8_ow() die Berechnung einer CRC Summe im letzten Byte des Puffers, wenn crc_included ungleich Null ist. Das jeweilige One Wire Gerät, in das geschrieben werden soll, muß zuvor durch andere Funktionen entsprechend vorbereitet werden (z.B. mit ow_function()). Warnung: Soll die Berechnung der CRC Summe innerhalb dieser Funktion erfolgen, dann darf das letzte Byte im Puffer keine relevanten Nutzdaten enthalten. Das letzte Byte buf[(buf_size-1)] wird mit der CRC Summe über die vorgelagerten Bytes buf[0..(buf_size-2)] überschrieben! Parameter: buf  Zeiger auf den Anfang des Puffers. buf_size  Anzahl der Bytes im Puffer (Größe). crc_included  Anzeige über enthaltene CRC Summe. Rückgabe: Die Funktion ow_buf_read() gibt bei fehlerhafter Übertragung eine Null(0) zurück. Ansonsten wird eine Eins(1) zurückgegeben.

unsigned char ow_byte_read (  void    )

Lesen eines Bytes vom One Wire Bus. Mit dieser Funktion wird die Signalfolge zum Lesen von genau einem Byte vom One Wire Bus ausgelöst. Das jeweilige One Wire Gerät, von dem gelesen werden soll, muß zuvor durch andere Funktionen entsprechend vorbereitet werden (z.B. mit ow_function()). Rückgabe: Die Funktion ow_byte_read() gibt das vom Bus gelesene Byte zurück.

unsigned char ow_byte_write (  unsigned char    byte )

Schreiben eines Bytes zum One Wire Bus. Mit dieser Funktion wird die Signalfolge zum Schreiben von genau einem Byte am One Wire Bus ausgelöst. Das zu schreibende Byte wird mit byte übergeben. Das jeweilige One Wire Gerät, in das geschrieben werden soll, muß zuvor durch andere Funktionen entsprechend vorbereitet werden (z.B. mit ow_function()). Parameter: byte  zu schreibendes Byte. Rückgabe: Die Funktion ow_byte_write() gibt immer eine Eins(1) zurück, da der Erfolg oder Mißerfolg einer Byteübertragung am One Wire Bus nicht direkt kontrolliert werden kann.

unsigned char ow_function (  unsigned char    code, unsigned char    device )

Bytes aus einem Puffer zum One Wire Bus schreiben. Mit dieser Funktion wird unter Zuhilfenahme von ow_byte_write() und ow_buf_write() ein neues Gerätekommando code an das über device referenzierte One Wire Gerät initiert. Hierbei stellt device einen Index in dem der Funktion ow_rom_search() übergebenen Feld vom Typ ow_device_st dar und zeigt so ein bestimmtes Gerät am Bus an. Parameter: code  One Wire Gerätekommando device  Referenz auf das zu benutzende One Wire Gerät Rückgabe: Die Funktion ow_function() gibt bei fehlerhafter Übertragung eine Null(0) zurück. Ansonsten wird eine Eins(1) zurückgegeben.

unsigned char ow_init (  void    )

(Re-)Initialisirung des One Wire Moduls. Mit Aufruf dieser Funktion wird der One Wire Bus durch ein entsprechendes Busreset initialisiert und die interne Geräteverwaltung zurückgesetzt. Rückgabe: Die Funktion ow_init() gibt eine Null(0) zurück, wenn keines der angeschlossenen One Wire Geräte das Busreset beantwortet. Ansonsten wird eine Eins(1) zurückgegeben.

unsigned char ow_ready (  void    )

Primitiver Bereitschaftstest. Mit dieser Funktion kann die Bereitschaft eines One Wire Gerätes nach Ausführung eines vorher abgesetzten Kommandos durch einen einfachen Bitlesezyklus getestet werden. Viele One Wire Geräte zeigen so die Beendigung einer Aktion an, so z.B. die einmalige Temperaturmessung im Sensor DS1820. Zum Schutz gegen endloses Warten aufgrund fehlerhafter One Wire Geräte oder Störungen beim Lesen eines Bits vom Bus, ist der Testzyklus mit einer Zeitschleife von 1 Sekunde versehen. Nach erfolglosem Test über diese Zeit hinaus wird automatisch abgebrochen! Rückgabe: Die Funktion ow_ready() gibt eine Null(0) zurück, wenn vom One Wire Gerät innerhalb der Zeitschleife von 1 Sekunde keine Bereitschaft angezeigt wurde. Ansonsten wird ein Wert ungleich Null(!=0) für einen erfolgreichen Bereitschaftstest zurückgegeben.

unsigned char ow_rom_search (  ow_device_st *    ow_dev )

One Wire ROM Code Ermittlung. Mit dieser Funktion wird der One Wire Bus so wie in [2] beschrieben nach Geräten durchsucht, wobei deren ROM Codes ermittelt und in einem Feld vom Typ ow_device_st hinterlegt werden. Der für dieses Feld notwendige Speicher wird nicht von der Bibliothek bereitgestellt, sondern muß vom Benutzer über den Zeiger ow_dev referenziert werden. Warnung: Für die interne Geräteverwaltung wird das über ow_dev referenziert Feld durch die Bibliothek weiter benutzt; auch über die Arbeit von ow_rom_search() hinaus. Sollte sich also die Größe dieses Feldes, welche immer in direktem Bezug zu der Anzahl physisch vorhandener One Wire Geräte steht, verändern, so muß eine Reinitialisierung mittels ow_init() und ow_rom_search() erfolgen. Parameter: ow_dev  Zeiger auf ein Feld für die interne Geräteverwaltung. Rückgabe: Die Funktion ow_rom_search() gibt eine Null(0) zurück, wenn kein One Wire Gerät gefunden wurde. Ansonsten wird die Anzahl der gefundenen One Wire Geräte zurückgegeben. Diese muß der Größe des durch ow_dev referenzierten Feldes entsprechen.

unsigned char w1_crc8 (  void *    p, unsigned char    n )  [inline, static]

CodeVision API Aliasfunktion für crc8_ow(). Ermittelt die im Dallas One Wire Bus verwendete 8 Bit CRC Summe für den über den Zeiger referenzierten Block der angegebenen Länge. Parameter: p  zeigt auf den Block. n  Größe des Blocks in Byte. Rückgabe: Die Funktion w1_crc8() besitzt den Rückgabewert von crc8_ow().

unsigned char w1_init (  void    )  [inline, static]

CodeVision API Aliasfunktion für ow_init(). Initialisiert die One Wire Geräte am Bus. Rückgabe: Die Funktion w1_init() besitzt den Rückgabewert von ow_init().

unsigned char w1_read (  void    )  [inline, static]

CodeVision API Aliasfunktion für ow_byte_read(). Liest ein Byte vom One Wire Bus. Rückgabe: Die Funktion w1_read() besitzt den Rückgabewert von ow_byte_read().

unsigned char w1_write (  unsigned char    data )  [inline, static]

CodeVision API Aliasfunktion für ow_byte_write(). Schreibt ein Byte zum One Wire Bus. Parameter: data  zu schreibendes Byte. Rückgabe: Die Funktion w1_write() besitzt den Rückgabewert von ow_byte_write().