Skip to content

Software Installation

Jump to bottom
Ben Thomas edited this page May 10, 2024 · 24 revisions

Installation Steps Overview

  1. Install an operating system on the Raspberry Pi - (Raspbian Bookworm 64bit Recommended as of 2024)
  2. Configure the Raspberry Pi OS
  3. Install a MongoDB on the Raspberry Pi
  4. Download the UTM source code from Github
  5. Install the Python control subsystem - (Python >3.11.0)
  6. Install the Node.js GUI subsystem - Nodejs, NPM and Electron
  7. Install and run the Arduino microcontroller code
  8. Troubleshooting and FAQ

Requirements

  • Raspberry Pi 4B - 4/8GB RAM models
    • Raspberry Pi 5 has also been tested for the 2nd Gen UTM.
  • Micro-SD Card (Class 10) 32-128GB
  • Wired or Wireless Network connection to update software and access Github
  • Laptop or Desktop PC running Windows 10/11 or Mac OS. If you only have access to a linux system all of these steps should still work but will not be supported by this guide.
  • Micro SD Card reader or card reader USB dongle.

1. Install the operating system

  • Use a class 10 SD card (minimum 32GB, preferably > 64GB depending on how heavily used the UTM machine will be and how much data it will generate)
  • Use Raspberry Pi Imager (download here) to select an operating system and flash the SD card
  • Click on "Choose OS"
  • Select "Raspberry Pi OS (other)" and choose Raspbian Bookworm 64 bit (not Lite as it doesn't include the main desktop environment needed to display the UTM software) (Bullseye will also work but Jessie, Buster or any older OS versions have not been tested). 32 bit OS has not been tested.
  • Put the SD card into the computer that you are running Raspberry Pi Imager on, select it and begin to flash the SD card. This process can take up to an hour but is typically completed within 10 minutes on modern laptops/desktops.
  • Once the flashing process has finished, eject the SD card and insert it into the Raspberry Pi.
  • Connect a monitor, mouse and keyboard to the Pi then power it up.
  • The Pi should boot to the desktop after a few minutes. Subsequent boots will be much faster as the operating system conducted some house-keeping during the initial boot.
  • Once the Pi has booted the operating system will guide you through a setup process.
  • Enter a username and password for the machine. Make a note of each as you will need to enter them during the software installation and in order to perform any software updates at a later date.
  • If you have a Wifi network within range, select and connect to it when prompted to. This will enable you to download the UTM software and all associated packages rather than having to transfer files on a USB drive. You can also use a wired ethernet connection if available and preferred.
  • If you have connected to a network the operating system will now check for any available updates, download and apply them for you.

It is also possible to use other operating systems such as Debian Buster or Ubuntu MATE but it is left to the user to install the software on these. Node.js/Electron and Python 3.X are all supported out of the box on other Raspberry Pi operating systems.

NOTE: We suggest that the UTM software is installed on a fresh operating system to prevent conflicts with any existing software. If the user already has a suitable 64 bit OS running on a Raspberry Pi 4B then it is left to the user to decide if they want to install the UTM software on top of this or whether to reflash the SD card with a new OS and start fresh.

2. Raspberry Pi Config

The UTM software makes use of features on the Raspberry Pi that are not activated by default. The Raspi-config Use the official guidance here from Raspberry Pi to activate the following features on your Pi.

  • SPI
  • I2C
  • Serial
  • Pi Camera (optional but required if you are attaching a camera via the Pi CSI-2 ribbon cable interface. NOTE: USB webcams have not been tested with the UTM yet and will not work in the UTM software.

3. Install MongoDB - UTM database

Installing MongoDB on Raspberry Pi 4B - 64 bit

After a lot of time spent upgrading the UTM front and backend software to support a proper NoSQL database it was discovered that MongoDB doesn't officially support RPi4 running Raspbian. However, some nice people have managed to cross-compile binaries of MongoDB v4.4 and v5.0 and host them on here.

The Materiom UTM uses MongoDB v5.0.5 - the binaries and installation instructions can be found here.

Database management

If there is ever any issues that require manual manipulation of the UTM database it is helpful to use to use a GUI application rather than the mongo command line interface.

UTM Control Software Installation

  • Before you start the installation, make sure the Raspberry Pi is completely up-to-date by running the following commands in Terminal. This is not necessary if you have just installed a new operating system and it has updated itself during the first boot process.
sudo apt update
sudo apt upgrade

Git and Github

  • All of the source code for the UTM is hosted on Github and you can use the 'git' command to download it all to your Raspberry Pi.
  • Open the Terminal application, which can be found in the top toolbar on the Raspbian OS desktop, or in the Start Menu -> Accesories.
  • Enter the following into terminal. This will download all of the UTM source code into a folder called 'UTM' in your home directory.
git clone https://github.com/materiom/UTM.git

Node.js and Electron.js (App framework)

  • Node.js - Recommended v18.12.0 but other versions > v18 may work

    • $ curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
$ sudo apt-get install nodejs
    • Test that Node.js was installed correctly with $ node -v

  • Node modules

    • Install all the node_modules from the package.json file by running $ npm install in the UTM directory. This command should install all the relevant modules with the correct versions.
    • NOTE: Electron MUST be v20.3.0. DO NOT USE v21 as there is a bug in the version of Chromium to do with ArrayBuffers that causes ZeroMQ to complain and the GUI will fail to work.
    • ZeroMQ can also complain if it is incorrectly installed for the ARM chips on the Raspberry Pi.
    • These last two help points need expanding as we attempt to install the software on more and more Raspberry Pis

7. Arduino Code Installation on Arduino Pro Micro

  • Use the Arduino IDE application to upload code
  • Choose the Arduino Leonardo board (not Leonardo Eth.) to upload sketches (.ino files) to the Arduino Pro Micro
  • Make sure the entire UTM PCB is powered up before connecting the Arduino and Raspberry Pi with a USB cable.
  • Check that the Arduino board is correctly detected in the Arduino IDE software.
  • Click on [VERIFY] to check the Arduino code is valid before uploading.
  • Click on [UPLOAD] to upload the code from the IDE to the Arduino.
  • Open the serial monitor in the IDE.
  • Use the UTM software to operate either the motor or LED lights (if available).
  • Check to see if data is printed out and it changing within the Arduino Serial Monitor.
  • If all is ok, you can disconnect the Arduino and Raspberry Pi from the micro-USB cable. All communications take place via the I2C data lines connected to the Pi GPIO pins.

Clone this wiki locally