This document describes how to install the software that runs on a Hedgehog controller. If you have bought a complete controller, it should have come with everything installed and you shouldn’t have to do this. If you somehow can’t connect to your controller anymore, you can re-install everything as described here as a last resort.

Using a Hedgehog SD card image

By using a prepared image, you can save the time needed to follow the setup described below. Most often this is the way to go, as you can still install custom software on top of the prepared image, while saving time because most of the software and more recent system updates are already installed.

Installing a Hedgehog image works the same way as installing plain Raspbian, installation instructions can be found at Of course, instead of using a Raspbian image file, a Hedgehog image is used. Hostname (raspberrypi), username (pi) and password (raspberry) are the Raspbian defaults, but unlike with Rasbian, SSH is enabled! We might disable SSH by default in future images.

If you are re-installing your controller, that is probably it. However, if you have a never-used hardware board or there was a firmware update, or you just want to be on the safe side, go to the firmware installation section.

Installing from scratch

Installing a Hedgehog is a simple step-by-step procedure:

  • installing the operating system
  • ensuring you can run commands on the hedgehog:
    • by connecting keyboard and monitor; or
    • by enabling SSH
  • connecting Hedgehog to the internet
    • via Ethernet
    • via WiFi
  • executing the setup scripts

If you don’t want to use keyboard and monitor, Hedgehog is a headless device. This means that you need to access your Hedgehog over the network, and/or provide some configurations before you boot your controller. We provide instructions for both options, but configuring WiFi requires you to access the ext4 root file system, for which you may need a Linux machine. If you run another operating system and can’t access the root partition, please use a wired connection or keyboard and mouse initially.

If you’re using keyboard and monitor, you can still follow the headless instructions instead of equivalent headed instructions if you feel like it.

Installing Raspbian

Like any Raspberry Pi, Hedgehog needs an operating system, for which we use Raspbian. Downloads and installation instructions can be found at There is a “lite” version without a graphical user interface, which is sufficient, but you can also install the full version.

Once you are done, don’t plug in your SD card and boot your Hedgehog just yet, especially if you want to work headless. Continue with the next section.

Pre-Boot Setup in Headless Environment

Without monitor and keyboard, some configurations need to be done before you boot your controller for the first time. Even if you use computer peripherals, you have the choice to follow these instructions instead of the equivalent instructions later on.


In a headless environment, network access is necessary to control a device; with peripherals, it’s optional. SSH is a simple way to run commands from another machine; newer versions of Raspbian require you to enable SSH first as a security measure. Follow the instructions for headless Raspberry Pis:

For headless setup, SSH can be enabled by placing a file named ssh, without any extension, onto the boot partition of the SD card. When the Pi boots, it looks for the ssh file. If it is found, SSH is enabled, and the file is deleted. The content of the file does not matter: it could contain text, or nothing at all.

The instructions also contain an overview of client software you can use on your computer.


For this, you will need to access the ext4 root file system, for which you may need a Linux machine. If you can’t access the root partition, please use a wired connection, or keyboard and a monitor.


add instructions

Host Name (optional)

Again, this requires accessing the root partition.

By default, Raspbian configures a network name of raspberrypi. If you don’t like that, or have multiple Raspberries (including Hedgehogs), you should change the hostnames to be unique (and to your liking, of course).

To do so, look into the files etc/hosts and etc/hostname on the Raspbian root file system, and change the ocurrences of raspberrypi to the same single word of your liking. For example, on Linux, this can be achieved like so:

# change into the Raspbian root partition, then:
sudo sed -i s/raspberrypi/new-name/ etc/hostname etc/hosts

Booting up & connecting

Now, put the SD card into your Hedgehog, connect the controller to a battery, and turn it on.

Whatever way you use to log in, the default credentials are pi/raspberry.

Connecting with keyboard & monitor

This is straight forward: as soon as the Pi has booted, you should be prompted for username and password.

Connecting via Ethernet directly to your computer

To connect the controller directly to your computer, your computer will need to act as a DHCP server. Configuring this depends on your operating system. For Ubuntu Linux, it can be achieved like this:

Menu > Network Connections > (select or create an Ethernet connection) > Edit > IPv4 Settings > Method: Shared to other computers > Save

In addition to providing addresses via DHCP, this will also let connected devices use your internet connection - during installation, this is necessary. At other times, you may deactivate your internet connection if you want to prevent that.

Finally, use an Ethernet cable to connect your controller and computer, and make sure that the saved configuration is used.

Connecting to an existing network

If you configured WiFi or connected your Hedgehog to a router via Ethernet, the Hedgehog should auto-connect to the network and receive a DHCP address. If you use a network without DHCP (if you don’t know what DHCP is, you’re probably using it), we assume that you know how to configure IP addresses manually; we won’t cover that here.

Now, to connect to the controller, you need either its host name or its IP address. Best, first try this (substitute your hostname):

ssh pi@raspberrypi.local


pi is the user name and raspberrypi.local is the host to connect to; this is how you use the default Linux SSH client. If you use a different SSH client program, refer to its documentation.

Host name resolution is platform dependent and might not work on some platforms out of the box, especially Windows. (the actual software setup will install a package that adds Windows support, but that doesn’t help for the very first connection). If it doesn’t work, you need to find out the controller’s IP address. If you also have a keyboard and monitor, you can simply execute this command:


It will show IP addresses for all network interfaces; look out for the inet addr: label. If you determined your Hedgehog’s IP address to be, for example,, use this command:

ssh pi@

Post-boot setup

Depending on your way of connection and what you configured pre-boot, you can skip some of the following steps.

SSH (optional)

If you plan on using SSH, either now or later on, read on. Otherwise, you can skip this.

Newer versions of Raspbian require you to enable SSH before using it; this is a security measure, as SSH allows remote access to a computer. The instructions also contain an overview of client software you can use on your computer.

Connecting to a network & the Internet

During installation only, an Internet connection is required. Whenever you use SSH, you will also need a network connection, even if that network does not have Internet access.

If you’re not using SSH right now and thus already have a network connection, do one of the following. Needless to say, whatever network you connect to, it needs to be connected to the Internet:


These instructions are also useful after the initial installation, to add new network connections.

In a headed environment (or if you already have an SSH connection via another network), the wpa_cli command can be used to configure wireless networks interactively, like this:

sudo wpa_cli
> add_network
> set_network 0 ssid "network-1"
> set_network 0 key_mgmt WPA-PSK
> set_network 0 psk "secret"
> enable_network 0
> save_config

This was for a WPA Personal secured WiFi. Configuring a WPA Enterprise secured WiFi might look like this:

sudo wpa_cli
> add_network
> set_network 1 ssid "network-2"
> set_network 1 key_mgmt WPA-EAP
> set_network 1 eap PEAP
> set_network 1 identity "username"
> set_network 1 password "password"
> enable_network 1
> save_config

wpa_cli can also be used non-interactively. For example, our Hedgehogs come with the following WiFi pre-configured:

sudo wpa_cli <<EOF
    set_network 0 ssid "hedgehog"
    set_network 0 key_mgmt WPA-PSK
    set_network 0 psk "hedgehog"
    enable_network 0

Note the initial flush command: this deletes all previous network connections. This is generally necessary for non-interactive network configuration because you want to be sure the network numbers are known, i.e. start at zero.

More options and usage information can be found in the man pages:

man wpa_cli
man wpa_supplicant.conf

Host Name (optional)

Changing the host name works the same way as in the pre-boot instructions for Linux. It’s necessary to reboot the controller for the change to take effect:

sudo sed -i s/raspberrypi/new-name/ /etc/hostname /etc/hosts
sudo reboot

Running the Hedgehog setup

Now with network connections figured out, we can run the actual Hedgehog setup. To do this, run the following commands:

curl -O
make setup-rpi setup-python setup-hedgehog install-server install-ide

The first command will download a Makefile, the actual Hedgehog setup script. The second command runs it, performing a couple of tasks; this will download a lot of software (so make sure you don’t run into a data limit, and have enough battery and time) and install it:

  • configure the current locale

    If you connect via SSH, the shell will use the connecting system’s locale, which may not be installed and in turn lead to errors. Installing the necessary locale will prevent errors now and for subsequent connections.

  • extend partition

    Before installing software, the root partition is expanded to the full SD card size to accomodate it.

  • activate serial connections

    Hedgehog uses the Raspberry’s serial port to talk to the hardware controller, so this needs to be enabled. This only goes into effect after a reboot.

  • update system software

    The freshly-installed image may not contain latest software updates, so install them

  • install additional system software

    • git is installed to handle Hedgehog software
    • usbmount allows to automatically mount USB flash drives, e.g. to auto-load configuration files
    • samba enables hostname resolution with Windows
  • install Python

    Considerable parts of Hedgehog are written in Python, so the necessary software is installed

  • install Hedgehog packages:

    The Server and IDE are installed to start automatically. Installing the firmware requires a serial connection, and that requires a reboot.

You are now done installing the Raspberry Pi software! If you are re-installing your controller, that is probably it. However, if you have a never-used hardware board or there was a firmware update, or you just want to be on the safe side, the next section shows how to install the firmware.

Installing the Hedgehog Firmware

If you just installed a fresh SD card, make sure that you reboot your controller to let serial connection settings take effect:

sudo reboot

Now connect, and install the firmware like this. The server is stopped before that to make sure the serial connection is free:

sudo service hedgehog-server stop
make install-firmware
sudo service hedgehog-server start

That’s it! Your controller’s firmware should be properly reinstalled.

Tips & tricks

These are some tricks that may or may not be useful in your workflow.

Modifying image files

On Linux, the losetup command can be used to use an image file as a loopback device:

# add the -r option the work read-only
sudo losetup -P /dev/loop0 path/to/image.img
# when finished, unmount the partitions, then detach the device:
sudo losetup -d /dev/loop0

After setting up the loopback device, most linux systems will automatically mount the boot and root partitions. You can then inspect and even change the image contents, as if it were a real SD card.

Installing development versions

The setup shown above installs released versions of the Hedgehog software. If you want to benefit from unreleased features and bugfixes, you can also install the latest code in our repositories: just replace the setup-hedgehog target with setup-hedgehog-develop.


The makefile does currently not contain a development setup for the IDE.