Help
Plain answers about setting up RING, the words setup uses, the sensors, and this site.
Still stuck?
Questions about a particular gateway or sensor are welcome. Write to [email protected] or [email protected].
Contact the teamGetting started
A way to send small sensor readings a long way on very little power. Sensors talk by radio to a gateway, often from more than a mile away in open fields, and the gateway passes their readings to a server over the internet or a private network.
It suits farms and research plots because one gateway can cover a lot of ground, and the sensors don’t each need a cellular plan.
Official reference: LoRa Alliance: About LoRaWAN (opens in a new tab)
Not much. RING tells you which command to run, which computer to run it on, and what you should see afterwards. You’ll open a terminal (explained in Help), paste commands, and sign in to your server with SSH (explained in Help). You don’t need to write configuration files or know Docker (explained in Help): the setup package does that.
Every technical word in setup links to a plain explanation on this page, like the ones in this answer.
A Linux (explained in Help) server you can reach over SSH (explained in Help): a mini-PC on site, or a cloud server (explained in Help) such as Amazon EC2 or Google Cloud Compute Engine. We test on Ubuntu Server 24.04 LTS on 64-bit x86, with Docker Engine and the Compose plugin. How big it needs to be (explained in Help).
For the field, a gateway that supports LoRa Basics Station (explained in Help) on US915, and your sensors’ registration details from the manufacturer: the DevEUI and AppKey (see OTAA (explained in Help)). You can finish the server setup before the hardware arrives.
No. This website never connects to your server. It builds the installation package in your browser and shows you the commands to run yourself, one step at a time. Automated remote installation is still being developed.
No. You type passwords only into your own terminal. RING never asks for SSH keys, server passwords, or your sensors’ keys, and it never stores them.
The setup package
A ZIP file the setup page makes in your browser from your answers. It’s under 1 MB and holds four things:
- The configuration generated for your server: which addresses and ports (explained in Help) to use, the US915 frequency plan, and your site’s name and place.
- The scripts you run on the server:
preflight,install,status,verify, andsensors. - Your site’s RING dashboard: the web pages that show your readings.
- The telemetry service’s source code: the small program that stores each reading.
It doesn’t contain the service software itself, or any password. When you run
./installon the server, it downloads the service software (as Docker (explained in Help) images, about 2 GB), builds the telemetry service, and creates the passwords there. Your settings never leave your browser.One self-contained group of services on your server (a Docker Compose project), with pinned versions and the US915 frequency plan (sub-band 2):
- The LoRaWAN network: ChirpStack (explained in Help); the ChirpStack Gateway Bridge (explained in Help), where Basics Station (explained in Help) gateways connect; the Mosquitto (explained in Help) MQTT (explained in Help) broker; and PostgreSQL (explained in Help) and Redis (explained in Help), ChirpStack’s storage.
- Your readings: MySQL (explained in Help), where RING stores every reading; the telemetry ingestion service, which saves each decoded reading from MQTT; the migrations that prepare its database; and the telemetry API, which serves readings to the dashboard.
- Your dashboard: your site’s own RING dashboard, served by Nginx.
It also leaves five tools in the project folder:
./preflightchecks the server before anything is installed, and changes nothing../installinstalls RING. Run again, it resumes or updates without losing data, passwords, or sensor choices../statuschecks that every service is working, one line each../verifyfollows a reading from the gateway to the dashboard and says where it stops../sensorslists the sensors RING has heard from, and chooses which ones the dashboard shows. The dashboard’s Add sensor does this for most people.
./statuschecks all eleven services. Nothing is published to the internet: ChirpStack and the dashboard are reached through an SSH tunnel (explained in Help).
Choosing a server
We measured a complete RING installation: its nine services used about 565 MB of memory at rest, most of it MySQL (about 442 MB), and Docker’s software and data took about 3.9 GB of disk before any readings were stored. With Ubuntu itself on top:
- Memory: 4 GB recommended, 2 GB at least. 1 GB servers (t3.micro, e2-micro) are too small.
- Processor: 2 vCPUs, 64-bit x86 (amd64). Arm servers aren’t supported.
- Disk: 30 GB recommended, 20 GB at least. Cloud providers start smaller, so set it when you create the server.
- For example: AWS t3.medium (4 GiB) or t3.small (2 GiB); Google Cloud e2-medium (4 GB) or e2-small (2 GB).
A small mini-PC with 4 GB or more of memory is plenty.
Not for RING’s server. Firebase Hosting publishes websites and web apps. It doesn’t give you a Linux (explained in Help) computer you can sign in to with SSH (explained in Help), or run Docker (explained in Help), and RING’s installer needs both.
If you use Firebase, you already have a Google Cloud project: every Firebase project is one. Create a Compute Engine virtual machine (explained in Help) in it, and follow the Google Cloud guide in setup, stage 2.
Official reference: Firebase Hosting overview (opens in a new tab)
Terms: your computer and the server
Words you’ll meet while preparing the server and running commands.
A window where you type commands instead of clicking. On a Mac it’s called Terminal (Apple’s guide (opens in a new tab)). On Windows, RING uses PowerShell inside Windows Terminal. You paste a command and press Return or Enter.
In RING: you paste each command setup shows into a terminal. The same window can work on your own computer or, once you sign in with SSH (explained in Help), on your server. The text before the cursor, the prompt, tells you which: setup shows what each looks like.
Official reference: Microsoft: Windows Terminal (opens in a new tab)
Linux is an operating system, like Windows or macOS, that most servers run. Ubuntu is a popular edition of it, and Ubuntu Server is the version without a desktop, used by typing commands.
In RING: your server runs Ubuntu Server 24.04 LTS, the version the RING team tests. LTS means long-term support: it gets security updates for years. It needs 64-bit x86 hardware, also written x86-64, x86_64, or amd64. Arm computers, such as a Raspberry Pi, aren’t supported.
Official reference: Ubuntu Server (opens in a new tab)
A computer that runs inside a cloud provider’s data centre, which you rent by the hour or month. You create it on the provider’s website and use it over the internet.
In RING: it can be RING’s server instead of a mini-PC. It must be a Linux virtual machine you can sign in to with SSH (explained in Help), such as Amazon EC2 or Google Cloud Compute Engine (opens in a new tab). Website hosting, such as Firebase Hosting (explained in Help), isn’t a virtual machine. Setup stage 2 has a guide for each provider.
Official reference: AWS: Get started with Amazon EC2 (opens in a new tab)
Secure Shell: a safe way to use another computer’s terminal over a network. After you connect, what you type runs on that computer, and everything is encrypted. SCP, its companion, copies files the same way.
In RING: you sign in to your server with
sshand copy the setup package to it withscp. Both are built into macOS and Windows. You sign in with the server account’s password, or with an SSH key: a pair of files, a private one kept on your computer and a public one on the server. Cloud servers usually require a key.Official reference: OpenSSH (opens in a new tab)
Docker runs software in containers: sealed packages that bring everything they need, so they run the same way on any server. Docker Compose starts a group of containers together from one file.
In RING: the installer uses Docker to download and run ChirpStack, the databases, and the dashboard, each in its own container, and Compose to run them as one project named after your package. You install Docker Engine and its Compose plugin once, while preparing the server.
Official reference: Docker: What is Docker? (opens in a new tab)
Terms: addresses and connections
How your computer, the server, and the gateway find each other.
A number that identifies a device on a network, much like a street address, such as 192.168.1.20. A hostname, such as
mini.farm.local, is a name that points to one. Private addresses (192.168.x.x, 10.x.x.x, 172.16–31.x.x, and Tailscale’s 100.64–127.x.x) work only inside one network; public addresses work across the internet.In RING: your server has two addresses that matter. Your computer uses the SSH address to sign in. The gateway uses the gateway-facing address, a private one, to send readings. They can be the same or different.
Official reference: MDN: IP address (opens in a new tab)
A numbered door on a computer. One address can offer many services, each listening on its own port: SSH usually on 22, websites on 80 or 443. It’s written after a colon, as in 192.168.1.20:23001.
In RING: the gateway connects on port 23001, ChirpStack’s web page is on 28080, and your dashboard on 28081. They’re the defaults, and you change one only if another program already uses it.
Official reference: MDN: Port (opens in a new tab)
A name that always means “this computer”, whichever computer you’re using. Its address is 127.0.0.1.
In RING: ChirpStack and your dashboard listen only on the server’s own localhost, so no one on the internet can reach them. The SSH tunnel (explained in Help) makes
http://localhost:28080on your computer lead to ChirpStack on the server. That’s why the address works only while the tunnel runs, and only on the computer running it.Official reference: RFC 6761, section 6.3: localhost (opens in a new tab)
An SSH connection that carries web traffic instead of typed commands. It joins a port (explained in Help) on your computer to a port on the server, encrypted all the way.
In RING: one tunnel command opens ChirpStack and your dashboard in your own browser, at localhost (explained in Help) addresses. It needs its own terminal window, which looks as if it’s doing nothing: keep it open while you use them. Closing it only closes your view; RING keeps running on the server.
Official reference: OpenSSH manual: ssh -L (opens in a new tab)
A network only your own devices can join, such as your farm or office network (a LAN), where devices have private addresses (explained in Help). Tailscale is a service that joins devices in different places into one private network over the internet, and gives each an address from 100.64.0.0 to 100.127.255.255.
In RING: the gateway sends readings to the server over a private network, never the open internet. With a mini-PC on the gateway’s network, that’s simply your LAN. With a cloud server, Tailscale connects the two: the server joins your Tailscale network, and an always-on device at the site passes the gateway’s traffic to it (a Tailscale subnet router (opens in a new tab)). Setup’s cloud guides show the steps.
Official reference: Tailscale: What is Tailscale? (opens in a new tab)
Terms: LoRaWAN and RING’s services
The software RING installs, and the words ChirpStack uses.
Open-source software that runs a LoRaWAN network: it keeps the list of your gateways and sensors, checks each sensor’s keys, and turns their radio messages into data.
In RING: ChirpStack manages your LoRaWAN network, gateways, and registered sensors. You register your gateway and sensors in its web page, which you open through the SSH tunnel (explained in Help). RING installs version 4.3.
Official reference: ChirpStack (opens in a new tab)
A small ChirpStack program that speaks the gateway’s language on one side and the server’s messaging system on the other.
In RING: it connects supported gateway traffic to the server’s messaging system: your gateway connects to it over Basics Station (explained in Help), and it passes the gateway’s messages on through MQTT (explained in Help). It’s the one service the gateway talks to, on the gateway-facing address.
Official reference: ChirpStack documentation (opens in a new tab)
LoRa Basics Station is a standard way for a gateway to connect to a LoRaWAN network server. The gateway opens the connection and keeps it open, so the server tells it which radio channels to use.
In RING: you set your gateway’s work mode to Basics Station and enter the server’s address and port. The Gateway Bridge (explained in Help) answers it and sends it the US915 sub-band 2 channel plan.
Official reference: Semtech: LoRa Basics Station (opens in a new tab)
A messaging protocol for small devices: programs publish messages on named topics, and anything subscribed to a topic receives them.
In RING: MQTT is how readings pass between services. The gateway’s traffic travels over it to ChirpStack, and ChirpStack publishes each decoded reading on it, where RING’s telemetry service picks it up.
Official reference: MQTT (opens in a new tab)
An open-source MQTT broker: the post office that receives every message and passes it to whoever subscribed.
In RING: Mosquitto is the MQTT broker that receives messages and passes them to subscribers. It runs inside your RING project only, never reachable from outside the server.
Official reference: Eclipse Mosquitto (opens in a new tab)
A widely used open-source database, often called Postgres.
In RING: PostgreSQL is the database used by ChirpStack: your gateways, sensors, device profiles, and ChirpStack’s accounts are kept there. Its password is created on your server by the installer.
Official reference: PostgreSQL (opens in a new tab)
A very fast store that keeps data in memory, for things that change often.
In RING: Redis is fast storage used by ChirpStack, for its working state such as each sensor’s session and recent events.
Official reference: Redis (opens in a new tab)
A widely used open-source database.
In RING: MySQL is the database where RING stores sensor readings: every decoded reading, kept, so the dashboard can chart any period. It’s separate from ChirpStack’s database.
Official reference: MySQL (opens in a new tab)
Over-the-air activation: the way a LoRaWAN sensor joins a network. The sensor sends a join request, the network checks it with the sensor’s key, and they agree on session keys that protect every reading after that.
Each sensor comes with a DevEUI, its unique 16-character ID, and an AppKey, its secret key. Dragino also lists an AppEUI (JoinEUI); ChirpStack 4.3 doesn’t ask for it.
In RING: you enter the DevEUI and AppKey in ChirpStack only, when you register the sensor. RING’s website never asks for them, and never stores them.
Official reference: LoRa Alliance: About LoRaWAN (opens in a new tab)
A message a sensor sends up to the network, usually one reading. A message sent the other way is a downlink.
In RING: the sensor sends an uplink about every 20 minutes. ChirpStack shows each one as an up event on the device’s Events tab, and RING stores it once it’s decoded.
A sensor sends each reading as a short message of bytes, to save radio time and battery: for example,
0E 1A 00 00 0A B7 07 1D 01 38 10. A payload decoder is a small piece of code that converts that message into readable measurements: from these bytes, Dragino’s decoder reads soil moisture 27.43 %, soil temperature 18.21 °C, conductivity 312 µS/cm, and battery 3.61 V.In RING: you paste the sensor maker’s decoder into ChirpStack’s device profile (the Codec tab). Without it, ChirpStack receives the bytes but RING has no measurements to store.
Official reference: ChirpStack: Device profiles (opens in a new tab)
This site and the project
From RING’s own deployment at Purdue. Two soil sensors report about every 20 minutes through a LoRaWAN gateway to ChirpStack, and a small service stores each reading. The Sensors page shows only public measurements, never device identifiers or raw payloads. Its Download button saves those readings, as received, as a CSV file or an Excel workbook for analysis.
No. The Weather page uses Open-Meteo’s forecast models for the location you choose. It is kept separate from the sensor data: it isn’t combined with it, and it isn’t used to give advice.
Very little, and only in your browser. Your setup answers and progress are kept in the current browser tab and are gone when you close it. Passwords, key contents, and pasted terminal output are never stored.
Your temperature unit and weather location are remembered in this browser. After your first visit, the browser also keeps a small page to show if you open the site without a connection. There are no accounts and no analytics. Fonts load from Google Fonts and weather comes from Open-Meteo, so those services receive ordinary requests from your browser. In setup, the map for finding your farm comes from OpenStreetMap, which also receives what you search for and the spot you confirm, to name the place; Open-Meteo receives the spot to find its time zone.
RING is a research prototype from Purdue University’s Department of Agricultural and Biological Engineering, shared for research and education. Read each step before you run it on your own equipment, and keep your own backups. Sensor readings, screening ranges, and weather are for information, not agronomic advice. If you would like to use RING in your own work, contact the team.
AgBridge was a separate summer initiative. It isn’t RING’s sponsor or funding source, and is mentioned here only as related history.