| name | felica |
| description | FeliCa/MRT Pass card protocol knowledge for this app — command and response byte layouts, transaction block anatomy, known headers, and how to test card-reading features without physical hardware (fixtures + FakeCardTransceiver). Load before any task touching nfc/, parsers, stations, or card data. |
FeliCa card reading in MRT Buddy
Dhaka MRT Pass / Rapid Pass cards are Sony FeliCa (NFC-F). The app reads the transaction-history service and parses 16-byte blocks. All parsing is pure Kotlin in commonMain — no hardware needed to test it.
Read command (built by NfcCommandGenerator, commonMain)
"Read Without Encryption", service code 0x220F, 10 blocks per call, two calls (blocks 0–9 and 10–19):
[0] LEN (total command length)
[1] 0x06 command code
[2..9] IDm (8-byte card id, from tag)
[10] 0x01 number of services
[11,12] service code little-endian → 0x0F, 0x22
[13] number of blocks
[14..] block list: 0x80, blockNo pairs (2 bytes per block)
Response frame (Android NfcF.transceive; parsed by the shared frame decoder)
[0] LEN
[1] response code (0x07)
[2..9] IDm
[10] status flag 1 ← must be 0x00
[11] status flag 2 ← must be 0x00
[12] number of blocks
[13..] blocks, 16 bytes each
iOS CoreNFC (readWithoutEncryptionWithServiceCodeList) returns status flags + per-block NSData directly — no frame. Both platforms are normalized into FelicaReadResult(statusFlag1, statusFlag2, blocks) behind the CardTransceiver interface.
Transaction block (16 bytes; TransactionParser.parseTransactionBlock)
[0..3] fixed header → transaction type (see below)
[4..6] timestamp, int24 big-endian (bit-packed, see below)
[6..7] transaction type bytes (hex string, stored)
[8] from-station code
[10] to-station code
[11..13] balance, int24 little-endian (BDT)
[14..15] trailing bytes
Timestamp bit-packing (decoded by TimestampService.decodeTimestamp(value, baseYear)):
hour = bits 3–7, day = bits 8–12, month = bits 13–16, yearOffset = bits 17–21; year = baseYear + offset. Always pass an explicit baseYear in tests — the default derives from the system clock.
Known fixed headers (TransactionType.fromHeader in model/Transaction.kt):
| Header | Meaning |
|---|
08 52 10 00 | Dhaka Metro commute |
08 D2 20 00 | Hatirjheel bus start |
42 D6 30 00 | Hatirjheel bus end |
1D 60 02 01 | Balance update (MRT Pass) |
42 60 02 00 | Balance update (Rapid Pass) |
| anything else | CommuteUnknown |
Station codes live in nfc/service/StationService.kt (metro line 6 + Hatirjheel BRT; unknown codes render as Unknown (code)). Transactions with timestamps ≤ 2020-01-01 are filtered as invalid.
Testing without a card
- Fixtures:
composeApp/src/commonTest/kotlin/net/adhikary/mrtbuddy/nfc/FelicaFixtures.kt builds valid blocks and full frames. Extend it rather than hand-rolling byte arrays in tests.
- Pipeline tests: implement
CardTransceiver with a fake returning fixture bytes and drive FelicaReader — this exercises the identical production orchestration (status-flag handling, filtering, partial-result semantics) on the JVM.
- Run with
./gradlew :composeApp:testDebugUnitTest.
- Real captured dumps: anonymize the IDm (bytes 2–9 of frames) before checking anything in.
