FPC - Převodník pro čínské čtečky F17 a F18 - podrobný popis služeb a příkazů verze 1.0, 16.5.2011 Jiří Libra,
[email protected]
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 vstup: výstup:
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 vstup: výstup:
ř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 vstup: výstup:
<32-bit edition_number>
Vrátí číslo verze čtečky.
FP_cmd_getSerial vstup: výstup:
<32-bit serial_number>
Vrátí sériové číslo čtečky.
FP_cmd_findFpId vstup: výstup:
<32-bit ID> -
Zahájí hledání otisků určitého ID uživatele v seznamu otisků čtečky.
FP_cmd_listFoundIndices vstup: výstup:
<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 vstup: výstup:
<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 vstup: výstup:
<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.
FP_cmd_getDataSegment vstup: výstup:
<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 1024-16 B), nelze žádat o data mimo tento buffer. Délka nekomprimovaných a nekódovaných dat otisku je 816B.
FP_cmd_writeDataSegment vstup: výstup:
<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 vstup: výstup:
<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 vstup: výstup:
<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.
FP_cmd_deleteFp vstup: výstup:
<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 vstup: výstup:
<8-bit success> success: 0 – OK >0 – error
Smaže všechny otisky ve čtečce.
FP_cmd_registerFp vstup: výstup:
<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 vstup: výstup:
<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 vstup: výstup:
<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.
FP_cmd_getGain vstup: výstup:
<8-bit gain> gain: hodnoty 1, 2, 4 nebo 8, defaultně 4
Vrátí nastavený zisk senzoru.
FP_cmd_setGain vstup: výstup:
<8-bit gain> gain: hodnoty 1, 2, 4 nebo 8, defaultně 4 Nastaví zisk senzoru.
FP_cmd_getDegree vstup: výstup:
<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 vstup: výstup:
<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 vstup: výstup:
<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 vstup: výstup:
<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ů.
FP_cmd_formatC2queue vstup: výstup:
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 vstup: výstup:
<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 vstup: výstup:
<32-bit ID> <8-bit result> result: 0x00 – ID uloženo 0x01 – chyba komunikace se čtečkou 0x05 – ID karty již ve čtečce existuje 0x0A – ID neplatné (0 nebo 0xffffffff)
Naučí čtečku novou kartu se zadaným ID.
FP_cmd_deleteCard vstup: výstup:
<32-bit ID> <8-bit result> result: 0x00 – OK, smazáno 0x01 – chyba komunikace se čtečkou 0x0A – ID nenalezeno
Smaže kartu se zadaným ID ze čtečky.
FP_cmd_deleteAllCards vstup: výstup:
<8-bit result> result: 0x00 – OK, smazáno 0x01 – chyba komunikace se čtečkou
Smaže všechny karty ze čtečky.
FP_cmd_getCardCount vstup: výstup:
<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 vstup: výstup:
<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 vstup: výstup:
Echo, test komunikace, vrací zaslaná data.
SetRTCCurrentTime vstup: výstup:
<ww><MM><mm><ss> -
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 2000-00-00 00:00:00.
SetImmediateRFSend vstup: výstup:
<8-bit value> value: 0 – posílá události službou 0xC2 1 – posílá události službou 0xFC
Nastaví druh služby pro posílání událostí.
ClearRecord vstup: výstup:
-
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 vstup: výstup:
<16-bit address> -
Nastaví adresu pro zasílání vynucených zpráv.
GetAliveDestination vstup: výstup:
<16-bit address>
Vrátí adresu pro zasílání vynucených zpráv.
SetCommAddress vstup: výstup:
<16-bit address> -
Nastaví vlastní adresu zařízení v protokolu P4.
GetSWVersion vstup: výstup:
<major_version>< minor_version><MM><0x00><0x00><0x00> <description_string>
Vrací verzi, datum a označení firmware.
SetAliveMsgTime vstup: výstup:
<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 vstup: výstup:
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.
Nevyžádané zprávy Služba 0xC2 výstup:
<8-bit ID_prefix> <32-bit ID> <WW><MM><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 2000. 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 výstup:
<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 výstup:
<0x02>
Vyšle <0xFE><0x02> po startu či restartu firmware.
Příloha A – Přehledný seznam příkazů a jejich kódů raw cmomunication FP_cmd_raw
0x01
data = raw packet to fp's rs485 line, answer = fp's line answer
detection FP_cmd_getFType FP_cmd_getEdition FP_cmd_getSerial
0x12 0x02 0x03
answer = "F17" or "F18" or "UNKNOWN" answer = firmware version / edition answer = serial
downloading of FingerPrint FP_cmd_findFpId 0x04 FP_cmd_listFoundIndices
0x05
FP_cmd_prepareFp FP_cmd_isFpReady FP_cmd_getDataSegment
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*] data = <16-bit index> answer = <8-bit READY, 1=not ready, 0=ready> [<16-bit SIZE> ] data = <16-bit OFFSET> <8-bit LENGTH>, answer=
uploading of FingerPrint FP_cmd_writeDataSegment FP_cmd_storeFp FP_cmd_getStoreFpResult
0x09 0x0A 0x0B
data = <16-bit OFFSET> , answer = <0=OK, 1=Error/Buffer overflow> data = <16-bit SIZE> , answer = <0=OK, 1=crc error> 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 = answer data = answer
settings FP_cmd_test FP_cmd_getGain FP_cmd_setGain FP_cmd_getDegree FP_cmd_setDegree FP_cmd_getSampleMode FP_cmd_setSampleMode FP_cmd_formatC2queue
0x10 0x13 0x14 0x15 0x16 0x17 0x18 0x1F
data=<8-bit what, 1=ImageSensing, 2=Memory, 3=Code>, answer=<8 bit, 0=OK> answer = <8-bit gain>, gain = 1, 2, 4 or 8, default = <4> data = <8-bit gain> answer = <8-bit comparison><8-bit identification>, values 1..9, default = <1><5> data = <8-bit comparison><8-bit identification> answer = <8-bit, 0=Normal, 2=Auto> data = <8-bit, 0=Normal, 2=Auto> formats eeprom C2 queue - use after firmware load, if eeprom content is not 0xff
card management FP_cmd_isCardExist
0x19
FP_cmd_importCard
0x1A
FP_cmd_deleteCard FP_cmd_deleteAllCards FP_cmd_getCardCount FP_cmd_cardFpResolution
0x1B 0x1C 0x1D 0x1E
data = <32-bit ID>, answer=<00=OK, 0Ah=not exists> 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> answer = <0=OK, 1=Error> answer = <16-bit count><16-bit capacity> data = <0 = 08 is fingerprint, 09 is card; 1 = no resolution, 5th byte is 08>
<32-bit ID>, answer = <0=OK, >0 Error> = <0=OK, >0 Error> <32-bit ID>, answer = <0=OK, >0 Error> = <16-bit count><16-bit capacity>
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:
20 30 40
20 30 40
FF
FF 01
20 FF FF FF 20
20 FF 03 20
FF FF
FF FF FF 01
FF FF FF FF FF 01
