New cards
There is no single standard way which is used to represent the data on your public transit smartcard. For the most part, every card is different, in every city in the world.
Typically, it takes on the order of weeks of time investment for each new card system, and it requires dozens of annotated card dumps from different cards.
We write this software for fun (and endorphins), and release it for free. There's no advertising, and no dollars changing hands. There's just hundreds of hours of (reverse) engineering effort going into opening data that should have been open in the first place, just because we can.
If you open issues here only asking for a card by name, not providing any useful, technical information, or are otherwise "looking to generate interest in your city's system", your issue will be locked and closed.
Conversely, if you:
- have useful, technical information (such as documentation or specifications)
- have made a reasonable effort to understand a card format yourself
- have made good quality notes on what you've got
- need help using tools that are part of this project (cracking keys doesn't count)
...then I'm happy to work with you! :)
"Reasonable effort" is intentionally ambiguous – you're not expected to be an expert right away! Tips like "card X parses as card Y but has some fault" are helpful: this sort of discovery lead to implementing support for Transit Access Pass and Cubic Nextfare MFC.
See also: Unsupportable Cards
In order to add a new card, the card needs to be readable:
- it may be unreadable as a result of authentication requirements on the card
- ...that can sometimes be cracked
- it may be encrypted at rest
- it may be used as simple storage
- ...or may use structured storage features of the card (eg: "value files")
- ...or may have custom Java Card applications running on the card
- ...or may not have any storage at all!
All of these factors impact how hard it is to read data off your card in the first place.
Your first step should be to try reading your unknown card with Metrodroid. Metrodroid contains a great deal of logic for dumping cards, and will save it to internal storage before trying to parse it.
Once you have some data, you can start iterating and start working on parsing.
This is what the raw data looks like on a Cubic Nextfare MFC card that I've been able to crack. This isn't possible to crack with a regular Android device.
Metrodroid tries a number of different parsers -- and sometimes you can get lucky.
If it turns out that a reader Metrodroid almost works on your city's card, then please get in touch with technical details, card dumps and travel logs.
If you want to give this a try yourself:
-
A good hex editor is essential, such as ghex (GNOME) or Hex Fiend (macOS).
Choose something that shows you arbitrary integer representations, such as little and big-endian representations of different length integers.
Something which shows binary values will help you decode bitfields. Something that supports arbitrary length, non-byte-aligned integers (eg: 12 bit integers) may make things easier, as it's not uncommon for data structures to be very tightly packed.
-
vbindiffshows a diff between two binary files. This is useful for showing what changed after using a card. -
This wiki has documentation about how different binary formats work. Have a look at Opal for a simple example.
While there are a small number of vendors who offer public transport ticketing systems (eg: ACS, Cubic, ERG, INIT, Vix), each deployment has customisations for their clients (that is, the transit agency). The scope of these customisations varies depending on business requirements (eg: fare structures).
This means that cards in use at one agency can have a completely different format from the another, even if they are designed by the same ticketing vendor.
Some practical examples of this, and other complexities:
-
Clipper had its operating contract change during operation, and both ERG (old vendor) and Cubic (new vendor) equipment is in active use.
-
Breeze uses a Cubic Nextfare system, but changed from the MIFARE Classic version to the DESFire version in 2017 (which allows no data access).
-
Opal and 2nd-generation Oyster cards are both built by Cubic on MIFARE DESFire, but Oyster allows no data access. Both are completely different to Cubic's other DESFire systems.
-
Metrocard (Christchurch) switched to INIT in around 2015, and their readers work with both the older ERG MFC system and their new DESFire cards which allow no data access.
-
Shenzhen Tong has both FeliCa cards that are similar to Hong Kong's Octopus, and a new generation of cards that is similar to what is used in other cities in China.
-
Myki was developed entirely from scratch, because of reasons.
Sometimes, you get some (small) wins in other places:
-
Los Angeles' TAP card was easier to understand because of the work that went into reverse engineering Brisbane's Go Card. They both are Cubic Nextfare MFC systems, and findings from Los Angeles (with very detailed logs and dumps provided by a Metrodroid user) helped with Brisbane.
-
Metrocard (Christchurch) was easier to understand because of work that went into reverse engineering the Manly Fast Ferry smartcard. They are both ERG MFC systems.
-
Metrocard (Adelaide) uses a variant of the Calypso format, despite there being no apparent mandate for it.
Sometimes it's a mixed bag:
-
Russia has two major ticket system vendors (Umarsh and Zolotaya Korona), who have very similar cards used across the country. The exceptions being Moscow and Saint Petersburg, which have their own systems, and also hybrid cards that work in both cities.
-
South Korea has a national transit card system (One Card All Pass), which is implemented by T-Money and others. However, the documentation is only available in Korean, and is spread between (paid) standards documents, federal legislation, and Bank of Korea publications.
-
Snapper "plus" cards implement a modified version of the South Korean T-Money application. This made it easier to read (after fixing some bugs), but the modifications require custom code.
-
The United Kingdom has a national interoperability standard for railcards which is not used by the largest operator, and supports multiple card media (making implementation complex).
There are a few different standards for interoperability (eg: Calypso, CEPAS, IC, Intercode, ITSO, KSX6923), but these are an exception. Only a small number of governments actually have these requirements.
Once the data is accessible, it must then be understood so that it can be made human-readable.
This is an extremely time consuming process, sometimes taking weeks of full-time work to complete, depending on the complexity of the data stored on the card.
In order to support a new card, one would need:
-
Access to multiple cards.
-
Detailed trip logs for each of the cards.
-
Some information about fare structures.
-
To actually visit the city where the cards are used, in order to observe different states that the card is in, and different assertions (this often involves visiting different stations, or sitting on a train and making backups of the card).
In some rare circumstances, the public transit agency will document the card format in English. This makes it significantly easier to support. As an example of this, HSL in Finland published documentation about their card format. However, one would still need example data to test the code against with known values.
If you are interested in reverse engineering cards, and want to write new providers, patches are happily accepted. There are some useful tools to help in the "extra" folder in this source repository which will allow you to find the data's structure.
If you understand the format to the point you can either write some documentation and/or demo code that reads dumps from the cards, I'm happy to help get the code into Kotlin (and within Metrodroid's frameworks). This normally needs a large amount of data for each format to validate edge cases: tens of card dumps from many cards for simple balance reading, hundreds of card dumps from many cards for more complex trip reading.
If you must query a remote web service for information about the card, then it will not be supported by this program.
This application will only reference data on the card itself. Most systems that allow online access have mandatory registration, and collect large amounts of personal information in the process.
If you open a request for a new card, and the only information you provide is the name of it, this literally cannot not be worked on.
The issue tracker is not a forum for "generating interest", and issues of this nature will be closed and locked. Ultimatums and blackmail will result in blocks. Try local communities or your city's subreddit instead.
This may seem harsh, but this is to ensure that we can actually use our issue tracker, and to avoid problems caused by open source consumerism.
See What other information is required to support a card? for what information is required to actually start working on this stuff.
For more details on the status of specific upcoming cards, see Project Status.