FPC - Převodník pro čínské čtečky F17 a F18

FPC - Převodník pro čínské čtečky F17 a F18
- podrobný popis služeb a příkazů verze 1.1, 17.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 0x00
vstup:
výstup:
<cokoliv>
<cokoliv>
Echo, test komunikace, vrací zaslaná data.
SetRTCCurrentTime 0x02
vstup:
výstup:
<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 2000-00-00 00:00:00.
SetImmediateRFSend 0x19
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 0x20
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 0x2D
vstup:
výstup:
<16-bit address>
-
Nastaví adresu pro zasílání vynucených zpráv.
GetAliveDestination 0x2E
vstup:
výstup:
<16-bit address>
Vrátí adresu pro zasílání vynucených zpráv.
SetCommAddress 0x2F
vstup:
výstup:
<16-bit address>
-
Nastaví vlastní adresu zařízení v protokolu P4.
GetSWVersion 0x30
vstup:
výstup:
<major_version>< minor_version><YYYY><MM><DD><0x00><0x00><0x00>
<description_string>
Vrací verzi, datum a označení firmware.
SetAliveMsgTime 0x34
vstup:
výstup:
[<8-bit interval_min> [<8-bit interval_max>]]
interval_min – minimální interval v desetinách sekundy, defaultní hodnota 5 s
interval_max – maximální interval v desetinách sekundy, defaultní hodnota 25 s
Nastavuje interval periodického vysílání služeb 0xC2 a 0xFC. Parametry jsou v desetinách sekundy,
pokud není parametr uveden, použije se defaultní hodnota. Minimální možné hodnoty jsou 0,2 s,
maximální 25,5 s.
SetEventType 0x48
vstup:
výstup:
<8-bit type>
-
Nastaví hodnotu VV pro služby 0xFC a 0xC2. Hodnota VV se určí dle vztahu VV = 0x81 + 2*type.
FPCManagement 0x4A
Viz výše.
Reset 0x62
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> <VV><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
VV:
typ události, nastavuje se službou SetEventType
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:
<VV> <8-bit ID_prefix> <32-bit ID>
VV:
typ události, nastavuje se službou SetEventType
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 pak opakuje 2x v intervalu 0,5 s.
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 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
0x0A
0x0B
data = <16-bit OFFSET> <DATA>,
answer = <0=OK, 1=Error/Buffer overflow>
data = <16-bit SIZE> <CRC16 of data>, 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
<blok 255 znaků FF>
FF FF
<blok 256 znaků FF>
FF FF FF 01
<blok 511 znaků FF>
FF FF FF FF FF 01