FPC - Převodník pro čínské čtečky F17 a F18 - podrobný popis služeb a příkazů -

Transkript

1 FPC - Převodník pro čínské čtečky F17 a F18 - podrobný popis služeb a příkazů - verze 1.0, Jiří Libra, jiri.libra@gmail.com Příkazy služby FPCManagement Formát dat služby FPCManagement v protokolu Elvis/P4: příkaz: < 0x4A > < 8-bit kód_příkazu > [< in_data >] odpověď: < 0xCA > < 8-bit kód_příkazu > [< out_data >] kód_příkazu viz příloha A, v odpovědi je zkopírován beze změny in_data, out_data data závislá na příkazu, specifikace viz níže Kódování vícebajtových parametrů se provádí stejně jako v protokolu P4, tj. MSB first, big-endian. Parametry <32-bit ID> jsou vždy kódovány pro přenost symetrickou šifrou prohazující pořadí bitů v nibblech. Tj. každý bajt přejde z ABCDEFGH na DCBAHGFE. Platí jak pro ID karet, tak pro ID otisků. FP_cmd_raw libovolná binární data k vyslání, max. délka 255 B přijatá binární data, max. délka 128 B Vyšle binární data na linku čtečky RS485 a vrátí odpověď do max. délky 128 B. Vysílaná data mohou mít libovolnou délku, která se vejde do jednoho P4 packetu. Lze použít na odeslání příkazů čtečky, které nepodporuje převodník, je však potřeba odeslat kompletní packet včetně hlavičky. FP_cmd_getFType řetězec s detekovaným typem čtečky Provede autodetekci a vrátí řetězec s typem čtečky. Možné návratové hodnoty jsou: 'F17', 'F18', 'UNKNOWN'. FP_cmd_getEdition <32-bit edition_number> Vrátí číslo verze čtečky.

2 FP_cmd_getSerial <32-bit serial_number> Vrátí sériové číslo čtečky. FP_cmd_findFpId <32-bit ID> - Zahájí hledání otisků určitého ID uživatele v seznamu otisků čtečky. FP_cmd_listFoundIndices <8-bit success> [<8-bit count> count x <16-bit index>] success: 0 hotovo, další data obsahují počet a seznam nalezených indexů 1 chyba, seznam je neplatný, nebyl načten, atd. 2 prohledávání dosud probíhá Vrací výsledek hledání zahájeného příkazem FP_cmd_findFpId. Pokud je parameter success=2, hledání dosud probíhá a je třeba poslat příkaz FP_cmd_listFoundIndices znovu. Je-li success=0, operace hledání úspěšně skončila a seznam obsahuje indexy otisků, které byly pro dané ID nalezeny. Pomocí těchto indexů se lze stáhnout data jednotlivých otisků. FP_cmd_prepareFp <16-bit index> - Zahájí načítání dat otisku z daného indexu. Data ukládá do vnitřního bufferu a komprimuje metodou RLE-FF, viz. příloha B. Operace trvá zhruba 1 s. Buffer je sdílený, proto je třeba po načtení data přečíst následujícími příkazy, dokud jsou platná. FP_cmd_isFpReady <8-bit ready> [<16-bit size> <16-bit crc16>] ready: 0 operace úspěšně skončila 1 operace dosud probíhá size: délka zkomprimovaných dat otisku crc16: kontrolní crc dat, algoritmus výpočtu stejný jako v protokolu P4 Vrací výsledek načítání dat otisku zahájeného příkazem FP_cmd_prepareFp. Je-li operace dokončena, vrací délku dat v bufferu a jejich kontrolní součet. Je-li parametr ready=1, operace probíhá a je třeba příkaz FP_cmd_isFpReady zaslat znovu.

3 FP_cmd_getDataSegment <16-bit offset> <8-bit length> <16-bit offset> <8-bit out_length> out_length x <8-bit data> offset < 1008 offset+length <= 1008 length <= 255 out_length <= length Příkaz pošle část obsahu vnitřního bufferu na linku P4. Parametr offset je adresa dat v bufferu, length je délka žádaných dat. Díky kódování protokolu P4 a neznalosti obsahu bufferu nelze z nadřazeného systému určit, jak velká data se vejdou do packetu P4. Proto lze parametrem length zažádat o data délky až 255, příkaz data připraví a odešle pouze takový počet, který lze aktuálně zakódovat do packetu P4. Odesláný počet vrátí v parametru out_length. Délka vnitřního bufferu je 1kB (vč. 16 B pro hlavičku, příkaz a parametry, tj. pro data B), nelze žádat o data mimo tento buffer. Délka nekomprimovaných a nekódovaných dat otisku je 816B. FP_cmd_writeDataSegment <16-bit offset> count x <8-bit data> <8-bit success> success: 0 data uložena 1 chyba, data se nevešla do bufferu Příkaz zapíše data do bufferu od adresy offset. Počet dat count není součástí příkazu, zapíšou se všechna přijatá data. FP_cmd_storeFp <16-bit size> <16-bit crc16> <8-bit success> success: 0 data odeslána do čtečky 1 chyba crc Odešle data z bufferu jako otisk do čtečky. Je třeba specifikovat délku dat a oveřit jejich obsah pomocí crc16. Data musí být před tím nahrána do bufferu příkazy FP_cmd_writeDataSegment. Data v bufferu musí být komprimovaná metodou RLE-FF (viz příloha B). Zápis trvá zhruba 1 s. Buffer je sdílený, proto je třeba otisk odeslat ihned po načtení dat do bufferu. FP_cmd_getFpResult <8-bit success> success: 0 OK 1 komunikace/příkaz dosud probíhá 2 chyba komunikace se čtečkou >2 jiná chyba čtečky, kód určuje čtečka v závislosti na příkazu Tento příkaz ověří úspěšné vykonání některých příkazů, např. zápis otisku do čtečky příkazem FP_cmd_storeFp nebo registraci nového otisku příkazem FP_cmd_registerFp.

4 FP_cmd_deleteFp <32-bit ID> <8-bit success> success: 0 OK >0 error Smaže otisky pro dané ID uživatele, tj. všechny jeho otisky. FP_cmd_deleteAllFps <8-bit success> success: 0 OK >0 error Smaže všechny otisky ve čtečce. FP_cmd_registerFp <32-bit ID> - Zaregistruje otisk prstu pod zadané ID. Prst musí být v tu chvíli přiložen na čtečce nebo se musí přiložit do 5 s od vyslání příkazu. Příkaz vrací prázdnou odpověď okamžitě. Stav registrace lze skenovat příkazem FP_cmd_getFpResult. Jeho návratový parameter success má potom následující význam: 0x00 - otisk úspěšně zaregistrován 0x01 čeká se na přiložení prstu (zhruba 5 s) 0x08 vypršel čas k přiložení prstu, otisk nebyl zaregistrován 0x0A špatné ID pro registraci (0 nebo 0xffffffff) 0x20 chyba otisku, patrně je shodný s nějakým již uloženým ve čtečce FP_cmd_getFpCount <16-bit count> <16-bit capacity> Vrátí počet count naučených otisků, tj. číslo >= počtu naučených ID uživatelů. Parametr capacity je kapacita paměti na otisky. U čteček F17 a F18 je fixně 3584 (0xE00) otisků. FP_cmd_test <8-bit subject> <8-bit result> subject: 1 Image sensor 2 Memory 3 Code result: 0 OK >0 error Self-testy čtečky. Provádějí se i při každém zapnutí čtečky.

5 FP_cmd_getGain <8-bit gain> gain: hodnoty 1, 2, 4 nebo 8, defaultně 4 Vrátí nastavený zisk senzoru. FP_cmd_setGain <8-bit gain> - gain: hodnoty 1, 2, 4 nebo 8, defaultně 4 Nastaví zisk senzoru. FP_cmd_getDegree <8-bit comparison><8-bit identification> comparison: hodnoty 1 až 9, defaultně 1 identification: hodnoty 1 až 9, defaultně 5 Vrátí nastavené stupně porovnávání a identifikace otisků. FP_cmd_setDegree <8-bit comparison><8-bit identification> - comparison: hodnoty 1 až 9, defaultně 1 identification: hodnoty 1 až 9, defaultně 5 Nastaví stupně porovnávání a identifikace otisků. FP_cmd_getSampleMode <8-bit mode> mode: 0 normal (před otiskem je nutné aktivovat senzor klávesou #) 2 auto (senzor je aktivní neustále) Vrátí nastavený mód vzorkování senzoru otisků. FP_cmd_setSampleMode <8-bit mode> - mode: 0 normal (před otiskem je nutné aktivovat senzor klávesou #) 2 auto (senzor je aktivní neustále) Nastaví mód vzorkování senzoru otisků.

6 FP_cmd_formatC2queue neodpovídá, restartuje firmware Zformátuje eeprom frontu pro odesílání událostí službou P4 0xC2. Označí všechny záznamy jako smazané. Není třeba použít, pokud je po naprogramování firmwaru paměť eeprom nastavena na hodnoty 0xFF, tj. nenaprogramovaná. FP_cmd_isCardExist <32-bit ID> <8-bit result> result: 0x00 ID nalezeno 0x01 chyba komunikace se čtečkou 0x0A ID nenalezeno Otestuje, zda se dané ID nachází v seznamu karet ve čtečce. FP_cmd_importCard <32-bit ID> <8-bit result> result: Naučí čtečku novou kartu se zadaným ID. FP_cmd_deleteCard <32-bit ID> <8-bit result> result: Smaže kartu se zadaným ID ze čtečky. FP_cmd_deleteAllCards <8-bit result> result: Smaže všechny karty ze čtečky. 0x00 ID uloženo 0x01 chyba komunikace se čtečkou 0x05 ID karty již ve čtečce existuje 0x0A ID neplatné (0 nebo 0xffffffff) 0x00 OK, smazáno 0x01 chyba komunikace se čtečkou 0x0A ID nenalezeno 0x00 OK, smazáno 0x01 chyba komunikace se čtečkou

7 FP_cmd_getCardCount <16-bit count> <16-bit capacity> Vrátí počet count naučených karet. Parametr capacity je kapacita paměti pro karty. U čteček F17 a F18 je fixně 3072 (0xC00) karet. FP_cmd_cardFpResolution <8-bit fp_resolution> - fp_resolution:0 rozlišuj karty a otisky 1 nerozlišuj karty a otisky Nastaví rozlišování mezi otisky a kartami. Přidává 5. bajt před ID, 0x08 je pro karty, 0x09 pro otisky. Pokud nerozlišujeme, pak přidává vždy 0x08. Reálně rozlišovat umí pouze čtečka typu F18. Typ F17 považuje detekované ID vždy za otisk, tj. přidává 0x09, pokud rozlišujeme nebo 0x08 pokud nerozlišujeme. Platí pro služby 0xFC i 0xC2. Ostatní implementované P4 služby převodníku Echo <cokoliv> <cokoliv> Echo, test komunikace, vrací zaslaná data. SetRTCCurrentTime <ww><yyyy><mm><dd><hh><mm><ss><cc> - Nastaví čas. Převodník nemá vlastní RTC, čas nastaví ve čtečce F18 a časy událostí získává z jejího logu. V případě použití čtečky F17 budou všechna pole času v událostech rovna 0. Čtečka F18 umí pouze krátký formát roku, tj. vždy 20YY. Čas ze čtečky F17 tedy bude vždy :00:00. SetImmediateRFSend <8-bit value> - value: Nastaví druh služby pro posílání událostí. 0 posílá události službou 0xC2 1 posílá události službou 0xFC

8 ClearRecord - Zastaví aktuální vysílání událostí služeb 0xFC a 0xC2 a u služby 0xC2 smaže poslední záznam z paměti a přejde na vysílání dalšího, pokud je k dispozici. SetAliveDestination <16-bit address> - Nastaví adresu pro zasílání vynucených zpráv. GetAliveDestination <16-bit address> Vrátí adresu pro zasílání vynucených zpráv. SetCommAddress <16-bit address> - Nastaví vlastní adresu zařízení v protokolu P4. GetSWVersion <major_version>< minor_version><yyyy><mm><dd><0x00><0x00><0x00> <description_string> Vrací verzi, datum a označení firmware. SetAliveMsgTime <8-bit interval> - Nastavuje interval periodického vysílání služeb 0xC2 a 0xFC. Parametr interval je v desetinách sekundy, čili interval=10 znamená jednu sekundu. FPCManagement Viz výše. Reset neodpovídá, restartuje firmware Slouží k restartu firmwaru. Realizuje se nekonečnou smyčkou a spuštěním watch-dog timeru, čili mikrokontrolér se restartuje hardwarově, tj. s veškerou hardwarovou inicializací jako po startu.

9 Nevyžádané zprávy Služba 0xC2 <8-bit ID_prefix> <32-bit ID> <WW><YYYY><MM><DD><hh><mm><ss> ID_prefix: 8 nebo 9, dle nastavení příkazem FP_cmd_cardFpResolution ID: ID karty nebo otisku, zakódované prohozením pořadí bitů v nibblech WW: den v týdnu, není podporován, vždy vrací 0xff YYYY/MM/DD hh:mm:ss datum a čas události Vysílá zprávu o události. První pokus je odeslán ihned, zpráva se opakuje v intervalu nastaveném příkazem SetAliveMsgTime. Zprávy se řadí do fronty a postupně vysílají. Poslední zpráva se odesílá neustále, dokud není potvrzena a vymazána z fronty službou ClearRecord. Události jsou zálohovány pro případ výpadu proudu v eeprom paměti a po startu se začnou opět automaticky vysílat od nejstarší po nejnovější. Typ čtečky F17 neumí čas, proto všechna pole času budou rovna 0, rok bude Odesílání packetu je chráněno antikolizním timeoutem 100 ms, který zajistí nepřerušení probíhající komunikace na lince P4. Služba 0xFC <8-bit ID_prefix> <32-bit ID> ID_prefix: 8 nebo 9, dle nastavení příkazem FP_cmd_cardFpResolution ID: ID karty nebo otisku, zakódované prohozením pořadí bitů v nibblech Vysílá zprávu o události. První pokus je odeslán ihned, zpráva se opakuje v intervalu nastaveném příkazem SetAliveMsgTime. Zprávu odešle 5x. Zasílání lze zastavit službou ClearRecord. Událost není zálohovaná pro případ výpadu proudu. Odesílání packetu je chráněno antikolizním timeoutem 100 ms, který zajistí nepřerušení probíhající komunikace na lince P4. Služba 0xFE FirmwareStarted <0x02> Vyšle <0xFE><0x02> po startu či restartu firmware.

10 Příloha A Přehledný seznam příkazů a jejich kódů raw cmomunication FP_cmd_raw detection FP_cmd_getFType FP_cmd_getEdition FP_cmd_getSerial 0x01 0x12 0x02 0x03 data = raw packet to fp's rs485 line, answer = fp's line answer answer = "F17" or "F18" or "UNKNOWN" answer = firmware version / edition answer = serial downloading of FingerPrint FP_cmd_findFpId 0x04 FP_cmd_listFoundIndices FP_cmd_prepareFp FP_cmd_isFpReady FP_cmd_getDataSegment 0x05 0x06 0x07 0x08 data = <32-bit ID> answer = <SUCCESS 8-bit 0=OK, >0 error (1=not requested or list lost, 2=reading/inProgress)> [<COUNT 8-bit> count*<found index 16-bit>] data = <16-bit index> answer = <8-bit READY, 1=not ready, 0=ready> [<16-bit SIZE> <data CRC16 like on P4>] data = <16-bit OFFSET> <8-bit LENGTH>, answer=<data, size<=length> uploading of FingerPrint FP_cmd_writeDataSegment FP_cmd_storeFp FP_cmd_getStoreFpResult 0x09 data = <16-bit OFFSET> <DATA>, answer = <0=OK, 1=Error/Buffer overflow> 0x0A data = <16-bit SIZE> <CRC16 of data>, answer = <0=OK, 1=crc error> 0x0B answer = <0=OK, >0 is Error> other FingerPrint management FP_cmd_deleteFp 0x0C FP_cmd_deleteAllFps 0x0D FP_cmd_registerFp 0x0E FP_cmd_getFpCount 0x0F data = <32-bit ID>, answer = <0=OK, >0 Error> answer = <0=OK, >0 Error> data = <32-bit ID>, answer = <0=OK, >0 Error> answer = <16-bit count><16-bit capacity> settings FP_cmd_test 0x10 data=<8-bit what, 1=ImageSensing, 2=Memory, 3=Code>, answer=<8 bit, 0=OK> FP_cmd_getGain 0x13 answer = <8-bit gain>, gain = 1, 2, 4 or 8, default = <4> FP_cmd_setGain 0x14 data = <8-bit gain> FP_cmd_getDegree 0x15 answer = <8-bit comparison><8-bit identification>, values 1..9, default = <1><5> FP_cmd_setDegree 0x16 data = <8-bit comparison><8-bit identification> FP_cmd_getSampleMode 0x17 answer = <8-bit, 0=Normal, 2=Auto> FP_cmd_setSampleMode 0x18 data = <8-bit, 0=Normal, 2=Auto> FP_cmd_formatC2queue 0x1F formats eeprom C2 queue - use after firmware load, if eeprom content is not 0xff card management FP_cmd_isCardExist 0x19 data = <32-bit ID>, answer=<00=ok, 0Ah=not exists> FP_cmd_importCard FP_cmd_deleteCard 0x1A 0x1B data = <32-bit ID>, answer=<00=ok, 0Ah=error (bad ID - 0 or 0xffffffff), 05=card already exists> data = <32-bit ID>, answer=<00=ok, 0Ah=error - not exists> FP_cmd_deleteAllCards 0x1C answer = <0=OK, 1=Error> FP_cmd_getCardCount 0x1D answer = <16-bit count><16-bit capacity> FP_cmd_cardFpResolution 0x1E data = <0 = 08 is fingerprint, 09 is card; 1 = no resolution, 5th byte is 08>

11 Příloha B Metoda komprimace RLE-FF Komprimace: blok znaků 0xFF se zakóduje dvojicí <0xFF><počet>, kde počet musí být 1 až 255 jeli blok delší než 255, musí se zakódovat do několika dvojic ostatní znaky se nekódují, jen kopírují Dekomprimace: při znaku 0xFF na vstupu načti další bajt jako počet a do výstupu zapiš blok znaků 0xFF o délce počet. ostatní znaky kopíruj ze vstupu na výstup beze změny Příklady: (všechna tučná data jsou hexadecimálně) data: komprimovaná data: FF FF FF FF FF FF <blok 255 znaků FF> FF FF <blok 256 znaků FF> FF FF FF 01 <blok 511 znaků FF> FF FF FF FF FF 01