Manual Installation Instructions¶

Warning

These instructions were created using Ubuntu version 16.04. Other operating system instructions may require additional information not provided in this documentation.

Materials Needed:

Minnowboard and power supply
GPS Lure
Monitor with HDMI support
Keyboard and Mouse
Ethernet cord to hook up to network
Drive for booting an OS
Persistent memory for the MB

Note

There is a semi-automatic script to do most of this work for you. Check it out on (Semi) Auto Installer Instructions. These are the basic instructions needed. There are help and tips at Troubleshooting, Debugging, and More! following these instructions for issues that may arise at each step.

Tip

You can find a video of the following process here: https://youtu.be/Jt5kh5Hau5c

Board and Lure Setup¶

Connect the MinnowBoard to the monitor, attach the lure and plug in the board's power.
OS: If not already installed, install a linux distribution onto the MB. HERE is a link to a tutorial to make a bootable flashdrive and install the OS. For the sake of this tutorial, Ubuntu is reccomended.

Time to download or update needed software. Run the following:

sudo -i
add-apt-repository main
add-apt-repository universe
add-apt-repository restricted
add-apt-repository multiverse
apt-get update
apt-get install pps-tools
apt-get install libcap-dev
apt-get install dkms
apt-get install ntp
apt-get install minicom
apt-get install git
apt-get install setserial

Setting up the Pulse Per Second¶

Create a folder then move into it and run:

git clone https://github.com/bsteinsbo/Minnowboard.git
cd Minnowboard/minnow-pps-gpio
nano minnow-pps-gpio.c

Scroll down to the line that reads "#define PPS_GPIO 483" and change the number to the pin that corresponds to the GPIO pin that PPS is on. For the Lure, this number is 340. Once changed save the file and then run:
```
make
chmod 777 Makefile
./Makefile
```
Next we will configure modules. Run:
```
nano /etc/modules
```
In that file, add "pps-gpio" on a new line. Then save and restart the board.
Time to check if everything is working so far. Run:
```
lsmod | grep pps
```
Your output should resemble the following (with XXXX being some number):
```
pps_gpio XXXX 1
pps_core XXXX 2 pps_gpio
```
Next we use DKMS to install and link the PPS. Run the following commands:
```
dkms add -m minnow-pps-gpio/20150721
dkms build minnow-pps-gpio/20150721
dkms install minnow-pps-gpio/20150721
modprobe minnow-pps-gpio
dmesg | grep pps
```
If the install worked, the last command should output a few lines similar to this:
```
[XX.XXXXX] pps pps0: new PPS source pps-gpio.-1
[XX.XXXXX] pps pps0: Registered IRQ XXX as PPS source
```
This shows the device is installed. To confirm PPS is working, run :
```
ppstest /dev/pps0
```
Note

When first running the PPS test, if the test returns a timeout error but says a device has been identitified, let it run for several minutes. From a cold start, the PPS could take 10-20 minutes or more to start, train itself, and be identified. However, if it's been identified it should be working.
Next, we need to tell the NTPD where to look for the PPS. This is done in the ntp.conf file. Run:
```
nano /etc/ntp.conf
```
In the file, scroll to the bottom. Edit the two PPS lines at the bottom like so:
```
server 127.127.22.0 minpoll 1 maxpoll 1 #ATOM (PPS)
fudge 127.127.22.0 refid PPS # enable PPS API
```
Save and close the file. To verify PPS is now installed in NTP, run:
```
service ntp restart
ntpq -p
```
One of the items in the list should be named something like PPS(0). If you see this, it's working! (Note it may take a few minutes for ntpq -p to show changes. Re-Run the ntpq command as needed.)

Setting up the GPS¶

Next it is time to set up the GPS to input the rought time data. First, verify the GPS is connected and on the correct port by running:
```
setserial -g /dev/ttyS4
minicom -b 9600 -o -D /dev/ttyS4
```
This should print out the NMEA sentences your gps is sending. If nothing appears, verify that the baud rate (9600 for the lure GPS) and port (ttyS4 for the lure is serial port 4) correspond to your device. Once you see full NMEA sentences being printed out, exit minicom by pressing [CTRL + A], then [X], then [ENTER].
Now time to map the serial port to gps0 so it can be read by the NTPD. Run:
```
ln -s /dev/ttyS4 /dev/gps0
chmod 777 /dev/gps0
```
You can verify the mapping worked by running the above minicom command and replacing ttyS4 with gps0.
Now for some final changes to the ntp.conf file. Reopen /etc/ntp.conf and scroll down in the file until you see the server and fudge lines for the GPS. Change them to match:
```
server 127.127.20.0 mode 18 minpoll 4 maxpoll 4 iburst prefer
fudge 127.127.20.0 flag1 1 flag2 0 flag3 0 time2 0.0 stratum 1
```
Then save and exit nano.
It is very likely that apparmor will deny ntp access to the gps signal. To ensure this is allowed, run the following:
```
nano /etc/apparmor.d/usr.sbin.ntpd
```
Scroll to the bottom and add "capability ipc_owner" if it's not present, then save and close the file.
Time to verify everything worked. At this point you should go through section 5, then reboot your system and run:
```
ntpq -p
```
You should see gps0 in the list of servers now. After several minutes, run ntpq -p again. You should see the offset and jitter values for the gps and pps. Over time these values will slowly get closer to zero. This process could take up to a few days, however the clock will update your system time as it trains itself, thus making it usable throughout the sync time.

Broadcasting the Time¶

Now that the time is working, we need toconfigure NTP on the MB to make sure it shares the time with the network. Run:
```
ifconfig
```
Find the address labeld "Bcast: " and write that address somewhere for later use.
We must now configure the NTPD to broadcast the time to the network. Open the ntp config file again and scroll down to the following section. Uncomment the broadcast line and update the IP to match the one you just wrote down.
```
# If you want to provide time to your local subnet.
# change the next line.
# (Again, the address is an example only.)
broadcast XXX.XXX.XXX.XXX
```
With this setting changed, restart ntp. The MB NTP time will now be discoverable on any network machine, however, a client NTPD may need to be configured to listen for the broadcast signal.

Final Steps¶

Since there are a few tasks which need to be performed every boot, it is convenient to create a script which runs at boot. To start copy the following text into a text editor and save it as a script (.sh) file.
```
    #!/bin/bash
modprobe minnow-pps-gpio
rm /dev/gps0
ln -s /dev/ttyS4 /dev/gps0
service ntp restart
```
Once the script is complete, run the following command, and add the dirctory of your script to the file.
```
nano /etc/rc.local
```
This will automatically run the script at the end of the boot process, when everything is set up, ensuring the system will work automatically.