FoxTelem - AMSAT Ground Station Software

Building and running FoxTelem

Setting up Eclipse environment

I do all of my Java development from Eclipse. I've used many IDEs over the years including Netbeans, but Eclipse works best for me. If you are passionate about another IDE, by all means use that, but you will have to configure the class path yourself.

I also use git. You don't need to use it. You can download the code as an archive and work on a local copy. If you have never used git and you just want to experiment with the code, then pull down a copy and ignore git. If you already know git, then you don't need me to explain how great it is and why you should use it. I use http://git-scm.com/ on Windows and it comes with a bash shell. Git is typically already installed on Linux, or you can install it with your package manager.

Download the code from github or replicate the FoxTelem github repo into your "Eclipse workspace" directory with this command:

git clone https://github.com/ac2cz/FoxTelem.git

Either approach will create a directory called "FoxTelem". Import the project into Eclipse with File > Import > Existing Projects into Workspace. In new versions of Eclipse this seems to work well. Eclipse is git aware, so if you are using git it will display the branch that you are on.

Setup Java Build Path

The main thing that needs to be configured for the build to work successfully is the build path. If you are "in the project", meaning you have highlighted or are in one of the classes in the "Project Explorer", then going to Project > Properties will bring up the settings for that project. Click on "Java Build Path" and fix or add any missing dependencies. Everything *should* already be there, because the file that stores the dependacies is stored in the source code, but sometimes Eclipse hard codes a path from my evironment. Or I forget to checkin the latest build path. All of the entries should be relative references to the FoxTelem/lib folder. Email me if there is a dependancy missing.

Run FoxTelem

To run from Eclipse you highlight the "main" class that you want to run. In this case it is FoxTelemMain.java in the "default" package in the src folder. Then click Run, either the green "Play button" or from the run menu. You can also right click and say "Run as > Java Application"

That's all you need to build and test FoxTelem. You can now decode live spacecraft or process recordings. Make sure that "Upload to Server" is off so that you don't send duplicate or unnecessary traffic to the amsat.org server. If you want to test with a local server, then read the additional instructions below.

Building and running the SERVER

To run the server you highlight FoxTelemServer.java and run it as above. Do that and it should print the "Usage" in the console. It is telling us we need to pass username and database on the command line. We can ignore all the other "optional" switches. But first we need a database to actually connect to.

Setup MySQL (if you want to run a local server)

Install mySQL: https://dev.mysql.com/downloads/mysql/. I seem to remember that the setup creates a root account, which you could use as the login. Or once installed run the mySQL Command Line client, login as the root user then setup a test user with:

CREATE USER 'testuser'@'localhost' IDENTIFIED BY 'password';
create database FOXDB;
GRANT ALL PRIVILEGES ON FOXDB . * TO 'testuser'@'localhost';
FLUSH PRIVILEGES;

Setup the Spacecraft files

The server loads the spacecraft definitions from the spacecraft sub-directory in a similar manner to FoxTelem. The files are named things like FOX-1A_fm.MASTER. FoxTelem actually takes those files and makes a copy of them in its logfiles directory. It renames them to things like FOX-1A_fm.dat. The copy is then writable if the user changes any of the settings. This stops us having an issue with Windows write protection on the install dir. But the server does not copy and install the files automatically. It just looks in the spacecraft dir for .dat files. So when you run the server it will exit and say it can't find any spacecraft. You need to manually install any of the .MASTER files you want to test with and name the copy with a .dat extension. Then when you run the server it will find the spacecraft.

Running the SERVER from Eclipse

We need to pass in the username, database and supply a password. The username and database are passed on the command line. The password is read from stdin. When you run a "main" class in Eclipse it creates a "Run Configuration". You can find that from Project > Properties > Run/Debug Settings. You should see one "Launch Configuration". Highlight it and Edit it. On the "Arguments" tab put your username and the database name FOXDB, just like this (replacing testuser with the username you used):

testuser FOXDB 

Close out the dialog.

Now when you run rhe server it should run and appear to do nothing. Type the password for your user into the console and hit enter. It should stay running. If it exits imeadiately there is an error or you did not setup the spacecraft files.

The server does not write any output to stdout or stderr. It all goes in the log. I typically open a git bash window and tail the log like this:

tail -f FoxServer20180330.log

The log is written in the root folder of the Eclipse project.

If it runs correctly you should see it create all of the tables for the spacecraft you setup. It then pauses with a message like this:

20180330120740: Waiting for connection ...
20180330120740: Started Thread to handle image assembly

You can confirm everything is setup correctly by logging into mysql command line and typing:

use FOXDB;
show tables;

Here is the result with just FOX-1C setup. Note that windows prints all the tables in lower case. Unix has them in the correct case. That is important because a query will succeed on windows if the case is wrong but fail later in a linux environment.

+-----------------------+
| Tables_in_foxdb       |
+-----------------------+
| fox3jpg_idx           |
| fox3maxtelemetry      |
| fox3mintelemetry      |
| fox3picture_lines_idx |
| fox3rad2telemetry     |
| fox3radtelemetry      |
| fox3rttelemetry       |
| stp_header            |
+-----------------------+
8 rows in set (0.01 sec)

Testing the local SERVER with FoxTelem

By default FoxTelem sends all of its data to the amsat.org server. We make it hard for the user to send it somewhere else. In fact the destination is under our control and is defined in this file:

http://amsat.us/FoxTelem/server.txt

That file is downloaded when FoxTelem starts and is checked about every 4 hours. The settings in it are automatically applied. That means we can change the destination for telemetry and all the FoxTelems around the world will update their settings. This is good and helpful. We used it at Fox-1A launch as we fiddled with DNS. But it is a pain for testing.

To disable the feature above you need to run FoxTelem once to get the FoxTelem.properties file. You can find where this is written from the File > Settings screen. It tells you at the top, where it says "Home Directory". Go there and edit the properties file. Find the line called serverParamsUrl. It should say:

serverParamsUrl=http\://amsat.us/FoxTelem/server.txt

Corrupt that line in some way. I usually set it to:

serverParamsUrl=http\://amsat: .us/FoxTelem/FAILserver.txt

Now FoxTelem fails to download the settings and we can apply our own. In the FoxTelem.properties file edit and set the following two lines:

primaryServer=127.0.0.1
secondaryServer=127.0.0.1

FoxTelem will now send telem to the server running on your local machine. You can confirm it has worked by running FoxTelem, going to the setttings screen and seeing that the servers are 127.0.0.1. If they are not then either you edited the wrong file (and it can be confusing) or the production settings are still being downloaded and are overwriting what you changed. Also, if you edit the file while you have FoxTelem open, then exit FoxTelem, it will overwrite what you changed. It only saves the properties at Exit.

Testing with a Recording

Run FoxTelem and play the recording through it. Make sure you have "Upload to server" set on the settings tab. I like to play my recordings back using Audacity fed through a virtual audio cable to FoxTelem. But you can open the recordings directly in FoxTelem too. If you do that, uncheck "Squelch When no Telemetry" otherwise it plays at too fast a speed.

You should see the frames get "queued" bottom right and then sent to the server. The server log should show they are being processed. You can log back into mySQL command line and type the following:

use FOXDB;
select count(*) from STP_HEADER;

That should tell you how many STP files have been processed by the server. It should be the same as the number of frames that FoxTelem reports. The STP files are also written to disk in a folder like FoxTelem/2018/03/30

Note that you can reset the server by logging into mySQL and typing:

drop database FOXDB;
create database FOXDB;

Now the database is all pristine and new again..

You can delete the whole server images directory and it will get recreated at startup. The same is true of the stp files directory. You can delete the whole 2018/... structure and it will get recreated when you restart. They will be empty of course, so this is just to reset things for testing.