#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 SpringCard 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 SpringCard Companion Service needs a direct access to the USB devices.

#Enable remote access

By default, the SpringCard 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 SpringCard 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 SpringCard Companion Service to start with the system

To be written