OLD Bare Metal System Image

This page will guide you through the steps to install a basic system image.

On this image you will have the ROS base system, the OpenMower installation, local configuration for your mower and some tools to help you work with the mower.

Prerequisites

In order to follow this guide, you will need the following:

1. A Raspberry Pi 4 (4GB or more recommended, 2GB works with swap, see here)
2. An SD card
3. A soldered OpenMower mainboard

Installing the Base System

There is also a YouTube video explaining the steps in this section: https://youtu.be/_bImqD-pQSA?t=562

Flashing Ubuntu to SD Card

The first step is to install the base system. We're using Ubuntu 20.04 Server for the Raspberry Pi. This is, because this image gives us best support ROS Noetic.

Installing the base image is easy:

1. Get the Raspberry Pi Imager software
2. Select the correct operating system: Other-general-purpose OS > Ubuntu > Ubuntu Server 20.04.4 LTS (RPI 3/4/400) 64-bit
3. Insert your SD card into your PC and select it in the Storage part of the software
4. Click write and wait for the process to finish

Once you have successfully flashed your image, remove the SD for your PC and reinsert it again.

Then replace the /boot/config.txt file with the one provided here: [1]

This will enable all hardware serial ports on the Raspberry Pi.

Note:

You can theoretically configure networking in this step as well, but I'm not recommending it. This is, because the networking information file gets only copied once and if you have an error it won't work.

We need an interactive terminal in the next step anyways.

Once you have done this step, you can eject the SD card and plug it into your Raspberry Pi 4.

Opening a Serial Terminal

Serial Terminal: minicom -D /dev/ttyACM0

This step is needed for the following sections. The goal is to have a serial terminal to do basic config (networking etc) easily.

The easiest way of doing so is:

1. Flash the SerialRedirect firmware into your Pico. Get it here: https://github.com/ClemensElflein/OpenMower/tree/main/Firmware/SerialRedirect/bin
2. Provide your mainboard with power
3. Plug your Pico into a computer. A virtual COM port should appear
4. Connect to the COM port (I'm using minicom, see image on the right), then press enter to start the Raspberry Pi.
5. The Pi boots and a serial terminal will appear.

Now you can login with the default credentials:

username: ubuntu

password: ubuntu

Note that you will need to change the password immediately.

Disable Boot Interrupt

Commands needed to disable boot interrupt on serial input.

The Raspberry Pi boot loader will interrupt the boot sequence if data is sent through the main serial port of the Raspberry Pi. Since we're connecting "nosiy" hardware to the port, this will always interrupt the boot sequence and we need to disable this feature.

In order to do this, reboot the Pi (sudo reboot) and send anything during the count-down in the bootloader (check the YouTube video linked above, if you're not sure).

Then enter the following commands into the bootloader prompt:

setenv bootdelay -2
saveenv
reset

The Pi should reboot and the count-down should be gone.

Some Settings

[TODO/WIP]

Here are some miscellaneous settings I think are a good idea for an OpenMower install:

• Remove the unnecessary snap system: sudo snap remove --purge lxd && sudo snap remove --purge core20 && sudo snap remove --purge snapd && sudo apt purge --autoremove snapd

• Disable unattended upgrades: sudo systemctl stop --force unattended-upgrades && sudo systemctl disable unattended-upgrades && sudo systemctl mask unattended-upgrades

• I like to add the following to cmdline.txt in order to fsck on boot: fsck.mode=force fsck.repair=yes

• I prefer to use a static IP (If you use the recommend WiFi Hot-Spot use sudo nmtui to configure a static IP)

• If you like to have a terminal wifi scanner/signal monitor just install sudo apt install wavemon

• If you like you can change the timezone: sudo timedatectl set-timezone Region/Location or sudo dpkg-reconfigure tzdata

• If you ever like to plug a keyboard into the Pi don't forget to change the keymap: sudo dpkg-reconfigure keyboard-configuration

Enable Swap (optional, needed for Pi with <= 2GB RAM)

Compiling the OpenMower software will need more than 2GB of RAM. In order to still do this on a Pi with <= 2GB of RAM, we will add a 2GB swap file to the system by entering the following commands:

# Create a new 2GB swap file
sudo fallocate -l 2G /swapfile
# Change permissions, so that only root can read and write
sudo chmod 600 /swapfile
# Create swap space in the file
sudo mkswap /swapfile
# Add it to the fstab
echo '/swapfile swap swap defaults 0 0' | sudo tee -a /etc/fstab /swapfile swap swap defaults 0 0
# Reboot to activate
sudo reboot

# Check if it's activated
sudo swapon --show

Installing a WiFi Hot-Spot (optional, but recommended)

Since we will be configuring the WiFi interface, make sure that you have connected Ethernet to your Raspberry Pi for this step.

As soon as you have closed your mower's enclosure, you won't have physical access to your Raspberry Pi anymore. If for some reason it's unable to connect to your WiFi (e.g. you have changed your password), you would need to open the case to get access to the SD card or Ethernet port on the Pi to regain access.

To prevent this, we're going to install a hot-spot software which helps you to connect to WiFi by opening a hot-spot each time the Pi cannot connect to a known WiFi connection.

Now is the best time to do this, because we have a serial terminal anyways and can mess with the network interfaces without shutting us out of the system!

Just use the following commands for this:

# We need to disable systemd-resolveds caching DNS stub resolver
# if you want to know why check: https://github.com/pi-hole/docker-pi-hole/#installing-on-ubuntu
sudo sed -r -i.orig 's/#?DNSStubListener=yes/DNSStubListener=no/g' /etc/systemd/resolved.conf
sudo systemctl restart systemd-resolved.service

ping ntp.org
# This will throw an dns error:
#   ping: ntp.org: Temporary failure in name resolution
sudo sh -c 'rm /etc/resolv.conf && ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf'
sudo systemctl restart systemd-resolved.service
nslookup ntp.org
# DNS should work now

# Install comitup using the latest version from the projects repo
wget https://davesteele.github.io/comitup/latest/davesteele-comitup-apt-source_latest.deb
sudo dpkg -i --force-all davesteele-comitup-apt-source_latest.deb
rm davesteele-comitup-apt-source_latest.deb
sudo apt update
sudo apt install comitup --no-install-recommends

sudo systemctl stop comitup
# Now use network-manager to:
# - add you wifi network
# optional:
# - change your hostname
# - add a dhcp ethernet connection without any device assigned
# (if even the hotspot malfunctions you can plug in a usb ethernet adapter)
sudo nmtui

# Edit comitup.conf to change the wifi name and password (I use OpenMower-<nn>)
sudo nano /etc/comitup.conf
sudo systemctl restart comitup
# reboot - it should work now
sudo reboot

Disable Serial Console

Now that we have setup the network and can access the Pi even if our WiFi is not in range, we need to disable that serial console so that we can use the serial port for hardware.

To do this, enter: sudo nano /boot/firmware/cmdline.txt

and remove the console=serial0,115200 part of the line.

Save the file and reboot. You should still see the bootloader output, but no serial output after that.

Installing Tools

If you're happy with your basic Ubuntu setup, it's time to install some tools required for the OpenMower

General Dependencies

Just install them with apt:

sudo apt install --no-install-recommends build-essential git

STR2STR (optional, recommended; only needed if you're using NTRIP, so probably most of you)

We need a newer version than the one available in apt, so install it from source:

sudo apt install gfortran
git clone https://github.com/rtklibexplorer/RTKLIB
cd RTKLIB
git checkout tags/b34c
cd app/consapp/
make -j$(nproc)
sudo make install

You should now be able to run str2str from anywhere.

OpenOCD (optional, recommended; only needed if you want to flash Pico from Raspberry Pi)

We need to get the OpenOCD version from the Raspberry Pi foundation, because the "original" one doesn't have the Pico support built in yet.

Install it from source:

sudo apt install automake autoconf build-essential libtool libftdi-dev libusb-1.0-0-dev texinfo pkg-config rpi.gpio-common
git clone https://github.com/raspberrypi/openocd.git --recursive --branch rp2040 --depth=1
cd openocd
./bootstrap
./configure --enable-ftdi --enable-sysfsgpio --enable-bcm2835gpio
make -j$(nproc)
sudo make install

You can test if it was a success by running:

ubuntu@ubuntu:~$ openocd -v
Open On-Chip Debugger 0.11.0-g610f137-dirty (2022-06-07-00:39)
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html

Installing ROS and OpenMower

We're using ROS Noetic for the OpenMower project. In this step we will install it, get the OpenMower sources, build the sources and create a basic configuration file for your mower.

Install ROS Noetic

Since we're running Ubuntu 20.04 installing ROS is as easy as running the following commands:

# Get the ROS apt repository
sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -

# Install the ROS base system
sudo apt update
sudo apt install --no-install-recommends ros-noetic-ros-base

We only need to register the ROS installation in your .bashrc file. This will enable you to call ROS specific commands from your terminal:

# If you're using bash (default on Ubuntu):
echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc
source ~/.bashrc

# Else if you're using zsh
echo "source /opt/ros/noetic/setup.zsh" >> ~/.zshrc
source ~/.zshrc

Installing OpenMower Software

Now we're finally able to install the OpenMower software. First, we're checking out the current version of the sources, then we're getting the dependencies and finally we're building the sources:

# Clone the GitHub Repository:
git clone --recursive https://github.com/ClemensElflein/open_mower_ros.git

# Get rosdep, only needed once
sudo apt install --no-install-recommends python3-rosdep
sudo rosdep init
rosdep update

# Get the dependencies using rosdep
cd ~/open_mower_ros/
sudo apt-get install --no-install-recommends $(rosdep install --from-paths src --ignore-src --simulate | sed --expression '1d' | sort | tr -d '\n' | sed -e 's/  sudo -H apt-get install//g')

# Finally, build the sources. This will take a while! 
catkin_make -j1 # on 2GB Pi with SWAP - this takes at least 30min
# OR
catkin_make -j2 # on 4/8GB Pi - this takes at least 20min

# Copy the default configuration file to your home directory
cp ~/open_mower_ros/src/open_mower/config/mower_config.sh.example ~/mower_config.sh

# The next step is to also source the OpenMower ROS install
# If you're using bash (default on Ubuntu):
echo "source ~/open_mower_ros/devel/setup.sh" >> ~/.bashrc
echo "source ~/mower_config.sh" >> ~/.bashrc
source ~/.bashrc

# Else if you're using zsh
echo "source ~/open_mower_ros/devel/setup.zsh" >> ~/.zshrc
echo "source ~/mower_config.sh" >> ~/.zshrc
source ~/.zshrc

At this point the OpenMower software is successfully installed! You will need to configure the OpenMower software and then you're finally ready to mow.

Some Additional Issues

I'm using an external WiFi dongle for better coverage, but sometimes it doesn't work

It seems that the Ubuntu sometimes puts external WiFi dongles to sleep. To prevent this, we create a service which disables powersave:

# Enter this to create the service
sudo systemctl --full --force edit wifi_powersave@.service

# Paste the following:
[Unit]
Description=Set WiFi power save %i
After=sys-subsystem-net-devices-wlan1.device

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/sbin/iw dev wlan1 set power_save %i

[Install]
WantedBy=sys-subsystem-net-devices-wlan1.device

# Save and exit, then activate using:
sudo systemctl disable wifi_powersave@on.service
sudo systemctl enable wifi_powersave@off.service