class CAN – controller area network -tietoliikenneväylä¶

CAN tukee sekä klassista CAN-väylää (bxCAN, käytössä OpenMV Cam M4:ssä ja M7:ssä) että CAN FD -väylää (FDCAN, käytössä OpenMV Cam H7:ssä, H7 Plussassa ja Pure Thermalissa). Fyysisellä tasolla CAN-väylä koostuu kahdesta linjasta, RX ja TX. Kytkeäksesi OpenMV Camin CAN-väylään sinun on käytettävä CAN-lähetinvastaanotinta, joka muuntaa CAN-logiikkasignaalit mikro-ohjaimesta väylän oikeille jännitetasoille.

Klassinen CAN takaisinkytkentä- eli loopback-tilassa (ilman lähetinvastaanotinta):

from pyb import CAN

can = CAN(1, CAN.LOOPBACK)

# Accept messages with id 123, 124, 125 or 126.
can.setfilter(0, CAN.LIST16, 0, (123, 124, 125, 126))

can.send("message!", 123)   # send a message with id 123
can.recv(0)                 # receive a message on FIFO 0

CAN FD kaikilla valinnaisilla ominaisuuksilla käytössä (FD-kehys, siirtonopeuden vaihto, laajennetut kehystunnisteet; 500 kbit/s arbitraatiovaihe, 1 Mbit/s datavaihe):

from pyb import CAN

can = CAN(
    1,
    CAN.NORMAL,
    baudrate=500_000,
    brs_baudrate=1_000_000,
    sample_point=80,
)

# Accept any id in the range 0xFFF0 .. 0xFFFF.
can.setfilter(0, CAN.RANGE, 0, (0xFFF0, 0xFFFF))

can.send(b"a" * 64, 0xFFFF, fdf=True, brs=True, extframe=True)
can.recv(0)

Seuraavat CAN-moduulin funktiot ja niiden argumentit ovat käytettävissä sekä klassisilla että FD CAN -ohjaimilla, ellei toisin mainita.

Konstruktorit¶

class pyb.CAN(bus: int | str, *args, **kwargs)¶

Luo CAN-objektin annetulle väylälle bus (kokonaislukuna ilmaistu oheislaiteindeksi, esim. 1 väylälle CAN1 ja 2 väylälle CAN2). Ilman lisäparametreja objekti luodaan, mutta sitä ei alusteta (se säilyttää aiemmat väyläasetukset, jos sellaisia on); jos lisäargumentteja annetaan, väylä alustetaan. Katso käytettävissä olevat parametrit kohdasta CAN.init().

CAN(2) on kytketty samoihin liitinnastoihin jokaisessa OpenMV Camissa, joka tarjoaa pyb.CAN-rajapinnan (M4 / M7 / H7 / H7 Plus / Pure Thermal):

Signaali	Liitinnasta	Huomautukset
`RX`	`P3`
`TX`	`P2`

CAN-oheislaite tuottaa vain logiikkatason signaaleja; oikean CAN-väylän ohjaamiseen tarvitaan ulkoinen CAN-lähetinvastaanotin.

pyb.CAN ei ole käytettävissä OpenMV Cam N6:ssa.

Metodit¶

init(mode: int, prescaler: int = 100, *, sjw: int = 1, bs1: int = 6, bs2: int = 8, auto_restart: bool = False, baudrate: int = 0, sample_point: int = 75, num_filter_banks: int = 14, brs_sjw: int = 1, brs_bs1: int = 8, brs_bs2: int = 3, brs_baudrate: int = 0, brs_sample_point: int = 75) → None¶

Alusta CAN-väylä annetuilla parametreilla:

mode on yksi seuraavista: NORMAL, LOOPBACK, SILENT, SILENT_LOOPBACK

prescaler on arvo, jolla CAN-tulokello jaetaan nominaalisen bittiajan kvanttien tuottamiseksi. Esijakaja voi olla arvo väliltä 1–1024 (rajat mukaan lukien) klassisessa CAN:issa ja väliltä 1–512 (rajat mukaan lukien) CAN FD:ssä.

sjw on uudelleensynkronoinnin hyppyleveys aikakvantteina nominaalibiteille; se voi olla arvo väliltä 1–4 (rajat mukaan lukien) klassisessa CAN:issa ja väliltä 1–128 (rajat mukaan lukien) CAN FD:ssä.

bs1 määrittää näytteenottopisteen sijainnin aikakvantteina nominaalibiteille; se voi olla arvo väliltä 1–16 (rajat mukaan lukien) klassisessa CAN:issa ja väliltä 2–256 (rajat mukaan lukien) CAN FD:ssä.

bs2 määrittää lähetyspisteen sijainnin aikakvantteina nominaalibiteille; se voi olla arvo väliltä 1–8 (rajat mukaan lukien) klassisessa CAN:issa ja väliltä 2–128 (rajat mukaan lukien) CAN FD:ssä.

auto_restart määrittää, yrittääkö ohjain automaattisesti käynnistää tietoliikenteen uudelleen bus-off-tilaan siirtymisen jälkeen; jos tämä on poistettu käytöstä, voidaan restart()-metodilla poistua bus-off-tilasta

baudrate jos annetaan muu siirtonopeus kuin 0, tämä funktio yrittää automaattisesti laskea CAN:in nominaalisen bittiajan (ohittaen parametrit prescaler, bs1 ja bs2), joka täyttää sekä baudrate-arvon (0,1 %:n tarkkuudella) että halutun sample_point-arvon (lähimpään 1 %:iin). Tarkempaa CAN-ajoituksen hallintaa varten aseta parametrit prescaler, bs1 ja bs2 suoraan.

sample_point määrittää bittinäytteen sijainnin suhteessa koko nominaaliseen bittiaikaan, ilmaistuna kokonaislukuprosenttina nominaalisesta bittiajasta. Oletusarvo sample_point-arvolle on 75 %. Tämä parametri jätetään huomiotta, ellei baudrate-arvoa ole asetettu.

num_filter_banks klassisessa CAN:issa tämä on niiden pankkien määrä, jotka osoitetaan CAN(1):lle; loput 28:sta osoitetaan CAN(2):lle.

Loput parametreista ovat käytettävissä vain korteissa, jotka tukevat CAN FD:tä, ja ne määrittävät valinnaisen CAN FD:n siirtonopeuden vaihdon (BRS, Bit Rate Switch) ominaisuuden:

brs_prescaler on arvo, jolla CAN FD -tulokello jaetaan databittiajan kvanttien tuottamiseksi. Esijakaja voi olla arvo väliltä 1–32 (rajat mukaan lukien).

brs_sjw on uudelleensynkronoinnin hyppyleveys aikakvantteina databiteille; se voi olla arvo väliltä 1–16 (rajat mukaan lukien)

brs_bs1 määrittää näytteenottopisteen sijainnin aikakvantteina databiteille; se voi olla arvo väliltä 1–32 (rajat mukaan lukien)

brs_bs2 määrittää lähetyspisteen sijainnin aikakvantteina databiteille; se voi olla arvo väliltä 1–16 (rajat mukaan lukien)

brs_baudrate jos annetaan muu siirtonopeus kuin 0, tämä funktio yrittää automaattisesti laskea CAN:in databittiajan (ohittaen parametrit brs_prescaler, brs_bs1 ja brs_bs2), joka täyttää sekä brs_baudrate-arvon (0,1 %:n tarkkuudella) että halutun brs_sample_point-arvon (lähimpään 1 %:iin). Tarkempaa BRS-ajoituksen hallintaa varten aseta parametrit brs_prescaler, brs_bs1 ja brs_bs2 suoraan.

brs_sample_point määrittää bittinäytteen sijainnin suhteessa koko nominaaliseen bittiaikaan, ilmaistuna kokonaislukuprosenttina nominaalisesta bittiajasta. Oletusarvo brs_sample_point-arvolle on 75 %. Tämä parametri jätetään huomiotta, ellei brs_baudrate-arvoa ole asetettu.

Aikakvantti tq on CAN-väylän perusaikayksikkö. tq on CAN-esijakajan arvo jaettuna PCLK1:llä (sisäisen oheislaiteväylän 1 taajuus); katso pyb.freq() PCLK1:n määrittämiseksi.

Yksittäinen bitti koostuu synkronointisegmentistä, joka on aina 1 tq. Sitä seuraa bittisegmentti 1, sitten bittisegmentti 2. Näytteenottopiste on bittisegmentin 1 päättymisen jälkeen. Lähetyspiste on bittisegmentin 2 päättymisen jälkeen. Siirtonopeus on 1/bittiaika, jossa bittiaika on 1 + BS1 + BS2 kerrottuna aikakvantilla tq.

Esimerkiksi OpenMV Cam H7:ssä (PCLK1 = 100 MHz) 250 kbps:n CAN 75 %:n näytteenottopisteellä voidaan määrittää näin prescaler=25, sjw=1, bs1=11, bs2=4: tq = 25 / 100 MHz = 250 ns, bittime = (1 + 11 + 4) × 250 ns = 4 µs, näytteenottopiste = (1 + 11) / 16 = 75% ja siirtonopeus on 1 / 4 µs = 250 kHz.

Katso lisätietoja OpenMV Camin mikro-ohjaimen STM32-viiteoppaan bxCAN/FDCAN-osiosta.

deinit() → None¶: Sammuta CAN-väylä.

restart() → None¶

Pakota CAN-ohjaimen ohjelmistollinen uudelleenkäynnistys nollaamatta sen asetuksia.

Jos ohjain siirtyy bus-off-tilaan, se ei enää osallistu väylätoimintaan. Jos ohjainta ei ole määritetty käynnistymään uudelleen automaattisesti (katso init()), tällä metodilla voidaan käynnistää uudelleenkäynnistys, jolloin ohjain noudattaa CAN-protokollaa poistuakseen bus-off-tilasta ja siirtyäkseen error active -tilaan.

state() → int¶

Palauta ohjaimen tila. Paluuarvo voi olla yksi seuraavista:

CAN.STOPPED – ohjain on täysin pois päältä ja nollattu;
CAN.ERROR_ACTIVE – ohjain on päällä ja Error Active -tilassa (sekä TEC että REC ovat alle 96);
CAN.ERROR_WARNING – ohjain on päällä ja Error Warning -tilassa (vähintään toinen TEC:istä tai REC:istä on 96 tai suurempi);
CAN.ERROR_PASSIVE – ohjain on päällä ja Error Passive -tilassa (vähintään toinen TEC:istä tai REC:istä on 128 tai suurempi);
CAN.BUS_OFF – ohjain on päällä mutta ei osallistu väylätoimintaan (TEC ylivuoti yli 255:n).

info(list: list | None = None) → list¶

Hae tietoja ohjaimen virhetiloista sekä TX- ja RX-puskureista. Jos list annetaan, sen tulee olla listaobjekti, jossa on vähintään 8 alkiota, ja siihen täytetään tiedot. Muutoin luodaan uusi lista ja täytetään se. Molemmissa tapauksissa metodin paluuarvo on täytetty lista.

Listan arvot ovat:

TEC-arvo
REC-arvo
kuinka monta kertaa ohjain siirtyi Error Warning -tilaan (palautuu nollaan 65535:n jälkeen)
kuinka monta kertaa ohjain siirtyi Error Passive -tilaan (palautuu nollaan 65535:n jälkeen)
kuinka monta kertaa ohjain siirtyi Bus Off -tilaan (palautuu nollaan 65535:n jälkeen)
odottavien TX-viestien määrä
odottavien RX-viestien määrä fifossa 0
odottavien RX-viestien määrä fifossa 1

setfilter(bank: int, mode: int, fifo: int, params: Tuple[int, ...], *, rtr: Tuple[bool, ...] | None = None, extframe: bool = False) → None¶

Määritä suodatinpankki:

bank on klassisen CAN-ohjaimen suodatinpankki tai CAN FD -suodatinindeksi, joka määritetään.
mode on tila, jossa suodattimen tulee toimia; katso alla olevat taulukot.
fifo on se fifo (0 tai 1), johon viesti tulee tallentaa, jos tämä suodatin hyväksyy sen.
params on arvojen taulukko, joka määrittää suodattimen. Taulukon sisältö riippuu mode-argumentista.

params-taulukon sisältö klassisille CAN -ohjaimille (OpenMV Cam M4 / M7):

mode	params-taulukon sisältö
`CAN.LIST16`	Neljä 16-bittistä tunnistetta, jotka hyväksytään.
`CAN.LIST32`	Kaksi 32-bittistä tunnistetta, jotka hyväksytään.
`CAN.MASK16`	Kaksi 16-bittistä id/maski-paria, esim. `(1, 3, 4, 4)`. Ensimmäinen pari (`1, 3`) hyväksyy kaikki tunnisteet, joissa bitti 0 = 1 ja bitti 1 = 0; toinen pari (`4, 4`) hyväksyy kaikki tunnisteet, joissa bitti 2 = 1.
`CAN.MASK32`	Yksi 32-bittinen id/maski-pari (muutoin sama kuin `CAN.MASK16`).

params-taulukon sisältö CAN FD -ohjaimille (OpenMV Cam H7 / H7 Plus / Pure Thermal):

mode	params-taulukon sisältö
`CAN.RANGE`	Kaksi tunnistetta, jotka muodostavat hyväksyttyjen tunnisteiden alueen.
`CAN.DUAL`	Kaksi tunnistetta, jotka hyväksytään (esim. `(1, 2)`).
`CAN.MASK`	Yksi `(id, mask)`-pari (esim. `(0x111, 0x7FF)`).

rtr Klassisilla CAN-ohjaimilla tämä on totuusarvojen taulukko, joka määrittää, tuleeko suodattimen hyväksyä etälähetyspyyntöviesti (remote transmission request). Jos tätä argumenttia ei anneta, sen oletusarvona on False kaikilla alkioilla. Pituus riippuu mode-arvosta:

mode

len(rtr)

Huomautukset

CAN.LIST16

4

CAN.LIST32

2

CAN.MASK16

2

CAN.MASK32

1

CAN FD:ssä tämä argumentti jätetään huomiotta.
extframe Jos True, kehyksellä on laajennettu tunniste (29 bittiä), muutoin käytetään vakiotunnistetta (11 bittiä).

mode	`len(rtr)`	Huomautukset
`CAN.LIST16`	4
`CAN.LIST32`	2
`CAN.MASK16`	2
`CAN.MASK32`	1

clearfilter(bank: int, extframe: bool = False) → None¶

Tyhjennä ja poista suodatinpankki käytöstä:

bank on klassisen CAN-ohjaimen suodatinpankki tai CAN FD -suodatinindeksi, joka tyhjennetään.
extframe CAN FD -ohjaimilla, jos True, tyhjennä laajennettu suodatin (määritetty arvolla extframe=True), muutoin tyhjennä vakiotunniste (määritetty arvolla extframe=False).

any(fifo: int) → bool¶: Palauta True, jos FIFO:ssa on viesti odottamassa, muutoin False.

recv(fifo: int, list: list | None = None, *, timeout: int = 5000) → list¶

Vastaanota dataa väylältä:

fifo on kokonaisluku, joka on se FIFO, jolta vastaanotetaan

list on valinnainen listaobjekti, jota käytetään paluuarvona

timeout on vastaanoton odotusaika millisekunteina.

Paluuarvo: Lista, joka sisältää viisi arvoa.

Viestin tunniste.

Totuusarvo, joka ilmaisee, onko viestin tunniste vakio vai laajennettu.

Totuusarvo, joka ilmaisee, onko viesti RTR-viesti.

FMI (Filter Match Index) -arvo.

Taulukko, joka sisältää datan.

Jos list on None, varataan uusi lista sekä uusi bytes-objekti datan säilyttämiseksi (listan viidentenä alkiona).

Jos list ei ole None, sen tulee olla listaobjekti, jossa on vähintään viisi alkiota. Viidennen alkion tulee olla memoryview-objekti, joka on luotu joko bytearray-objektista tai tyypin ’B’ tai ’b’ taulukosta, ja tässä taulukossa on oltava tilaa vähintään 8 tavulle. Listaobjekti täytetään tällöin neljällä ensimmäisellä yllä mainitulla paluuarvolla, ja memoryview-objektin koko muutetaan paikan päällä datan kokoon ja täytetään kyseisellä datalla. Samaa lista- ja memoryview-objektia voidaan käyttää uudelleen seuraavissa tämän metodin kutsuissa, mikä tarjoaa tavan vastaanottaa dataa käyttämättä kekoa. Esimerkiksi:

buf = bytearray(8)
lst = [0, 0, 0, 0, memoryview(buf)]
# No heap memory is allocated in the following call
can.recv(0, lst)

send(data: int | bytes | bytearray, id: int, *, timeout: int = 0, rtr: bool = False, extframe: bool = False, fdf: bool = False, brs: bool = False) → None¶

Lähetä viesti väylälle:

data on lähetettävä data (lähetettävä kokonaisluku tai puskuriobjekti).

id on lähetettävän viestin tunniste.

timeout on lähetyksen odotusaika millisekunteina.

rtr on totuusarvo, joka määrittää, lähetetäänkö viesti etälähetyspyyntönä (remote transmission request). Jos rtr on True, vain data-arvon pituutta käytetään kehyksen DLC-kentän täyttämiseen; data-arvon varsinaisia tavuja ei käytetä.

extframe jos True, kehyksellä on laajennettu tunniste (29 bittiä), muutoin käytetään vakiotunnistetta (11 bittiä).

fdf CAN FD -ohjaimilla, jos asetettu arvoon True, kehyksellä on FD-kehysmuoto, joka tukee jopa 64 tavun datakuormia.

brs CAN FD -ohjaimilla, jos asetettu arvoon True, siirtonopeuden vaihtotila on käytössä, jolloin datavaihe lähetetään eri siirtonopeudella. Katso databittiajan asetusparametrit kohdasta CAN.init().

Jos timeout on 0, viesti sijoitetaan yhteen kolmesta laitteistopuskurista ja metodi palaa välittömästi. Jos kaikki kolme puskuria ovat käytössä, heitetään poikkeus. Jos timeout ei ole 0, metodi odottaa, kunnes viesti on lähetetty. Jos viestiä ei voida lähettää määritetyssä ajassa, heitetään poikkeus.

Paluuarvo: None.

rxcallback(fifo: int, fun: Callable[[CAN, int], None] | None) → None¶

Rekisteröi funktio, jota kutsutaan, kun viesti hyväksytään tyhjään FIFO:on:

fifo on vastaanottava FIFO.
fun on funktio, jota kutsutaan, kun FIFO muuttuu ei-tyhjäksi.

Takaisinkutsufunktio ottaa kaksi argumenttia: ensimmäinen on itse CAN-objekti; toinen on kokonaisluku, joka ilmaisee takaisinkutsun syyn:

Syy	Merkitys
`0`	Viesti on hyväksytty tyhjään FIFO:on.
`1`	FIFO on täynnä.
`2`	Viesti on menetetty täyden FIFO:n vuoksi.

Esimerkki rxcallbackin käytöstä:

def cb0(bus, reason):
  print('cb0')
  if reason == 0:
      print('pending')
  if reason == 1:
      print('full')
  if reason == 2:
      print('overflow')

can = CAN(1, CAN.LOOPBACK)
can.rxcallback(0, cb0)

Vakiot¶

Väylätilavakiot (init()-metodin mode-argumentti):

NORMAL: int¶: Ohjain osallistuu väylään normaalisti – lähettää omat kehyksensä ja kuittaa kelvolliset vastaanotetut kehykset.

LOOPBACK: int¶: Sisäinen loopback-tila: ohjain on irrotettu nastoista ja reitittää lähetetyt kehykset suoraan takaisin vastaanottopolulle. Hyödyllinen itsetesteissä ilman lähetinvastaanotinta.

SILENT: int¶: Pelkkä kuuntelutila: ohjain vastaanottaa kehyksiä mutta ei koskaan ohjaa väylää (ei ACK:ia, ei lähetyksiä). Hyödyllinen väylän nuuskimiseen.

SILENT_LOOPBACK: int¶: Yhdistää SILENT- ja LOOPBACK-tilat: ei nasta-aktiviteettia eikä kuittauksia, sisäisellä TX:n loopbackilla RX:ään.

Ohjaimen tilavakiot (state()-metodin palauttamat):

STOPPED: int¶: Ohjain on täysin pois päältä ja nollattu.

ERROR_ACTIVE: int¶: Ohjain on päällä ja Error Active -tilassa (sekä TEC että REC ovat alle 96).

ERROR_WARNING: int¶: Ohjain on päällä ja Error Warning -tilassa (vähintään toinen TEC:istä tai REC:istä on 96 tai suurempi).

ERROR_PASSIVE: int¶: Ohjain on päällä ja Error Passive -tilassa (vähintään toinen TEC:istä tai REC:istä on 128 tai suurempi).

BUS_OFF: int¶: Ohjain on päällä mutta ei osallistu väylätoimintaan (TEC ylivuoti yli 255:n).

Klassisen CAN:in suodatintilat (setfilter()-metodin mode-argumentti OpenMV Cam M4:ssä / M7:ssä):

LIST16: int¶: Suodattimen params-taulukko sisältää neljä 16-bittistä tunnistetta, jotka hyväksytään.

LIST32: int¶: Suodattimen params-taulukko sisältää kaksi 32-bittistä tunnistetta, jotka hyväksytään.

MASK16: int¶: Suodattimen params-taulukko sisältää kaksi 16-bittistä (id, mask)-paria.

MASK32: int¶: Suodattimen params-taulukko sisältää yhden 32-bittisen (id, mask)-parin.

CAN FD -suodatintilat (setfilter()-metodin mode-argumentti OpenMV Cam H7:ssä / H7 Plussassa / Pure Thermalissa):

RANGE: int¶: Suodattimen params-taulukko sisältää kaksi tunnistetta, jotka muodostavat hyväksyttyjen tunnisteiden alueen.

DUAL: int¶: Suodattimen params-taulukko sisältää kaksi tiettyä hyväksyttävää tunnistetta.

MASK: int¶: Suodattimen params-taulukko sisältää yhden (id, mask)-parin.