FAQ and glossary

Questions

Is it really free? Yes. BikeKit is free and open-source software, under the GNU Affero General Public License, version 3: no licence fee, no per-bike or per-ride charge, and you may change it. If you run a changed copy, you offer its source code to the people who use it, which the backoffice's Source code link does once SOURCE_URL points at it. Your costs are the bikes, stations, server, hosting and the outside services every scheme needs: a payment provider, certified invoicing, and push and email.

What hardware does it work with? Any station, bike or e-lock that speaks BikeKit's station and bike protocol: a short HTTP contract in which stations report their docks, bikes report where they are, and the server sends unlock and lock commands (plan.md §8.2 to §8.5). Ask your supplier to build to it, or put a small gateway between their system and BikeKit. Virtual stations need only bikes with their own lock and a gateway.

Do we need docks? No. Virtual stations are marked parking areas where the bike locks itself. A scheme can mix both, or use only virtual stations.

How big a city can it run? One server and one database are designed for a city of about 140 stations, 2,600 bikes and 50,000 riders, and tested with 550 stations, 10,000 bikes and 60,000 riders on a machine held to a Raspberry Pi 4's power. Larger cities can use a larger server.

What if the server or a station goes down? Nothing that matters is lost: every state is in the database, and the server picks up where it was when it restarts. A station that can't be reached refuses unlocks until it reports again. When a station's report is lost, the next one corrects the records, and any ride it closes late is charged to the earlier time, in the rider's favour.

What if a station and the server disagree? The station wins: it can see the bikes. The server corrects its records to match and records an issue for a person to check.

Can riders be charged twice? No. A ride is charged once, whatever the station reports twice. Each payment is recorded before the payment provider is asked, an app that retries a payment with the same key gets the first one back, and a payment left unfinished by a crash is checked with the provider and either finished or given back.

What about privacy? Riders' data is used to run the service. Riders can ask for a copy of everything held about them and close their account, from the app; staff answer within 30 days. Open data never names a rider or shows a route. The positions bikes report are deleted after 30 days, and a closed account's routes are erased. Photos lose their location data on upload. Every look at an identity document is logged.

Which languages? The backoffice, notifications, invoices and open data are in Portuguese and English. Adding another language means translating the backoffice's message files and the notification templates.

Can it be used outside Portugal? Most of it, yes. The scheme's names, the seller on invoices, the VAT rate, the time zone and the map are settings. Tax numbers are checked for Portugal, Spain, the Netherlands and Belgium, and kept as typed for other countries; adding a country's check is a small change in the code. Invoicing still follows Portuguese law (series, ATCUD, signatures), which needs changing in the code for another country (see What stays fixed).

Can we change the time zone later? No: set TIME_ZONE before the server's first start. The reports keep a total for each day, cut at your midnight, and some of the records behind them are deleted after a month, so they could not be cut again at another zone's. A server started later with another zone refuses to start and names the zone it keeps. To start again in another zone, start from an empty database.

Is this guide available in Portuguese? Not yet. The backoffice itself is.

Can we sign in with our council's accounts? Yes. Staff can sign in through any OpenID Connect provider, such as Microsoft Entra ID, with their role taken from it (see Settings).

Glossary

Alert. A condition the server watches for, such as a low battery or a station empty too long. Raised and cleared by itself. See Alerts.

Bike states. Where a bike is: In a dock, On a ride, With a worker, Missing or Retired. Separate from its condition.

Closure. A rule that stops riders unlocking at a station, a zone, a dock, a bike or everywhere, now or on a schedule. Workers aren't stopped. See Closures.

Condition. Whether a bike is fit to ride: Good, Worn (rideable, flagged) or Not rideable.

Cooldown. The wait between rides: five minutes by default after a ride ends before the rider can unlock again.

Custody. A bike taken out of a dock by staff, for rebalancing, repair, inspection or storage. Docking it anywhere ends custody.

Deposit. Money held on a rider's card while a day pass lasts, released five days after. Support may keep part of it for a lost or damaged bike.

Device token. The secret a station or bike sends with every report, shown once when it is added.

Dock. One place at a station that holds and locks a bike. It is free, occupied, faulty (it reported a fault) or blocked (a closure or equipment state shuts it).

Equipment state (sub-state). A state your team defines for bikes, docks or stations, such as Awaiting repair, on top of the fixed ones. Set by hand or by a rule. See Equipment states.

Event. A record of a change (a ride ended, an invoice issued) that webhooks deliver to other systems.

False start. A ride under three minutes that ends at the station it started from: free, and not counted in statistics.

GBFS, MDS. The open data standards BikeKit publishes. See Open data.

Issue. Something a person must look at: a bike reported lost, a return not registered, a station report that didn't match the records, a call for help. See Issues.

Pass. What lets a rider ride for a time: annual, monthly, day. A ticket is a number of rides instead.

Period. The unit a ride is charged by, 45 minutes by default. The first is free on every pass that comes with BikeKit.

Points. Earned per ride and for helping balance stations; they pay for a ride's charge, nothing else.

Rebalancing. Moving bikes from full stations to empty ones, usually by van. A station empty or full for 30 minutes opens a rebalancing order.

Reconciliation. What happens when a station reports something the server didn't expect: the station is believed, the records are corrected, and an issue is recorded for Support.

SLA. The targets for picking up and resolving work orders, by kind and priority. See Deadlines.

Shift sheet. A technician's record of a shift: team, vehicle, odometer, tools, damage, and the orders done.

Station status. Commissioning (added, not yet reporting), Active, Closed (by hand, with a reason) or Decommissioned.

Virtual station. A marked area on the street where bikes lock themselves, with a set number of places (points). It behaves like a dock station for riders and staff.

Wallet. A rider's prepaid euro balance. Ride charges come out of it; it can go negative, which blocks the next unlock.

Work order. A job for a technician: a repair, an inspection or rebalancing, about a bike, a dock or a station. See Maintenance.

Zone. A named area of the city drawn on the map. See Zones.