In this tutorial, we'll look at how to set up and use your shiny new HyperPixel 4.0. It's all fairly straghtforward. Note that you'll need a keyboard, mouse, and keyboard to set the software up, and a Phillips screwdriver to attach the metal standoffs to your Pi.

When you open your HyperPixel 4.0 box, you find the following:

• HyperPixel 4.0 PCB and display
• standoff kit with 4x metal standoffs and 4x screws
• female header

We'll start with how to attach your HyperPixel 4.0 to your Raspberry Pi. These instructions apply to the Raspberry Pis B+, 2, 3, and 3 B+, and we'll cover what to do with a Zero or Zero W after.

Attaching your HyperPixel 4.0 to your Raspberry Pi

Note: you should all of the following section with your Pi powered off.

The first thing to note is that your HyperPixel 4.0 screen has a protective film on the screen. It's best to leave this on while you're attaching it, to prevent accidentally scratching the glass.

On the underside of your HyperPixel, you'll see four silver metal mounting posts that have little orange pieces of film on. Peel the pieces of film off, and then screw the threaded ends of the four black metal standoffs into the four mounting posts.

The female extended header that comes with your HyperPixel 4.0 lifts it high enough to clear the USB and ethernet ports at the right-hand side of your Pi. Push the male end of the extended header into the female header on your HyperPixel firmly, until it's all the way in.

Now, push the extended header on your HyperPixel 4.0 onto your Pi's GPIO pins, making sure not to press on the centre of the HyperPixel's display but instead holding the edges of the display and PCB and pressing gently but firmly. Make sure that both headers are aligned properly; you can check this by looking at the alignment of the standoffs with the mounting holes on the Pi.

Flip your Pi over and secure the standoffs with the four metal screws, using a Phillips screwdriver. You can peel the film off the front of the diplay now, if you wish.

Using it with a Raspberry Pi Zero or Zero W

If you're using a Raspberry Pi Zero or Zero W, then you won't need to use the additional extended header, and just plug it straight onto the pins!

Setting up your Raspberry Pi

Download Raspbian Stretch with desktop and then use Etcher to burn the operate system onto a micro SD card that's at least 8GB. We sell a NOOBS micro SD card that comes pre-loaded with a range of operating systems, including Raspbian, so if you're not sure what you're doing then you could grab one of them instead.

You'll need an HDMI display, keyboard and mouse connected for the next part, until the HyperPixel installation is complete, or you could follow our guide on how to set up a Raspberry Pi headlessly, and then use SSH to install the HyperPixel software.

Pop the micro SD card with Raspbian installed into the slot on the underside of your Pi and plug your power supply into the micro USB port; the Pi should start booting up.

You'll need to be connected to the internet with either an ethernet cable plugged into the ethernet socket on your Pi, or to a Wi-Fi network. If you're booting into Raspbian for the first time, then it will guide you on connecting to Wi-Fi.

Installing the HyperPixel 4.0 software

We've put together a nifty one-line installer for the HyperPixel 4.0 software that'll get everything configured properly for you. If you're an advanced user, and you'd like to know what the code is doing, then you can look at the GitHub repository and the install.sh script.

Open a terminal window, and then type the following and press enter:

curl https://get.pimoroni.com/hyperpixel4 | bash

The installer may prompt you to type y or n and press enter at various points and, if it asks you whether you'd like to reboot once it's finished, then type y to reboot.

Once rebooted, your HyperPixel display should be displaying the Raspbian desktop! Try touching the touchscreen, if you're using the Touch version of HyperPixel 4.0.

If you're not bothered about using I2C, then you're done! If you want to learn more, then read on!

Using the alternate I2C interface on HyperPixel 4.0 (for advanced users)

HyperPixel 4.0 uses literally all of the GPIO pins on the Raspberry Pi, including the standard I2C pins (BCM 2 and 3), but we've broken out pins BCM 10 and 11 as well as 3V3 power and ground, so that you can use I2C devices at the same time as using your HyperPixel 4.0.

You can use a cable with a 2mm pitch, 4-pin, male JST connector on one end and either bare ends that you can solder to your I2C device, or male DuPont connectors (the sort that you get on male jumper jerky). We'll be selling a cable to do this in the very near future.

The nifty trick to using the alternate I2C interface is to symlink i2c-3 to i2c-1 to fool any I2C devices into talking to the alternate one rather than the standard one. Open a terminal, and type:

sudo ln -s /dev/i2c-3 /dev/i2c-1

Now any software libraries that use I2C should talk to i2c-3 rather than to i2c-1, meaning that you don't have to meddle with the sotware libraries themselves.

If you want to undo this, you can simply delete the i2c-1 symlink file by typing in the terminal:

sudo rm /dev/i2c-1