Dodatkowy przewodnik programisty dla D2XX

Transkrypt

1 Dodatkowy przewodnik programisty dla D2XX Zawartość Wstęp Nowe funkcje FT_GetDeviceInfo FT_SetResetPipeRetryCount FT_StopInTask FT_RestartInTask FT_ResetPort Rozszerzenia dla Location ID FT_ListDevices FT_OpenEx FT_W32_CreateFile Wstęp Ten dokument zawiera opisy nowych funkcji i rozszerzeń istniejących funkcji, które nie zostały jeszcze opisane w Przewodniku programisty D2XX. Nowe Funkcje Funkcje FT_GetDeviceInfo, FT_SetResetPipeRetryCount, FT_StopInTask, FT_RestartInTask, and FT_ResetPort zostały dodane do API D2XX. FT_GetDeviceInfo Pobiera informacje o urządzeniu FT_STATUS FT_GetDeviceInfo ( FT_HANDLE fthandle, FT_DEVICE *pfttype, LPDWORD lpdwid, PCHAR pcserialnumber, PCHAR pcdescription, PVOID pvdummy ) Parametry fthandle FT_HANDLE: uchwyt zwrócony przez FT_Open lub FT_OpenEx. pfttype Wskaźnik długiej zmiennej (long) nieoznakowanej do zapisania typu urządzenia lpdwid Wskaźnik długiej zmiennej (long) nieoznakowanej do zapisania ID urządzenia pcserialnumber Wskaźnik buforu do zapisania numeru seryjnego urządzenia jako tablicy (nullterminated) pcdescription Wskaźnik buforu do zapisania opisu urządzenia jako tablicy (null-terminated) pvdummy Zarezerwowany do wykorzystania w przyszłości powinien być ustawiony jako NULL Strona 1 z 10

2 Ta funkcja używana jest do zwracania typu urządzenia, ID urządzenia, opisu urządzenia i numeru seryjnego. ID urządzenia zakodowane jest w wartości DWORD najważniejsza część zawiera ID producenta, a mniej ważna część zawiera ID produktu, więc zwrócone ID 0x to VID_0403 & PID_6001. Przykład Ten przykład pokazuje jak można uzyskać informacje o urządzeniu FT_DEVICE ftdevice; DWORD deviceid; char SerialNumber[16]; char Description[64]; // właściwy uchwyt zwrócony przez FT_OpenEx ftstatus = FT_GetDeviceInfo( fthandle, &ftdevice, &deviceid, SerialNumber, Description, NULL ); if (ftdevice == FT_DEVICE_232BM) ; // jeśli urządzenie to FT232BM else if (ftdevice == FT_DEVICE_232R) ; // jeśli urządzenie to FT232R else if (ftdevice == FT_DEVICE_232AM) ; // jeśli urządzenie to FT8U232AM else if (ftdevice == FT_DEVICE_100AX) ; // jeśli urządzenie to FT8U100AX else ; // nieznane urządzenie (nie powinno do tego dojść!) // deviceid zawiera zakodowane ID urządzenia // SerialNumber, Description zawierają tablice danych (0-terminated) // FT_GetDeviceType FAILED! FT_SetResetPipeRetryCount Ustawienie ResetPipeRetryCount. FT_STATUS FT_SetResetPipeRetryCount ( FT_HANDLE fthandle, DWORD dwcount ) Parametry fthandle dwcount FT_HANDLE: łącznik zwrócony przez FT_Open lub FT_OpenEx. DWORD: nieoznakowana długa zmienna zawierająca wymagany ResetPipeRetryCount. Strona 2 z 10

3 Ta funkcja używana jest do ustawienia ResetPipeRetryCount. ResetPipeRetryCount. Kontroluje maksymalną liczbę prób zresetowania przez sterownik, pipe a, na którym wystąpił błąd. Wartość domyślna ResetPipeRequestRetryCount to 50. Ta wartość może wymagać zwiększenia w przypadku dużych zakłóceń, przy których może występować dużo błędów USB. Przykład Ten przykład pokazuje jak zwiększyć wartość ResetPipeRetryCount do 100. DWORD dwretrycount; // właściwy uchwyt zwrócony przez FT_OpenEx dwretrycount = 100; ftstatus = FT_SetResetPipeRetryCount(ftHandle,dwRetryCount); // ResetPipeRetryCount zmienione na 100 // FT_SetResetPipeRetryCount FAILED! FT_StopInTask Zatrzymanie zadanie typu IN. FT_STATUS FT_StopInTask ( FT_HANDLE fthandle ) Parametry fthandle FT_HANDLE: łącznik zwrócony przez FT_Open lub FT_OpenEx. Ta funkcja jest używana do ustawienia działania IN (wait) sterownika w tryb czekania. Może ona być używana w sytuacjach gdzie dane są odbierane nieprzerwanie, po to aby wyczyścić urządzenie bez konieczności pobierania dodatkowych danych. Ta funkcja jest używana w połączeniu z funkcją FT_RestartInTask która ponownie uruchamia zadanie IN Przykład Ten przykład pokazuje jak używać funkcji FT_StopInTask. // właściwy uchwyt zwrócony przez FT_OpenEx do { ftstatus = FT_StopInTask(ftHandle); while (ftstatus!= FT_OK); Strona 3 z 10

4 // // Dowolne działanie np wyczyszczenie urządzenia // do { ftstatus = FT_RestartInTask(ftHandle); while (ftstatus!= FT_OK); FT_RestartInTask Ponowne uruchomienie zadania typu IN. FT_STATUS FT_RestartInTask ( FT_HANDLE fthandle ) Parametry fthandle FT_HANDLE: łącznik zwrócony przez FT_Open lub FT_OpenEx. Ta funkcja jest używana do ponownego uruchamiania zadania typu IN (wait) sterownika, po tym jak zostało ono zatrzymane przez funkcję FT_StopInTask. Przykład Ten przykład pokazuje jak używać funkcji FT_RestartInTask. // właściwy uchwyt zwrócony przez FT_OpenEx do { ftstatus = FT_StopInTask(ftHandle); while (ftstatus!= FT_OK); // // Dowolne działanie np wyczyszczenie urządzenia // do { ftstatus = FT_RestartInTask(ftHandle); while (ftstatus!= FT_OK); FT_ResetPort Wyślij polecenie zresetowania portu. FT_STATUS FT_ResetPort ( FT_HANDLE fthandle ) Strona 4 z 10

5 Parametry fthandle FT_HANDLE: łacznik zwrócony przez FT_Open lub FT_OpenEx. Ta funkcja używana jest do przywrócenia działania portu po błędzie. Przykład Ten przykład pokazuje jak zresetować port // właściwy uchwyt zwrócony przez FT_OpenEx ftstatus = FT_ResetPort(ftHandle); // Port został zresetowany // FT_ResetPort FAILED! Rozszerzenia dotyczące Location ID Location ID to 32-bitowa liczba całkowita (długa), która reprezentuje położenie urządzenia w drzewie USB. Na przykład, jeżeli sterownik tworzy zmienną tekstową położenia urządzenia, która ma formę a&b&c, to Location ID w tym przypadku będzie równe 0x00000abc. Location ID można pobrać używając narzędzia USBView, które jest dostępne na FTDI. Aby pobrać Location ID dla konkretnego portu USB, trzeba uruchomić program USBView i podłączyć dane urządzenie do portu, który nas interesuje. Z menu trzeba wybrać Options LocationIDs i wcisnąć klawisz F5 aby odświeżyć ekran. Numery portów zastąpione zostaną numerami LocationID w formie LocXY, gdzie X i Y to wartości szesnastkowe. XY są używane do tworzenia zmiennej położenia, zawierającej ciąg znaków w formie X&Y i LocationID w formie 0xAB. Flaga, FT_OPEN_BY_LOCATION, została stworzona aby wspierać ID położeń i jest definiowana: #define FT_OPEN_BY_LOCATION 4 Funkcje FT_ListDevices, FT_OpenEx, i FT_CreateFile wspierają również ID położeń.. FT_ListDevices Pobranie informacji o urządzeniach podłączonych. Ta funkcja może zwrócić informacje takie jak liczba podłączonych urządzeń, numer seryjny urządzenia i opis urządzenia, oraz ID położeń urządzeń podłączonych. FT_STATUS FT_ListDevices (PVOID pvarg1,pvoid pvarg2,unsigned long dwflags) Strona 5 z 10

6 Return Value Ta funkcja może być używana na wiele sposobów i może zwracać wiele informacji. W najprostszej formie może ona być używana do zwracania liczby podłączonych urządzeń. Jeśli w dwflags jest ustawiony bit FT_LIST_NUMBER_ONLY, parametr pvarg1 jest interpretowany jako wskaźnik lokacji zmiennej DWORD, która zawiera liczbę podłączonych urządzeń. Może być też używana do zwracania informacji o urządzeniu: jeśli w dwflags jest ustawiony bit FT_OPEN_BY_SERIAL_NUMBER, funkcja zwróci nam numer seryjny urządzenia; jeśli w dwflags jest ustawiony bit FT_OPEN_BY_DESCRIPTION, funkcja zwróci opis urządzenia; jeśli w dwflags jest ustawiony bit FT_OPEN_BY_LOCATION, funkcja zwróci Location ID; jeśli nic nie jest ustawione, funkcja domyślnie zwraca numer seryjny urządzenia. Można jej używać do zwracania ciągu znaków z informacjami o konkretnym urządzeniu. Jeśli w dwflags jest ustawiony bit FT_LIST_BY_INDEX i FT_OPEN_BY_SERIAL_NUMBER lub FT_OPEN_BY_DESCRIPTION, parametr pvarg1 jest interpretowany jako indeks urządzenia i paramentr pvarg2 jest interpretowany jako wskaźnik do bufora zawierającego odpowiedni ciąg znaków. Indeksy są to tablice (zero-based), a kody błędów FT_DEVICE_NOT_FOUND są zwracane jako niewłaściwy indeks. Można jej używać do zwracania ciągu znaków z informacjami o wszystkich podłączonych urządzeniach. Jeśli w dwflags jest ustawiony bit FT_LIST_ALL i FT_OPEN_BY_SERIAL_NUMBER lub FT_OPEN_BY_DESCRIPTION, parametr pvarg1 jest interpretowany jako wskaźnik do tablic wskaźników do buforów zawierających odpowiedni ciąg znaków, a parametr pvarg2 jest interpretowany jako wskaźnik do położenia wartości DWORD, która zawiera ilość wszystkich podłączonych urządzeń. Trzeba zauważyć, że w parametrze pvarg1 ostatnią wartością w tablicy wskaźników do buforów powinien znajdować się wskaźnik NULL, aby tablica zawierała o jeden wpis więcej niż ilość podlączonych urządzeń. Location ID urządzenia jest zwrócone jeśli bity FT_LIST_BY_INDEX i FT_OPEN_BY_LOCATION są ustawione w dwflags. W tym wypadku parametr pvarg1 jest interpretowany jako indeks urządzenia, a parametr pvarg2 jest inrepretowany jako wskaźnik do zmiennej typu long który zawiera Location ID. Indeksy są typu zero-based, a kody błędów FT_DEVICE_NOT_FOUND są zwracane jako niewłaściwy indeks. Location ID wszystkich podłączonych urządzeń są zwracane jeśli w dwflags ustawione są bity FT_LIST_ALL i FT_OPEN_BY_LOCATION. W tym wypadku parametr pvarg1 jest interpretowany jakos wskaźnik do tablicy zmiennych typu long, która zawiera Location ID, a parametr pvarg2 jest interpretowany jako wskaźnik do położenia wartości DWORD, która zawiera ilość wszystkich podłączonych urządzeń. Przykłady W tym przykładzie użyte są zmienne: DWORD numdevs; Pobieranie liczby urządzeń podłączonych ftstatus = FT_ListDevices(&numDevs,NULL,FT_LIST_NUMBER_ONLY); // FT_ListDevices OK, numdevs liczba podłączonych urządzeń // FT_ListDevices failed Pobieranie numeru seryjnego urządzenia Strona 6 z 10

7 DWORD devindex = 0; // pierwsze urządzenie char Buffer[64]; // więcej miejsca niż potrzeba! ftstatus = FT_ListDevices((PVOID)devIndex,Buffer,FT_LIST_BY_INDEX FT_OPEN_BY_SERIAL_NUMBER); // FT_ListDevices OK, Buffer numer seryjny urządzenia // FT_ListDevices failed Warto zauważyć że indeksy są typu zero-based. Jeśli podłączonych jest więcej niż jedno urządzenie, inkrementacja devindex spowoduje pobranie pokolei numeru seryjnego każdego podłączonego urządzenia. Pobieranie opisu wszystkich podłączonych urządzeń char *BufPtrs[3]; char Buffer1[64]; char Buffer2[64]; // wskaźnik do tablicy 3 wskaźników // bufor opisu pierwszego urządzenia // bufor opisu drugiego urządzenia // inicjalizacja tablicy wskaźników BufPtrs[0] = Buffer1; BufPtrs[1] = Buffer2; BufPtrs[2] = NULL; // ostatnia wartość powinna być pusta (NULL) ftstatus = FT_ListDevices(BufPtrs,&numDevs,FT_LIST_ALL FT_OPEN_BY_DESCRIPTION); // FT_ListDevices OK, opisy produktów znajdują się w Buffer1 i Buffer2 a w //numdevs znajduje się liczba podłączonych urządzeń // FT_ListDevices failed Warto zauważyć, że ten przykład zakłada, że podłączone są dwa urządzenia. Jeśli jest podłączonych więcej urządzeń rozmiar tablicy wskaźników musi być powiększony i powinno być przydzielonych więcej buforów na opisy. Pobierz położenie podłączonych urządzeń long locidbuf[16]; ftstatus = FT_ListDevices(locIdBuf,&numDevs,FT_LIST_ALL FT_OPEN_BY_LOCATION); // FT_ListDevices OK, Location ID znajdują się w locidbuf // numdevs zawiera ilość podłączonych urządzeń // FT_ListDevices failed Warto zauważyć, że ten przykład zakłada że podłączonych jest nie więcej niż 16 urządzeń. Jeśli podłączonych jest więcej urządzeń powinniśmy zwiększyć rozmiar tablicy wskaźników. FT_OpenEx Otwarcie konkretnego urządzenia i zwrócenie uchwytu, który będzie używany do późniejszego dostępu. Urządzenie można wyszczególnić po jego numerze seryjnym, opisie, lub położeniu. Ta funkcja może być także używana do otwierania wielu urządzeń w tym samym czasie, jeśli tylko będą one rozróżnialne po numerze seryjnym lub opisie. Opcjonalnie można je rozróżniać po ich Location ID - Strona 7 z 10

8 informacje o położeniu pochodzące z ich fizycznego położenia na USB. Location ID może być uzyskane używając narzędzia USBView. FT_STATUS FT_OpenEx (PVOID pvarg1,unsigned long dwflags, FT_HANDLE *fthandle) Znaczenie pvarg1 zależy od dwflags: jeżeli dwflags ma wartość FT_OPEN_BY_SERIAL_NUMBER, to pvarg1 jest interpretowany jako wskaźnik do ciągu znaków (null-terminated), który reprezentuje numer seryjny urządzenia; jeśli dwflags ma wartość FT_OPEN_BY_DESCRIPTION, to pvarg1 jest interpretowany jako wskaźnik do ciągu znaków (null-terminated), który reprezentuje opis urządzenia; jeśli dwflags ma wartość FT_OPEN_BY_LOCATION, to pvarg1 jest interpretowany jako wartość long, która zawiera Location ID urządzenia. fthandle to wskaźnik do zmiennej typu FT_HANDLE gdzie przechowywany jest uchwyt. Ten uchwyt musi być używany do połączenia się z urządzeniem. Przykłady W przykładzie użyte są następujące zmienne FT_STATUS ftstatus2; FT_HANDLE fthandle1; FT_HANDLE fthandle2; long dwloc; Otwarcie urządzenia o numerze seryjnym "FT000001" ftstatus = FT_OpenEx("FT000001",FT_OPEN_BY_SERIAL_NUMBER,&ftHandle1); // sukces - urządzenie o numerzez seryjnym "FT000001" jest otwarte // failure Otwarcie urządzenie o opisie "USB Serial Converter" ftstatus = FT_OpenEx("USB Serial Converter",FT_OPEN_BY_DESCRIPTION,&ftHandle1); // sukces - urządzenie z opisem "USB Serial Converter" jest otwarte // failure Otwarcie 2 urządzeń o numerach seryjnych "FT000001" i "FT999999" ftstatus = FT_OpenEx("FT000001",FT_OPEN_BY_SERIAL_NUMBER,&ftHandle1); ftstatus2 = FT_OpenEx("FT999999",FT_OPEN_BY_SERIAL_NUMBER,&ftHandle2); if (ftstatus == FT_OK && ftstatus2 == FT_OK) { // sukces - oba urządzenia otwarte // failure - jedno lub oba urządzenia nie zostały otwarte Otwarcie 2 urządzeń z opisami "USB Serial Converter" i "USB Pump Controller" Strona 8 z 10

9 ftstatus = FT_OpenEx("USB Serial Converter",FT_OPEN_BY_DESCRIPTION,&ftHandle1); ftstatus2 = FT_OpenEx("USB Pump Controller",FT_OPEN_BY_DESCRIPTION,&ftHandle2); if (ftstatus == FT_OK && ftstatus2 == FT_OK) { // sukces - oba urządzenia są otwarte // failure - jedno lub oba urządzenia nie zostały otwarte Otwarcie urządzenia o położeniu 23 dwloc = 0x23; ftstatus = FT_OpenEx(dwLoc,FT_OPEN_BY_LOCATION,&ftHandle1); // success - urządzenie o położeniu 23 otwarte // failure Otwarcie 2 urządzeń o położeniach 23 i 31 dwloc = 0x23; ftstatus = FT_OpenEx(dwLoc,FT_OPEN_BY_LOCATION,&ftHandle1); dwloc = 0x31; ftstatus2 = FT_OpenEx(dwLoc,FT_OPEN_BY_LOCATION,&ftHandle2); if (ftstatus == FT_OK && ftstatus2 == FT_OK) { // sukces - oba urządzenia są otwarte // failure - jedno lub oba urządzenia nie zostały otwarte FT_W32_CreateFile Otwarcie konkretnego urządzenia i zwrócenie uchwytu, który będzie używany do późniejszego dostępu. Urządzenie można wyszczególnić po jego numerze seryjnym, opisie, lub położeniu. Ta funkcja musi być użyta jeżeli wymagane jest overlapped I/O. FT_HANDLE FT_W32_CreateFile ( PVOID pvarg1, DWORD dwaccess, DWORD dwsharemode, LPSECURITY_ATTRIBUTES lpsecurityattributes, DWORD dwcreate, DWORD dwattrsandflags, HANDLE htemplate ) Jeśli funkcja zakończy się powodzenie zwracany jest uchwyt. Jeśli funkcja zakończy się niepowodzeniem zwracany jest kod błędu Win32 - INVALID_HANDLE_VALUE. Znaczenie pvarg1 zależy od dwattrsandflags: jeśli dwattrsandflags ma wartość FT_OPEN_BY_SERIAL_NUMBER lub FT_OPEN_BY_DESCRIPTION, pvarg1 zawiera wskaźnik do ciągu znaków (null-terminated), który zawiera numer seryjny urządzenia lub jego opis; jeśli dwattrsandflags ma wartość FT_OPEN_BY_LOCATION, pvarg1 jest interpretowany jako wartość typu long, która zawiera Location ID urządzenia. Strona 9 z 10

10 dwaccess może być GENERIC_READ lub GENERIC_WRITE lub oboma; dwsharemode musi być ustawione na 0; dwattrsandflags jest kombinacją FILE_ATTRIBUTE_NORMAL i FILE_FLAG_OVERLAPPED, jeśli użyte jest overlapped I/O, FT_OPEN_BY_SERIAL_NUMBER lub FT_OPEN_BY_DESCRIPTION lub FT_OPEN_BY_LOCATION; htemplate musi być puste (NULL). Przykłady Przykład poniżej używa zmiennych: char Buf[64]; Otwarcie urządzenia dla overlapped I/O używając numeru seryjnego ftstatus = FT_ListDevices(0,Buf,FT_LIST_BY_INDEX FT_OPEN_BY_SERIAL_NUMBER); fthandle = FT_W32_CreateFile(Buf,GENERIC_READ GENERIC_WRITE,0,0, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL FILE_FLAG_OVERLAPPED FT_OPEN_BY_SERIAL_NUMBER, 0); if (fthandle == INVALID_HANDLE_VALUE) ; // FT_W32_CreateDevice failed Otwarcie urządzenia dla non-overlapped I/O używając opisu ftstatus = FT_ListDevices(0,Buf,FT_LIST_BY_INDEX FT_OPEN_BY_DESCRIPTION); fthandle = FT_W32_CreateFile(Buf,GENERIC_READ GENERIC_WRITE,0,0, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL FT_OPEN_BY_DESCRIPTION, 0); if (fthandle == INVALID_HANDLE_VALUE) ; // FT_W32_CreateDevice failed Otwarcie urządzenia dla non-overlapped I/O używając położenia long locid; ftstatus = FT_ListDevices(0,&locID,FT_LIST_BY_INDEX FT_OPEN_BY_LOCATION); fthandle = FT_W32_CreateFile((PVOID) locid,generic_read GENERIC_WRITE,0,0, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL FT_OPEN_BY_LOCATION, 0); if (fthandle == INVALID_HANDLE_VALUE) ; // FT_W32_CreateDevice failed Strona 10 z 10