Getting started · OpenITS

Pick the path that matches your role, then bring up Vikasa's reference stack to watch real device state flow through the models end to end.

Pick your path

OpenITS serves four audiences, each with a natural reading order:

Operators: Why OpenITS → Conformance → this guide. Then write RFPs against a testable bar.
Vendors: Architecture → Extension model → Conformance. Implement once, extend in your own namespace.
Integrators: Architecture → the model reference → AsyncAPI. One consumer reads every conforming source.
Researchers: Standards alignment → the schema registry. Pin an immutable revision and cite it for years.

Run the Vikasa stack

vikasa-collector, from the Vikasa project, is the reference edge poller. It reads roadside devices over SNMP, gNMI and ATSPM sources, translates their state into the OpenITS event model, and publishes typed events as CloudEvents over NATS. Standing it up locally is the fastest way to see that the models carry real device state end to end.

Vikasa’s collector and NATS are one valid deployment, not part of the standard. Any faithful binding conforms; this one exists to prove the models run.

You need three things: a NATS server (the event bus), the nats CLI (to watch events), and the collector’s own toolchain, which its repository documents. The commands below cover the parts that are the same for everyone; the collector’s build and flags live in its README, since they track that repository, not this one.

1. Start the event bus. NATS ships as a single container, so no install is required:

# event bus on localhost:4222, monitoring on :8222
$ docker run --rm -p 4222:4222 -p 8222:8222 nats:latest

2. Run the collector against a device. Clone it, then build and run it per its README, pointing it at the bus you just started (nats://localhost:4222) and at a device: a real roadside controller, or the simulator the repository ships for exactly this purpose.

$ git clone https://github.com/Vikasa2M/vikasa-collector
$ cd vikasa-collector
# build + run per the repo README (Go toolchain or container),
# configured with NATS_URL=nats://localhost:4222

See typed events

With the collector polling, subscribe to the OpenITS subject tree and watch events arrive in real time:

# every OpenITS event on the bus
$ nats sub "openits.>"

Each message is a CloudEvent. Its type is the model’s ce-type (for example openits.signal-control.comm-health-event.v1), and its subject follows the canonical pattern openits.<geo>.<agency>.<district>.<service>.<location>.<event>:

# subject of a signal-controller health event
openits.us.example-dot.d01.signal-control.exit-12.comm-health-event

Because every revision is published to the schema registry, you can validate any payload you receive against the exact schema it claims, offline, with no runtime fetch. That is the whole point: the same consumer code reads any conforming source, unchanged.

Next steps

Browse the model reference to see every domain and its event families.
Generate a typed client from the AsyncAPI description instead of hand-writing one.
Pin a revision in the schema registry and cite it; there is no latest alias, so a reference stays valid for years.
Read Conformance to turn the model into procurable RFP language, or Governance to find out how to get a seat at the table.