popufare/Documentation

Popufare

Popufare is a free/libre/open source and open source hardware bus fare system.

This includes hardware and software for fare collection on buses and server infrastructure to manage ridership.

This document is intended to give a high level overview of the different components of the system. Popufare is quickly evolving and this document is expected to change as the system continues to grow.

Overview

Popufare can be split into four main sections

• The "Popufare Bus Unit" (PBU) which consists of a Driver Interface Unit (DIU) and a Passenger Interface Unit (PIU) hardware that resides on the physical buses to collect fares, manage routes and communicate back to the central server
• The server side infrastructure to collect fares from the fleet of deployed PBUs the underlying database and other infrastructure
• An administrator web interface to interface with the system both to add new routs to the buses, add/remove cards, add/remove passes and other administrative tasks
• A "store front" web site that allows for purchase of the fare media (magnetic cards, etc), pass purchase and rider account management

Popufare Bus Unit (PBU)

The Popufare Bus Unit (PBU) consists of a Driver Interface Unit (DIU) and a Passenger Interface Unit (PIU).

The Driver Interface Unit (DIU) is a small computer with screen that allows driver login, driver route management, fare acceptance and fare display. The DIU connects to the Passenger Interface Unit (PIU) via a physical connection to receive bus fare media presented by the ridership.

The DIU also manages a network connection to the central server through a GPRS modem connecting to a 3G cell phone network. PBU/DIU communication to the central server consists primarily of pushing pass usage updates, receiving pass updates, communicate bus position as well as any other server to bus fare unit communication that is needed.

Custom pass types can be added with rules for versatile and complex approval criteria.

Driver Interface Unit (DIU)

The Driver Interface Unit (DIU) has the following list of main tasks:

• Present a user interface to the driver so the driver can
  • Login
  • Set the route number
  • Accept cash fares
  • "Manually" advance stops if need be
  • Show passes accepted
  • Give audio feedback about pass acceptance or denial
  • Show diagnostic information on the system if need be
• Send and receive messages to/from the PIU
  • Send message information to the PIU for time updates and pass acceptance or denial
  • Receive fare media data as passes are presented to the PIU
• Record and update GPS information
• Manage the route information
  • Take GPS coordinates and update stop changes in the route accordingly
• Manage card and pass information updates and rule checks
  • Accept or decline ridership depending on custom rules
  • Update card and pass information locally
• Send and receive card and pass updates due to card and pass usage
• Manage the inter process communication of all the services
• Manage and monitor processes, restarting as necessary if they become unresponsive or crash
• Monitor configuration and software version updates from the central server and download and install updates as necessary

Most peripheral connections use a USB to serial connection to communicate.

Connection to the central server is done through an SSH tunnel, connecting local ports to the DIU to listening ports on the central server where each service resides. Encryption is done though SSH to alleviate the complexity of managing the secure connection and to allow for ease of debugging.

Locally to the DIU, the rules for pass acceptance criteria are encoded as a scheme file that is run against every pass type received. Since the rules are evaluated as code, the criteria can be complex and can include:

• Pass checks for time
• Pass checks for route
• Pass checks for GPS coordinates

Each of these pass acceptance criteria can be combined and new ones can be added as desired.

Passenger Interface Unit (PIU)

The Passenger Interface Unit (PIU) has the following list of main tasks:

• Manage the RFID and Magstripe reader, recording fare media information as it's presented
• Send fare media data to the DIU through the (USB) serial connection
• Update display to the passenger
• Listen for messages from the (USB) serial connection from the DIU (for example, time and date presentation, pass acceptance or denial, etc.)

There are plans of adding a camera to the PIU to accept QR and bar codes but as of yet, this is not implemented

Server Infrastructure

The central server manages connections from the fleet of deployed Popufare Bus Units (PBUs).

This includes:

• Listening to updates to the services for:
  • Billing updates
  • Pass updates
  • GPS updates
  • Version updates (configuration and software versions)
  • "PING" requests
• Update central database with appropriate updates
  • Update billing log
  • Update card and pass information due to usage
  • Update GPS coordinates of buses
• Manage connections to the API to satisfy query requests

The API acts as an abstraction to query, manage and update data in the database.

Administrative Web Interface

The Administrative Web Interface provides a tool to access and manage the system for administrators and other privileged operators of the system.

The Administrative Web Interface provides facilities to:

• Update route information
  • Sends a signal to start the process of packaging a configuration file for deployment to the fleet
• Manage card and pass information
• Manage information about ridership users

Web Store Front

The web store front allows for ridership users to order cards in addition to purchasing and recharging passes on their cards.

Users can register with the system and register cards they already have in their position with their user account or purchase new cards to be shipped. Once a card has been associated with a ridership user, passes can be purchased as desired.

Passes can be 'queued' in an order so that when the current pass has been depleted, the next pass in the queue is automatically registered as the next 'active' pass.

License

See the appropriate files for individual licenses.

By default, Popufare source code is primarily under an Affero GNU Public License v3 (AGPLv3) (see LICENSE.txt for details) and Popufare

By default, non source code digital artifacts are under a Creative Commons, By Attribution, Share Alike (CC-BY-SA) license.

Popufare uses third party libraries and, where possible, the licenses have been kept unaltered.