D2XX - Programátorská příručka v. 3.1

(1)

D2XX - Programátorská příručka v. 3.1

Zde je „volný“ překlad části originální příručky doplněný o další informace.

Přeložil: elecon.

Přehled

FT_ListDevices vrací informaci o FTDI zařízeních která jsou připojena. V systémech s více zařízeními může být použito pro určení ke kterému zařízení požaduje aplikační software přístup

(použití FT_OpenEx viz níže).

Před přístupem k zařízení ho musíme otevřít (připojit). FT_Open a FT_OpenEx vrací handle které je použito pro všechny funkce v klasickém programovacím rozhraní pro identifikaci zařízení. Když je zařízení úspěšně otevřeno, můžeme k němu přistupovat pomocí funkcí FT_Read

a FT_Write . Jestliže vykonáme všechny operace musíme zařízení zavřít použitím FT_Close .

Jestliže zařízení otevřeme, máme k dispozici doplňkové funkce pro reset zařízení (FT_ResetDevice );

vyprázdnění přijímacího a vysílacího bufferu (FT_Purge ); nastavení přijímacího a vysílacího časového limitu (FT_SetTimeouts ); zjištění stavu přijímací fronty (FT_GetQueueStatus ); zjištění stavu zařízení (FT_GetStatus ); nastavení a nulování přerušovací podmínky (FT_SetBreakOn ,FT_SetBreakOff );

a nastavení podmínky pro hlášení událostí (FT_SetEventNotification ).

Doporučení

Typové definice parametrů funkcí a návratových kódů použitých v D2XX klasickém programovém rozhraní jsou obsaženy v příloze.

1. FT_Open

Otevře zařízení a vrací handle, které bude použito pro další přístupy.

FT_STATUS FT_Open (int iDevice, FT_HANDLE *ftHandle) Parametry

idevice musí být 0 jestliže je otevřeno jen jedno zařízení. Pro více zařízení je 1, 2 atd.

ftHandle ukazatel na proměnou typu FT_HANDLE kde bude handle uloženo. Toto handle musí být použito pro přístup k zařízení.

Návratová hodnota

FT_OK jestliže bylo zařízení otevřeno, v jiném případě je vráceno FT error code.

Poznámky

I když tato funkce může být použita pro otevření více zařízení pomocí nastavení iDevice na 0, 1, 2 atd.

není schopna otevřít specifické zařízení s popisem. Pro otevření pojmenovaných zařízení použijte funkci FT_OpenEx .

Příklad

Tento příklad ukazuje jak otevřít zařízení.

FT_HANDLE ftHandle;

FT_STATUS ftStatus;

ftStatus = FT_Open(0,&ftHandle);

if (ftStatus == FT_OK) {

// FT_Open OK, používej ftHandle pro přístup k zařízení }

else {

// FT_Open nezdařilo se otevřít zařízení }

(2)

2. FT_OpenEx

Otevře zařízení a vrací handle které bude použito pro další přístupy.

Zařízení může být specifikováno sériovým číslem, popisem nebo umístěním.

Tato funkce může být použita pro otevření více zařízení současně. Více zařízení může být otevřeno současně, jestliže mohou být rozlišeny sériovým číslem, nebo popisem.

Alternativně, více zařízení může být otevřeno současně použitím IDs – umisťovací informace získaná z fyzického umístění na USB. Lokalizační IDs může být získáno použitím utility USBView a je uloženo v hexadecimálním formátu.

.

FT_STATUS FT_OpenEx (PVOID pvArg1, DWORD dwFlags, FT_HANDLE *ftHandle) Parametery

pvArg1 Je závislé na dwFlags, ale bude normálně interpretováno jako pointer na nulou zakončený řetězec.

dwFlags FT_OPEN_BY_SERIAL_NUMBER,

FT_OPEN_BY_DESCRIPTION nebo FT_OPEN_BY_LOCATION.

ftHandle Ukazatel na proměnnou typu FT_HANDLE kde bude handle uloženo. Toto handle musí být použito pro přístup k zařízení.

Poznámky

Význam pvArg1 je závislý na dwFlags: jestliže dwFlags je FT_OPEN_BY_SERIAL_NUMBER, pvArg1 je interpretováno jako ukazatel na nulou ukončený řetězec který reprezentuje sériové číslo zařízení; jestliže dwFlags je FT_OPEN_BY_DESCRIPTION, je interpretováno jako ukazatel na nulou ukončený řetězec který reprezentuje popis zařízení; jestliže dwFlags je

FT_OPEN_BY_LOCATION, pvArg1 je interpretováno jako long číslo které obsahuje lokalizační ID zařízení. Windows CE and Linux nepodporují lokalizační IDs.

ftHandle je ukazatel na proměnnou typu FT_HANDLE kde je handle uloženo. Toto handle musí být použito pro přístup k zařízení.

Příklady

Příklady používají tyto proměnné.

FT_STATUS ftStatus;

FT_STATUS ftStatus2;

FT_HANDLE ftHandle1;

FT_HANDLE ftHandle2;

long dwLoc;

Otevření zařízení se sériovým číslem "FT000001"

ftStatus = FT_OpenEx("FT000001",FT_OPEN_BY_SERIAL_NUMBER,&ftHandle1);

// úspěch – zařízení se sériovým číslem "FT000001" je otevřeno }

else { // chyba }

Otevření zařízení s popisem "USB Serial Converter"

ftStatus = FT_OpenEx("USB Serial Converter",FT_OPEN_BY_DESCRIPTION,&ftHandle1);

// úspěch – zařízení s popisem "USB Serial Converter" je otevřeno }

else { // chyba }

(3)

Otevření 2 zařízení se sériovými čísly "FT000001" a "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) { // úspěch – obě zařízení jsou otevřena

} else {

// chyba – jedno nebo obě zařízení nejsou otevřena }

Otevření 2 zařízení s popisem "USB Serial Converter" a "USB Pump Controller"

ftStatus = FT_OpenEx("USB Serial Converter",FT_OPEN_BY_DESCRIPTION,&ftHandle1);

ftStatus2 = FT_OpenEx("USB Pump Controller",FT_OPEN_BY_DESCRIPTION,&ftHandle2);

} else {

Otevření zařízení na umístění 23

dwLoc = 0x23;

ftStatus = FT_OpenEx(dwLoc,FT_OPEN_BY_LOCATION,&ftHandle1);

// úspěch – zařízení na umístění 23 je otevřeno }

else { // chyba }

Otevření 2 zařízení na umístění 23 a 31

dwLoc = 0x23;

ftStatus = FT_OpenEx(dwLoc,FT_OPEN_BY_LOCATION,&ftHandle1);

dwLoc = 0x31;

ftStatus2 = FT_OpenEx(dwLoc,FT_OPEN_BY_LOCATION,&ftHandle2);

} else {

3. FT_Close

Zavře otevřené zařízení .

FT_STATUS FT_Close (FT_HANDLE ftHandle) Parametery

ftHandle Handle zařízení.

(4)

4. FT_ListDevices

Podává informace vztahující se k běžně připojeným zařízením.

Tato funkce může vracet informace jako je počet připojených zařízení, sériová čísla, popisy zařízení a lokalizační IDs připojených zařízení

.

FT_STATUS FT_ListDevices (PVOID pvArg1, PVOID pvArg2, DWORD dwFlags) Parametery

pvArg1 Je závislé na dwFlags.

pvArg2 Je závislé na dwFlags.

dwFlags Určuje formát vracené informace.

FT_LIST_NUMBER_ONLY = 0x80000000 FT_LIST_BY_INDEX = 0x40000000 FT_LIST_ALL = 0x20000000

FT_OPEN_BY_SERIAL_NUMBER = 1 FT_OPEN_BY_DESCRIPTION = 2 FT_OPEN_BY_LOCATION = 4

Poznámky

Tato funkce může být použita mnoha způsoby k získání různých druhů informací. Efektivnější způsob jak získat informace o zařízení je použít funkce FT_CreateDeviceInfoList , FT_GetDeviceInfoList a

FT_GetDeviceInfoDetail které dávají všechny informace o zařízení.

V této jednoduché podobě může být funkce použita pro zjištění počtu připojených zařízení. Jestliže FT_LIST_NUMBER_ONLY bit je nastaven v dwFlags, pak parametr pvArg1 je interpretován jako ukazatel na DWORD lokaci pro zapamatování počtu připojených zařízení.

Použití pro získání informací o zařízení: jestliže FT_OPEN_BY_SERIAL_NUMBER bit je nastaven v dwFlags, je vrácen řetězec se sériovým číslem; jestliže FT_OPEN_BY_DESCRIPTION bit je nastaven v dwFlags, je vrácen popis zařízení; jestliže FT_OPEN_BY_LOCATION bit je nastaven v dwFlags, bude vráceno lokalizační ID; jestliže žádný z těchto bitů není nastaven, je vrácen standardně řetězec se sériovým číslem.

Použití pro získání informačního řetězce o jednom zařízení. Jestliže FT_LIST_BY_INDEX a

FT_OPEN_BY_SERIAL_NUMBER nebo FT_OPEN_BY_DESCRIPTION bity jsou nastaveny v dwFlags, parametr pvArg1 je interpretován jako index zařízení a parametr pvArg2 je interpretován jako ukazatel na buffer obsahující příslušný řetězec. Indexy jsou od nuly, a error code FT_DEVICE_NOT_FOUND je vracen pro neplatný index.

Použití pro získání informačního řetězce o všech připojených zařízeních. Jestliže FT_LIST_ALL a FT_OPEN_BY_SERIAL_NUMBER nebo FT_OPEN_BY_DESCRIPTION bity jsou nastaveny v dwFlags, parametr pvArg1 je interpretován jako ukazatel na pole ukazatelů na buffery obsahující příslušné řetězce a parametr pvArg2 je interpretován jako ukazatel na DWORD lolokaci pro zapamatování počtu připojených zařízení. Nutno poznamenat, že pro pvArg1 poslední vložené pole ukazatelů na buffery může být NULL ukazatel, takže pole bude obsahovat o jednu lokaci navíc než je počet připojených zařízení.

Lokalizační ID zařízení je navráceno jestliže FT_LIST_BY_INDEX a FT_OPEN_BY_LOCATION bity jsou nastaveny v dwFlags. V tomto případě parametr pvArg1 je interpretován jako index zařízení a parametr pvArg2 je interpretován jako ukazatel na proměnnou typu long obsahující lokalizační ID. Indexy jsou číslovány od nuly, a error code FT_DEVICE_NOT_FOUND je vracen pro neplatný index.

Windows CE and Linux nepodporují lokalizační IDs.

(5)

Lokalizační IDs všech připojených zařízení jsou vracena jestliže FT_LIST_ALL a

FT_OPEN_BY_LOCATION bity jsou nastaveny v dwFlags. V tomto případě parametr pvArg1 je Interpretován jako ukazatel na pole proměnných typu long obsahujících lokalizační IDs, a parametr pvArg2 je interpretován jako ukazatel na DWORD lolokaci pro zapamatování počtu připojených zařízení.

Příklady

Příklady používají tyto proměnné.

.

FT_STATUS ftStatus;

DWORD numDevs;

Získání počtu připojených zařízení

ftStatus = FT_ListDevices(&numDevs,NULL,FT_LIST_NUMBER_ONLY);

// FT_ListDevices OK, počet připojených zařízení je v numDevs }

else {

// FT_ListDevices neúspěšné }

Získání sériového čísla prvního zařízení

DWORD devIndex = 0; // první zařízení char Buffer[64]; // dostatečný prostor!

ftStatus =

FT_ListDevices((PVOID)devIndex,Buffer,FT_LIST_BY_INDEX|FT_OPEN_BY_SERIAL_NUMBER);

// FT_ListDevices OK, sériové číslo je v Buffer }

else {

Nutno poznamenat, že indexy jsou číslovány od nuly. Jestliže je připojeno více zařízení, navýšený devIndex bude obsahovat počet všech připojených zařízení.

Získání popisu všech připojených zařízení

char *BufPtrs[3]; // ukazatel na pole třech ukazatelů char Buffer1[64]; // buffer pro popis prvního zařízení char Buffer2[64]; // buffer pro popis druhého zařízení // inicializace pole ukazatel?

BufPtrs[0] = Buffer1;

BufPtrs[1] = Buffer2;

BufPtrs[2] = NULL; // poslední by měl být NULL

ftStatus = FT_ListDevices(BufPtrs,&numDevs,FT_LIST_ALL|FT_OPEN_BY_DESCRIPTION);

// FT_ListDevices OK, popis je v Buffer1 a Buffer2, a // numDevs obsahuje počet připojených zařízení }

else {

Nutno poznamenat, že tento příklad předpokládá že jsou připojena dvě zařízení. Jestliže je připojeno více zařízení, pak velikost pole ukazatelů musí být zvětšena a musí být alokováno více bufferů pro popisy.

(6)

Získání umístění všech připojených zařízení

long locIdBuf[16];

ftStatus = FT_ListDevices(locIdBuf,&numDevs,FT_LIST_ALL|FT_OPEN_BY_LOCATION);

// FT_ListDevices OK, lokalizační IDs je v locIdBuf, a // numDevs obsahuje počet připojených zařízení }

else {

Nutno poznamenat, že tento příklad předpokládá, že je připojeno 16 zařízení. Jestliže je připojeno více zařízení pak velikost pole ukazatelů musí být zvětšena.

5. FT_Read

Čtení dat ze zařízení.

FT_STATUS FT_Read (FT_HANDLE ftHandle, LPVOID lpBuffer, DWORD dwBytesToRead, LPDWORD lpdwBytesReturned)

Parametery

ftHandle Handle zařízení.

lpBuffer Ukazatel na buffer, který přijme data ze zařízení.

dwBytesToRead Počet byte která mají být přečtena ze zařízení.

lpdwBytesReturned Ukazatel na proměnnou typu DWORD do které bude uložen počet byte přijatých ze zařízení.

FT_OK jestliže je vše v pořádku, FT_IO_ERROR v jiných případech.

Poznámky

FT_Read vždy vrací počet přečtených byte v lpdwBytesReturned.

Tato funkce není ukončena pokud počet byte dwBytesToRead není přečten do bufferu. Počet byte v přijímací frontě může být zjištěn voláním FT_GetStatus nebo FT_GetQueueStatus , a uložen do FT_Read jako dwBytesToRead tak že funkce přečte byte obsažené ve frontě v zařízení a je pak ihned ukončena.

Když je nastaven časový limit v předchozím volání FT_SetTimeouts , FT_Read je ukončena po uplynutí nastaveného času nebo když je přečten počet byte dwBytesToRead , podle toho co je dříve splněno.

Jestliže uplyne časový limit, FT_Read přečte data která má momentálně k dispozici do bufferu a vrací FT_OK.

Aplikace by měla používat návratovou hodnotu a lpdwBytesReturned když zpracovává buffer. Jestliže návratová hodnota je FT_OK, a lpdwBytesReturned se rovná dwBytesToRead pak FT_Read byla ukončena normálně. Jestliže návratová hodnota je FT_OK, a lpdwBytesReturned je menší než dwBytesToRead pak uplynul časový limit a čtení nebylo kompletní.

Nutno poznamenat, že při uplynutí časového limitu a při nepřečtení žádných dat je vráceno též FT_OK.

Návratová hodnota FT_IO_ERROR znamená chybu v parametrech funkce, nebo fatální chybu jako je odpojení USB.

(7)

Příklad

Tento příklad ukazuje jak přečíst všechna data která jsou k dispozici v zařízení.

FT_HANDLE ftHandle;

FT_STATUS ftStatus;

DWORD EventDWord;

DWORD TxBytes;

DWORD BytesReceived;

char RxBuffer[256];

ftStatus = FT_Open(0, &ftHandle); // Otevření zařízení if(ftStatus != FT_OK) {

// FT_Open neúspěšné return;

}

FT_GetStatus(ftHandle,&RxBytes,&TxBytes,&EventDWord); // Zjištění počtu dat v bufferech v zařízení if (RxBytes > 0) { // Přijímací buffer v zařízení není prázdný ftStatus = FT_Read(ftHandle,RxBuffer,RxBytes,&BytesReceived); //Přečti celý buffer

if (ftStatus == FT_OK) { // FT_Read OK

} else {

// FT_Read neúspěšné }

}

FT_Close(ftHandle);

Tento příklad ukazuje jak číst s časovým limitem 5 sekund.

FT_HANDLE ftHandle;

FT_STATUS ftStatus;

DWORD RxBytes = 10;

DWORD BytesReceived;

char RxBuffer[256];

ftStatus = FT_Open(0, &ftHandle); // Otevření zařízení if(ftStatus != FT_OK) {

// FT_Open neúspěšné return;

}

FT_SetTimeouts(ftHandle,5000,0); // Nastavení časového limitu

ftStatus = FT_Read(ftHandle,RxBuffer,RxBytes,&BytesReceived); //Přečti data if (ftStatus == FT_OK) {

if (BytesReceived == RxBytes) { // Byl přečten požadovaný počet dat ??

// FT_Read OK }

else {

// FT_Read Uplynul časový limit // Nebo uplynul časový limit ? }

} else {

// FT_Read neúspěšné }

FT_Close(ftHandle);

6. FT_Write

Zápis dat do zařízení.

FT_STATUS FT_Write (FT_HANDLE ftHandle, LPVOID lpBuffer, DWORD dwBytesToWrite, LPDWORD lpdwBytesWritten)

(8)

Parametery

lpBuffer Ukazatel na buffer který obsahuje data pro zápis do zařízení.

dwBytesToWrite Počet byte které budou zapsány do zařízení.

lpdwBytesWritten Ukazatel na proměnnou typu DWORD do které bude uložen počet byte zapsaných do zařízení.

FT_OK jestliže je vše v pořádku, v jiném případě je vrácena hodnota FT error code.

Poznámka

Jestliže data nejsou z bufferu zařízení odebírána dojde při třetím použití FT_Write k nahlášení chyby FT_IO_ERROR ! ! !

7. FT_ResetDevice

Tato funkce zasílá příkaz reset do zařízení.

FT_STATUS FT_ResetDevice (FT_HANDLE ftHandle) Parametery

8. FT_Purge

Tato funkce vyprázdní přijímací a vysílací buffer v zařízení.

FT_STATUS FT_Purge (FT_HANDLE ftHandle, DWORD dwMask) Parametery

dwMask Libovolná kombinace FT_PURGE_RX a FT_PURGE_TX.

Příklad

Tento příklad ukazuje jak vyprázdnit přijímací i vysílací buffer

FT_HANDLE ftHandle;

DWORD dwMask;

FT_STATUS ftStatus;

dwMask = FT_PURGE_RX || FT_PURGE_TX;

ftStatus = FT_Purge (FT_HANDLE ftHandle, DWORD dwMask);

9. FT_SetTimeouts

Tato funkce nastavuje časový limit pro čtení a zápis.

FT_STATUS FT_SetTimeouts (FT_HANDLE ftHandle, DWORD dwReadTimeout, DWORD dwWriteTimeout)

(9)

Parametery

ftHandle Handle zařízení.

dwReadTimeout Časový limit pro čtení v milisekundách.

dwWriteTimeout Časový limit pro zápis v milisekundách.

Příklad

Tento příklad ukazuje jak nastavit časový limit pro čtení 5 sekund a časový limit pro zápis 1 sekunda.

FT_HANDLE ftHandle;

FT_STATUS ftStatus;

ftStatus = FT_Open(0, &ftHandle);

if(ftStatus != FT_OK) { // FT_Open neúspěšné return;

}

ftStatus = FT_SetTimeouts(ftHandle,5000,1000);

if (ftStatus == FT_OK) { // FT_SetTimeouts OK }

else {

// FT_SetTimeouts neúspěšné }

FT_Close(ftHandle);

10. FT_GetQueueStatus

Získání počtu znaků (Byte) v přijímací frontě.

FT_STATUS FT_GetQueueStatus (FT_HANDLE ftHandle, LPDWORD lpdwAmountInRxQueue) Parametery

lpdwAmountInRxQueue Ukazatel na proměnnou typu DWORD do které se uloží počet znaků v přijímací frontě.

11. FT_SetBreakOn

Nastavení přerušovací podmínky pro zařízení.

FT_STATUS FT_SetBreakOn (FT_HANDLE ftHandle) Parametery

(10)

Příklad

Tento příklad ukazuje jak nastavit přerušovací podmínku pro zařízení.

FT_HANDLE ftHandle;

FT_STATUS ftStatus;

}

ftStatus = FT_SetBreakOn(ftHandle);

if (ftStatus == FT_OK) { // FT_SetBreakOn OK }

else {

// FT_SetBreakOn neúspěšné }

FT_Close(ftHandle);

12. FT_SetBreakOff

Nulování přerušovací podmínky pro zařízení.

FT_STATUS FT_SetBreakOff (FT_HANDLE ftHandle) Parametery

Příklad

Tento příklad ukazuje jak nulovat přerušovací podmínku pro zařízení.

FT_HANDLE ftHandle;

FT_STATUS ftStatus;

}

ftStatus = FT_SetBreakOff(ftHandle);

if (ftStatus == FT_OK) { // FT_SetBreakOff OK }

else {

// FT_SetBreakOff neúspěšné }

FT_Close(ftHandle);

13. FT_GetStatus

Získání stavu zařízení obsahující počet znaků v přijímací a vysílací frontě a aktuální stav zařízení.

FT_STATUS FT_GetStatus (FT_HANDLE ftHandle, LPDWORD lpdwAmountInRxQueue, LPDWORD lpdwAmountInTxQueue, LPDWORD lpdwEventStatus)

(11)

Parametery

lpdwAmountInRxQueue Ukazatel na proměnnou typu DWORD do které se uloží počet znaků v přijímací frontě.

lpdwAmountInTxQueue Ukazatel na proměnnou typu DWORD do které se uloží počet znaků ve vysílací frontě.

lpdwEventStatus Ukazatel na proměnnou typu DWORD do které se uloží stav zařízení.

Poznámky

Pro příklad jak použít tuto funlci se podívejte na kód v FT_SetEventNotification.

14. FT_SetEventNotification

Nastavení podmínek pro hlášení událostí.

FT_STATUS FT_SetEventNotification (FT_HANDLE ftHandle, DWORD dwEventMask, PVOID pvArg)

Parametery

dwEventMask Podmínka, která způsobí nastavení události.

pvArg Interpretováno jako handle události.

Poznámky

Aplikace může použít tuto funkci pro nastavení podmínky, která dovoluje blokovat plynulý chod programu až do doby, kdy je podmínka splněna. Typicky, aplikace vytvoří událost, volá tuto funkci a pak je blokována událostí. Když je podmínka splněna událost je nastavena a aplikace je odblokována.

dwEventMask je bitová-mapa která popisuje události, které zajímají aplikaci. pvArg je interpretováno jako handle událostí, které jsou vytvářeny aplikací. Jestliže jedna z podmínek je splněna pak je událost nastavena.

Jestliže FT_EVENT_RXCHAR je nastavena v dwEventMask, událost bude nastavena když znak byl přijat zařízením. Jestliže FT_EVENT_MODEM_STATUS je nastaven v dwEventMask, událost bude nastavena, když se v modemu změní signál detekující zařízení.

Windows a Windows CE příklad

Tento příklad ukazuje jak počkat na příjem znaku nebo změnu stavu modemu.

Nejdříve vytvoříme událost a zavoláme FT_SetEventNotification.

FT_HANDLE ftHandle; // handle otevřeného zařízení FT_STATUS ftStatus;

HANDLE hEvent;

DWORD EventMask;

hEvent = CreateEvent(

NULL,

false, // auto-reset událost false, // nesignalizovaný stav

""

(12)

);

EventMask = FT_EVENT_RXCHAR | FT_EVENT_MODEM_STATUS;

ftStatus = FT_SetEventNotification(ftHandle,EventMask,hEvent);

Někdy později (časem) se zablokuje chod aplikace a čeká se na událost, když událost nastane tak se pokračuje.

.

WaitForSingleObject(hEvent,INFINITE);

DWORD EventDWord;

DWORD RxBytes;

DWORD TxBytes;

FT_GetStatus(ftHandle,&RxBytes,&TxBytes,&EventDWord);

if (EventDWord & FT_EVENT_MODEM_STATUS) {

// jestliže je detekována událost na modemu, tak získej aktuální stav modemu FT_GetModemStatus(ftHandle,&Status);

if (Status & 0x00000010) { // CTS is high

} else {

// CTS is low }

if (Status & 0x00000020) { // DSR is high

} else {

// DSR is low }

}

if (RxBytes > 0) {

// volání FT_Read() umožní přijímat data ze zařízení }

15. FT_GetDeviceInfo

Získání informací o zařízení.

FT_STATUS FT_GetDeviceInfo (FT_HANDLE ftHandle, FT_DEVICE *pftType, LPDWORD lpdwID, PCHAR pcSerialNumber, PCHAR pcDescription,

PVOID pvDummy) Parametery

pftType Ukazatel na unsigned long pro zapamatování typu zařízení.

FT_DEVICE_BM FT_DEVICE_AM FT_DEVICE_100AX FT_DEVICE_UNKNOWN FT_DEVICE_2232C FT_DEVICE_232R

lpdwId Ukazatel na unsigned long pro zapamatování ID zařízení.

pcSerialNumber Ukazatel na buffer pro zapamatování sériového čísla jako nulou zakončeného řetězce.

pcDescription Ukazatel na buffer pro zapamatování popisu zařízení jako nulou zakončeného řetězce.

pvDummy Rezervováno pro budoucí použití – mělo by být nastaveno na NULL.

(13)

Poznámky

Tato funkce slouží pro získání typu zařízení, ID zařízení, popisu a sériového čísla.

ID zařízení je zakódováno v DWORD – nejvyšší slovo obsahuje vendor ID, a poslední slovo obsauhe product ID. Takže ID 0x04036001 koresponduje s IDzařízení VID_0403&PID_6001.

Příklad

Tento příklad ukazuje jak získat informace o zařízení.

FT_HANDLE ftHandle;

FT_DEVICE ftDevice;

FT_STATUS ftStatus;

DWORD deviceID;

char SerialNumber[16];

char Description[64];

}

ftStatus = FT_GetDeviceInfo(

ftHandle,

&ftDevice,

&deviceID, SerialNumber, Description, NULL

);

if (ftDevice == FT_DEVICE_2232C); // zařízení je FT2232C else if (ftDevice == FT_DEVICE_BM); // zařízení je FTU232BM else if (ftDevice == FT_DEVICE_AM); // zařízení je FT8U232AM else

; // neznámé zařízení (toto by nemělo nastat!) // deviceID obsahuje zakódované ID zařízení

// SerialNumber, Description obsahuje nulou zakončený řetězec }

else {

// FT_GetDeviceType neúspěšné!

}

FT_Close(ftHandle);

16. FT_CreateDeviceInfoList

Tato funkce vytváří informace o zařízení a vrací počet D2XX zařízení připojených do systému.

Přehled obsahuje otevřené i neotevřené zařízení .

FT_STATUS FT_CreateDeviceInfoList (LPDWORD lpdwNumDevs) Parametery

lpdwNumDevs Ukazatel na unsigned long pro uložení počtu připojených zařízení.

Poznámky

Aplikace může použít tuto funkci pro získání počtu zařízení připojených do systému. Pak může být alokován prostor pro seznam zařízení a jeho získání pomocí FT_GetDeviceInfoList .

Jestliže se zařízení připojené do systému změní, seznam zařízení se nezmění až do opětovného volání funkce FT_CreateDeviceInfoList.

(14)

Příklad

Tento příklad ukazuje jak volat FT_CreateDeviceInfoList.

FT_STATUS ftStatus;

DWORD numDevs;

//

// vytvoření seznamu zařízení //

ftStatus = FT_CreateDeviceInfoList(&numDevs);

printf("Počet zařízení je %d\n",numDevs);

} else {

// FT_CreateDeviceInfoList neúspěšné }

17. FT_GetDeviceInfoList

Tato funkce vrací seznam zařízení a počet D2XX zařízení v seznamu.

FT_STATUS FT_GetDeviceInfoList (FT_DEVICE_LIST_INFO_NODE *pDest, LPDWORD lpdwNumDevs)

Parametery

*pDest Ukazatel na pole FT_DEVICE_LIST_INFO_NODE strukturu.

lpdwNumDevs Ukazatel na počet prvků v poli.

typedef struct _ft_device_list_info_node { DWORD Flags;

DWORD Type;

DWORD ID;

DWORD LocId;

FT_HANDLE ftHandle;

} FT_DEVICE_LIST_INFO_NODE;

Poznámky

Tato funkce by měla být volána pouze po volání FT_CreateDeviceInfoList . Jestliže se zařízení připojené do systému změní, seznam zařízení se nezmění až do opětovného volání funkce FT_CreateDeviceInfoList .

Lokalizační ID není vráceno pro zařízení která jsou otevřena když FT_CreateDeviceInfoList je voláno.

Pole FT_DEVICE_LIST_INFO_NODES obsahuje všechna dostupná data na každé zařízení. Struktura FT_DEVICE_LIST_INFO_NODES je dána v příloze . Paměť pro seznam musí být alokována aplikací.

K tomu může být použit počet zařízení vrácený funkcí FT_CreateDeviceInfoList.

Jestliže programujeme ve Visual Basicu, LabVIEW nebo podobných jazycích, FT_GetDeviceInfoDetail Může být vyžadován na rozdíl od této funkce.

Windows CE and Linux nepodporují lokalizační IDs. Lokalizační ID parametr ve struktuře zůstane prázdný pod Windows CE a Linuxem.

(15)

Příklad

Tento příklad ukazuje jak volat FT_GetDeviceInfoList.

FT_STATUS ftStatus;

FT_DEVICE_LIST_INFO_NODE *devInfo;

DWORD numDevs;

//

printf("Number of devices is %d\n",numDevs);

} //

// alokování paměti pro seznam založená na numDevs //

devInfo = (FT_DEVICE_LIST_INFO_NODE*)malloc(sizeof(FT_DEVICE_LIST_INFO_NODE)*numDevs);

//

// získání seznamu zařízení //

ftStatus = FT_GetDeviceInfoList(devInfo,&numDevs);

for (int i = 0; i < numDevs; i++) { printf("Dev %d:\n",i);

printf(" Flags=0x%x\n",devInfo[i].Flags);

printf(" Type=0x%x\n",devInfo[i].Type);

printf(" ID=0x%x\n",devInfo[i].ID);

printf(" LocId=0x%x\n",devInfo[i].LocId);

printf(" SerialNumber=%s\n",devInfo[i].SerialNumber);

printf(" Description=%s\n",devInfo[i].Description);

printf(" ftHandle=0x%x\n",devInfo[i].ftHandle);

} }

18. FT_GetDeviceInfoDetail

Tato funkce vrací záznam seznamu zařízení.

FT_STATUS FT_GetDeviceInfoDetail (DWORD dwIndex, LPDWORD lpdwFlags, LPDWORD lpdwType, LPDWORD lpdwID, LPDWORD lpdwLocId, PCHAR pcSerialNumber, PCHAR pcDescription, FT_HANDLE *ftHandle)

Parametery

dwIndex Index záznamu v informačním seznamu zařízení.

lpdwFlags Ukazatel na unsigned long pro zapamatování návěští zařízení.

lpdwType Ukazatel na unsigned long pro zapamatování typu zařízení.

lpdwID Ukazatel na unsigned long pro zapamatování ID zařízení.

lpdwLocId Ukazatel na unsigned long pro zapamatování lokalizačního ID.

pcSerialNumber Ukazatel na buffer pro zapamatování sériového čísla zařízení jako nulou zakončený řetězec.

pcDescription Ukazatel na buffer pro zapamatování popisu zařízení jako nulou zakončený řetězec.

*ftHandle Ukazatel na proměnnou typu FT_HANDLE kde bude uloženo handle.

FT_OK jestliže je vše v pořádku, v jiném případě je vrácena hodnota FT error code Poznámky

Tato funkce by měla být volána pouze po volání FT_CreateDeviceInfoList . Jestliže se zařízení připojené do systému změní, seznam zařízení se nezmění až do opětovného volání funkce

FT_CreateDeviceInfoList.

(16)

Hodnota Index je počítána od nuly.

Hodnota návěští je 4-byte bitová mapa obsahující různá data. Bit 0 (poslední platný bit) tohoto čísla indikuje jestliže port je otevřený (1) nebo uzavřený (0). Zbývající bity (1 - 31) jsou v této chvíli rezervovány.

Lokalizační ID informace není vrácena pro zařízení, která jsou již otevřena když byla volána funkce FT_CreateDeviceInfoList.

Pro vrácení celého seznamu zařízení jako pole FT_DEVICE_LIST_INFO_NODE struktury, použijte FT_GetDeviceInfoList .

Windows CE a Linux nepodporují lokalizační IDs. Lokalizační ID parametr ve struktuře zůstane prázdný pod Windows CE a Linuxem .

Příklad

Tento příklad ukazuje jak volat FT_GetDeviceInfoDetail.

FT_STATUS ftStatus;

FT_HANDLE ftHandleTemp;

DWORD numDevs;

DWORD Flags;

DWORD ID;

DWORD Type;

DWORD LocId;

//

printf("Počet zařízení je %d\n",numDevs);

} //

// získání informací pro zařízení 0 //

ftStatus = FT_GetDeviceInfoDetail(0, &Flags, &Type, &ID, &LocId, SerialNumber, Description, &ftHandleTemp);

if (ftStatus == FT_OK) { printf("Dev 0:\n");

printf(" Flags=0x%x\n",Flags);

printf(" Type=0x%x\n",Type);

printf(" ID=0x%x\n",ID);

printf(" LocId=0x%x\n",LocId);

printf(" SerialNumber=%s\n",SerialNumber);

printf(" Description=%s\n",Description);

printf(" ftHandle=0x%x\n",ftHandleTemp);

}

19. FT_SetResetPipeRetryCount

Nastavení ResetPipeRetryCount.

FT_STATUS FT_SetResetPipeRetryCount (FT_HANDLE ftHandle, DWORD dwCount) Parametry

dwCount Unsigned long obsahující požadovaný ResetPipeRetryCount.

(17)

Funkce je použita pro ResetPipeRetryCount. ResetPipeRetryCount ovládá maximální velikost času po který zkouší driver resetovat pipe (komunikační kanál) na kterém nastala chyba.

ResetPipeRequestRetryCount je standardně 50. Může být nutné zvětšit tuto hodnotu v zašuměném (zarušeném) prostředí kde nastává mnoho USB chyb.

Příklad

Tento příklad ukazuje jak nastavit ResetPipeRetryCount na 100.

FT_HANDLE ftHandle; // platné handle získané z FT_OpenEx FT_STATUS ftStatus;

DWORD dwRetryCount;

dwRetryCount = 100;

ftStatus = FT_SetResetPipeRetryCount(ftHandle,dwRetryCount);

// ResetPipeRetryCount nastavena na 100 }

else {

// FT_SetResetPipeRetryCount neúspěšné!

}

20. FT_StopInTask

Přerušení činnosti driveru.

FT_STATUS FT_StopInTask (FT_HANDLE ftHandle) Parametry

ftHandle Handle zařízení.

Funkce je použita pro přerušení činnosti driveru (při čtení) a uvedení do čekacího stavu. Toto může být využito v situaci, kdy jsou průběžně přijímána data, tak že zařízení může být vyčištěno (vyprázdněno) bez dalšího příjmu dat. Používá se společně s FT_RestartInTask které obnoví další činnost driveru.

Příklad

Tento příklad ukazuje jak použít FT_StopInTask.

FT_HANDLE ftHandle;

FT_STATUS ftStatus;

} do {

ftStatus = FT_StopInTask(ftHandle);

} while (ftStatus != FT_OK);

//

// Nějaká činnost – například vyčištění front v zařízení //

do {

ftStatus = FT_RestartInTask(ftHandle);

FT_Close(ftHandle);

(18)

21. FT_RestartInTask

Obnovení činnosti driveru.

FT_STATUS FT_RestartInTask (FT_HANDLE ftHandle) Parametry

Tato funkce je používána pro obnovení činnosti driveru (čtení) poté co byla přerušena voláním funkce FT_StopInTask .

Příklad

Tento příklad ukazuje jak použít FT_RestartInTask.

FT_HANDLE ftHandle;

FT_STATUS ftStatus;

} do {

ftStatus = FT_StopInTask(ftHandle);

//

// Nějaká činnost – například vyčištění front v zařízení //

do {

ftStatus = FT_RestartInTask(ftHandle);

FT_Close(ftHandle);

22. FT_ResetPort

Zaslání resetovacího příkazu na port.

FT_STATUS FT_ResetPort (FT_HANDLE ftHandle) Parametry

Tato funkce je používána pro násilné uvolnění portu po chybě. Není to ekvivalent unplugreplug události.

Není k dispozici pro Windows CE a Linux.

Příklad

Tento příklad ukazuje jak resetovat port.

FT_HANDLE ftHandle; // platné handle získané z funkce FT_OpenEx FT_STATUS ftStatus;

(19)

ftStatus = FT_ResetPort(ftHandle);

if (ftStatus == FT_OK) { // Port bude resetován }

else {

// FT_ResetPort NEÚSPĚŠNÉ!

}

23. FT_CyclePort

Zaslání cyklovacího (obnovovacího) příkazu na USB port.

FT_STATUS FT_CyclePort (FT_HANDLE ftHandle) Parametry

FT_OK jestliže je vše v pořádku, v jiném případě je vrácena hodnota FT error code .

Poznámky

Účinek této funkce je stejný jako rozpojení a nové připojení zařízení do USB. Je možné použít tuto funkci v situaci, kdy nastala fatální chyba a je těžké, nebo nemožné obnovit činnost bez odpojení a opětovného připojení USB zařízení. Funkce může být též použita po přeprogramování EEPROM pro rychlé přečtení jejího nového obsahu.

Když je driver znovu nahráván, bežná nastavení nejsou obnovena a aplikace musí být schopná je obnovit po volání tétot funkce.

Není k dispozici pro Windows 98, Windows CE a Linux.

Pro FT2232C zařízení, FT_CyclePort bude pracovat jen pod Windows XP.

Příklad

Tento příklad ukazuje jak obnovit port.

FT_HANDLE ftHandle; // platné handle získané z funkce FT_OpenEx FT_STATUS ftStatus;

ftStatus = FT_CyclePort(ftHandle);

if (ftStatus == FT_OK) { // Port bude obnoven.

} else {

// FT_CyclePort NEÚSPĚŠNÉ!

}

24. FT_SetBaudRate

Tato funkce nastaví baudovou rychlost pro zařízení.

Určeno též pro BitBang mód pro stanovení rychlosti posunu příjmové a vysílací fronty = 16 * dwBaudRate [ms].

FT_STATUS FT_SetBaudRate (FT_HANDLE ftHandle, DWORD dwBaudRate) Parametery

dwBaudRate Baudová rychlost (maximální hodnota je 3000000) FT_BAUD_300

FT_BAUD_600 FT_BAUD_1200 FT_BAUD_2400

(20)

FT_BAUD_4800 FT_BAUD_9600 FT_BAUD_14400 FT_BAUD_19200 FT_BAUD_38400 FT_BAUD_57600 FT_BAUD_115200 FT_BAUD_230400 FT_BAUD_460800 FT_BAUD_921600

FT_OK jestliže je vše v pořádku, v jiném případě je vrácena hodnota FT error code.

25. ROZŠÍŘENÉ API Funkce

Úvod

FTDI FT232R USB UART (4th generace), FT245R USB FIFO (4th generace), FT2232C Dual USB UART/FIFO (3^rdgenerace), FT232BM USB UART (2^ndgenerace) a FT245BM USB FIFO (2nd generace) nabízí zvláštní funkce, obsahující programové návrhy vůči svým předchůdcům.

Programové rozšíření jsou podporovány rozšířeným D2XX driverem, a programovací rozhraní je v FTD2XX.DLL.

Přehled

Nové rozšíření obsahuje programovatelný časový limit pro přijímaci buffer a bit bang mód. Časový limit pro přijímaci buffer je řízený přes čekací dobu funkcí FT_GetLatencyTimer a FT_SetLatencyTimer.

Bit bang módy a další FT2232C bit módy jsou řízeny funkcemi FT_GetBitMode a FT_SetBitMode . Funkce mohou být zpřístupněny jestliže je zařízení otevřeno. Win32API funkce CreateFile, vrací handle, které je použito pro všechny funkce na identifikaci zařízení.

Odkaz

Typové definice funkčních parametrů a návratových kódů použitých v D2XX rozšířeném programovém rozhraní jsou obsaženy v dodatku .

25.1 FT_GetLatencyTimer

Získá aktuální hodnotu časového limitu časovače.

FT_STATUS FT_GetLatencyTimer (FT_HANDLE ftHandle, PUCHAR pucTimer) Parametry

pucTimer Ukazatel na unsigned char pro zapamatování hodnoty časového limitu časovače.

FT_OK jestliže je vše v pořádku, v jiném případě je vrácena hodnota FT error code

(21)

Poznámky

V FT8U232AM a FT8U245AM zařízeních, překročení časového limitu přijímacího bufferu je použito pro vy- prázdnění zbývajících dat z přijímacího bufferu a je nastaveno na 16 ms. Ve všech jiných FTDI zařízeních je časový limit programovatelný a může být nastaven po 1 ms mezi hodnotami 2ms až 255 ms. Toto dovoluje zlepšit optimalizaci zařízení pro protokoly vyžadující rychlejší reakci na krátké datové pakety.

Příklad

HANDLE ftHandle;

FT_STATUS ftStatus;

UCHAR LatencyTimer;

}

ftStatus = FT_GetLatencyTimer(ftHandle, &LatencyTimer);

// LatencyTimer obsahuje b?žnou (aktuální) hodnotu }

else {

// FT_GetLatencyTimer NEÚSPĚŠNÉ!

}

FT_Close(ftHandle);

25.2 FT_SetLatencyTimer

Nastaví hodnotu časového limitu časovače.

FT_STATUS FT_SetLatencyTimer (FT_HANDLE ftHandle, UCHAR ucTimer) Parametry

ucTimer Požadovaná hodnota v milisekundách. Platný rozsah je 2 - 255.

Poznámky

V FT8U232AM a FT8U245AM překročení časového limitu přijímacího bufferu je použito pro vyprázdnění zbývajících dat z přijímacího bufferu a je nastaveno na 16 ms. Ve všech jiných FTDI zařízeních je časový limit programovatelný a může být nastaven po 1 ms mezi hodnotami 2ms až 255 ms.. Toto dovoluje zlepšit optimalizaci zařízení pro protokoly vyžadující rychlejší reakci na krátké datové pakety.

Příklad

HANDLE ftHandle;

FT_STATUS ftStatus;

UCHAR LatencyTimer = 10;

}

ftStatus = FT_SetLatencyTimer(ftHandle, LatencyTimer);

// LatencyTimer nastaven na 10 milisekund }

else {

// FT_SetLatencyTimer NEÚSPĚŠNÉ!

}

FT_Close(ftHandle);

(22)

25.3 FT_GetBitMode

Získání okamžitého stavu datové sběrnice.

FT_STATUS FT_GetBitMode (FT_HANDLE ftHandle, PUCHAR pucMode) Parametry

pucMode Ukazatel na unsigned char pro uložení hodnoty bit módu.

Poznámky

Pro popis dostupných bit módů pro FT2232C, se podívej do aplikační poznámky "Bit Mode Functions for the FT2232C".

Pro popis Bit Bang Módu pro FT232BM a FT245BM, se podívej do aplikační poznámky

"FT232BM/FT245BM Bit Bang Mode".

Tyto aplikační poznámky jsou k dispozici na Application Notes stránkách v Documents sekci FTDI website.

Příklad

HANDLE ftHandle;

UCHAR BitMode;

FT_STATUS ftStatus;

}

ftStatus = FT_GetBitMode(ftHandle, &BitMode);

if (ftStatus == FT_OK) { // BitMode obsahuje aktuální hodnotu }

else {

// FT_GetBitMode NEÚSPĚŠNÉ!

}

FT_Close(ftHandle);

25.4 FT_SetBitMode

Nastavení hodnoty bit módu.

FT_STATUS FT_SetBitMode (FT_HANDLE ftHandle, UCHAR ucMask, UCHAR ucMode) Parametry

ftHandle Handle zařízení

ucMask Požadovaná hodnota pro bit mode masku. Toto nastavení určuje které bity jsou vstupní a které jsou výstupní. Bitová hodnota 0 nastavuje korespondující pin na vstup a hodnota 1 nastavuje korespondující pin na výstup. V případě CBUS Bit Bang, horní část této hodnoty řídí které piny jsou vstupní a které jsou výstupní. Dolní část řídí které výstupy jsou high a low.

ucMode Mode hodnota. Může být následující:

0x0 = Reset

0x1 = Asynchroní Bit Bang

0x2 = MPSSE (FT2232C pouze toto zařízení)

0x4 = Synchroní Bit Bang (FT232R, FT245R a FT2232C pouze tato zařízení) 0x8 = MCU Host Bus Emulační Mód (FT2232C pouze toto zařízení)

0x10 = Fast Opto-Isolated Serial Mode (FT2232C pouze toto zařízení) 0x20 = CBUS Bit Bang Mode (FT232R pouze toto zařízení)

(23)

FT_OK jestliže je vše v pořádku, v jiném případě je vrácena hodnota FT error code .

Poznámky

FT245BM, FT232BM

Jakákoliv data zapsaná do zařízení normálním způsobem budou ve stejném časovém intervalu předána na datové piny (platí pro piny které jsou naprogramovány jako výstupní). Každý pin může být nastaven jako vstupní, nebo výstupní nezávisle na jiných pinech. Rychlost předávání dat na výstup je dána baudovým generátorem. Tento je v FT245BM a v FT232BM.

Jestliže mají být zapsána na výstup nová data v daném časovém intervalu (baud) a data nejsou k dispozici, zůstanou piny ve stavu z předchozího zápisu.

Pro popis dostupných bit módů pro FT2232C, podívej se do aplikační poznámky "Bit Mode Functions for the FT2232C".

Pro popis Bit Bang módů dostupných pro FT232R a FT245R zařízení podívej se do aplikační poznámky

"Bit Bang Modes for the FT232R and FT245R".

Tyto aplikační poznámky jsou k dispozici na Application Notes stránkách v Documents sekci FTDI website.

.

Poznámka - použití CBUS Bit Bang pro FT232R, CBUS musí být konfigurováno pro CBUS Bit Bang v EEPROM.

Příklad

HANDLE ftHandle;

FT_STATUS ftStatus;

UCHAR Mask = 0xff;

UCHAR Mode = 1; // Nastaven asynchroní bit-bang mód ftStatus = FT_Open(0, &ftHandle);

}

ftStatus = FT_SetBitMode(ftHandle, Mask, Mode);

if (ftStatus == FT_OK) { // 0xff zapsáno do zařízení }

else {

// FT_SetBitMode NEÚSPĚŠNÉ!

}

FT_Close(ftHandle);

25.5 FT_SetUSBParameters

Nastavení USB požadavku na velikost přenosu.

FT_STATUS FT_SetUSBParameters (FT_HANDLE ftHandle, DWORD dwInTransferSize, DWORD dwOutTransferSize)

Parametry

dwInTransferSize Velikost přenosu USB při požadavku čtení.

dwOutTransferSize Velikost přenosu USB při požadavku zápisu.

Dříve byla USB velikost přenosu nastavena na 4096 byte a nebyla konfigurovatelná. Tato funkce může být použita pro změnu velikosti přenosu pro zlepšení uspokojení požadavků aplikace.

Nutno poznamenat, že je k dispozici pouze když je podporována dwInTransferSize.

(24)

HANDLE ftHandle;

FT_STATUS ftStatus;

DWORD InTransferSize = 16384;

}

ftStatus = FT_SetUSBParameters(ftHandle, InTransferSize, 0);

if (ftStatus == FT_OK) { // Vstupní velikost přenosu je 16 Kbytes }

else {

// FT_SetUSBParameters NEÚSPĚŠNÉ!

}

FT_Close(ftHandle);

26. Dodatek

Některé typové definice FT_STATUS (DWORD) FT_OK = 0

FT_INVALID_HANDLE = 1 FT_DEVICE_NOT_FOUND = 2 FT_DEVICE_NOT_OPENED = 3 FT_IO_ERROR = 4

FT_INSUFFICIENT_RESOURCES = 5 FT_INVALID_PARAMETER = 6 FT_INVALID_BAUD_RATE = 7

FT_DEVICE_NOT_OPENED_FOR_ERASE = 8 FT_DEVICE_NOT_OPENED_FOR_WRITE = 9 FT_FAILED_TO_WRITE_DEVICE = 10

FT_EEPROM_READ_FAILED = 11 FT_EEPROM_WRITE_FAILED = 12 FT_EEPROM_ERASE_FAILED = 13 FT_EEPROM_NOT_PRESENT = 14 FT_EEPROM_NOT_PROGRAMMED = 15 FT_INVALID_ARGS = 16

FT_NOT_SUPPORTED = 17 FT_OTHER_ERROR = 18