Installation on Raspberry

These instructions assume that Raspbian is being used as the operating system on the Raspberry.

If has been tested on Raspbian "Buster" (based on Debian 10).

Prerequisites

Install PC/SC and the USB CCID driver

$ sudo apt-get install libusb-dev libusb++
$ sudo apt-get install libccid
$ sudo apt-get install pcscd
$ sudo apt-get install libpcsc-perl
$ sudo apt-get install pcsc-tools

Verify PC/SC is up and running

Launch the PC/SC daemon pcscd

$ sudo systemctl start pcscd.socket

Plug a SpringCard PC/SC reader to one of the USB ports and run pcsc_scan to list the PC/SC readers

$ pcsc_scan
Scanning present readers...
 Reader 0: PUCK [CCID] (C69178AE) 00 00
   Event number: 0
   Card state: Card removed.

Put a contactless smartcard on the reader to check everything is working fine:

 Reader 0: PUCK [CCID] (C69178AE) 00 00
  Event number: 1
  Card state: Card inserted,
  ATR: 3B 82 80 01 03 02 02

If the reader does not appear...

If the reader does not appear, check that it is known by the CCID driver.

Use lsusb to list the connected USB devices.

$ lsusb
Bus 001 Device 007: ID 1c34:6132 SpringCard

In the above example, we have one device with VendorID=1c34 (SpringCard) and ProductID=6132 (PUCK). Until the CCID distribution is updated, the device IDs have to be added into the CCID driver's Info.plist configuration file.

Edit Info.plist

sudo vim /usr/lib/pcsc/drivers/ifd-ccid.bundle/Contents/Info.plist

At the beginning of the ifdVendorId array, add the SpringCard's VendorID:

	<key>ifdVendorID</key>
	<array>
		<string>0x1C34</string>

Then, at the beginning of the ifdProductID array, add the device's ProductID:

	<key>ifdProductID</key>
	<array>
		<string>0x6132</string>

And finally, at the beginning of the ifdFriendlyName, add the device's name:

	<key>ifdFriendlyName</key>
	<array>
		<string>SpringCard PUCK</string>

Save the file and restart the PC/SC daemon pcscd

$ sudo systemctl restart pcscd.socket

List the PC/SC readers again:

$ pcsc_scan

and confirm the reader and the card are seen OK.

Enable SCardControl

SpringCard Companion and springcore-tools use the SCardControl to communicate with the devices. Unfortunately, this function is disabled in the default installation of PCSC-Lite.

We have to edit the CCID driver's Info.plist configuration file to enable this function.

$ sudo vim /usr/lib/pcsc/drivers/ifd-ccid.bundle/Contents/Info.plist

Locate the ifdDriverOptions entry and set the following string to 0x0001 (instead of 0x0000which is the default value)

	<key>ifdDriverOptions</key>
	<string>0x0001</string>

Save the file and restart the PC/SC daemon pcscd

$ sudo systemctl restart pcscd.socket

Install Mono runtime

sudo apt-get install mono-runtime
sudo apt-get install libmono-system-serviceprocess4.0-cil
sudo apt-get install libmono-system-runtime-serialization4.0-cil

Validate the installation

Test springcore-tools

PC/SC readers

Use springcoretool.exe to list all the PC/SC devices.

$ mono springcore-tools/springcoretool.exe --list --pcsc

Use springcoretool.exe to list all the SpringCore devices that are available using USB Direct communications.

This shall for example return

Found 1 possibly SpringCore compliant device(s):
        0: Puck
        1: H663
		2: H663

SpringCore devices

$ mono springcore-tools/springcoretool.exe --list

This shall for example return

Found 1 possibly SpringCore compliant device(s):
        0: Puck

If you have only SpringProx devices, the command will fail - don't panic.

Test Companion Service

$ sudo mono SpringCardCompanionSvc.exe --console --verbose=6

The --console flag tells the application to run in interactive CLI mode, not to daemonize.

The --verbose=6 enabled debugging. If a fatal exception occurs, please send the detailed output to SpringCard Support for investigation.

sudo is required because the Companion Service needs a direct access to the USB devices.

Enable remote access

By default, the Companion Service's interfaces (REST API and WebSocket server) are restricted to local connections only. Since the Raspberry is likely to be used as a headless interface, it is generally a good idea to allow remote connections.

Stop the running SpringCardCompanionSvc.exe by hitting any key in the console.

Edit file /etc/springcard/companion.cfg

$ sudo vim /etc/springcard/companion.cfg

Add these two lines:

HttpRestApiOpen=true
WebSocketOpen=true

Save the file and launch Companion Service again (this time with less verbosity to increase speed).

$ sudo mono SpringCardCompanionSvc.exe --console --verbose=4

The go to another machine with the wget utility installed and enter

$ wget -qO- http://<IP ADDRESS OF RASPBERRY>:3998/service

The response shall be something like (but on a single line):

{
	"Name":"SpringCard Companion Service",
	"Version":"20.9.7626.27758",
	"API":"1.0",
	"UniqueId":"A06ED1A5-847B-425F-A83D-8FBCF1FC74E5",
	"Platform":"unix",
	"Mode":"console"
}

Remark:

If you have a firewall, open TCP ports 3997 and 3998.

Configuring Companion Service to start with the system

To be written