This repo contains specifications for MQTT message exchange (topic + payload) intended for hardware topologies running in busses using MT Bus client for sales and validation.
Scope of this specification is primarly for Møre og Romsdal Fylkeskommune and FRAM, but the overall ambition is for a broad consensus with other operators and authorities.
Note
Some discussions can be found at the old archived repository.
In this repo you'll find a test client, CLI validator, documentation page, and the specification it self.
- All specification and docs found in /specifications
- Tools, test clients, cli found in /packages
- Running web page with specificatiosn is located in /packages/web
/ ├── device │ ├── [deviceId] │ │ └── diagnostics │ │ └── request │ └── diagnostics │ └── request ├── sensors │ └── location └── validators ├── [deviceId] │ ├── configure │ │ ├── current │ │ └── request │ └── response ├── barcode ├── configure │ ├── current │ └── request └── nfc └── apdu ├── [deviceId] │ └── transmit └── receive
See documentation specifications/README.md.
Given that you have installed Node.js on your system, you can use this package as a CLI for validationg local JSON-files. See documentation on usage
Usage: npx @frammr/mqtt-validator -t [topic] -f [file]
Options:
--version Show version number [boolean]
-f, --file file to validate [required]
-t, --topic choose a topic [required] [choices: ""]
-h, --help Show help [boolean]
Examples:
Validate foo.json with location specification
npx @frammr/mqtt-validator -t sensors/gnss/location -f foo.json
Running the validator and test client as a service connecting to a MQTT Broker (e.g. a hub or gateway in a bus test rig).
- Node.js 18
# 1. Get repo
git clone https://github.com/mrfylke/frammr-mqtt-validator.git
# 2. Install dependencies
yarn install
# 3. Copy .env.example and configure
cp ./packages/test-client/.env.example ./packages/test-client/.env
# Edit .env file
# 4. Start MQTT client
yarn run-testclientThis will add a subscriber to the Broker as specified in .env. You might need
a local test broker also. An alternative might be
Mosquitto.
This shows an example component overview as it could be connected in a bus. All protocols here are MQTT, with the option of multiple Barcode and NFC devices.
---
title: Component connections w/protocols
---
graph TB
subgraph terminal
A(Sales Client)
end
A(Sales Client) <--MQTT--> B(Gateway)
subgraph READERS
D(Barcode/NFC)
E(Barcode/NFC)
F(Barcode/NFC)
end
B <--MQTT--> READERS
B<--MQTT-->G(GPS)
B<-.MQTT.->C(APC)
style C opacity:0.7,stroke-dasharray: 4
The Gateway in this example is the MQTT broker and components and the terminal are producers/consumers.
The following is a pseudo-example of how the communication will go with message passing using MQTT. All payload will be expected to be JSON. See example models further down in this document.
---
title: Example communication flow
---
sequenceDiagram
participant Sales Client
participant Gateway
Gateway->>Barcode: connect()
Barcode-->>Gateway: ack
Sales Client->>Gateway: connect()
Gateway-->>Sales Client: ack
Sales Client->>Gateway: subscribe(/barcode/validation/request)
activate Gateway
Barcode->>Gateway: publish(/barcode/validation/request)
Gateway-->>Sales Client: :validation-request
deactivate Gateway
activate Gateway
Sales Client->>Gateway: publish(/barcode/validation/confirm)
Gateway-->>Barcode: :validation-confirm
deactivate Gateway
The following are examples of what topics and layloads might look like. This will be under continuous change and will be updated as development progresses. For the final source of truth check out the specifications.
{
"atDateTime": "2023-02-06T12:45:50+01:00",
"position": {
"latitude": 0,
"longitude": 0
}
}{
"type": "aztec",
"deviceId": "<id>",
"code": "<base64-encoded-code>"
}Other similar work that is used as inspiration.
- Ruter
- ITxPT
- Samverkansgruppen Validation Services messages