Raspberry Pi-based RM3100 Magnetometer Data Acquisition Software User Manual

Ver. 1.0

David Witten

 

1. Make sure to set up a Raspberry Pi password

2. Set up system time to UTC
$ sudo raspi-config

3. Install data acquisition software

$ sudo apt-get update
$ sudo apt-get install git
$ git clone https://github.com/wittend/rm3100-runMag
$ cd rm3100-runMag
$ make

If there is an earlier code on the Raspberry Pi:

$ cd rm3100-runMag 
$ make clean
$ git pull
$ make

4. Run the software

4.1. For a long-term operation
$ ./runMag -kPS [SITEID*] 
OR
$ ./runMag -kS [SITEID*] 
(The -P optionn causes the program to print out the initial settings (to the screen) to let you know what settings you have given – mostly for debugging -  may be omitted)
*SITEID: Create your own site ID for others to recognize the location of the magnetometer. 

This should start the program, putting logged output into file named something like:
../logs/<site ID>-20200623-runmag.log
appears in the logs directory. The program should continue to append to this file until 23:59:59 when the program closes this file and opens a new one, in this case:
../logs//<site ID>-20200624-runmag.log
It then continues to append to this file for the next 24 hours, and repeats this process.

Note: to be paired with a newly assembled sensor assembly (provided by Julius Madey), use the following command:
$ ./runMag -H -M 0x23 -A 10 -c400 -U140 -kPZS <your callsign> &
(for the older sensor, try to use 0x20)
This will NOT show output to the screen.  It writes to the logfile.  

4.2. For a short-term testing
$  ./runMag or ./runMag -H
This will show the output of the program on the console Without logging to file. 

If you want to write to the log file but also view the output:
$ ./runMag -k -S [SITEID]. 

Then open another terminal window in the same folder and type:
$ tail -n 15 -f logs/[SITEID]-[UTCDATE]-runmag.log.log 

This is to read the logfile as it is written. It displays outpout log file as it is wirtten in the window. This will work until the UTC date changes (8:59 pm edt). At this poiint the data will begin to be logged to a new file:
../logs/[SITEID]-[UTCDATE + 1]-runmag.log.log
and the display in the window will just stop. (because the original logfile is not being written to any more).

Another method, 
runMag | tee > logs/[SITEID]-[CURRENT UTC TIME]-runmag.log
This version will not roll the log file over at 00 UTC.  

4.3. Other options
$ ./runMag -l -Z - b 1

  • This command tells the MAG Support board read the devices at alternate addresses.  
  • ​The -l command tells the system to read only the local thermometer chip, not the one on the remote board.  This is useful for testing simple setups that are not using the remote extender.
  • The -Z command tells the output stream to include the ‘totalized’ sum of the vector components measured by the mag seneor  in the output. :  [ sqrt((x*x) + (y*y) + (z*z)) ]  as the last field.
  • The -b 1 exists to inform the software which I2C bus is the one we want ti use for the Single Board Computer (SBC) we are using. -b 1 is actually the default, so can be omitted.  
  • -b2 is required for the Odroid Nano N2.  Others use other numbers. 
  • -a provides a list of a few other known SBC I2C bus numbers that can be used with these boards.
  • These commands behave as above with regard to the -Z and -b1  

$ ./runMag -Z - b 1 > data.txt :
This Creates and writes output to a file named ‘data.txt’.  Will overerite previous file with that name.

$ ./runMag -Z - b 1 >> data.txt: 
This Creates or Appends to an existing file named  ‘data.txt’.  Will not overwrite existing file.

$ ./runMag -Z - b 1 | tee data.txt: This command uses a command line trick to split the output between the storage file ( data.txt ) and the console window Program was launched from.

$ ./runMag -lkS <site id> 
This command line will read only the local thermometer chip and then write the results to a file in ./logs/ called something like JennyJump-20200703-runmag.log. Data will be appended to this until 23:23 UTC (should be 08:23 edt for you).  At that point that file will be closed, another file will be opened with the name JennyJump-20200704-runmag.log and log entries should be entered into this new file for the next 24 hours. Then the process repeats ad infinitum.

$ tail -f ./logs/jjump01-20210307-runmag.log 
To view the contents of the log file that it is writing. 
To do this, press enter one time and get your prompt.
Type the command tail -f followed by the name (with path) of the log file that is being written.
This will print each new line written to the logfile to the screen. This will continue until you use CTRL-C or until 00:00:00 UTC, at which time no new lines will be displayed (8:00 pm EST). The reason that the output stops at that time is that runMag has closed the initial log file and opened a new one. To see the new log file being created, reenter the command from before, but increment the date part of the file name by one. For example: tail -f ./logs/jjump01-20210308-runmag.log 

5. Power interruption Mitigation
This is based on an assumption that the Raspberry Pi is connected to the internet and has access to internet time and the board is configured to quickly calibrate its internal time using the internet time services (ntp). This is the usual case for properly configured Raspberry-Pi’s. 

There are (at least) two situations where time keeping will be degraded.  

If network connectivity is lost for some period the measurements recorded are likely to drift in time because the internal clock on Rpi’s is pretty poor and not ordinarily backed up.  The system in this case will continue logging data, but the trustworthiness of the timestamps will degrade.  The log files may not roll at precisely 23:23 UTC.  This is not usually the case for Odroid boards which do provide a battery backed real time clock.

The second situation is one where the Raspberry Pi loses its main power or the program is manually stopped.  If the program is restarted within the same UTC DAY using the same parameters that were used before, logging will continue to the same output file as before.  The only consequence will be that there will be a gap in the data equivalent to the down time.  But the time stamps should be reasonably coherent across the gap in the samples.  

The real solution for deploying these devices for long-term evaluation with limited supervision is to load a software package such as GPSd and a simple but reliable GPS module such as the Adafruit Ultimate GPS hat plus some sort of UPS supply designed for Pi or Odroid boards.  I have these Items available. I can provide them if desired.