12.3. Pakettimuoto

Jokainen kameran ja isännän välillä siirtoyhteyden ylittävä tavu on osa pakettia. Paketti alkaa 10 tavun otsikolla, jatkuu vaihtuvanmittaisella payloadilla ja päättyy 4 tavun lopussa olevaan CRC:hen. Muita tavuja ei esiinny siirtoyhteydessä – kun isäntä on nähnyt 2 tavun synkronointisanan, seuraavat tavut ovat otsikko tässä täsmällisessä järjestyksessä.

12.3.1. Otsikko

Kymmenen tavua, pakattu ilman täytettä. Kukin kenttä:

• sync – 16-bittinen sana 0xD5AA little-endian-järjestyksessä. Tavu 0 siirtoyhteydessä on 0xAA, tavu 1 on 0xD5. Tavuja skannaava vastaanottaja voi löytää paketin alun etsimällä paria AA D5; kaikkea sitä edeltävää käsitellään roskana. Arvon valinta on tarkoituksellinen: 0xAA ja 0xD5 esiintyvät harvoin tulostettavassa tekstissä, ja pari esiintyy epätodennäköisesti vahingossa keskellä payloadia.

• seq – yksi tavu. Laskuri, joka kasvaa yhdellä jokaista tiettyyn suuntaan lähetettyä pakettia kohti. Vastaanottaja tarkistaa, että seuraavan paketin sekvenssinumero on odotettu; jos ei, luotettavuuskerros pyytää uudelleenlähetystä.

• chan – yksi tavu. Kanavan ID, johon tämä paketti kuuluu. Kanavat 0..31 ovat käytettävissä; sisäänrakennetut stdin-, stdout-, stream- ja (valinnaisesti) profile-kanavat ottavat kiinteät ID:t, jotka kamera varaa.

• flags – yksi tavu. Bittikenttä, joka kertoo vastaanottajalle, miten paketti tulkitaan:

  • bitti 0 ACK – tämä paketti on edellisen kuittaus.

  • bitti 1 NAK – tämä paketti hylkää edellisen.

  • bitti 2 RTX – tämä paketti on uudelleenlähetys.

  • bitti 3 ACK_REQ – lähettäjä haluaa tämän paketin kuitattavan.

  • bitti 4 FRAGMENT – tätä seuraa lisää fragmentteja suuremmassa viestissä.

  • bitti 5 EVENT – tämä paketti kuljettaa kanavatapahtumaa datan sijaan.

  • bitit 6 ja 7 on varattu.

• opcode – yksi tavu. Käsky- tai vastauskoodi. Protokollakirjasto varaa käskykoodialueet käyttötarkoituksen mukaan:

  • 0x00..0x0F – protokollakäskyt (SYNC, GET_CAPS, SET_CAPS, STATS, VERSION).

  • 0x10..0x1F – järjestelmäkäskyt (RESET, BOOT, INFO, EVENT, MEMORY).

  • 0x20..0x2F – kanavakäskyt (LIST, POLL, LOCK, UNLOCK, SHAPE, SIZE, READ, WRITE, IOCTL, EVENT).

• len – kaksi tavua, little-endian. Otsikkoa seuraavien payload-tavujen määrä. Nollapituus on sallittu – monet kuittaukset ja pienet käskyt eivät kuljeta payloadia.

• crc – kaksi tavua. CRC-16 edellisten kahdeksan otsikkotavun yli. Vastaanottaja, joka saa otsikon, jolla on virheellinen CRC, pudottaa koko paketin edes katsomatta payloadia.

12.3.2. Payload

Nolla tai useampi tavu, joita kehystyskerros käsittelee läpinäkymättöminä. Payloadin sisältö riippuu käskykoodista: CHANNEL_READ-vastauksessa se on varsinainen kanavadata; GET_CAPS-vastauksessa se on pieni kiinteä rakenne; kanavakirjoituksessa se on mitä tahansa isäntä lähetti.

Suurin payload-koko riippuu kameran protokollapuskurin koosta (katso korttikohtainen taulukko funktiossa protocol.init()). Ylärajaa pidemmät viestit jaetaan fragmentteihin, joissa FRAGMENT-lippu on asetettu kaikkiin paitsi viimeiseen.

12.3.3. Lopussa oleva CRC

Neljä tavua, CRC-32 payloadin yli. Havaitsee vioittumiset, joita otsikon CRC ei voi nähdä, erityisesti pitkissä payloadeissa, joissa yksittäisen bitin virhe kehyksen keskellä muuten livahtaisi läpi.

Eheystarkistuksen jakaminen kahteen CRC:hen on tarkoituksellista. Otsikon CRC suojaa itse kehystyskenttiä – erityisesti payloadin pituutta. Ilman erillistä otsikon CRC:tä yksittäisen bitin kääntyminen pituustavussa saisi vastaanottajan lukemaan väärän määrän tavuja payloadille ja ajautumaan kokonaan pois synkronista tavuvirran kanssa; sellaisen kanssa vioittunut otsikko hylätään suoralta kädeltä ja vastaanottaja skannaa uudelleen seuraavaa synkronointisanaa. Payloadin CRC suojaa sitten viestin runkoa erillisenä asiana, joten datan bitin kääntyminen raportoidaan vioittuneena payloadina eikä erehdytä kehystysvirheeksi.

Muoto on tarpeeksi pieni käytäväksi läpi tavu tavulta, ja se, että jokaisella paketilla on sama asettelu – synkronointisana, sitten otsikko, sitten payload, sitten CRC – tarkoittaa, että käsin koodattu jäsennin mahtuu yhteen näyttötilan verran koodia. Siksi pieni isäntätoteutus C:llä, Pythonilla tai Rustilla on viikonloppuprojekti; protokollakirjasto on ylläpidetty Python-versio kummallakin puolella.