National Railways Federation

Branch federation of the railway operating cooperatives

Interfaces, specifications and source

Article 10 puts technical knowledge in the knowledge commons and prohibits a patent over it. What follows is the whole of what the federation holds: the wire protocol of the card, the interfaces the application reads, the guide for a transit system that wants to fork the standard, and the flags that decide what a build contains.

  • 4 documents
  • 0 licences to sign
  • 3,100 lines in the driver
  • 2 interfaces to read

The four documents

  • Card wire protocol

    Frames, command encoding, the authentication sequence, record encoding, the CMAC, status words and test vectors. The overview of the card sits on the CARD-ROM page; this is what a reader has to send.

    Read the protocol

  • Application interfaces

    What the federation publishes at api.nrf.rof: timetable, platforms, changes, reports, stations and routes.

    The vehicle positions come from Podnik and are documented by them.

    Read the interfaces

  • Forking the standard

    What a transit system outside the Bloc may change and still be read by the gates here, how to register an issuer key, and how the conformance suite is run.

    Read the guide

  • Build flags

    Every flag in the reader firmware and the card personalisation tool, its default here, and what compiling it in costs in memory. The fare and purse modules live here.

    Read the flags

Source

Published trees, all public domain under Article 10
Tree Published at Language Lines What it is
cardrom-driver source.nrf.rof/cardrom-driver C99 3,100 Reference driver. Mounts the three regions of a card as block devices under FreeRTOS. Allocates nothing after start.
gate-firmware source.nrf.rof/gate-firmware C99 11,400 The gate as it stands on the platform: four tasks, the 300 ms deadline, the panel in twelve languages.
machine-firmware source.nrf.rof/machine-firmware C99 18,900 The concourse machine. Adds the contact carrier, the printer and the section list.
railways-app source.nrf.rof/railways-app C++ and QML 26,000 The application, Qt and Kirigami.
conformance source.nrf.rof/conformance Python 4,700 The suite a fork runs against its own build, with the test vectors.
Samples on this page
File Shows Take it
cardrom_read.c Selecting a card, authenticating, and reading the last records under FreeRTOS. cardrom_read.c
append_record.c Journalling a record and committing it inside the gate deadline. append_record.c
board.py A departure board client: the federation timetable joined to the Podnik positions. board.py
vectors.txt Test vectors for diversification, authentication and the record CMAC. vectors.txt

The addresses above resolve inside the Republic. source.nrf.rof serves each tree over git and as a tarball, and a mirror sits at mirror.podnik.rof/nrf. The four samples are served from this site as well, so that a reader outside the Republic can take them.

Versions

  • The standard

    Revision 3 since 2021. A revision is agreed between the three networks of the Bloc and published a year before any gate requires it. Revision 3 cards are read by every gate and will be until the last of them expires.

  • The interfaces

    Versioned in the path. /v1 has stood since 2019 and will stand for two years past the announcement of a successor. Fields are added and never removed inside a version.

  • The firmware

    Released with the signature beside it. A gate refuses an image whose signature does not check, and a worker at the station has to unlock a gate that has been reflashed.

  • The station and route identifiers

    An identifier is retired and never reused, and the retirement is in the change feed for a year before it takes effect.