Remote control your Pi using your Mac

This is the first of what will hopefully be a series of posts by me. There will be an emphasis on the more technical side of things but, with any luck, things will be explained in plain English. I like to think that even though I am a geek by day I can still see things from the perspective of a ‘normal’ person 🙂

I have been asked by a couple of schools to give them guidance and/or training on how best to use their Pis without having to beg, borrow or steal monitors, keyboards etc when they already have a perfectly (good?) functioning suite of computers. As I tinker with Apple kit all day long, a lot of these posts will be weighted towards making a Pi work with Macs.

When I asked one school I regularly visit about the unopened boxes of Pis that had been sitting in the corner of the suite for almost a year, I was told that they couldn’t use them with the children or even get a trainer in to run a workshop as every trainer that had come in had requested HDMI monitors, USB hubs, power supplies, etc etc. When I asked the school why they didn’t simply use their existing iMacs & MacBooks to control the Pis via a VNC & SSH session, they said it sounded brilliant and would I be able to do it for them! They asked me if I could configure their Pis to work in this way and then provide them some basic training on how to actually use the Pis to aid in teaching the primary computing curriculum.

As I configured the devices I thought it would be wise to take notes so that it could turn into a blog post for other schools to use. After following the instructions below you should have a Raspberry Pi that you can connect to a power supply, Ethernet cable and no more. The Pi can then be controlled by a Mac using standard VNC and SSH protocols (don’t panic yet). This removes the requirement to purchase HDMI/DVI monitors just for your Pis and also makes getting them out of the cupboard and setting them up far less hassle.

Writing for what will mainly be an audience of teachers & educators, I am aware that there will be a wide range of skill levels. Most of my friends are teachers and I work in schools all day long, so I know both teachers that are more than comfortable living in the command line editing config files all day long and teachers that would feel completely overwhelmed using any form of command-line interface. Therefore I have chosen to write two versions of this guide – one for users that have prior knowledge of a system like the Pi and one for complete beginners. I hope the beginners version is not patronising, I certainly don’t intend it to be. The more techie-friendly version is more or less a set of bullet points that you can follow in order to get up and running whereas the beginners guide will hopefully leave no stone unturned. It may be a long read but I will try my best to format it in chunks that are logically ordered and easy to read. With that out of the way, let’s crack on. If you are after the more techie focussed ‘how-to’, follow the following link:

A Mac Geek’s guide to VNC on the Pi

Right, now that we’ve got rid of the bearded geeks (I’m only bitter as I’m incapable of growing a real beard), I will move on to a ‘dummies’ guide. I have plenty of books on a variety of subjects from the Dummies series – we all have to start somewhere…

Take your Pi out of the box, ensure that the SD card is inserted and, using a bog-standard network cable, plug it in to a network socket that you know is working. Perhaps shut down a working computer and temporarily borrow its network cable for this purpose. When it comes to powering the Pi, you can purchase a mains adapter that has a micro-USB connector on it or, my preferred and by far the neatest solution, use a standard micro-USB to USB ‘A’ lead and plug one end into your Mac’s USB port and the other into your Pi’s power socket. Powering the Pi this way has worked fine for me with relatively new Macs (most mid-late 2012 and later models) and even with older Macs the Pi has run absolutely fine for most tasks. Certainly fine for users that are getting started and aren’t going to be connecting multiple devices to the Pi’s GPIO pins (more on those later).

Once the Pi has got its power and network connection, its red power light should be lit and within a couple of minutes it will be waiting for input from you. Well that’s all well and good, you might say, but how on earth do I control the Pi or see what’s on its screen? The first stage of gaining remote access into the Pi involves identifying it on the network. When your Pi boots it will request an IP address from your network’s DHCP server just in the exact same way that every other computer, printer etc does. Because we know that the Pi will obtain an address within a certain range, we can use a tool on the Mac to perform a quick scan of all devices on your network and report back with the address of the Pi. The tool is called nmap and is downloadable from: http://nmap.org/download.html#macosx
You want to download the installer from the ‘Mac OS X Binaries’ section. Once you’ve downloaded the installer it will most likely be in the Downloads folder on your Mac. Double click on the file that you have just downloaded and you should be presented with a window containing the nmap installer. Hold down the control (ctrl) key on your keyboard and click on the ‘nmap-xxx’ (where xxx is the version of nmap you’ve been provided) icon that looks like an open cardboard box. Now let go of the control key and click on open. If given a warning about the file being from an unidentified developer, choose open and you should then see the standard Mac OS X Installer which may be familiar if you’ve installed software on your Mac in the past. Keep clicking on the continue/install buttons until you are prompted for your admin password. Once you enter this the software will be installed. This should take a matter of seconds and once done you can close/quit the installer application. Now that you have installed the nmap tool you can use it to search the network for your Pi and connect to it. Open the ‘Terminal’ application which can either be found in your Utilities folder (inside Applications) or by using the Spotlight icon in the upper right-hand section of your menu bar. Once the Terminal opens you will be able to type in commands for the Mac to run. The command we’re after is nmap. Simply type in ‘nmap’ to the Terminal and press return. If the installation went successfully you should see a mountain of text flash by, with the last few lines at the bottom describing some usage examples.
nmap needs to know which range of addresses to scan. If you already know what your school’s IP range is, great. Otherwise you will need to use the following method which is not 100% foolproof but should certainly work for 99.9% of primary and most secondary networks. On your Mac go to System Preferences from the Apple menu and click on the Network icon in the window that appears. In the left hand side of the Network preferences you should see at least one entry with a green dot next to it. Ideally your Mac will be plugged into the network and the entry will most likely be labelled ‘Ethernet’ or a variation on this. Click on the green entry to select it and then from the right hand section of the window click on the ‘Advanced’ button to see further detail. Click on the ‘TCP/IP’ tab at the top and note down the address at the top and the Subnet Mask. Click on cancel to come out of the advanced settings and then quit out of System Preferences completely. In order to translate the details you’ve noted down into a range to scan visit this website: http://mxtoolbox.com/subnetcalculator.aspx
In the ‘IP Address or Subnet’ text box, type in the IP address of your Mac that you noted down. Then from the menu to the right choose the subnet mask that matches your Mac’s. Be careful here as a lot of the look similar! In my example, I typed in 10.0.1.4 as my IP address and selected 255.255.255.0 for my subnet mask. Click on the ‘View Subnet’ button. When the page reloads you will see lots of numbers in a table, but the info that you’re after is in the upper left hand section and contains a portion of your IP address followed by a forward slash and then a number. In my case this was 10.0.1.0/24. It’s this info that we need to feed into nmap and so note it down and go back to the Terminal app. You’re going to once again type in nmap but this time followed by a few other bits of info. Type the following in exactly as shown:

sudo nmap -p22 --open xxx.xxx.xxx.xxx/xx

where xxx.xxx.xxx.xxx/xx is the info you noted in the previous step.

You will likely be prompted for a password which will be your own password for your Mac. As you type your password in, nothing will appear on the screen so just go ahead and type carefully before hitting return.

Depending on the size of your network, you may see some feedback within a few seconds or it may take a few minutes. Once the scan has complete you should have a list of devices on the network that nmap has detected using the criteria specified in the command you typed in. With any luck you will see somewhere in the list in plain English ‘Raspberry Pi Foundation’ and then a couple of lines above this will be the IP address of the Pi. If you have multiple ‘Raspberry Pi Foundation’ lines it means that more than one Pi has been discovered on your network, but if you’re a beginner and therefore following this guide that’s unlikely to be the case.
Now we have the address of the Pi we can use another Terminal command to connect to and configure it.

Type in the following:

ssh pi@xxx.xxx.xxx.xxx

(xxx being the address that you’ve identified as belonging to the Pi, e.g 10.0.1.5)

After a few moments you should see a question asking if you want to continue connecting. Type in yes and press return. The Pi is now prompting you for a password for the ‘pi’ user account. The default password is ‘raspberry’. Type this in and press return. Again, for security the password won’t appear as you type so type carefully. It’s all lowercase.

If all’s gone well you will see the Raspberry Pi’s command prompt, awaiting further instructions from you. The first command we’ll give to the Pi is to launch its basic configuration utility called raspi-config. Type in the following and press return:

 sudo raspi-config

You should then see a screen similar to the one below:

raspi-config

There are two things we need to change using the utility. First, use the arrow keys on your keyboard to navigate down to ‘Enable boot to Desktop/Scratch’ and press return. From the next screen that appears move down to ‘Desktop Log in as user ‘pi’ at the graphical desktop’ and press return. After a flash you should be taken back to the main menu. Use your down arrow key to now move down to the ‘Advanced options’ line and press return. From the next screen select the ‘Hostname’ option and press return. Read the instructions and then press return. From the following screen you can now give this particular Pi a unique name so that it doesn’t clash with other Pis that you connect to your network. If you’ve only got a handful you can use something simple like ‘pi-01’ etc. After pressing return and being taken back to the main menu, press the right arrow key twice to highlight the ‘Finish’ option and press return. You will be asked if you want to reboot, press return again to answer yes and wait a moment for your Pi to reboot with its new name. When the Pi reboots, your Mac will lose connection to it but it’s easy to get back in. After 30 seconds or so, press the up arrow on your keyboard to recall the last command you issued to the Mac. This should be the ‘ssh’ command that you used to gain remote access to the Pi. Press return and after a short delay you should once again be asked for the password for your Pi. If nothing happens or if you receive an error, wait another 30 seconds and try again. Once you’ve logged back in to the Pi the first thing you may notice is that the text that is displayed to the left of where you type (the prompt) has updated to reflect the new name you gave the Pi.

Now we will move on to the installation of some additional software and utilities that will enable you to establish a ‘remote control’ connection to the Pi. We live in a world of software updates and the Pi is certainly no different in that respect. Almost as soon as it leaves the factory the software on it is out of date. It’s good practice to update the Pi’s software and fortunately it’s fairly easy.

If your school Internet connection requires that you use a proxy (filter) server, you will have to obtain those details either by looking at the network settings on your Mac or by asking your technician. If you don’t need to enter specific filtering details to access the web, skip all of this blue text. If you’re unsure, try moving onto the next step but if it doesn’t work you’ll have to ask someone for the filter information. Once you have it you can tell the Pi to use the filter by entering the following command on the Pi:

cd
echo "export http_proxy=http://yourproxyaddress:proxyport" >> .bashrc
echo "export http_proxy" >> .bashrc

e.g:

cd
echo "export http_proxy=http://proxy.crossover.solutions:8000" >> .bashrc
echo "export http_proxy" >> .bashrc

Now log out of the Pi (type exit and press return) and then use the up arrow on the keyboard to recall the ssh command and press return. Log in as you did before and the Pi should now be able to access the Internet.

The first thing we’ll do is run the following command to update a few things on the Pi:

sudo apt-get update

Hopefully that will complete without any errors. If you receive an error it’s likely that any proxy settings you had to define in the previous step contained a typo. Try again or leave a comment below for further help.
Now run the following two commands to install two pieces of software – avahi-daemon and x11vnc. Avahi is something that will allow you to more easily find your Pis on your network and x11vnc is the tool that will allow you to remote control the Pi from a Mac or PC. After you type in the first command and hit return, there will be a lot of text that flashes past on the screen. You may be prompted to continue by typing in a ‘y’ and pressing return. Let this all finish before moving on to the next command.

sudo apt-get install avahi-daemon
sudo apt-get install x11vnc

Once that finishes type in the following which will duplicate one of avahi’s config files and allow the Pi to advertise its VNC/Screen Sharing service to the Macs on your network:

sudo cp /etc/avahi/services/udisks.service /etc/avahi/services/rfb.service

Now you will edit the copy of the file and enter information specific to the VNC service. Enter the following:

sudo nano /etc/avahi/services/rfb.service

A text editor called nano will open. Using the arrow keys, move down to the end of the text ‘udisks-ssh’, use the backspace/delete key to erase this text and replace it with ‘rfb’. Then move down to the number ’22’ and replace it with ‘5900’. That portion of the file should end up looking like this:

<service>
<type>_rfb._tcp</type>
<port>5900</port>
</service>
</service-group>

Once you’re done press the control key along with ‘x’. This tells nano to quit. It should prompt you to “Save modified buffer” at the bottom of the window. Respond with the ‘y’ key and press enter. You should now be taken back to the command prompt.
The avahi service needs to be restarted to pick up the changes you’ve just made. Type in the following:

sudo service avahi-daemon restart

Finally (for the VNC/avahi service at least!), type in the following command to set a password:

x11vnc -storepasswd

You’ll be asked to supply a password. Enter something simple like ‘password’ or even just a single letter. Press return, type in the password once more to verify, hit return and then answer ‘y’ and return to the question.

Screen Shot 2014-11-30 at 11.41.24

In order to start the VNC service automatically when the Pi is switched on, perform the following:

Type:

cd
cd .config
mkdir autostart
cd autostart
nano x11vnc.desktop

Screen Shot 2014-11-30 at 18.30.22

Once the nano text editor opens, select and copy the following text:

[Desktop Entry]
Encoding=UTF-8
Type=Application
Name=X11VNC
Comment=
Exec=x11vnc -forever -usepw -display :0 -ultrafilexfer
StartupNotify=false
Terminal=false
Hidden=false

Now go back to nano and paste the text in using the normal method of edit and paste or Apple/cmd + V. Press control and x to exit nano, answering ‘y’ and pressing return when prompted to save.

Screen Shot 2014-11-30 at 18.30.04

Thanks to emg’s post at http://www.raspberrypi.org/forums/viewtopic.php?p=108862#p108862 for the above information.

You should be back at the command prompt and the only thing left to do is reboot the pi and see if all of your hard work has paid off. Type the following and press return:

sudo reboot

and then go back to the Finder/Click on the desktop on your Mac. From the ‘Go’ menu choose ‘Network’ which should display a window that contains all Macs & PCs on your network that are offering some kind of sharing service (file sharing, VNC/Screen Sharing etc). Hopefully after your Pi has rebooted you will see it listed in there! All that’s now left to do is double click on it and then from the upper right corner of the window choose ‘Share Screen’. The Mac’s Screen Sharing application should launch and prompt you for a password. This will be the password you set earlier using the x11vnc -storepasswd command. Once you type it in and click connect/press return you should hopefully see your Raspberry Pi’s desktop and be able to use it just like you would had you a proper monitor, keyboard & mouse connected directly to the Pi.

Screen Shot 2015-01-28 at 22.36.55

Screen Shot 2015-01-28 at 22.38.13

Screen Shot 2015-01-28 at 22.38.04

Screen Shot 2015-02-01 at 17.19.30

If you happen to notice that the screen size is extremely small, you may need to edit one last file and reboot the Pi. I’ve had this happen on one Pi but not on others and I haven’t yet worked out what the pattern is.

To fix a small VNC screen size:
Log back in to the Pi using ssh from your Mac, e.g.

ssh pi@xxx.xxx.xxx.xxx

Edit /boot/config.txt:

sudo nano /boot/config.txt

Using the arrow keys on your keyboard, scroll down to the line that says
#hdmi_force_hotplug=1
and remove the hash at the beginning using the delete/backspace key on your Mac’s keyboard. Then scroll down a bit further until you get to the bit that looks like:
#hdmi_group=1
#hdmi_mode=1
Once again, remove the hashes and then change hdmi_group=1 to hdmi_group=2
Also change hdmi_mode=1 to hdmi_mode=16. This will set the Pi’s screen resolution to a more useful 1024×768 which should be enough for most if not all tasks.
Finally, save the file and exit by pressing ctrl and x and pressing y and return when prompted to save. Now reboot the Pi by issuing ‘sudo reboot’ and you should find that when you reconnect to your Pi using VNC/Screen Sharing, the screen size is a bit more useful!

If you run into any problems or have any suggestions on how to make this guide better, please leave a comment below and I’ll do my best to get back to you as soon as poss.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s