popufare/busunit/passdb

passdb

passdb is responsible for checking fares against the rule set, updating the local pass database and communicating formatted billing entries to the inter-process communication (IPC) hub.

The main fare media are RFID and mag stripe cards. There are also "manual" fares that can be issued by the driver, in most/all cases from the DIU process, for things like cash fares or other non media fare acceptances.

passdb connects to a central server for updates to card and pass information. The card and pass updates are updated in the local database. The local database is used to ensure that if there is a loss of connectivity, the most recent card and pass information will be used.

By default, passdb connects to the central server through a system wide tunnel through the localhost, 127.0.0.1, on port 7277.

Database Structure

passdb uses a local database of cards and passes. The database is, by default, located in /home/bus/database/passes.mem. See busunit/common/common_config.h for details.

The pass database is a fixed record flat file. Each record mirrors the in memory struct and is as follows:

| seq_num | logical_card_id | magstripe_value | rfid_value | rule_name | rule_param |

| Field Name | Type | Byte Length | Description | |---|---|---| | seq | unsigned long long | 8 | Sequence number of entry | | logical_card_id | unsigned long long | 8 | Logical ID of card | | magstripe_value | charCREDENTIAL_LEN] | 32 | ASCII string of magstripe token | | rfid_value | char[CREDENTIAL_LEN] | 32 | ASCII string of RFID token | | rule_name | char[RULENAME_LEN] | 24 | ASCII string of rule name | | rule_param | char[PARAM_LEN] | 24 | ASCII string of rule parameter |

The structure is created to be an exact power of two (8+8+32+32+24+24=128). Currently, the number of entries is 1048576 (2^20 or just over 1M).

When messages are received for local fare updates, the database is updated appropriately and pass updates are sent via billing messages that are handled by the appropriate processes.

Server updates to cards and passes override entries in the local database. This serves to allow for "quick" fare updates, for example, many NRIDE passes being used locally and not allowing more than the appropriate number of rides, while allowing for "slower" updates from the server to propagate back and update cards and passes to reach eventual consistency.

The pass database is memory mapped if possible to keep on-disk consistent with the in memory representation.

passdb stores the latest sequence number (seq above) to know what its latest entry is and to send back to the central server for incremental updates relative to the most current sequenc number.

In Memory State

passdb creates three hashes to facilitate quick lookup, an ID hash, a magstripe hash and an RF hash.

Each hash list uses the appropriate hash of its field (logical_car_id, magstripe_value, rfid_value) to put it in a "bucket", which then resolves to a linear linked list to traverse.

Additions and deletions update the appropriate in memory hash list.

Each hash entry stores the index into the flat file pass database.

Rules

passdb loads a the scheme file rules.scm (located by default in /home/bus/config/rules.scm) to process complex rule logic. By pushing the rules into a scheme file, complex rules for fare acceptance can be created and customized depending on need.

passdb exposes a few functions to the underlying rules.scm file:

Funciton	Description
debug_print_nonl	Debug print
debug_print	Debug print
tell_rider	Send a PIU message
accept_fare_no_passback	Accept a fare without updating the passback state
drop_vault	Drop vault cash vault on bus (deprecated)
accept_fare	Accept fare updating the passback state
reject_fare	Reject fare
handle_rule_error	Handle rule error (display message to driver, etc.)
get_stopnum	Get the stop number
get_routenum	Get the route number (the floor route number divided by 100)
get_longroutenum	Get the complete route number
get_tripnum	Get the trip number
get_time	Get the time in HH:MM format
get_date	Get the date in YYYY-mm-dd format
get_day_of_week	Get the day of week
get_gps	Get the GPS position (latitude and longitude)
get_rulename	Get the current rule name (e.g. for billing log purposes)
get_ruleparam	Get the rule parameter (e.g. for NRide or NDay processing)
scheme_set_lookaside
scheme_get_lookaside
get_lookaside_param
scheme_strtok
gps_distance	Return GPS distance of two GPS positions as returned by get_gps

The rules.scm file is processed using tinyscheme. Rules can be re-loaded on a HUP signal to the passdb process.

init.scm holds common functions that can be used in the rules.scm file. init.scm is loaded before the rules.scm file is loaded and will be reloaded on a HUP signal.

Additional Information

The passdb listens to the following messages:

Message Type	Action
MAILBOX_UPDATE_PASSES	A pass update from the central server indicating an entry in the local pass database should be updated
MAILBOX_FLUSH_PASSES	A message to recreate the pass database by asking for all current passes
MAILBOX_STATUS_REQUEST	Status request
MAILBOX_TOKEN_RFID	Handle an RFID fare media presenteation
MAILBOX_TOKEN_MAG	Handle a magstripe fare media presentation
MAILBOX_RULE_CALL	Handle a generic rule call
MAILBOX_GPS_STATUS	Update "anti-passback" logic to allow for NDay rules to be allowed
MAILBOX_STOP_STATUS	Update "anti-passback" logic to allow for NDay rules to be allowed

---

Though billdb is the process that communicates billing messages back to the central server, passdb is the process that originally formats the message through a call to format_billing_message.

Additional log messages (through calls to format_log_message) are also contructed here and find their way to the diagnostic_log table in the central server.