Skip to content

User Manual

Jump to bottom
Colin Cogle edited this page Oct 10, 2024 · 5 revisions

How to use aprs-weather-submit

Check out one of the OS-specific pages to learn how to download, compile (maybe), and install this app. This documentation assumes that you got it installed one way or another.

Prerequisites

You'll need an amateur radio license or membership in the Citizen Weather Observers Program. Once you have your ham radio callsign or whatever CWOP uses, great!

You'll also need to know your location (latitude and longitude) and have some weather data to report. If you don't even own a thermometer, go drive by a bank or something.

Theory of Operation

This app was designed to be a quick and dirty way to submit weather station data. Maybe you're typing this all on the command line, or maybe you're using this to power some script. No matter what, there's going to be a lot of typing. (This will change in a future release that I'm still brainstorming that.)

There are two ways to use this app.

  1. If you specify an APRS server, port, username, and password, then your APRS data will be sent to the APRS-IS network.
  2. If you do not specify all four of those things, the APRS packet will be printed to your terminal (on stdout). This may be useful if you're using another app to send APRS data, like Direwolf to a locally-connected radio that sends your weather data over the air!

Help Is Here

To learn how to use this, type aprs-weather-submit for quick help, and aprs-weather-submit --help (/? on DOS) to see all of the options that are available:

$ aprs-weather-submit --help
aprs-weather-submit, version 1.7.2.
Copyright (c) 2019-2024 Colin Cogle.
This program comes with ABSOLUTELY NO WARRANTY. This is free software, and you
are welcome to redistribute it under certain conditions.  See the GNU Affero
General Public License (version 3.0) for more details.

Usage: aprs-weather-submit --callsign [CALLSIGN[-SSID]] --latitude [LATITUDE] --longitude [LONGITUDE] [OTHER PARAMETERS]

Special parameters:
	-H, --help                 Show this help and exit.
	-v, --version              Show version and licensing information, and exit.
	-C, --compressed-position  Create a packet with the compressed position format.
	-Q, --no-comment           Don't include this app's name and version in the comment field.

Required parameters:
	-k, --callsign      Your callsign, with SSID if desired.
	-e, --longitude     The longitude of your weather station, in degrees east of the Prime Meridian.
	-n, --latitude      The latitude of your weather station, in degrees north of the equator.

APRS-IS IGate parameters:
	-I, --server        Name of the APRS-IS IGate server to submit the packet to.
	-o, --port          Port that the APRS-IS IGate service is listening on.
	-u, --username      Authenticate to the server with this username.
	-d, --password      Authenticate to the server with this password.

Optional parameters:
	-A, --altitude                 The altitude of your weather station (in feet above mean sea level).
	-b, --pressure                 Barometric pressure (millibars or hectopascals).
	-c, --wind-direction           Direction that the wind is blowing (degrees).
	-F, --water-level-above-stage  Water level above flood stage or mean tide (feet).
	-g, --gust                     Peak wind speed in the last five minutes (miles per hour).
	-h, --humidity                 Relative humidity (percentage).
	-i, --icon                     Override the default symbol table code and identifier (/_).
	-L, --luminosity               Luminosity (watts per square meter).
	-M, --comment                  Add a custom comment to the packet.
	-p, --rainfall-last-24-hours   Total rainfall in the past 24 hours (inches).
	-P, --rainfall-since-midnight  Total rainfall since midnight local time (inches).
	-r, --rainfall-last-hour       Total rainfall in the past hour (inches).
	-s, --snowfall-last-24-hours   Total snowfall in the past 24 hours (inches).
	-S, --wind-speed               Sustained wind speed in the past minute (miles per hour).
	-t, --temperature              Temperature (degrees Fahrenheit).
	-T, --temperature-celsius      Temperature (degrees Celsius).
	-V, --voltage                  Battery voltage of your weather station.
	-X, --radiation                Radiation levels (nanosieverts per hour).

Find this project online at https://github.com/rhymeswithmogul/aprs-weather-submit

macOS and Linux users can also use man aprs-weather-submit to read the man page, where each option is explained in excruciating detail.

If you've worked with APRS at a low-level before, you may find that many of the short options (such as -T) correspond to their APRS equivalents. However, this isn't always the case, so please double-check your typing or use the long options instead.

Optional: Pick an APRS Tier 2 server

If you want to send your data to the APRS-IS network, you'll need to pick one of the [APRS-IS Tier 2 servers]. You can use rotate.aprs2.net but you may find it better to pick a local server such as noam.aprs2.net for North America. The default port is TCP 14580.

You should have your APRS-IS username and password. The username is your callsign (without an SSID) and your password isn't something you set somewhere; rather, it's formulaic and can be determined by many open-source tools and web forms.

Find Yourself

Find the latitude and longitude of your weather station (not your current location, but where your measuring tools are located). You can use a GPS, a GPS app on your phone, or look at Google Maps or something to find your exact coordinates. You'll need them in decimal format; if you have them in DMS or dd.mmmm format, find a conversion tool online.

Finally Make the Packet

Build your command line. It may look something like this:

aprs-weather-submit --callsign WX1CLUB-13 \
        --latitude 41.123456 --longitude -73.987654 \
        --username WX1CLUB --password 12345 --server noam.aprs2.net --port 14580 \
        --temperature-celsius 20  \
        --rainfall-last-hour 0.25 \
        --pressure 1000

This will make an APRS packet with the following information:

  • Callsign WX1CLUB-13 is reporting that,
  • at coordinates 41.123456°N 73.987654°W,
  • the temperature is 20°C,
  • there was one quarter-inch of rainfall in the past hour,
  • and the barometric pressure is 1000 millibars.

Mapping APRS Data

aprs-weather-submit does not do any mapping on its own, other than sending packets with location information. There are several websites that will collect APRS-IS data and display it on a map. The most popular one seems to be APRS.fi. If you send an APRS packet, that site will eventually hear about it, log it, and display it.

Tips

There is no undo!

If you mistype something and send it to the APRS-IS network, it's permanent! All you can do is correct your input and send a second packet.

Why can't my app report (insert silly thing here)?

This app only supports what APRS supports. Considering that the creator, Bob Bruninga, is now a silent key, it's highly unlikely that we'll see new extensions to the APRS protocol, version 1.2.1. I'm not going to create non-standard extensions, as no other software or hardware would support that. If you want to specify some custom data, you can use the --comment parameter to type a little bit of freeform text.

For example, let's say you wanted to report the wind chill. That's not supported by APRS, but you could do:

aprs-weather-submit [everything else] --temperature 0 --wind-speed 15 --comment "Wind chill: -10°F"

Make a wrapper and save yourself some typing.

While this app doesn't have a way to save preferences or commonly-used options (yet?), you can write a wrapper script to "pre-fill" some data. This is what I use on my computer, a little script I call aprs-weather-report:

#!/bin/bash
aprs-weather-submit --callsign W1DNS \
        --latitude 41.123456 --longitude -73.987654 \
        --username W1DNS --password 12345 --server noam.aprs2.net --port 14580 \
        $*

The $* is a Bash expression meaning "everything else I typed," or more specifically, all of the arguments I specified on the command line.

Then, I can just do something like aprs-weather-report --temperature-celsius 20 to send a report!

Clone this wiki locally