Skip to main content Link Menu Expand (external link) Document Search Copy Copied

Anyone can explore the RF spectrum

OpenRFSense is an experimental software suite to explore radio frequency data using remote devices and a centralized server.

Get started now View the source code

The OpenRF project is a suite of free-as-in-freedom software which uses a central control and reporting server to communicate with an arbitrary fleet of remote sensors. Each sensor (or “node”, as it may be referred to) is equipped with a Software-defined Radio (or SDR for short), such as a cheap RTL-SDR.

This project is powered by the following technologies:

Golang

Docker

NATS

PostgreSQL

Getting started

Getting OpenRF up and running can be really easy, thanks to Docker. This guide will show examples and code snippets using fragments of Docker Compose configuration (docker-compose.yml) because of its relative ease of understanding and concise representation of containers and resources.

The backend has to be deployed first, but it requires a running PostgreSQL instance to store the radio measurements received from the sensors.

PostgreSQL

There are no particular requirements regarding the database structure, since the backend will automatically migrate the database table schemas it needs. The database can even be just anything compatible with the PostgreSQL wire protocol, like CockroachDB.

Following the official PostgreSQL Docker documentation (found here), an instance can be deployed like this:

1
2
3
4
5
6

postgresql:
  image: postgres:alpine
  ports:
    - 5432:5432
  environment:
    POSTGRES_PASSWORD: postgres

This will run PostgreSQL on port 5432 on the host, with username postgres and password postgres

Backend

The backend is also trivially simple to deploy, thanks to it being developed with containerization in mind. Based on the PostgreSQL instance used above, a snippet for the backend could look like this:

1
2
3
4
5
6
7

orfs_backend:
  image: openrfsense/backend:latest
  ports:
    - 2222:2222     # Measurement collector port
    - 8080:8080     # Backend API/UI HTTP port
  environment:
    ORFS_NATS_TOKEN: nats-token

This example uses the least configuration possible for the backend, as the default configuration baked in the binary:

  • expects the database to be reachable on localhost:5432 (with username postgres and password postgres), which is the default on PostgreSQL too
  • listens for raw TCP packets coming from the sensors on port 2222 (forwarded to the host)
  • sends HTTP reponses on port 8080 (also forwarded to the host)

Complete example

Joining together the two snippets above, a docker-compose.yml would look something like the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

services:
  postgresql:
    image: postgres:alpine
    ports:
      - 5432:5432
    environment:
      POSTGRES_PASSWORD: postgres

  orfs_backend:
    image: openrfsense/backend:latest
    ports:
      - 2222:2222     # Measurement collector port
      - 8080:8080     # Backend API/UI HTTP port
    environment:
      ORFS_NATS_TOKEN: nats-token

The service stack can then be started with Docker Compose in the usual way:

1

$ docker compose up

You should then be able to open localhost:8080 on your machine to see the sensor management UI.

Node

Deploying and maintaining a sensor/node is also really easy, but it can be done in two main ways.

Manual deployment on a generic machine

Since all that’s needed for the node to run are the binary executable and the configuration file, you can just download the latest release and run it:

1

$ ./orfs-node --config <your config file>

Disk image on a supported board

Since this method warrants its own page, see node/deployment.

What’s next?

If you wish to explore the rest of documentation (highly recommended) or get a better understanding of how the whole system works, visit the following pages: