# JS8Spotter MIT License, Joe Lyman KF7MIX
# You should have received a copy of the source and license with the program
# Special thanks to KE0DHO, KF0HHR, KQ4DRG, N4FWD, and N0GES, for help in early
# development. Additional thanks to the operators mentioned in the changelog

# Overview

A JS8Call API mechanism to track activity containing specific search
terms, including callsigns or other activity. Matches on RX.ACTIVITY,
RX.DIRECTED, and RX.SPOT only. Tested with v2.2.0 through v3.0.2

# Installation

There is no installation for JS8Spotter, it may be run in-place after downloading and
unpacking. It is recommended that you keep your files in a JS8Spotter folder under your
documents folder, or somewhere else *outside* the Program Files folder(s). You may
right-click the executable to create a desktop shortcut if you wish.


# Settings

JS8Spottter requires the TCP API in JS8Call. To turn it on, go to JS8Call, enter
the "File>Settings" menu, then go to the "Reporting" tab, and enable the
following three checkmarks:

* Allow setting station information
* Enable TCP Server API
* Accept TCP Requests

If you change port or IP from the default, TCP address and port settings for
JS8Spotter may be modified in the application file menu.

Make sure to set your callsign and grid in the application file menu when
running the software for the first time. You may leave the other settings at
default unless changes are needed. All other options are set via the
menus.


# Usage

JS8Spotter is designed to help you keep track of specific, desired traffic as it
passes through JS8Call. From within JS8Call itself, you can access all traffic
via the ALL.TXT log file. JS8Spotter simply provides a method to sort out some
of this traffic as it comes in, and view the traffic in a quick and organized
way.

## Starting the Program

Make sure to start JS8Spotter only after running the JS8Call application, as it
needs to connect to JS8Call in order to function properly. Starting JS8Spotter
before JS8Call may result in undesired behavior.

## Profiles

A profile in JS8Call is a container where you keep a collection of specific
search terms.

   Example 1: You run a net for your stamp collecting group, with the JS8Call
              group name @STAMPS. You create a profile named "@STAMPS", and
              add search terms for each callsign in the roster, a keyword for
              the group name "@STAMPS", plus several keywords relating to the
              group.

   Example 2: You have a group of close friends who you see on the air often.
              You create a profile named "Contacts" and populate it with search
              terms for each of their callsigns.

   Example 3: You participate in @JS8CHESS. You create a "Chess" profile, and
              populate it with the search term "CHESS" to capture all traffic
              that mentions chess (including anything with "@JS8CHESS". You
              also include search terms for each of the callsigns you are
              playing games with.

   Example 4: You're an OSINT guy, and want to gather data related to specific
              events, people, or groups. You create a container called "Conspiracy"
              and populate it with search terms related to your intelligence efforts.

JS8Spotter's database file comes with a single profile named "Default". You may
rename this profile to whatever you wish. It may be deleted only after adding
additional profiles.

## Search Terms

As JS8Call runs, it provides decoded activity on the TCP network port.
JS8Spotter watches that TCP traffic, and looks for keywords / search terms that you
provide in each of your profiles. When it finds a match, it saves that traffic
to your specific log (and to a database on the back-end.) The latest 100 entries
are visible at any time, older entries are also visible in the export window
or in the database.

Search terms can be anything you like. They can be a single letter, a word, a
callsign, a JS8Call command, or multiple words.

   Example 1: You have a "Testing" profile, where you track random things that
              are happening on the waterfall. In it, you create a "MSG" search
              term, which lets you capture and save all MSG traffic as it goes
              by. Later, you can look back at any MSGs that were sent. You add
              ">" to your search terms, so you can capture any relays, even if
              they weren't MSG relays.

   Example 2: You are curious about station info, but don't want to always be
              the one requesting it. You create a "Stations" profile, and add
              the search terms "INFO" and "STATUS".

   Example 3: You're part of an emcomm group, and you know that several of the
              group members use JS8Call. You create a profile just for them, and
              add the full roster of callsigns as individual search terms, so
              you can get a feel for when your fellow group members are on the
              air.

## Background Scanning

If enabled, background scanning allows profiles to scan even when the profile is
not actively selected. If disabled, a profile will only record activity when
selected/active.

Background scanning is disabled by default, and may be enabled with the checkbox
at the top-right of each profile. The background scanning setting is set on a
per-profile basis. Settings are retained when the program is closed.

   Example 1: You have a "Testing" profile, which gathers a lot of data. You
              don't want to gather it all the time, only when you are testing,
              so you uncheck the box for that profile.

   Example 2: You don't ever want to miss any JS8CHESS traffic, so you enable
              background scanning on that profile.

   Example 3: Your @STAMPS net is once a month, and you don't need to track
              it except when the net is active. You leave background scanning
              disabled on that profile.

   Example 4: Your want to always know when your friends are around, so you
              keep your "Contacts" profile active with background scanning on.

## User Interface

### Main Window

* The profile drop-down will let you quickly switch between your profiles
* The "Search Term" and "Matched Activity" panes show the corresponding data
* The "Matched Activity" pane will either show the last 100 entries, or a time range
* You may double-click on individual search terms or activity for details
* An entry box at the bottom-left allows you to add new search terms
* The "Remove Selected" button allows you to remove the highlighted search term
* The "Export Log" button brings up the export window
* The "Clear Log" button deletes ALL activity entries for the current profile
* The "Filter" entry box lets you filter what is shown in the activity pane
* Menu actions hopefully perform as labeled

## Export Log Window

The export log window shows all database entries for activity, for the current
profile. The data is tab-delimited. Highlight and copy what you wish, and
paste it into a spreadsheet for easy access. Or, use the "Copy All" or "Save As"
buttons.

## Export Search Terms Window

Allows you to copy/save your search terms, as a backup or to share with others.

## Add Search Terms Window

Allows you to add/import new or previously saved search terms, or enter search terms in
bulk, line by line.

## Hide Menu Items

The "Hide" items in the View menu allow you to hide/show items in the
Matched Activity pane. These items are still retained in the database, they are
simply hidden on the screen when this option is selected. These options is not
profile specific. These settings are retained when the program is closed.

## Simple Offline Map Window

Provides a simple offline maidenhead grid map of the latest 100 contacts. Maps
are included for certain areas, but new maps may be added or requested.

## Visualize Waterfall Window

This window lets you visualize waterfall activity on a simulated waterfall.
Activity is gathered as you RX on a band. When you view the visual, you'll be
able to quickly get a feel for the parts of the band that are more or less
busy.

## Expect Window

The Expect subsystem allows you to specific text that your station "expects" to
see, along with a response that your station will send automatically if the
expected text is found. All expect commands are prefixed with "E?". You may
specify which stations or groups may trigger a response, and you may specify
how many times your station will respond to a single expect.

In order to automatically transmit from Expect, the following MUST be true:

* You must DISABLE/UNCHECK the "Allow sending standard messages without callsign" option in 
  JS8Call settings "General>Behavior" tab, or "E?" requests will not function.
* Autoreply must be enabled in JS8Call in order for JS8Spotter to cause JS8Call to transmit.
* You must have no station selected in your JS8Call Call Activity Pane
* TX must be enabled
* Your outgoing message box must be empty (gray text "TYPE YOUR OUTGOING MESSAGES HERE"


See the in-program help for more details.

## Multiple-Choice Forms (MCForms)

!! It is highly recommended that you read the PDF manual, and examine all files in the forms folder !!!

The MCForms subsystem extends JS8Call with some basic forms capabilities.
Naturally, you don't want to send large amounts of information over a mode
like JS8Call. MCForms allows you to maintain forms on both sides of the
communiation, and send only the answers to form questions. Forms are .txt
files located in the forms folder. Their format is as follows:

* First line MUST be the human readable title of the form, then the pipe
  symbol |, and then the form ID. Like this example: Test Form|F!001
* Headers are created with !<space><text>, with one, two or three ! for header
  levels 1, 2, and 3, as in: ! Important Info
* Display text / instructions are created with .<space><text>, as: . Test
* A Question line is created with ?<space><text>, as: ? What is your favorite color?
* All Answer lines that follow, up to the next question, will be associated.
* Answer lines are created with @<space><text>, as: @1 Red, or @Y Yes
* A Question may have up to 36 Answers (A-Z an 0-9 are valid response chars)
* Blank lines are ignored. Lines that start with anything other than !.?@
  are also ignored.
* It is recommended that comments start with #. The first line of the file
  MUST be as described above, and not a comment.
* Use ASCII characters only. A basic text editor (such as notepad++ on Windows)
  is strongly recommended.

Details of the included forms formats will be posted on KF7MIX.com in the
JS8Spotter section. Operators are encouraged to contact KF7MIX to post any forms
they will be using on the air, so that those formats may be publicly available.

For more form format details, view the included forms in the forms folder.

Filled out forms are posted to the Expect system. When collected over the air,
received form responses will be in the tools menu under form responses for
easy viewing. Viewing in text mode is availble by double-clicking a response,
viewing in GUI mode is available by selecting and right-clicking. Responses may
be forwarded to other stations or groups. Responses may be deleted with the
delete key.

The form responses window has a gateway option. If a URL is entered, your system
will automatically forward received forms to your gateway. A test gateway is
available at kf7mix.com, or program your own gateway to receive forms data.

## CommStatOne v1.0.5 statreps

For those who want to participate in CommStat status reports, but don't want to
or can't install CommStatOne, JS8Spotter includes basic statrep functionality.
In order for this to function, you must first set a CommStat group in the
settings. Then you can send, receieve, and forward statreps with other members
of your group.

## APRS Commands

JS8Call supports APRSIS gateway commands. The APRS options in the Tools menu
help you format these commands for easy and quick use. Use them for sending
an SMS (with registration on the target phone side, see http://aprs.wiki/SMS/),
an email, POTA Gateway, or reporting your grid location.

# Support

Thank you for your help, testing, bug reports, and encouragement! I'm a hobbyist
programmer, and I've done very little GUI programming.

The software is free, but I'd be happy to lend a hand with it as needed. Contact
KF7MIX via the information on QRZ.com with questions.


73, Joe KF7MIX
