Editing The Code
It should be rare that the code needs to be edited, but there are two situations where it might be necessary:
- Where the existing software cannot be configured to your exact needs
- To add support for an extra sensor
All source code is provided, and you will find the source code files in /home/pi/pits/tracker. There are some C source code files (*.c) that are compiled to build the tracker (filename tracker), and a simple shell script for the camera (filename camera). You can edit whichever of these you need.
The camera script is very simple. It consists of a loop with delays, where each time round the loop it takes an image for the SSDV system (to send to the ground) and a large image for storage only. The latest release of this file is here.
A typical reason for editing the camera script might be to change parameters for the large images. The line for this is currently:
raspistill -w 2592 -h 1944 -v -t 3000 -ex auto -mm matrix -o keep/$current_date/$current_time.jpg
You can add any parameters supported by raspistill
SSDV images are taken by running a separate script called "take_pic". Do not edit this file - it is created automatically by the tracker program, so your changes will be lost as soon as the tracker program recreates the file! Basic image parameters (width and height) are set by the tracker program according to the parameters in the configuration file /boot/pisky.txt, but if you want to add any other parameters then you will need to edit the C source. Don't worry if you don't know C - a change like that is very simple and is explained below.
The tracker program is built from a number of C source code files. These are ordinary text files written in the C language. If you don't know C, then you can still make some simple changes. For example, suppose you want to flip images (because you want to mount the camera upside-down). To do this, edit the file snapper.c which is responsible for creating the take_pic file mentioned above. Edit using vi or nano or whatever Linux editor you are familiar with. The specific line you would need to edit for the above change is this one:
fprintf(fp, "raspistill -w %d -h %d -t 3000 -ex auto -mm matrix -o /home/pi/pits/tracker/download/$1.jpg\n", width, height);
This line writes a single line to the take_pic file; specifically it adds the "raspistill" command so that a photograph is taken. To understand, you can ignore the "fprintf" part and just concentrate on the part in bold above. If you are familar with raspistill but not with C, you may wonder what the -w %d -g %d bit does. Well, in C, the "%d" bits tell it to replace those parts with numbers, and in this case those are the width and height numbers at the end of the line. To simply things a little, -w %d -g %d gets replaced with something like -w 320 -g 240 to set the width and height of the image. The reason that it is done this way is that the program can change the size of the images during the flight, so that images taken at higher altitudes are larger.
Anyway, all you probably want to do is add a simple paramater to that line; something like this one from the raspistill documentation:
-vf, --vflip : Set vertical flip
So you would just insert "-vf" into that raspistill line, to get something like;
fprintf(fp, "raspistill -w %d -h %d -t 3000 -vf -ex auto -mm matrix -o /home/pi/pits/tracker/download/$1.jpg\n", width, height);
So long as you are careful to insert -vf in the right place (exactly as if you were running it from a command line) then all should be fine. So, open the file in your editor (e.g. type nano snapper.c), scroll down to that line, make the change, then save and close the file.
Now, if you're not used to programming, or you're used to interpreted languages such as Python, then you will assume that you're finished. Not so! C is a compiled language and you need to convert the source code into an executable program that you can run. Fortunately this is all set up for you, so all you need to do is type make and press ENTER. You will then see a couple of lines appear with, hopefully, no error messages. After that, the tracker program is ready for use.
Now, one important point. you must stop the tracker program before you start it again. Otherwise, you will have 2 programs trying to do the same thing, and neither will work properly. The tracker program is started automatically when the Pi boots, so you need to kill it first (not as messy as it sounds) by typing sudo killall tracker. The tracker program will then stop immediately.
To run the newly built tracker program, just type sudo ./tracker and it will start. Within a few seconds it will create a new take_pic file, and a few seconds later the camera script will take a photo using that new file and your new settings. Remember though that if the tracker is already sending an old image, it will have to send that first before your new (flipped) images are chosen for transmission. It might even take a bit longer if there are some other images left over from earlier.
Adding A New Sensor
This section is for those who are familiar with C and wish to add support for a new sensor; if you do not have those skills then please feel free to add an issue to the github repository, marking it as "enhancement".
Sensors can be added using the i2c port on the PITS board, or (for PITS+) stacking a separate HAT on top.
Always start by writing a test program to confirm that the device works. Also, check that it does not interfere with any hardware on the PITS board. For HATs the mostly likely conflict would be with the SPI bus - boards of V2.3 and earlier use an SPI ADC. For boards of V2.4 and later this has been replaced by an I2C device. If in doubt, check the schematic (in github) or ask us for help.
With all the above checked out, follow these steps. The following is generic and is a guide to ensure that what you do fits in with the structure of the existing software:
- Create new .c and .h files for your new device, naming them appropriately. A good place to start, especially if you are adding an i2c device, would be to copy the existing adc_i2c.c and .h files
- Change the function names to suit the new device
- Edit the makefile, adding the new files to the compile and link steps
- #include the .h file in tracker.c
- Also in tracker.c, add a pthread_t variable to main() for the new device
- Add code to create the new thread
- Add one or more new variables (for your sensor readings) to the TGPS structure in gps.h
- Add the variables to the telemetry line (sprintf(TxLine, "$$%s,%d,%...) in telemetry.c (extend the string length if necessary).
As yo will have noticed, each device has its own thread and we suggest you maintain that rule. The threads are loaded using code like this:
if (pthread_create(&ADCThread, NULL, I2CADCLoop, &GPS))
fprintf(stderr, "Error creating ADC thread\n");
and meanwhile, in your .c file, you have an infinite loop for that thread. If you check an example, you will see that the device is polled each time round the loop, and that the loop includes something like sleep(10) to prevent it from using excessive CPU cycles.
With the changes made, just use make to rebuild the tracker program