RC_LIBRARY 1.0
Roman Bartosinski, ZS UTIA, (C)2005,2006
--------------------------------------------------------------------------------

Simulink library for Celoxica RC boards (RC10,RC250) support and communication
via USB and serial (COM) - Serial communication can be used for all boards with
RS232

Knihovna pro podporu komunikace s RC karetami pres USB a take pres seriovy port


Historie verzi:
--------------------------------------------------------------------------------
v0.1: Pocatecni verze
v0.2: Pridana moznost dvourozmernych dat posilanych normalne nebo ve framech
      Pridana moznost vypnuti vypisovani hlasek do matlabi konzole
      Do serveru pridano flushovani pipe bufferu po kazde transakci
v0.3: RC10 SFunkce i komunikacni process predelany na dynamicky buffer dat,takze
      velikost dat posilanach pres USB je omezena pouze prostredky pocitace a
      driverem od Celoxicy.
      Pridany moznosti 'signed' dat INT8,INT16,INT32
      Pridano demo na data zasilana po framech (s DSP blocksetem)
v0.4alpha:
      Komunikacni process rozsiren o komunikaci pres seriovy port (COM)
      Do knihovny pridan blok pro komunikaci pres seriove rozhrani.
      Pridano demo na otestovani komunikace pres seriove rozhrani.

v1.0:-Zmena z prime komunikace na komunikaci pres multithreadovy spolecny
      server, coz umoznuje jednotnou komunikaci s vice kartami z ruznych
      programu i sdileni jedne karty z vice programu.
     -Pridano monitorovaci okno serveru, ktere zobrazuje zakladni statistiky
      komunikace (Bude v budoucnu rozsireno a upraveno)
     -Spolecny system konfigurace (zatim nepouzity v blocich Simulinku).
     -Pridana moznost jednorazove zaslani/precteni dat z/do promennych MATLABu.
      (pred vlastnim behem simulace)
     -Pridana moznost zadat Sample time bloku.
     -Pridana moznost multirate (jiny sample time pro vstup a jiny pro vystup).
     -Pridana dema na demonstraci multiblock a multirate chovani
v1.1:-Zmena monitorovaciho okna komunikacniho serveru.      
     -!!! Spousteni serveru s chybeji RC.DLL musi ohlasit rozumnou chybu -
       coz nelze vyresit (jednoduse), protoze rc.dll musi byt prilinkovana
       staticky.
     -Oprava spousteni serveru z klienta - zmena na eventy
v1.1.1:-Vytvoreni RCCOM objektu, popisujiciho zarizeni pripojene pomoci RC Serveru.
      Objekt lze iniciovat jmenem rozhrani a jmenem zarizeni, pote jej lze
      otevrit pomoci 'fopen', zavrit pomoci 'fclose', zrusit pomoci 'delete',
      zjistit a nastavit vlastnosti objektu pomoci 'get' a 'set'. Pomoci 'fread'
      a 'fwrite' lze precist a zapsat data do zarizeni.
v1.1.2:-Pridani vypisu chyb zarizeni do stavoveho radku pro prave monitorovanou
      komunikaci. Oprava drobne chyby v S-funkci pri nastavovani hodin u RC250.

TODO:
v1.2:-Zmena matlabiho okna s parametry bloku na Windowsovy dialog (castecne
      hotovo pro univerzalni blok)
     -Dokonceni univerzalniho bloku.
     -Oprava dedeni sample time ze vstupu na dedeni z modelu
      (jinak ma warning pro blok bez vstupu(nebo vystupu))
     -Zkontrolovat, zda neni problem s urcenim cesty k bitstreamu v S-funkci
      (relativni cesta).


Instalace:
--------------------------------------------------------------------------------
1)Knihovnu staci kamkoliv zkopirovat.
2)Bud lze pridat do Matlabu rucne cestu do knihovny (tam co se naleza soubor 
	'rc_library.mdl', nebo z Matlabu spustit 'install_rclibrary', pri tom
	je potreba byt v adresari, kde se tato funkce nachazi (tj. tam, kam
	byla knihovna zkopirovana).
3)Knihovnu lze jiz normalne pouzivat... V Simulink library pribude polozka
	'Celoxica RC boards'.


Pouziti:
--------------------------------------------------------------------------------
Po pridani cesty ke knihovne do Matlabu je v Simulink Library Browseru nova
polozka 'Celoxica RC Boards', kde jsou bloky RC10, RC250, RCCOM a RCComBlock.

Po vlozeni bloku do modelu je treba jej nastavit. Nastaveni vstupu a vystupu
musi odpovidat aplikaci v Celoxice, tak aby spolu obe strany mohli spravne
komunikovat pres USB.
Komunikace je blokujici na obou stranach, ale na strane Matlabu je zablokovani
komunikace osetreno timeoutem, ktery ovsem skonci simulaci s chybou komunikace.
Blok v Simulinku muze mit maximalne jeden vstupni port ruzne sirky a maximalne
jeden vystupni port ruzne sirky. Zatim podporovane typy dat jsou UINT8, UINT16 a
UINT32, INT8, INT16, INT32 pricemz vstup a vystup je nezavisly (rozdilne sirky
i typy).
Blok muze byt nastaven i jako multirate, tj. s rozdilnym vzorkovanim vstupu a
vystupu, coz prakticky znamena, ze se do bloku mohou zapisovat data jinou
rychlosti nez se z nej ctou.
Blok take umoznuje inicializaci jednorazovym zapisem/ctenim do/ze zarizeni.
Zapisovat je mozne bud nuly nebo obsah promenne Matlabu a cist lze take do
promenne Matlabu.
Bloky RC10 a RC250 take umoznuji sdileni karty, tedy vicenasobne pouziti bloku
propojujici Matlab (a pripadne i jine programy) s jednou kartou (se stejnym
indexem).
Bloky RC10 a RC250 bez vstupu a vystupu lze pouzit i pouze ke konfiguraci FPGA.

Vice informaci je u popisu jednotlivych parametru bloku.


Upozorneni:
--------------------------------------------------------------------------------
!!! Z podstaty Matlabu je do bloku zapisovano/cteno kazdy nasobek sample time,
coz znamena ze pri spusteni simulace od casu=0 je prvni zapis/cteni provedeno
ihned v case 0. S tim je treba pocitat u multirate bloku, kdy napriklad pro
vstup bloku se sample time = 1 a vystup bloku se sample time = 2 nedojde
napoprve ke dvema zapisum do zarizeni (dvakrat vstup) a naslednemu jednomu cteni
ale pouze k jednomu zapisu nasledovanemu jednim ctenim. Tato situace muze
zpusobit nechtene chovani zarizeni. Tento 'nedostatek' je mozne napravit dvema
zpusoby: 1) Posunutim casu startu simulace, nebo 2)Pridanim zapisu jedne hodnoty
pred vlastni simulaci (pomoci parametru 'Number of zeros to write ...'.

!!! Data jsou do USB a z USB zapisovana/ctena po sloupcich. To jest pri jednom
prenosu (napriklad do desky) jsou data poskladana po celych delkach postupne pro
vsechny vstupy. 
Pri delce dat L indexovanych <1..L> a sirce portu W (kde jednotlive signalu
portu jsou oznaceny w1,w2,...,wW) je matice dat
[ 1w1 1w2 1w3 ... 1wW]
[ 2w1 2w2 2w3 ... 2wW]
      ....
[ Lw1 Lw2 Lw3 ... LwW]

poslana jako posloupnost dat  1w1,2w1,3w1,..,Lw1,1w2,2w2,3w2,...,Lw2, ... LwW.


--------------------------------------------------------------------------------
--------------------------------------------------------------------------------

RC_Server:
--------------------------------------------------------------------------------
Soucasti knihovny je i komunikacni server s monitorovacim oknem. Diky tomuto
serveru je sjednocen pristup ke vsem komunikacim (RC-USB,Serial,...). Dale
server zajistuje soucasny pristup z ruznych programu a take sdileni karet
(pro RC-USB). Pomoci monitorovaciho okna lze sledovat statistiky komunikace z
jednotlivych programu. Tento server pridava ikonu na tray. Poklepanim na teto
ikone je mozne zobrazit(nebo skryt) monitorovaci okno, nebo server zastavit.


Obsah knihovny 'Celoxica RC board' pro Simulink:
--------------------------------------------------------------------------------
Blok:       Popis:
RC10        Blok pro komunikaci s kartami Celoxica pres USB (obecne jakymikoliv)
RC250       Blok pro komunikaci s kartami Celoxica pres USB (stejne jako RC10,
            ale je mozne nastavit frekvenci nastavitelnych hodin FPGA)
RCCOM       Blok pro komunikaci s kartami pomoci serioveho prenosu.
RCComBlock  Obecny, univerzalni blok, ktery v budoucnu nahradi vsechny ostatni
            bloky, protoze bude mit spolecne nastavovani parametru, zavisle na
            desce. - Zatim neni scela funkcni


--------------------------------------------------------------------------------
--------------------------------------------------------------------------------

Spolecne nastaveni bloku RC10,RC250,RCCOM:
--------------------------------------------------------------------------------

Width of input port
	- sirka vstupniho portu. Pro hodnotu 0 nema blok vstupni port. Pokud je
	  zadana hodnata zaporna, sirka portu je dynamicky brana z pripojenych
	  bloku.
Length of input port
	- delka vstupniho portu (pro framed signaly je to delka framu). Pokud je
	  nula, blok nema vstupni port. Pro zaporne hodnoty je delka urcena z
	  pripojenych bloku. (Pro normalni signaly by mela byt hodnota=1)
Input data type mode
	- typ vstupu. Lze nastavit 'auto','uint8','uint16','uint32'.Vyberem 'auto'
	  bude typ urcen z pripojenych bloku, pripadne bude nastaven na UINT8,
	  pokud nelze urcit.
Width of output port
	- sirka vystupniho portu. Pro hodnotu 0 nema blok vystupni port. Pokud je
	  zadana hodnata zaporna, sirka portu je dynamicky urcena - vetsinou je
	  nastavena stejne jako je sirka vstupniho portu nebo podle pripojenych
	  bloku.
Length of output port
	- delka vystupniho portu (pro framed signaly je to delka framu). Pokud je
	  hodnota nula - blok nema vystup. Pro zaporne hodnoty je delka stejna jako
	  delka vstupu. Pro normalni signaly by mela je hodnota = 1.
Output data type mode
	- typ vystupu. Lze nastavit 'auto','uint8','uint16','uint32'.Vyberem 'auto'
	  bude typ urcen z pripojenych bloku, pripadne bude nastaven na UINT8,
	  pokud nelze urcit.
Framed data
	- data jsou ctena a zapisovana z/do bloku po framech. Specialni druh signalu
	  zavedeny v Signal processing blocksetu, proto je potreba jeho licence.
Send/Receive data in BIG endian
	- normalne jsou data z Matlabu posilana postupne po jednotlivych signalech
	  v little endian. Pri zaskrtnuti jsou data posilana v big endianu.
	  (Casem bude rozdeleno na samostatna prepinatka pro zapis a ctani)

Number of zeros to write to board before simulation or MATLAB variable
	- pocet bytu (nul), ktere budou zapsany pred spustenim simulace (po
	  konfiguraci FPGA). Misto poctu nul je mozne zadat jmeno promenne, ktera bude
	  zapsana do FPGA. Je poslan vzdy cely obsah promenne a to ve tvaru, v jakem
    ji uklada MATLAB do pameti (velikost dat je zjistena z promenne.
Number of bytes to read from board before simulation or MATLAB variable
	- pocet bytu, ktere budou pred spustenim simulace (po konfiguraci FPGA)
	  precteny a zahozeny, nebo jmeno promenne Matlabu, do ktere budou data
	  nactena - promenna musi existovat a mit pozadovanou velikost a typ dat,
	  protoze se pocet ctenych dat zjistuje primo z promenne.
Read refuse first then write zeros
	- normalne je nejdrive do karty zapisovano a teprve pak cteno(i pri simulaci),
	  pro pripad ze by bylo potreba cist i zapisovat pred simulaci, lze timto
	  otocit poradi operaci, tj. nejdrive cteni a potom zapis.
Block sample time (input for multirate)
	- perioda vzorkovani bloku (v cele nasobky tohoto casu bude k bloku
    pristupovano). Pokud je povoleno ruzne vzorkovani pro vstup a vystup, urcuje
    tento parametr cas zapisu do bloku.
Multirate block
	- povoluje ruzne rychlosti zapisu a cteni do/z bloku. Funkce je pouzita pouze
	  pokud jsou nastaveny oba vzorkovaci casy.
Blocksample time (output)
	- perioda vzorkovani vystupu (v cele nasobky tohoto casu bude k vystupu
    pristupovano a tim i z bloku cteno), Pri povolene funkci multirate.
	  !!! Pro cas=0 dojde vzdy k pristupu na vstup i vystup soucasne (pro
    jakekoliv vzorkovaci periody) !!!


Specialni nastaveni bloku RC10,RC250:
--------------------------------------------------------------------------------
Index of used RC board
	- index pripojene desky, ke ktere se pomoci bloku pristupuje. Desky mohou
	  byt sdilene, tj. jedna deska muze byt pripojena k vice blokum, ale
	  poradi v jakem jednotlive bloky ke karte pristupuji je dano vzorkovaci
	  periodou bloku a Matlabem. Pro jednu desku je to index 0. Urceni indexu
	  zatim neni automaticke - lze zjistit pomoci 'FTU3' nebo 'rcx'.

Configure FPGA before simulation
	- povoleni konfigurace pri staru simulace.
Clear FPGA before configuration
	- pred vlastni konfiguraci je poslan prikaz pro smazani obsahu FPGA.
Name of FPGA configuration bitstream file
	- jmeno souboru (i s cestou) k bitstreamu, kterym bude FPGA nakonfigurovano.

Specialni nastaveni bloku RC250:
--------------------------------------------------------------------------------
FPGA clock (MHz)
	- Ciselna hodnota pozadovane frekvence FPGA, pokud nelze nastavit je pri
	  spusteni vypsano varovani v MATLABu s opravdu nastavenou frekvenci.


Specialni nastaveni bloku RCCOM:
--------------------------------------------------------------------------------
Index of communication port COMx
	- index serioveho portu, ktere je soucasti jmena portu COMx. Prednastavena
	  hodnota je 1, tj. seriovy port COM1.
COM port setting string
  - retezec obsahujici parametry nastaveni serioveho rozhrani. Format retezce
    je stejny jako u prikazu 'mode' na prikazove radce. Zakladni parametry jsou:
    baud - pouzita prenosova rychlost, parity - pouzita parita,
    data - pocet bitu v prenasenem znaku, stop - pocet stop bitu.
    Pokud je jako retezec zadano 'def' je ponechano nastaveni portu ze systemu.
    Pokud neni zadan zadny retezec je pouzito prednastaveni 9600,8,N,1




Skryte nebo zrusene nastaveni:
--------------------------------------------------------------------------------
Verbose communication
	- do okna Matlabu budou vypisovany nektere informacni hlasky o probihajici
	  komunikaci se serverem pro komunikaci pres USB.



--------------------------------------------------------------------------------
--------------------------------------------------------------------------------


Priklady:
--------------------------------------------------------------------------------
V adresari knihovny 'demos' jsou pokusne priklady i s jejich HW protejsi (pro
RC10 jsou vyrobene i bitstreamy).

usb_cnt: 
	Priklad na zapis dvou 16 bitovych cisel do karty a cteni jednoho 32 bitoveho
	cisla z karty. V HW je nyni delan jejich soucin.

adcinput:
	Pokus s AD prevodnikem na RC10. Aby to aspon trochu fungovalo spravne, tak
	je treba mit nastavenou stejnou frekvenci v simulinku i v HW pro cteni ADCcka.

dsp_audio:
  Pokus s daty ve framech vetsimi nez interni buffer. Z mikrofonu jsou data
  nacitana jako 2x2048 vzorku INT16. Ty jsou v RC10 poslana zpet s nasledujici
  upravou: Pokud je joystick vlevo, je levy kanal na vystupu vypnut, pokud
  je joystick doprava, je vypnut pravy kanal, Pri stisku joysticku jsou vypnuty
  oba kanaly (vypinani probiha po framech - je vypnut vzdy cely frame)

serial_cnt:
  Jednoduchy testovaci priklad, ktery cte v FPGA ze serioveho portu dve 32bitova
  cisla UINT32 a posila jedno 32 bitove UINT32 cislo. V FPGA se provadi soucet
  dvou cisel.

multiblock:
  Stejny priklad jako usb_cnt, ale s tim rozdilem, ze pro konfiguraci, zapis
  i cteni jsou pouzity samostatne bloky, ktere pristupuji na jednu kartu.
multirate:
  Stejny priklad jako usb_cnt, ale blok ma pouze jeden vstup, ktery je zapisovan
  dvakrat rychleji nez je cten vystup. ! Simulace je startovana od casu 1, aby
  se predeslo problemu v case 0, kdy je do bloku zapsano i z nej cteno(po jednom
  zapisu).
trigtest:
  Priklad jednorazove precte 4000 bytu z karty a pote je jednorazove zapise do
  karty. Priklad je urcen pro kartu RC10 a nekonfiguruje FPGA pred vlastni
  simulaci. V RC10 musi byt spusten zakladni 'Board test' (soucasti RC10). Krome
  poslani dat zpet do desky jsou data ulozena i do promenne Matlabu.
