Configure RV Telemetry

The RV Telemetry plugin expects to obtain telemetry information either from shell scripts and HTTP queries, or from Raspberry Pi GPIO interfaces. However, it is expected that these sources may not provide information in units matching APRS conventions, so the plugin can perform transformations on the data before putting it in outgoing APRS traffic.

Configuring the plugin is done from the RVTelemetry tab of the expert-mode Configuration dialog. There are 6 sub-tabs on the RVTelemetry tab:

1. The General tab.

   This configures the I2C bus number to use. Note the numbering of I2C busses changes with each release of the Raspberry Pi hardware, so this will have to be set correctly for the hardware YAAC is running on. Note this tab will only appear on Linux systems where the I2C bus devices appear in the "/dev" directory; typically, this will be on Raspberry Pi systems where "raspi-config" has been used to enable access to the I2C busses.

2. The Input tab.

   This is where all the telemetry data sources are defined. Each row in the table defines one raw data input, using the following fields:

   • The name of the input. An arbitrary string unique among all other inputs.
   • The type of input. The following types of input are supported:
     • GPIO - obtain information from a digital GPIO pin on a Raspberry Pi computer using the Pi4J library.
     • HTTP Query - issue an HTTP GET request to an arbitrary URL and parse the return value out of the response.
     • Shell command - spawn a command on the local system, and parse the return value out of the response.
     • Received HTTP - not yet available.
     • ADS1015 - read analog data from one of the channels of an ADS1015 analog-to-digital converter chip connected to the Pi's I2C bus.
     • SHT31 - read temperature (in degrees Celsius) and relative humidity (in percent) from a SHT31 on the Pi's I2C bus.
   • Which input of a multi-input source. For GPIO, specifies the pin number. For ADS1015 and SHT31, it specifies the channel on the device (0 to 3 on the first ADS1015, 4 through 7 on the second, 0 for SHT31 temperature and 1 for SHT31 humidity).
   • The URL for HTTP queries or the local operating system shell command for shell commands.
   • The regular expression pattern (with zero or one group) to look for in the text response for an HTTP query or shell command. Only the group (or whatever matches the entire pattern) will be used to extract the value of the input.
   • The format (in java.text.MessageFormat syntax) for extracting the numeric value from the matched text. Should be of the form "{0,number,format}" where format is as defined by the DecimalFormat class in Java.
   • The polling interval in seconds that the data should be queried for updates.
   • The type of location where the extracted value should be stored. The known types are:
     • one of the weather data fields (if a collection of lesser sensors are being used to emulate a complete multi-sensor weather station).
     • one of the 5 analog value fields in an APRS Telemetry message to be originated by the local station.
     • one of the 8 binary digital values in an APRS Telemetry message.
     • the bearing (or orientation relative to True North) of the local station.
     • the speed of motion of the local (mobile) station.
     • an intermediate variable, used to provide input to later mathematical and logical processing steps.
     • A named YAAC macro (which can be referenced in beacon, status, and auto-answer text messages).
     • A GPIO output pin (such as a pin driving an LED or alarm buzzer).
     • An LED connected to an SN3218 LED PWM driver (the value becoming the brightness of the LED).
   • Which field of a multi-field destination. For weather, the weather field to populate. For analog and digital, the 1-based index into the set of fields of the type in a Telemetry message (5 analog, 8 binary/digital). For intermediate variables, a string identifying the variable; this string will be used in later processing steps to specify from where to read the stored value.
3. The constants tab.

   This is where names may be associated with numeric constant values. These constants may be referenced as inputs to processing steps, e.g., the constant to convert kilometers per hour to statute miles per hour for a speed field.

4. The processing tab.

   This is where mathematical and logical transformations may be done on telemetry values. Each row in the table specifies where to store the output of a transformation, the type of transformation, whether computed changes to the output of the transformation should force immediate transmission of the telemetry message (instead of waiting for the next periodic transmission), and what input values are processed by the transformation to produce the output value.

   Outputs can be any of the fields that raw inputs can be stored in (including other intermediate variables). Inputs can also be any of those fields, plus certain standard input fields defined for other YAAC input sources (such as the primary and alternate GPS receivers), or constants defined on the constants tab.

   The types of processing that can currently be performed are:

   • ADD - add 1 to 4 values together and return the sum
   • SUB - subtract a second value from a first value and return the difference
   • MUL - multiply 1 to 4 values together and return the product
   • MUL10 - multiply a single value times 10.0 (since many APRS values are in tenths)
   • °C->°F - convert a temperature in degrees Celsius to degrees Fahrenheit
   • HPa->inHg - convert a pressure in hectopascals to inches of mercury
   • Vehicle Bearing - converts a front latitude and longitude and back latitude and longitude into an orientation of the pair of GPS receivers relative to True North
   • > - compares two values and return a value of 1 if the first value is greater than the second value, and 0 otherwise (useful for calculating digital telemetry bits for exceeded thresholds)
   • |x| - returns the absolute value of the input, which is the input value if greater than or equal to 0, or the negation of the input value if it was already negative, i.e., making it positive.
5. The output tab.

   This displays the expected output of a Telemetry message, and also the current real-time values of all defined intermediate variables. The tab also has a control for specifying how frequently (in seconds) the Telemetry message should be transmitted (zero means not to send it).

6. The display tab.

   This configures the Telemetry tab on the smallscreen plugin's small screen view (should this plugin also be used in YAAC and its view displayed). A two-column display of labels and formatted numeric values extracted from raw input, intermediate variables, or final output fields will be displayed, and the contents and formatting of this display is configured here. A blank screen tab is also provided so the user can black out the monitor when not using the smallscreen display.