telraam-rs

Telraam is a system for collecting data from streets by way of people placing IOT devices in their homes to track the usage of their street. It provides crucial data on various modes of transport, including motor vehicles, cyclists, pedestrians, and more. Telraam networks can help create the opportunity for dialogue between traffic planners, local authorities and their most affected communities: the citizens who live on - and use - these streets, by turning traffic counting into an open and accessible citizen science project.

This project is a library and CLI for accessing the data captured by the Telraam network. It is intended for collecting data which can then be stored in another system for analysis. Feel free to make suggestions on any improvements that can be made, or contribute to the project.

Getting Started

This project requires the Rust toolchain, use rustup to install, or a system package manager.

Installing from the current published version

This will install the currently published crate from the Crate.io public Rust package manager

> cargo install --features=clap --bin telraam telraam-rs

Working from source

Clone this repo:

> git clone https://github.com/radical-bike-lobby/telraam-rs.git

note, the next series of commands assume your current working directory is in telraam-rs, i.e. cd telraam-rs

Running tests:

> cargo test --all-features

Run directly from the project with the cargo run command:

> cargo run --features=clap -- --help

This can be installed from source as well:

> cargo install --features=clap --path . --bin telraam

Running the commands

All of the commands are derived from the Telraam documentation. You will need to login into your Telraam account and get an API token: https://telraam.net/en/admin/mijn-eigen-telraam/tokens

The telraam CLI will read this from the environment TELRAAM_TOKEN, or from the parameter -t ${TELRAAM_TOKEN}. It's recommended to use the environment variable as this won't end up with the token in logs or shell history.

Test that your token and the CLI work with the welcome command,

> telraam welcome
msg = hello! Telraam server 2.0 is up and running

When running with cargo run, all options to telraam must follow --,

> cargo run --features=clap -- welcome
    Finished dev [unoptimized + debuginfo] target(s) in 0.39s
     Running `target/debug/telraam welcome`
msg = hello! Telraam server 2.0 is up and running

For the other options, use help:

> telraam --help

Some commands have their own parameters:

> telraam traffic --help

Output

All output is currently in json, the formats are the inner types defined in the API, like the list of reports in traffic, see the documentation for traffic.

Contributing

This project is licensed under the MIT license. Please feel free to contribute.

Let's all work to make our streets safer!