Sunday, October 11, 2015

Parallax Smart Card Reader - Revisited

I believe I have mentioned that at some time, I was going to implement an Arduino Library for the Parallax Smart Card Reader.   Well, that time is now.

The library has support for the 3 smart cards that are also available from Parallax.   The samples are equivalent to the stand-alone samples that have been available for quite some time now.   The big difference is that using the 3 smart cards is now very similar.   You initialize the cards with an Initialize() function, you read and write data to the cards with Read() and Write() functions.   There is an Authenticate() function available for the IS23SC4442 card.   The parameters are similar for each card (but they aren't always identical ... the IS24SC16A card requires a Page parameter, where the IS24SC02A doesn't, for example).   Update:  This library now has 3 additional functions for each card:  WriteString(), ReadString() and ClearString() ... basically you can write a string at a location on a page of the memory (note, it does NOT attempt to write past page boundaries ... very important for the IS24SC16A card!) ... so for a single page card, you could write a string starting at a specific location...WriteString(0x50, "Test");  Then if you needed to, at some time, you could read data into a string buffer ... ReadString(0x50, 4, buffer);  // buffer needs to be 1 byte larger than required in order to handle NULL terminator ... so a definition of char buffer[5]; would be fine in the previous example.  Finally if you need to clear the string you would simply call ClearString(0x50, 4); to set the 4 non-null memory locations to NULL (or 0x00).  The IS24SC16A version of the functions do have a Page # as the first parameter.  The location parameter is zero-based ... so if you wanted to clear all memory in a single-page card or all memory of a page in the IS24SC16A card, you could call ClearString(0x00, 256); ... or ClearString(5, 0x00, 256); to clear page 5 of the IS24SC16A card.  Each of the card samples have a new function showing samples of using the new String functions. Remember a page is 256 bytes in size, regardless of the card type.  So the maximum string size is going to be 256 bytes ... if you have a string that takes up an entire page, the buffer size would still need to be 257 to allow for the null terminator returned from the ReadString() functions.

Note:  Initially there wasn't an addressable Read() function for the IS23SC4442 card (i.e. the ability to pass a location to read from).  Even though the Card doesn't seem to directly support it, I worked out a way to make it possible to support it from the Library.

Also Note:  The Constructor for each Card actually accepts 5 parameters ... those parameters are int IOPin, int CLKPin, int CDPin, int RSTPin, int Delay ... but they all default to int IOPin = A4, int CLKPin = A5, int CDPin = 3, int RSTPin = 2, int Delay = 50  ... so you don't have to specify the parameters unless you want to change the values (and the samples don't use the parameters) ... but if you wanted to, you could do something like:   IS24SC02A CardReader(A4, A5, 3, 2, 50);  which would just be the defaults, but can be changed as-needed.   Also, if you are familiar with how default parameter values work, you know that you really don't have to always specify all parameters, but I'm not going to take the time to explain that here.

Final Note: The IS23SC4442 card can be locked if authentication fails, however the IS23SC4442.cpp Authenticate() function is coded to help make sure that doesn't happen (but also means that it doesn't really have the full protection that it could have).   I have put comments in the code showing what was there (when I locked a card!!!!), and you are welcome to change it back to provide full security support.   BUT, if you do, be very careful.  When you lock a card, it can't be unlocked and is no longer usable!!!

Please see the original post about the Parallax Smart Card Reader, because a lot of it is still very relevant.

The Parallax Smart Card Reader Library is now downloadable directly from the Arduino Library Manager.   Simply search for Parallax.

--- or ---

You can find the Parallax Smart Card Reader Library on Github Here.

NOTE: If you are using an older version of the Arduino IDE that does not include the more recent Arduino Library Manager, you may need to move all of the files in the libraries\SmartCardReader\src directory to the root libraries\SmartCardReader directory.   Also, the .properties file may need to be deleted.   Neither of these actions will change the ability to use the library (or samples) and should work fine after doing so.   At the time that I updated the libraries for Library Manager support, I was using version 1.6.9 of the Arduino IDE.


Updates:

10-11-2015 - First release of Library available on GitHub.

10-11-2015 - Added Addressable Read Support to IS23SC4442 Card.    Checked into GitHub.

10-12-2015- A couple minor changes (just some cleanup).  Checked into GitHub.

10-12-2015 - Improved consistency of examples (again, just some cleanup).  Checked into Github.

10-15-2015 - Fix a potentional issue with the IS23SC4442 card when swapping multiple cards in and out of the Card Reader.  Checked into Github.

10-15-2015 - Added String Functions to Library.  Checked into Github.

05-23-2016 - Now available from the Arduino Library Manager (changes required are also checked into Github).