This tutorial will show you the shortest way to get Citofonoweb working on your Raspberry Pi.

I'll assume you have a Raspberry Pi with the latest Raspbian, a keyboard (or a device that fakes it, like Olimex MOD-RFID) and a PiFace connected.

Configure devices

Make sure PiFace works

If you haven't fixed the module blacklist, run this one-line command:
sed -i /etc/modprobe.d/raspi-blacklist.conf -e "s/^blacklist[:space:](/pierinz/citofonoweb/wiki/:space:)*spi-bcm2708.*/#blacklist spi-bcm2708/"

Then load the modules, or (lazy way) reboot the Pi.

Get keyboard info

Before you proceed, ensure your keyboard/device is detected as keyboard (connect a monitor and see if something appears when you press the keys/swipe a badge).

In order to configure the software you'll need to know the event device file of your keyboard.
Type:
ls /dev/input/by-id/*
to list all the input devices connected with a friendly name. You should recognise your device (especially because you should get only one). Write down that string: you'll need it later.

Build the software

Get the dependencies

You need a working toolchain, a MySql server & client, libjson and some headers (the -dev packages). Install them:
apt-get update
apt-get install git-core build-essential libjson0 libjson0-dev mysql-server libmysqlclient-dev lsb-release

If you want to use a MySql server on another machine, just replace "mysql-server" with "mysql-client".
Write down the MySql server password, you'll need it soon.

Get the software

This is simple:
git clone https://github.com/pierinz/citofonoweb.git

Compile

Enter the directory:
cd citofonoweb

Fetch PiFace command-line tool:
make piface

Build & install CitofonoWeb:
make -j3 BACKEND=mysql install

Software Configuration

Configure the database

First, you need a database and a dedicated user, so open the MySql shell:
mysql -u root -p

Enter the root password and when you are logged create the database:
create database citofonoweb;

Then create the user and give it the right privileges:
grant usage on *.* to citofonoweb@localhost identified by 'citofonoweb';
grant all privileges on citofonoweb.* to citofonoweb@localhost ;

Now you are ready to load the default structure. Exit the shell with Ctrl+d and type:
cd resources mysql -u root -p < citofonoweb.sql

If you are familiar with SQL, you should read that file and edit it to fit your needs. Field/table structure is documented in /etc/badge_daemon/badge_daemon.conf.

Service configuration

Now you are ready to configure the CitofonoWeb main service: it is called badge_daemon, and reads the configuration from /etc/badge_daemon/badge_daemon.conf (You can copy this file and run different instances of this service, but this is outside the scope of this guide).

Open this file with your favourite editor, for example:
nano /etc/badge_daemon/badge_daemon.conf

You'll see many options, but if you followed this guide, you must change only a few lines.

1. In the source line, replace /dev/input/by-id/usb-Olimex_Ltd._MOD-RFID125-USBSTICK_Tag_Keyboard_*-event-kbd with your event device file;
2. Comment the led_on_command and the led_off_command directives under #test (line 24, 25) and decomment those under #piface (line 30,31);
3. Comment the door_open_command and the door_close_command directives under #test (line 38, 39) and decomment those under #piface (line 44,45);
4. If you are using a remote database, change dbhost (line 62);
5. Give a name to this device with the directive id_device (line 67).

First run

We are ready to start the service:
/etc/init.d/badge_daemon start

If you're lucky, the daemon will happily show in pstree:

init-+-badge_daemon-+-door_open
      |               |-hid_read
      |               `-2*[{badge_daemon}]

Now test it: swipe your badge on your reader/type your code an then enter on the keyboard. You should get a denied entry in the logfile:
tail /var/log/badge_daemon/badge_daemon.log

15/09/14 14:51:37 - Got badge xxxxxxxxx from source 15/09/14 14:51:37 - Badge xxxxxxxxx: UNKNOWN - DENIED BY POLICY

If something went wrong, go to the Troubleshooting section.

Insert some data

[...]

Troubleshooting

The daemon won't start

Check the error messages in /var/log/badge_daemon_lastrun and in /var/log/badge_daemon/badge_daemon.log and read below.

I got a 'segmentation fault' or a 'stack smashing detected' error

It is a known bug: some version of gcc simply won't work with this. Try adding CFLAGS=-fno-stack-protector to the make command above (this happens automatically if gcc-4.6 is detected). In the worst case, you'll need CFLAGS="-fno-stack-protector -O0".
I suggest you to install gcc-4.8 and add CC=gcc-4.8 to the make command. To sum up, run in the source folder:
make clean
make CFLAGS="-fno-stack-protector -O0" BACKEND=mysql install
or
make clean
make CC=gcc-4.8 BACKEND=mysql install

I got some error about the input device

Open /etc/badge_daemon/badge_daemon.conf and copy all text after "source" (line 2).
Execute that command: if it crashes, the error message will tell you if the device file you entered is wrong or you need more privileges to access it (or whatever).
If it works but you enter a code/swipe a badge and nothing happens, you choose the wrong input device (go to keyboard info section).

The badge_daemon is not parsing data correctly from the input device

You need to tune the source command options. Use hid_read -h to get documentation.

The daemon gets the correct code, but then strange thing happens

You should check the helper program. Read below.

Can I test authentication without entering codes/swiping badges?

Sure. The door_open process reads badge codes from standard input, so you can launch it standalone (the command is after helper, line 20 of /etc/badge_daemon/badge_daemon.conf). Just enter the code followed by a newline, and you will get the result on stdout. Read door_open -h, there are some debug options.