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.

A paranccsal az I²C funkció inicializálható a SETUP blokkban.

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.

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.

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.

  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

Az átvitel megkezdése az adott slave-en. A parancsot a Wire.write()-nak, majd az endTransmission()-nak kell követnie.

Wire.beginTransmission(address)

address (byte): 7 bites slave címe, ahová az adatokat kell továbbítani (0..127)

Az átvitel lezárása az adott slave-en. A parancsot a Wire.write()-nak, és az endTransmission()-nak kell megelőznie.

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

A paranccsal adatok küldhetők az I²C-n keresztül.

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.

// 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);
}

A paranccsal a pufferben beolvasásra váró bájtok száma érhető el.

Wire.available()

A függvénynek paramétere nincs, visszatérési értéke a beolvasásra váró bájtok száma.

A paranccsal egy bájt olvasható a pufferből.

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.

// 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);
}

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.

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.

A regisztálható funkció akkor kerül felhívásra, ha a slave egység forgalmazást vár a master-től.

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.

// 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
}

A regisztálható funkció akkor kerül felhívásra, ha a master egység forgalmazást vár a slave-től.

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.