Home

Pypilot Workbook

Originally this was called Pypilot for Dummies, but that connotation was not appropriate. Pypilot is not for dummies. I would say that building an automatic steering device for an oceangoing vessel, and trusting your and other’s lives to it, is the ultimate challenge for a sailor with technical inclination, and it should not be taken lightly. This is not a model RC plane that you can crash and have a good old laugh about it with your mates. This is a device that you must be able to trust when you cross a traffic separation scheme by night, in building winds; it should keep your boat straight when you go out of the safety of your cockpit to set a reef or change a sail.

The reward is huge. To have a classical understanding of your on-board systems, to have the ability to tweak it to your liking and to repair it if needed, is the ultimate self-sufficiency that all sailors should strive for, but not many achieve. Not to be dependent on commercial vendors, ignorant shopkeepers and sloppy repairmen is a powerful feeling. In a good autopilot you will find a trusted first mate.

Yes, it will be fun to build, but the devil is in the details, and everything will break many times before you have made it robust enough. So let there be no mistake – you are in for a long ride. The beginning is complex, that’s what this manual is for. It is supposed to help you understanding the pypilot system from the ground up and make it a bit fun as well. For me, I only describe what someone else has created. Welcome to the wondrous world of free, open-source autopilots and enjoy the read.

What is pypilot?

Pypilot is an autopilot system. It has multiple components that can be configured in more than one way. To understand pypilot, it is necessary to identify and describe the different components. For the sake of explaining pypilot, these components are first explicitly named and described:

• The software component;
• The hardware component; and
• The user interface component.

The software component

The core component of pypilot is the pypilot software. The pypilot software is open source, free software, and for people who know how to deal with it: that source is available at https://github.com/pypilot. The readme file at github has all the information that you need to install the software from source. But this is very technical stuff. If you are not familiar with open-source software, this is not for you.

Distributions

To make open-source software available to a wider public, ready-made distributions are made out of it. Pypilot is distributed in two distributions:

• OpenPlotter image, and
• TinyPilot image.

**OpenPlotter **is an elaborate marine navigation system, based on raspberry pi hardware and various open-source, free software components. Pypilot is one of them. You can download the system from the openplotter download site as an image, put it on an SD card, stick it in a raspberry pi and you have all the software components at your fingertips.

**Tinypilot **is also an image-based pypilot distribution, that sits well on a small, dedicated raspberry pi; dedicated to and highly optimized for just pypilot. It can be downloaded from the pypilot.org site. It is slightly more technical to roll out, as it is intended to run with a specially made keyboard and display unit, although you could do without. The good news is, that you can buy a ready-made tinypilot at the pypilot store, including hardware and software.

---

For those who don’t know what an image is: this is the contents of a complete disk. Rather than first installing an operating system like linux om a computer, and then installing all other pieces of software on it and configuring them to work together: an image is the contents of a disk that has all those components preinstalled on it. All you need to do is download the image (typically a large file) and burn it to a disk. If that sounds difficult – it isn’t: you can be up and running in half an hour.

---

Pypilot runs on linux, but it was developed on Raspbian, and most implementations run on raspberries pi3 or pi4. Tinypilot is intended to run on a pizero-w; the image has a special lightweight linux on it called tinycore.

The hardware component

So, you either install pypilot from source, or you download a distribution. What more do you need? There are two specific hardware components that are always needed for pypilot:

• The Inertial Motion Unit (IMU); and
• The Arduino Controller.

The IMU measures compass heading and the motion of the boat. As we will see later, these two are inextricably linked: you cannot separate them and they both are crucial to the pypilot functioning as an autopilot. The IMU is one single chip (integrated circuit) and it needs to be connected to the raspberry pi. Typically, it sits on top of the raspberry gpio header. Pypilot cannot function without this IMU – it is not possible for pypilot to steer based on an external compass, for example.

The Arduino Controller is the link between the pypilot software and the actuator (motor), and any other sensors. It is always an Arduino, and typically an Arduino Nano. The software that must run on this Arduino (in Arduino-parlour: a sketch) is included in the pypilot software distribution, and this is a sketch called motor.ino. You must take this file from a pypilot directory and burn it onto the Arduino with Arduino programming software.

The Arduino Controller talks to the pypilot raspberry through a bidirectional serial connection. This can either be a serial TTL connection or a USB cable. The protocol that is spoken over this connection is binary, bespoke, and highly optimized. It makes no sense trying to interface at this level, and nobody has ever tried. In one direction, pypilot tells the Arduino controller to move the rudder, how far and how fast. In the other direction, the Arduino controller tells the pypilot various things about the measurements of the sensors that are connected to the Arduino, like rudder angle, and the condition of the controller itself, like voltage, current and temperature.

The Arduino Controller is not a motor controller, but it connects to various types of motor controller. This can be an H-bridge interface, an RC style interface or a PWM controller. Details on how to select the type of motor controller are documented in the code of the motor.ino sketch itself, and they can be set by pulling Arduino pins high or low. Occasionally, you might have to tweak the sketch.

On the pypilot.org web site and in common conversation, the Arduino controller with an H-bridge motor controller attached to it, is called the ‘Pypilot Motor Controller’, and you can purchase one in the store. This might confuse people into thinking that you can take any other common motor controller instead and hook it directly to the raspberry. You cannot, because then you miss the Arduino Controller with its specific sketch. You could say that pypilot software is not complete without the Arduino sketch.

The User Interface Component

So we have software, and we have hardware. How do we interact with this system? We do that through a User Interface. Before we describe the various options, first a word about the internal workings of the pypilot software.

The pypilot software consists of various modules that run at the same time in parallel. Software can do that. The modules interact with each other. How do they interact? They interact by reading and writing things on a common data storage module, like a blackboard. For instance, the compass module writes the current heading to the blackboard, the user interface module writes the intended bearing to the blackboard, and then the autopilot module reads those two values from the blackboard and steers the boat.

Now it becomes clear how a user interface could work: It shows on a display the values of some of those blackboard parameters, and if you press a button, the user interface writes new values to that blackboard. Then, the combined hardware and software system does its thing based on what it reads from the blackboard.

In fact, that is how the pypilot user interfaces all work. There are a couple of them. They all write and read to this same blackboard. They can even work in parallel: if you press a button in one user interface, you see the same thing happening in the other user interface. Roughly spoken, all these interfaces offer the same functionality.

Now let’s go through the various interfaces that are available: • Browser interface • Hat Interface • OpenPlotter Interface (Python) • OpenCPN Plugin Interface

First, the Browser interface. When you start pypilot, you can go to http://your-pypilot-server and you get a web based interface with all basic pypilot functions. What those functions are, I’ll explain later. It should always work from any laptop, tablet or smart phone. Of course, sailing a boat with a phone in your hand is not optimal, but it’s a good last resort to keep in mind.

Second, the Hat Interface. This is the one that works with the small LCD screen and little keyboard. It was baptized Hat because it typically works with some hardware circuit board that you can stick on top of the raspberry. You don’t really need this specific hardware circuit board: you can just wire your keys straight to the gpio pins of the raspberry. The Hat interface offers the full set of pypilot functionality in menu items on the LCD panel interface. In combination with the TinyPilot distribution image and a miniature raspberry (“pizero”) this makes for an autonomous, very compact pypilot implementation.

Third, the Openplotter Interface. As said, you can download the OpenPlotter marine navigation system and it has pypilot included. Specially for OpenPlotter, a python-based interface was added, with popup windows etc. This Openplotter interface is typically connected to the same pypilot that runs on the openplotter raspberry. Again, it has all the standard functionality that pypilot offers.

Last, but not least, there is a very special pypilot interface, that takes the shape of a plugin to OpenCPN. OpenCPN is nautical chart plotter software, it has a moving map etc. If you install the pypilot plugin in opencpn, you get an extra button, and when you click it, yet another pypilot user interface pops up. In theory, this plugin has nothing to do with opencpn, in the sense that it is yet another pypilot user interface. It is relatively slick and snappy because it has been programmed in C++, like OpenCPN, and it’s conveniently located under a button, so it does not take long to start up. What makes it special is that is has some specific integration features with OpenCPN. For instance, it shows on the map where pypilot is steering towards. More on this later.

---

So these four user interfaces all have in common that they interface to the pypilot system through this blackboard module, that is part of the pypilot software. The real pypilot functions are defined by the pypilot software; the user interfaces only make them accessible. So now it is time to describe what those pypilot functions really are.