WIRE library funkciók
A Wire könyvtárral valósítható meg legegyszerűbben az I²C és TWI kommunikáció az Arduino kártyákkal. A kommunikáció az I²C esetében minden esetben master-slave jellegű, de ez nem zárja ki az oda-vissza kommunikációt sem. Sőt, az Arduino-k között is alkalmazható a (kétirányú) I²C.
A standard I²C egyaránt alkalmazhat 7 és 8 bites címzést. A Wire könyvtár 7 bites címzést használ. Ezen felül a könyvtár 32 bájt hosszú puffert használ, azaz ennél nagyobb méretű telegrammokat nem tud továbbítani (az efölötti részt egyszerűen levágja).
A könytár a Wire.h néven hívható fel, az alapból telepített IDE tartalmazza:
#include <Wire.h>
Külön problémát jelenthet, hogy az I²C bájtos átvitelt alkalmaz, ehhez sok mindent, például a float típusú méréseredményeket vég nélkül konvertálgatni kell. Erre ad pár megoldást az avr_libc standard könyvtár. Konkrétan a fenti példára például itt talál megoldást.
Wire.begin()
Szintaktika
Wire.begin()
Wire.begin(address)
address (byte): 7 bites slave cím (0..127)
A címet a slave-nél kell megadni. Ha nincs cím-megadás, akkor a master-t definiáltuk.
Wire.requestFrom()
A masteren alkalmazható parancs egy slave eszköztől kér adott mennyiségű információt. Mindaddig, amíg a kérés nem teljesül, a master blokkolja az I²C forgalmát, azaz prioritással várja az adott mennyiségű információt a slave-től.
Szintaktika
Wire.requestFrom(address, quantity)
Wire.requestFrom(address, quantity, stop)
address (byte): 7 bites slave címe, ahonnan az adatokat várja (0..127)
quantity (byte): a várt adathossz bájtban
stop (bool): true: a kérés után felszabadítja az I²C-t, false: folyamatosan újraküldési parancsot ad ki a slave felé, ezáltal blokkolja az I²C-t
Default: TRUE.
A függvény visszatérési értéke bájt, megadja, hogy hány bájt érkezett a slave felől.Olvasása opcionális.
Példa
Wire.beginTransmission(address); Wire.write(0x5); // starting with register 0x5 Wire.endTransmission(false); Wire.requestFrom(address,3,true); // request a total of 3 registers value1 = Wire.read(); //register 0x5 value2 = Wire.read(); //register 0x6 value3 = Wire.read(); //register 0x7
Wire.beginTransmission()
Az átvitel megkezdése az adott slave-en. A parancsot a Wire.write()-nak, majd az endTransmission()-nak kell követnie.
Szintaktika
Wire.beginTransmission(address)
address (byte): 7 bites slave címe, ahová az adatokat kell továbbítani (0..127)
Wire.endTransmission()
Az átvitel lezárása az adott slave-en. A parancsot a Wire.write()-nak, és az endTransmission()-nak kell megelőznie.
Szintaktika
Wire.endTransmission()
Wire.endTransmission(stop)
stop (bool): true: „stop” parancsot küld, felszabadítja az I²C-t, false: folyamatosan újraküldési parancsot ad ki a slave felé, ezáltal blokkolja az I²C-t
Default: TRUE.
A függvény visszatérési értéke bájt: Olvasása opcionális.
- 0 : végrehajtva
- 1 : az adat túl nagy a pufferhez képest (> 32 byte)
- 2 : a cím nem érvényes / nem található
- 3 : az adat nem továbbítható (nem fogadja a címzett egység)
- 4 : egyéb probléma
Wire.write()
Szintaktika
Wire.write(value)
Wire.write(string)
Wire.write(data, length)
value (byte): egy bájt küldése
string (byte): egy sorozat bájt küldése (kisbetűs string!)
data (byte): egy bájt-tömb küldése
length (byte): a bájtok száma (maximum 32 fér a pufferbe, a többit levágja)
A függvény visszatérési értéke bájt, az átvitt bájtok számát adja meg. Olvasása opcionális.
Példa
// OB121.com példaprogram magyarul #include <Wire.h> byte val = 0; void setup() { Wire.begin(); // az i2c felhívása } void loop() { Wire.beginTransmission(44); // a #44 című egység felé forgalmazás (0x2c) Wire.write(val); // egy bájt küldése Wire.endTransmission(); // átvitel leállítása val++; // érték növelése if(val == 64) // 64-nél.. { val = 0; // ..vissza 0-ra } delay(500); }
Wire.available()
Szintaktika
Wire.available()
A függvénynek paramétere nincs, visszatérési értéke a beolvasásra váró bájtok száma.
Wire.read()
Szintaktika
Wire.read()
A függvénynek paramétere nincs, visszatérési értéke a következő bájt (azaz mindig csak egy bájt) a pufferből. Az ott található adatmennyiséget a requestFrom()-mal lehet lekérdezni. A függvény a Steam alkalmazási osztályt hívja fel.
Példa
// OB121.com példaprogram magyarul #include <Wire.h> void setup() { Wire.begin(); // i2c start Serial.begin(9600); // soros monitor bekapcsolása } void loop() { Wire.requestFrom(2, 6); // 6 bájtot vár a #2 című slave-től while(Wire.available()) // lehet, hogy a slave kevesebbet küldött { char c = Wire.read(); // a bájtnyi információ beolvasása char-ként Serial.print(c); // az egy karakter kiírása a soros monitorra } delay(500); }
Wire.SetClock()
A funkció módosítja az I²C kommunikáció órajelét. Az I²C slave-eknek nincs minimum sebességhatáruk, de jellemzően az I²C egységek 100KHz-en kommunikálnak.
Szintaktika
Wire.setClock(clockFrequency)
clockFrequency (long): a kommunikáció frekvenciája:
Az elfogadott értékek:
- 100000 (standard mode)
- 400000 (fast mode)
Néhány processzor kezeli az alábbi értékeket is:
- 10000 (low speed mode)
- 1000000 (fast mode plus)
- 3400000 (high speed mode)
Tájékozódjon a technikai leírásokból, hogy az adott egységek mely sebességeket preferálják.
A függvénynek visszatérési értéke nincs.
Wire.onReceive()
Szintaktika
Wire.onReceive(handler)
handler A paraméter a slave által várt bájtok számát adja meg. A funkciót függvényként kell felhívni: void myHandler(int numBytes).
A funkciónak visszatérési értéke nincs.
Példa
// OB121.com példaprogram magyarul #include <Wire.h> void setup() { Wire.begin(8); // bejelentkezik a i2c-re a 8-as címmel Wire.onReceive(receiveEvent); // a funkció regisztrálása Serial.begin(9600); // soros monitor inicializálása } void loop() { // a loop maradhat ezesetben üresen, delay(100); // némi késleltetéssel } // a regisztrálás után a funkció önálló függvényként érhető el: void receiveEvent(int howMany) { while (1 < Wire.available()) { // amíg van a pufferben valami char c = Wire.read(); // egy bájt beolvasása char-ként Serial.print(c); // kiírás a soros monitorra } int x = Wire.read(); // a megkapott bájtok száma Serial.println(x); // kiírás a soros monitorra }
Wire.onRequest()
Szintaktika
Wire.onRequest(handler)
handler A funkciót függvényként kell felhívni: void myHandler(). A hívásnak paramétere nincs.
A funkciónak visszatérési értéke nincs.