====== Attendance ======
{{tag>project infrastructure software hardware UEBLES_GEMURKSE}}
 :!: :!: :!: :!: :!: :!: :!: :!: :!: :!:
 This project is now obsolete. Please see [[friedhof:shackles]] :!: :!: :!: :!: :!: :!: :!: :!: :!: :!:

The whole project code is stored under
[[https://github.com/makefu/attendance]]
====== Project Summary ======

This is the documentation for the attendance infrastructure formerly deployed in the shackspace. The project consists of different parts which will be described in detail on this page.

It creates the possibility for the shack members to "log into" the shackspace and provide a way for other members to see who is currently in the shackspace. The Project is an 'opt-in', nobody has to use the infrastructure.


The project can be separated in the following parts:
  * NFC Gateway 
  * User Suppository Server
  * IRC Bot

====== NFC Gateway ======
{{http://i.imgur.com/Zbd7xjJ.jpg}}
===== Overview =====
The NFC Gateway creates the possibility for shack members to physically log into shackspace. It provides an usb nfc reader and a [[http://shackspace.de/wiki/doku.php?id=52x_20x2_x_7x5_dot-matrix_vfd|2x20 character dotmatrix display]].
It is also part of and implemented in the Minikrebs Project as [[http://shackspace.de/wiki/doku.php?id=project:minikrebs#profilenfc-gate|NFC Gateway]]
===== Hardware =====
The NFC Gateway consists of the following parts:
  - TP-Link MR3020 [[https://www.amazon.de/dp/B00634PLTW/?tag=krebsco-21|amazon de]],[[http://www.amazon.com/dp/B006DEBXD0/?tag=krebsco-20|amazon com]]
  - SCM SCL3711 NFC Reader [[https://www.amazon.de/dp/B008LT0SFY/?tag=krebsco-21|amazon de]]
  - A VFD LCD [[http://shackspace.de/wiki/doku.php?id=52x_20x2_x_7x5_dot-matrix_vfd]]
  - For a stable performance, use a powered USB Hub with >2A Power Adapter 

==== MR3020 ====
I am using the MR3020 as a platform because it provides Wifi AND a directly usable TTL Port where the pins are already attached on the PCB.
==== SMC SLC3711 ====
This is an nfc reader which "just works" with libnfc-bin. The reader reads quite a lot of 13mhz cards.
==== VFD LCD ====
The LCD is connected directly to the MR3020 Ports. The VFD RX is connected to MR3020 TX. 5V is connected to the MR3020 USB Power and GND is connected to the MR3020 Switch GND:
{{https://lh3.googleusercontent.com/-216KiHPOy_Y/URhComXSWJI/AAAAAAAAAbM/PJJTxOFBzpk/w813-h610-no/IMG_20130211_010749.jpg}}

===== Software =====
The NFC Gateway is running on OpenWRT with the NFC Gateway Profile of Minikrebs.
The profile provides the following capabilities:
  - usb + stty to write to the nfc display
  - :!: configured to connect to shack wifi 
  - tinc configured for the retiolum darknet
  - nfc Polling software
  - fortune-mod
==== VFD Display ====
We write raw display strings to the Serial Port and we use it for all the fancy stuff

==== The NFC Gateway Software ====
The software is using a very simple (-> easy to maintain) polling mechanism which uses nfc-list to look if someone has put an nfc card in front of the nfc reader. The script is running as daemon via /etc/rc.local .

The basic idea:
  - Poll for NFC Card, retrieve NFC-UID
  - get username and login status for NFC-UID from server-backend via HTTP (wget)
    * User does not exist: error message
    * User exists then log the user out or in according to their current status.
  - Send welcome/bye message to the LCD VFD

See [[https://github.com/krebscode/minikrebs/blob/master/traits/special_purpose/nfc_login/files/usr/bin/login-13mhz| github login nfc code]].

==== Fortune-mod ====
When the nfc gateway is not used for logging in it shows funny fortune cookies in an interval. The script is running as a daemon started by /etc/rc.local.

See [[https://github.com/krebscode/minikrebs/blob/master/traits/special_purpose/nfc_login/files/usr/bin/lcd-fortune|github nfc_login code]] for the daemon code.

===== Installation =====
<code>
git clone git@github.com:krebscode/minikrebs.git
cd minikrebs
./prepare nfc_gateway
./upgrade <ip-addr-of-mr3020>
</code>
For a detailed description, see [[https://github.com/krebscode/minikrebs|github minikrebs]]

===== Caveats/Lessons Learned =====
  * The LCD is using a LOT of power, when connected directly to the MR3020 
  * pcscd is quite unstable and slow under Openwrt, it is better to just use libnfc directly.
  * It looks quite fancy when booting the mr3020 because the VFD has a baud rate of 9600 but when booting the baud rate of the MR3020 is configured to 115200.

====== User Suppository Server ======
===== Introduction =====
The user suppository server is the backend of the NFC Gateway. For Storage it uses the Shack provided redis storage [[project:glados|G.L.A.D.O.S]]. The user suppository is essentially a python http server which talks to the redis db to store online and offline status of the users.

===== API =====

The implemenation is an HTTP Server which provides a number of API calls:
<code>
// all returns are json
ident=[0-9A-Z]+ //the unique user id - currently from RFID chips

    /user/online - returns all online users 
    /user/list   - returns all users
    /user/<ident>/online - returns if user with 'ident' is online
    /user/<ident>/name    - returns name of user with ident
    /user/<ident>/login  - logs user with 'ident' in
    /user/<ident>/logout -logs out user
    /user/<ident>       - returns cool info about user with 'ident'
    /user/create/<ident>/<name> - creates a new user with 'ident' with 'name'
</code>
See [[https://github.com/shackspace/user_suppository/blob/master/server/API|the current API]] in github.
===== Redis Store =====
The user suppository server stores the state of the shack users.
<code>
## Scheme
- always correct scheme in 'users.config'
{
    "users": {
        "<uid>": {
            "history": " the login-logout history", 
            "name": "the nick name", 
            "online": "user online -expires after 1 day"
        }, 
        "all": "contains all available user hashes",
	"config" : "this text"
    }
}
</code>
===== Installation =====
<code>
git clone https://github.com/shackspace/user_suppository
# Install python3, python-flask, python-redis
cd server
# edit init.py for hostnames,etc
python3 ./init.py
</code>
To autostart use autostart/user_suppository.conf for supervisor. add the user usersupp to your environment
====== IRC Bot ======
===== Introduction =====
The IRC bot is currently the only way to know if a user is logged in or not. The irc bot is connected to irc.freenode.com to channel #shackspace. Also the irc bot will write to the IRC channel if a user has logged into the shack by sending a channel query. 

The IRC bot implementation used is [[https://github.com/lepinkainen/pyfibot|pyfibot]], two modules are written to implement the 
===== Usage ======
<code>
# write in #shackspace channel
.online
</code>

===== IRC Gateway =====
After opening a socket on port 1234 it takes arbitrary messages and sends them to the IRC. The module opens a tcp listen socket via twisted and listens for messages.
each message will be written to the irc.

See [[https://github.com/krebscode/pyfibot/blob/master/pyfibot/modules/module_reactor.py| Reactor module of the onbot]]
===== IRC Online =====
The irc bot is using python-requests to query the user_suppository server online users (see user_suppository API).
===== Installation =====
see [[https://github.com/lepinkainen/pyfibot/wiki/Installation|pyfibot installation]].

the clone url is: https://github.com/krebscode/pyfibot

no additional software is required.

To autostart use autostart/onbot.conf for supervisor. add the user usersupp to your environment