A Xamarin wrapper for the ACS USB library for Android



A while back, we were using RFID readers made by ACS.  They make a number of decent readers and we used one of the USB models, ACR1220U, with our bespoke Android tablet.  To communicate to the reader, ACS provides libraries for Windows and Android.  The Android library comes with a .jar file and some sample (but very limited) code.  The demo showed how to connect to the reader, but didn’t have that much for getting information from the reader.

The ACS reader follows the SmartCard standards.  Their library provides the low level access to the reader.  It’s up to the consumer of the library to write the code that actual sends and receives data from the RFID reader.  If you are working with a SmartCard reader, then you’ll need to know how to create APDU packets.  An APDU, application protocol data unit, is the command packet that is sent from the reader to the card, and from the card to the reader.  When you use this reader, your code is responsible for creating and sending the packets.

The logic that I used more or less follows this flow:

  • Reader signals the application that a card has been detected (or no longer detected)
  • Applicate tells the reader to a warm reset of the card
  • Application tells the reader to set the communications protocol for talking to the card
  • Application tells the reader to transmit the APDU command to get the unique identifier (UID) from the card
  • The response from the transmit command will have the UID from the card.

And that’s just to get the UID from a card.  If you are trying to read a NDEF packet, then you have a lot more work to do.  NDEF records are stored differently, depending on what kind of card that you are reading.  If you are using RFID data from cards with the built-in NFC support that Android provides for hardware that comes with the device, you are benefiting by the low level code being handled for you.

For the last .5 decade, we’ve been using Xamarin for our Android coding.  To use the ACS reader, I created a Xamarin wrapper library for their Java library.  It basically takes and embeds the .jar file and provides a nice .NET API to their library.  I then took their sample library and did a more or less straight port from Java to C#.  If you grab that repo from Github, you’ll get the library and and the demo app.  It was created with Visual Studio on Windows, but should work on the Mac.  Should being the code word for “I didn’t do anything that was platform specific, but I didn’t test it on the Mac.”

The results of that wrapper/conversion are up on Github.  You can grab it here. The .jar file that the library is compiled with is included in the repository. It is part of an API kit that should be downloaded from https://www.acs.com.hk/en/mobile-support/. The API kit includes the API documentation in HTML format.

The library does not have the APDU code to get the data from a RFID card.  I do have that code, but at the moment it’s part of some code that I can’t share.  I’ll pull the APDU code from our business code and post it later.  In the meantime, this is the code from the OnStateChange event that gets assigned to the reader.

        public void OnStateChange(int slotNum, int prevState, int currState)
            // If the previous state and the current state are outside the range of allowable
            // values, then assign min/max of the range
            if (prevState < Reader.CardUnknown || prevState > Reader.CardSpecific)
                prevState = Reader.CardSpecific;

            if (currState < Reader.CardUnknown || currState > Reader.CardSpecific)
                currState = Reader.CardUnknown;

            // Create output string
            string outputString = "Slot " + slotNum + ": "
                    + stateStrings[prevState] + " -> "
                    + stateStrings[currState];

            // Log the status change

            // We tapped the card
            if ((prevState == Reader.CardAbsent) && (currState == Reader.CardPresent))
                // We have the right slot - opening the reader generates a spurious StateChange event
                if (slotNum == SlotNumber)
                    // read the card

                    // The APDU (smart card application protocol data unit) byte array to get the UID from the card
                    // Command  | Class | INS | P1 | P2 | Le
                    // Get Data |   FF  | CA  | 00 | 00 | 00
                    var command = new byte[] { 0xFF, 0xCA, 0x00, 0x00, 0x00 };

                    // The byte array to contain the response
                    var response = new byte[300];

                        // In order to set the Get Data command to the card, we need to send a warm reset, followed by setting
                        // the communications protocol.
                        var atr = this.Power(slotNum, Reader.CardWarmReset);

                        this.SetProtocol(slotNum, Reader.ProtocolT0 | Reader.ProtocolT1);

                        // Send the command to the reader
                        var responseLength = this.Transmit(slotNum,
                            command, command.Length, response,

                        // We appear to be getting all 9 bytes of a 7 byte identifier.  Since 9 would be considered a too
                        // large value of 7, we drop the last 2 bytes

                        if ((responseLength > ForcedIdSize) && (ForcedIdSize > 0))
                            responseLength = ForcedIdSize;

                        // If we got a response, process it
                        if (responseLength > 0)
                            // Convert the byte array to a hex string
                            var s = ByteArrayToString(response, responseLength);

                            // Add the scan to the collection and notify any watchers

                            // Notify any watchers
                            LogMsg($"UID: {responseLength} {s}");

                    catch (Java.Lang.Exception e)


This is probably as a good point as any to menton that we no longer use the ACS readers.  While their documentation is obtuse and technical support is non-existent, they do exactly what they are supposed to do.  Which is fine, but it just didn’t mesh up with our needs.

Our use case is for scanning student and driver RFID tags for our Android tablet.  We use an external RFID reader so that the students are scanned as they get on the bus.  Our tablets are securely mounted in cradles, which tends to block RFID readers that are built in to the tablets.  We had the following problems with our use of the ACS readers

  1. The ACS readers are NFC only.  RFID covers a multitude of sins.  NFC is just a subset of that.  Our customers may have RFID cards that use different technologies, like HID PROX or EM400.
  2. The steps needed to get a UID were quick, but not fast.  To get the UID. there needs to be several round trip conversations between the table, the reader, and the card.  If a student getting on the bus didn’t hold the card long enough to the reader, we ended up missing some scans.
  3. The power draw was draining school bus batteries.  The ACS readers are designed to draw power continuously from the USB port.  Because the readers are mounted to the bus, they would be drawing power all the time.  They are radios and there’s a power cost to run those radios.

These issues turned up during our initial deployment.  We found a better solution with the Elatec RFID readers, but the ACS readers are a good solution.  The ACS NFC readers are pretty much the industry standard for external FNC readers.  If I was wiring up and external RFID reader that was connected to a device with AC power, an ACS reader would be the first thing I would consider for the project.

Vermont Code Camp 2017

So it looks like I’ll be speaking at Vermont Code Camp 2017 on September 16th.  I’ll be doing a presentation on using vector graphics with Xamarin.  If you targeting multiple platforms, using vector graphics like SVG files lets you have one set of images for multiple resolutions.  It’s a short session, but it will be useful for mobile developers of any stripe.

It’s not too late to register for #VTCC9.  You can register here and it’s free.  It’s held at Champlain College in Burlington.  It’s worth travelling up to visit Burlington in the fall.  It’s right on Lake Champlain and it’s a pretty part of the country.   You find the Vermont Code Camp on the twitters at @vtcodecamp. They have a Slack channel at vtcodecamp.slack.com and you can join at vtcodecamp.herokuapp.com.

And one other thing.  Mike Halsey has xray vision.  It’s his super power.  This has nothing to do with the code camp, but it’s worth mentioning.

You can now register for the Dream.Build.Play 2017 Challenge

Microsoft has revived it’s indie game dev contest – Dream.Build.Play and you can register now.

Dream.Build.Play 2017 Challenge

The 2017 Challenge is a six month game contest aimed at indie devs. Teams of up to 7 (individuals can go solo if they desire) can enter one or more of the four categories available:

  • Cloud-powered game – Grand Prize: $100,00 USD
    Azure Cloud Services hands you a huge amount of backend power and flexibility, and it’s cool. So, here’s your shot of trying Azure out and maybe even win big. Build a game that uses Azure Cloud Services on the backend, like Service Fabric, CosmosDB, containers, VMs, storage, and Analytics. Judges will give higher scores to games that use multiple services in creative ways-and will award bonus points for Mixer integration.
  • PC Game – Grand Prize: $50,000
    Building on Windows 10, for Windows 10? This is the category for you. Create your best UWP game that lives and breathes on Windows 10 and is available to the more than 450 million users through the Windows Store. It’s simple: create a game with whatever technology you want, and publish it into the Windows Store. Judges will look favorably on games that add Windows 10 features like Cortana or Inking.
  • Mixed Reality Game – Grand Prize: $50,000
    Ooh, so you want to enhance this world you live in with something a little… augmented? Virtual? Come and join us in the Mixed Reality challenge and build a volumetric experience that takes advantage of 3D content in a virtual space. You’ll need to create your game for Windows Mixed Reality but you can use technology like Unity to get you kickstarted. Oh, and don’t forget the audio to really immerse us in your world.
  • Console Game – Grand Prize: $25,000
    Console gamers unite! Want to try your hand at building a game for Xbox? This category is your jam. Your UWP game will be built for the Xbox One console family, and incorporate Xbox Live Creators Program with at least Xbox Live presence. Consideration will be taken for games that incorporate more Xbox Live services such as leaderboards and statistics.

Teams will be judged on fun factor, innovation, production quality and business aspects of their entry, and winners will be selected from the top three from each of the four categories for a grand final in 2018 where the prizes will be awarded.

Visit the Dream.Build.Play site for more information.  There is a video explaining the competition on Channel 9.

Free event at Union College: Out-thinking Old School: the Intersection of Play and AI

On Friday, May 26th 2017, there will be a presentation at Union College in Schenectady on Gamification and AI.  It will be in Karp Hall, room 105 and will be held from 12:50 PM to 2 PM.  The presenter is Phaedra Boinodiris (@innov8game),a Senior Strategy Lead for Education/Technology for IBM.  Phaedra will be discussing how Artificial Intelligence is being used to enhance game play.

This event is open to the public.  For a map of Union College, jump to this link.  For directions to Union, enter “807 Union St, Schenectady, NY 12308” into your GPS device of choice.

Phaedra Boinodiris holds 6 patents in the gaming space, was named one of the top 100 women in the games industry and is the co-founder of womengamers.com. Author of Serious Games for Business, Boinodiris started the first scholarship for women to pursue degrees in game design and development in the US. She currently teaches at UNC-Chapel Hill where she is also the UNC Social Entrepreneur in Residence.


A Xamarin port of the usb-serial-for-android library

Back in January, I ported the excellent usb-serial-for-android library from the Java source code to Xamarin C#.  We have an Android application that needs to use an external RFID reader.  The reader is an Elatec TWN4 RFID reader and it can work as virtual comm port over USB. To use that reader, I needed a general purpose serial over USB library.  I ended taking a very good one from the open source Java community and porting it over to C#. That ported library is up on Github under the name UsbSerialForAndroid.

Out of the box, Android doesn’t come with a lot of support for serial port devices.  It’s probably not a common use case.  Starting in Android 3.1, support was added for USB Host mode to allow access to USB devices from Android apps.  There was enough of a need for serial devices that Mike Waverly wrote a very good library in Java named usb-serial-for-android.  It supports many of the common USB serial chipsets.  So I wanted to use that.

With Xamarin Android, you have basically two ways of consuming Java libraries.  You can use them directly by creating a C# to Java wrapper and bundling the .jar file with your project.  While that can work, and work very well, it can also be a bit clunky and you can hit some issues mapping the Java method calls to C#.  Another group had gone down that path.  They implemented a wrapper for the .jar file and added some helper classes.  It looked like their project was abandonware and was not using a current version of Mike’s code.  You would also have the limitation of not being to debug into that code library.

If you have the source code, you can port the code from Java to C#.  I decided to go down that route.  It took a couple of days, but I was able to port all of the Java code to C#.  It went over more or less as is.  Some changes needed to made because reflection is handled differently in C# than in Java.  There were also a bug in Xamarin’s API access code that mangled the array handling in some Java code.

In Java, ByteBuffer.wrap(someBuffer) allows for two-way updating of a Java array with a stream buffer,  A bug in Xamarin’s API mapping tool emits code that allocates a new buffer when you call Wrap.  Changes made to the ByteBuffer are not reflected in the original byte array.  This is logged in Xamarin’s Bugzilla database here and here.

In the CdcAcmSerialPort.Read() method, defined here in C# and here in Java, I needed to add a line to copy the new array back over the original array.

In the original Java (edited) code, we had this
final ByteBuffer buf = ByteBuffer.wrap(dest);
if (!request.queue(buf, dest.length)) {
throw new IOException("Error queueing request.");

final int nread = buf.position();
if (nread > 0) {
return nread;

In the C# code, I added a call to BlockCopy to overwrite the original byte array with the updated contents
ByteBuffer buf = ByteBuffer.Wrap(dest);
if (!request.Queue(buf, dest.Length))
throw new IOException("Error queueing request.");

int nread = buf.Position();
if (nread > 0)
System.Buffer.BlockCopy(buf.ToByteArray(), 0, dest, 0, dest.Length);
return nread;

I also replaced some integer constants with enumerated types where it made sense to do so. I also took the C# helpers from the LusoVU repository.

As much as I could do so, I followed the code structure’s of the Java library.  When changes are made to that library, I can view those changes and make the equivalent changes in the C# code.  The end result was that I ended up with all C# code and it works great.

The TWN4 has become my favorite RFID reader.  It’s very good at reading different card types and you can write custom firmware for it in C.  I used it in another project where it had to work with a custom protocol to with the host device.

TWN4 reader

My book about localization with Xamarin is out

Cross-platform Localization for Native Mobile Apps with Xamarin

Cross-platform Localization for Native Mobile Apps with Xamarin

Last month Apress published my book on writing localized apps with Xamarin. It’s titled “Cross-platform Localization for Native Mobile Apps with Xamarin” and is available on Apress’s site or on Amazon

It’s not a long book, about 110 pages.  It provides the basic information you would need to localize your app for other languages and countries.  It’s written for the Xamarin developer, but the topics apply to other developers.

After discussing the basics of localization, the book covers how to get your text translated.  There is a chapter that covers the Multilingual App Toolkit (aka MAT), which is Visual Studio extension that is a workflow management tool for language resource files.

Multilingual App Toolkit

I love this tool

If you are using Xamarin.Android and Xamarin.iOS to build your apps, you can use MAT to generate Android and iOS string resource files.

Besides translating the text that is compiled into the app, I spend time discussing how to manage language resources coming from web services.  Once again, the MAT is handy for managing language resources server side.

The sample app (Spanish version)

There is a chapter that builds a Xamarin.Forms app from scratch and then localizes it for the Chinese, Spanish, and German languages.  For the German translations, I was helped out by one of my co-workers, David Krings.  David is a native German speaker with technical writing experience.

When translating language resources, a fellow co-worker is one of the best resources.  Besides knowing the language, that person will know the domain of the app.  Context is very important with language translation.

Consider a string resource of “boot” in English and you need to translate it to the Polish language.  You need to know which meaning of “boot” to translate.  In US English, it means a type of footware and it could be translated as “kalosze”.  It could also mean to start up a process, which could translate to “rozruchu”.  In UK English, it’s the part of the car where you store things, that translates more or less as “bagażnika”.  Without the context, it’s easy to get the wrong translation.

For the Chinese and Spanish translations, I used a commercial translation company called SmartCAT.  Two of their translators, Max Diaz and Максим Морковкин, did the Spanish and Chinese translations.  I like how that SmartCAT works and recommend it to anyone that needs translation services performed.  SmartCAT’s Head of Community, Vova Zakharov, arranged for the translation services and at the last too.

When you have your app translated, you will need to have done by someone with the language expertise.  Machine translation has come a long way, but it’s better to do it right.

Besides language translation, the book covers how to deal with numbers, dates, currency, and other country/regional formatting.  The nice thing about using the .NET Framework is that most of the heavy lifting is done for you.  You don’t have to worry about how to handle it with one OS and then figure it out for another OS.

The source code for the book is up on Github.  You can access it from Apress/cross-platform-localization-xamarin.  You will want to download or clone the repo to follow along with the book.

And while I’m thanking people, I wanted to give a shout out to the technical reviewers.  Craig Dunn is part of the Xamarin team that is now part of the Microsoft team. He made this book much, much better.  Cameron Lerum created the Multilingual App Toolkit, which made most of this book possible.  Between the subject expertise and technical writing skills, I could not have had any better reviewers for this book.

Taking the Acer W3 from Preview to RTM

It was time to install Windows 8.1 on my Acer Iconia W3-810. I received the tablet at the Build conference. The W3 came with the 32-bit edition of Windows 8 and Microsoft provided a USB drive with preview copies of Windows 8.1 for it and the Surface Pro. I had installed the preview version of Windows 8.1. With the availability of Windows 8.1 RTM on MSDN, I decided to repave the Acer with a fresh 8.1 install

One of the nice touches with the Build giveways was that Microsoft included a 16GB USB3 flash drive. You don’t get any faster performance from the USB3 drive on the Acer, but the Surface Pro has a USB3 port.

The first thing I did was download the ISO image. I needed the 32 bit version, the Atom Z2760 processor on the Acer is a 32-bit CPU. Next step was to get the latest drivers for the Acer. Headed over to the Drivers and Manuals page on the Acer site and searched for “W3-810”. This brought up all of the files available for the W3.

There is a BIOS update and a Driver Package download. I grabbed them both. I downloaded the BIOS update to the desktop on the Acer and ran it. It rebooted and installed itself with out any issue. I didn’t see any release notes with the BIOS update, but the tablet was fine after  installing it. The BIOS upgrade may have been moot, when I installed the Drive Package later on, it did a BIOS update with a newer version.

I chose to repave the W3 and do a clean install. Windows 8.1 does not come with the touch screen drivers for W3. That’s why I downloaded them ahead of time. If you do this, get a USB hub and a spare USB mouse and keyboard, this will make life much easier for the upgrade.

There is a hidden folder on the c: partition named c:\oem, make a backup copy of it just in case something goes wrong. That has a bunch of Acer specific files and it should have a copy of the Office 2013 installer.

One more file I needed to get was the Windows 7 USB/DVD Download Tool. Ignore the “Windows 7” part of the title, it works just fine with Windows 8. This tool makes it easy to make a bootable USB drive from an ISO file.

When you download/install/run this tool, it will prompt you for the ISO file and then ask if you want do a USB hard drive or a USB DVD. Pick the hard drive option and let it reformat the drive. It will then make the drive bootable and extract the ISO image to the drive. I used this to make the /Build drive a bootable Win 8.1 boot disk. It turned out that I didn’t need to make the drive bootable, but it’s good to know to do it.

With the drive now a bootable bucket of 32 bit Windows 8.1 joy, I then copied the contents of the driver package ZIP that I had downloaded from the Acer site to the thumbdrive. I had what I needed to upgrade the Acer. I went into the Acer BIOS and changed the boot order so that it would boot from an external drive first. To get into the BIOS screen, reboot the Acer and press the F2 key on the USB keyboard. You can get into the BIOS by holding the up volume button while pressing the power button. But since you’ll need the USB keyboard, you might as well start off with it attached.

There is probably more than one way to do this, and I hope an easier one. To get the Acer to install from the USB, I had to boot into recovery mode. Press and hold the power button and the Windows button as it boots up. That should boot up into the Windows 8.1 Troubleshooter. It will ask you for your language. On the next screen, select the “Troubleshoot” option. On the Troubleshoot screen, select “Advance Options”. I then selected “Command line prompt”

This opened up a cmd.exe shell. From here, I switched to the D: drive and ran setup.exe. This started the Windows 8.1 install. From that point on, it was just like installing the OS as a new install on any other machine. When it prompts you for a destination partition, choose the largest one, it should be about 48Gb in size on this model.

After a long while, the Acer booted up into Windows 8.l, RTM. The touch drivers will need to be installed. I went to the Windows Desktop and use Explorer to access the thumbdrive. This is where it is handy to have a keyboard and mouse connected. Then I opened the folder with the Acer drivers and ran the setup.exe. If you do this, you will see a a banner for the Intel Atom Processor drivers. Click through it and go have a sparkling beverage, it”s going to take a while. After it’s was done, it will prompted to restart the tablet, on the reboot it flashed the BIOS.

After rebooting, I had touch, but I visual glitches in about half of the Windows Store apps. The text had the same color background as the foreground, making the apps unusable. Fortunately desktop mode was fine. I was able to run Windows Update and that seems to have sorted it all out.

I do need to re-install the Home & Student Edition of Office 2013 that came with the tablet. Installing 8.1 in this way will remove all the installed apps. I wanted to start with a clean slate, so I knew this going in. The installer is supposed to be in the hidden c:\oem folder, but I couldn’t find it on mine. I still have the registration key, I’ll either find another source for the installer or just install Office Pro.

Now that everything is in place, my last step was to remove the remaining bits of the previous version of Windows. The installer had renamed the c:\windows to c:\windows.old , and that was still there. Microsoft has a page that explains how to this.

  1. Open Disk Cleanup by swiping in from the right edge of the screen, tapping Search (or if you’re using a mouse, pointing to the upper-right corner of the screen, moving the mouse pointer down, and then clicking Search), entering Disk Cleanup in the search box, tapping or clicking Settings, and then tapping or clicking Free up disk space by deleting unnecessary files.
  2. If you’re prompted to choose a drive, select the drive that you just installed Windows on, and then click OK.
  3. In the Disk Cleanup dialog box, on the Disk Cleanup tab, click Clean up system files.
  4. If you’re again prompted to choose a drive, select the drive you just installed Windows on, and then click OK.
  5. Select the Previous Windows installation(s) check box, and any other check boxes for the files you want to delete, and then click OK.
  6. In the message that appears, click Delete files.

And that’s how I did a clean install install of Windows 8.1. If you have Windows 8, you shouldn’t need to go through of this. The update to 8.1 will be in the Windows Store and will be a free download.