PIU Notes
===

These are notes for the a PIU upgrade to include
newer hardware.

Overview
---

The PIU should be able to accept a variety of fare media,
including magstripe cards (multiple track), RFIDs (125kHz and
Mifare) and barcode/QR codes using a camera.

The display should be such that communication is given back to
the rider.
The camera can also be used to potentially help with QR code alignment to
the (down facing) camera.

There's some investigation that should be done in terms of what, if any,
gets offloaded to a microcontroller but the basic idea is:

* The Raspberry Pi (Zero) manages the HID devices, camera and screen
* The camera can be used to scan for QR codes
* For QR code scanning, a passthrough of the camera to the screen can
  be used for alignment
* The touch screen can be used for confirmation if need be
* Whatever is used for communication back to the DIU can use the same
  protocol already in place

By having a microcontroller (Arduino, say) that's in charge of communication or
the RFID and Magstripe devices, this provides an 'instant on' for that portion
of the PIU.
Putting everything behind the Raspberry Pi is conceptually simpler but is sluggish
to boot up.

Requirements
---

* Housing
* 12-24v in (requires buck converter)
* Display
* RFID reader (125kHz and Mifare?)
* Magstripe reader (3 tracks)
* Camera
* Arduino

RFID Reader
---

Some electronics speak "Wiegand Protocol".

There's an Arduino library that has appropriate code (from [monkeyboard](https://github.com/monkeyboard/Wiegand-Protocol-Library-for-Arduino)).

The current system is focused on using HID prox card readers.

---

The [proxmark3](https://github.com/Proxmark/proxmark3) is a general purpose RFID hardware tool that can be used to read and write
low frequency (125 kHz - 134 kHz) as well as high frequency (12.57 MHz).
The code is under LGPL and I assume the hardware files are under the same or similar license.
The hardware files don't have a license on them but I think the proxmark3 is marketed as an open source hardware project so
it's probably safe to assume this was the intent.

The `proxmark3` is sold in the $250-$300 (as of this writing) but there are clones available at a fraction of the cost ($60-$80) on eBay.

The `proxmark3` can read HID class cards so I think it's an ideal candidate to use as a general purpose RFID reader.
At the least, this will be a relatively low cost solution that will read a variety of cards that any organization can use.
If needed, there is the possibility of using it as a writer, either in the field or offline, for custom RFID tags.

#### Proxmark3 Setup

There are few key points to setup the Proxmark3 for use:

* The latest `proxmark3` project should be [downloaded, compiled and flashed onto the device](https://github.com/Proxmark/proxmark3/wiki/Ubuntu-Linux). Failure to do so was causing some basic functions to malfunction (`hw version`), slowness and inconsistent behavior of `lf hid read`. See [an issue suggestion the flash would solve the issues being experienced](https://github.com/Proxmark/proxmark3/issues/104)
* A Lua script can be used to automate the process (see [this issue](https://github.com/Proxmark/proxmark3/issues/840) and the Lua script below)
* I guess the client wants things in the `scripts` directory? Be sure to place it where it can find it

The Lua script:

```
local cmds = require('commands')
local getopt = require('getopt')
local bin = require('bin')
local utils = require('utils')
local format=string.format
local floor=math.floor
local os = require("os")

function sleep (a)
    local sec = tonumber(os.clock() + a);
    while (os.clock() < sec) do
    end
end

local function main(args)
  print( string.rep('--',30) )
  print( string.rep('--',30) )

  -- core.console will go async when waiting for the proxmark to return
  -- so need to wait for a response (sleep)
  core.console('lf hid read')
  os.execute("sleep 30")

  print( string.rep('--',30) )

end
main(args)

```

The script should be put into the `scripts` directory and can be run via:

```
$ stdbuf -eL -oL ./proxmark3 /dev/ttyACM0 -l lf-hid-read.lua | tee test.log
```

The following will also work:

```
$ stdbuf -eL -oL ./proxmark3 /dev/ttyACM0 -c "script run lf-hid-read.lua" | tee test.log
```

Note that the `stdbuf` is needed to get results as soon as a line is read.


Magstripe Reader
---

The current PIU has a dual head, 3-track magstripe reader.
As of this writing, single head 3-track USB magstripe readers sell for around $15.
I see some alternatives on Aliexpress and Alibaba that are in the range of $10 in
single units and $6 in quantity 5k+.

Dual head, 3-track magstripe USB readers sell for around $60 on Amazon and Ebay.

The possible solutions to this are:

* Use the $60 'off-the-shelf' solution
* Buy two USB off-the-shelf single head USB readers and make a housing
  via 3d printing, say, to put both heads in for 1/3 to 1/6 the cost.
* Live with single head magstripe reader


#### USB Magstripe Setup

Some of the peripherals act as keyboard input devices.
In order to not have them pollute input, they need to be
taken over by a process.

[SO](https://stackoverflow.com/questions/1698423/how-can-you-take-ownership-of-a-hid-device) has
an article on it.
More investigation needs to be done but the basics look to be:

* Use the "event device interface" `/dev/input/event*` to look for the device
* Use an `ioctl` `EVIOCGRAB` call to get exclusive use of the device

```
cat /proc/bus/input/devices  | grep -P '^[NH]: ' | paste - -
```

---

There's a [Python tutorial](https://python-evdev.readthedocs.io/en/latest/tutorial.html) that looks to have an easy way to do this:

```
import evdev
import asyncio
dev = {}

evfns = [ "/dev/input/event0", "/dev/input/event1", ... , "/dev/input/event12" ]

for evfn in evfns:
  _dev = evdev.InputDevice(evfn)
  if dev.name == HID_NAME:
    dev = _dev
    break

dev.grab()

async def print_events(device):
  async for event in device.async_read_loop():
    print(device.path, evdev.categorize(event, sep=': '))

for device in dev:
  asyncio.ensure_future(print_events(dev))

...

```

The above has to be played around with but it looks like the seeds are there.

---

If you don't care about capturing multiple devices at once (within a single program), the following does an active poll:

```
#!/usr/bin/python3

import os, sys, evdev, asyncio, os.path
from evdev import InputDevice, categorize, ecodes

dev_init = False
dev = { }

HID_NAME = 'HID c216:0180'

evfns_n = 13
evfns_bd = "/dev/input/"
evfns = [ ]

for x in range(evfns_n):
  fn = evfns_bd + "event" + str(x)
  if (os.path.exists(fn)):
    evfns.append(fn)

for evfn in evfns:
  _dev = evdev.InputDevice(evfn)
  print("device:", _dev.name)
  if _dev.name == HID_NAME:
    dev_init = True
    dev = _dev
    break

if not dev_init:
  print("could not find device, exiting")
  sys.exit(0)

print(dev)
print(dev.capabilities())
print(dev.capabilities(verbose=True))

dev.grab()

for event in dev.read_loop():
  if event.type == ecodes.EV_KEY:
    print(categorize(event))

```

Note that the `HID_NAME` is specific to the USB magstripe reader I had on hand.
Multiple of the same could be attached and would need to be differentiated by the `/dev/input/event*` endpoints.


---

I'm still playing around with a policy on the USB magstripe reader use but there are a few things of note:

* [disabling USB inputs through udev](https://incenp.org/notes/2014/disable-new-usb-input-devices.html)
* Getting errors on startup of the form "couldn't find an input interrupt endpoint" [SO: usbhid can't find input interrupt endpoint](https://unix.stackexchange.com/questions/116615/usbhid-cant-find-input-interrupt-endpoint)



Display
---

The passenger needs feedback so a display is required.
I think it's good practice to provide a mechanism for user interaction and high resolution display.

The high resolution display can be used for fare media presentation feedback.
For example, letting the rider see what the camera is seeing to better align a QR codes ticket.

The touch feedback can be used for complex fare media or for future options.

---


There's a [2.8 inch touch display](http://www.raspberrypiwiki.com/index.php/2.8_inch_Touch_Screen_for_Pi_zero) that could be a candidate ([MZDPI](https://github.com/tianyoujian/MZDPI)).

Apparently there's a simple install script:

```
cd ~/
git clone https://github.com/tianyoujian/MZDPI.git
cd MZDPI/vga
sudo chmod +x mzdpi-vga-autoinstall-online
sudo ./mzdpi-vga-autoinstall-online
sudo reboot
```

---

I much prefer capacitive touch screens to resistive ones so it'd be nice to have an alternative.

One option is Pimroni's [HyperPixel 4.0 Display](https://shop.pimoroni.com/products/hyperpixel-4?variant=12569485443155) (~ $45).


Camera
---

I would recommend a Pi NoIR that can be hooked into the Pi Zero ([Adafruit](https://www.adafruit.com/product/3100)).

I've had success in getting it up and running with a Raspberry Pi Zero before and it might be easy to set up and fast enough to use.

`zbar-tools` (perhaps [mcheheb/zbar](https://github.com/mchehab/zbar)?) looks to be a tool to scan QR codes.

Here's an example:

```
$ sudo apt-get install zbar python-zbar
$ git clone https://github.com/mchehab/zbar
$ cd zbar/python/examples
$ python ./scan_image.py ../../examples-qr-code.png
('decoded', 'QRCODE', 'symbol', '"https://github.com/mchehab/zbar"')

```


References
---

* [SO: Ownership of HID device](https://stackoverflow.com/questions/1698423/how-can-you-take-ownership-of-a-hid-device)
* [Python evdev tutorial](https://python-evdev.readthedocs.io/en/latest/tutorial.html)
* [GitHub: monkeyboard/Wiegand-Protocol-Library-for-Arduino](https://github.com/monkeyboard/Wiegand-Protocol-Library-for-Arduino)
* [2.8 inch touch display](http://www.raspberrypiwiki.com/index.php/2.8_inch_Touch_Screen_for_Pi_zero)
* [GitHub: tianyoujian/MZDPI](https://github.com/tianyoujian/MZDPI)
* [GitHub: mcheheab/zbar](https://github.com/mchehab/zbar)
* [Pimroni's HyperPixel 4.0 Raspberry Pi Display (Touch)](https://shop.pimoroni.com/products/hyperpixel-4?variant=12569485443155)
* [Installing Proxmark3 on Ubuntu Linux](https://github.com/Proxmark/proxmark3/wiki/Ubuntu-Linux)
* [Proxmark3 Issue #104 -Huge slowdown after issuing some commands](https://github.com/Proxmark/proxmark3/issues/104)
* [Proxmark3 Issue #840 - How to script a simple proxmark3 command?](https://github.com/Proxmark/proxmark3/issues/840)
