Things to Know

A few prerequisites for you to be able to understand how we do things here, and for you to be able to start your work.

The basics

Git

You should know how to git. It’s the most common VCS out there, and everything that we do—including this site—is done with git.

Using git as VCS for your own projects is pretty straightforward and you don’t really need to know how git really works, but when you are working on repositories that have more than one person working on it at the same time—things tend to get a little complicated, and you’ll see a lot of errors if you don’t know what you’re doing. Having a good understanding of first the problem git is trying to solve, and how it solves that problem goes a long way.

You can watch a few 2 hour long videos to get a decent enough understanding of Git, but like with most software—a little more effort spent reading the official documentation will leave you with much more. There a are few selected reads from the official Git Book (Yes, that’s a thing.) on this page too.

Here’s a good bunch of things to look at (in order please):

1. What is Version Control?
2. Learn Git Branching (interactive, how fun!)
3. IBM’s Learn the workings of Git

Going through those three things should get you up to speed.

Also, before you get your hands dirty, please take a look at Git Etiquette.

The Terminal

You should know your way around a modern terminal.

A few terms before you start

A Terminal is program that emulates an actual old school terminal.
In simpler words, its a program that is responsible to display and interact via a text based interface. On a Linux system, this can be XTerm or Gnome Terminal, iTerm2/Terminal on the Mac, and Windows Terminal or the conhost on Windows.
Basically, the program that is displaying the text and taking your input.

A Shell is the program responsible for the actual text itself. While the terminal is only concerned with showing you the text (and also taking your inputs to give back to the shell), the shell is the actual program that processes your inputs, performs actions, and outputs the text that is displayed by the terminal. Examples include the famous bash and cmd, powershell, zsh, and a few others (fish is lovely to use).

A programming language with a REPL is also a shell. They’re usually called interactive shells, and Python is a great example. The python shell is what you’re interacting with when type in python into your terminal.

Most people use these terms interchangeably but it’s important to know what you’re dealing with.

Most modern shells usually have the same basic command set, but the differences start to become apparent when you try to do something a bit more involved or try to write a script.

You can do a lot of things with just shell commands alone, and when you put them together in a file, you have a shell script. When you run a shell script, the shell does noting but execute those commands in order, no different from if you had typed in each one line by line.

While there are much better alternatives to shell scripting available, sometimes a shell script is the right combination of quick and dirty to fulfill all your quick and dirty needs, and help with tasks ranging from speeding up common workflows to full fledged automation.

Where do I learn?

You can obviously google it. Pick up your shell of choice. However, most of us here will be using bash so it’s better you learn that too. Here’s a nice resource. One more if you’re feeling confident.

At the end of the day you should be comfortable with navigating around the file system, dealing with files and using any usual command line application.

Will I actually use all of this?

Maybe, maybe not. But is good to know, and more importantly you have to remind yourself that bash scripting is something you were forced to learn because of this document.

Why? Because most don’t make use of bash scripts even though they are very simple to write.

Take an example, but this might not make sense to you right now—when you’re working on something on your computer, you might find yourself running several commands in sequence repeatedly. Starting the Stonefish simulator with the bot, the scripts and nodes to control the bot, and run a specific program on it usually involves a lot of commands run over and over again. And you’ll do it very often too. A simple bash script can save you the 15-20s it takes you run those in order, and considering that workflow might be used hundreds or even thousands of times—that’s a lot of time saved.

Other Tools

Some of these are indispensable, and others make your life easier.
Knowing how and when to use them will make your life as a developer much easier.

IDEs

A good IDE goes a long way. It’s very likely you’re a student, so please sign up for the Github Education Pack so you can some of the good stuff built by people at JetBrains.

VS Code is also a great option, and is cut out to do pretty much anything. Install the appropriate extensions for your use case.

Remote Access

Once you’re familiar with the terminal, you can ssh into a terminal from another computer. SSH-ing is very important for us as it’s our primary means of accessing the onboard computer on a bot, especially during testing.

SSH also lets you copy files to a remote computer via SCP, and also allows you to run GUI applications on the remote computer using X forwarding.
Here’s a simple guide to get started. Add the -Y flag to enable X forwarding if it’s supported and enabled.

In many test runs, the connection to the bot is sometimes unstable. When the connection drops, your SSH session will drop as well, and you’ll lose access to that terminal too. Mosh helps prevent that. It will automatically reconnect and restore your previous session so you can continue from where you left off, and is highly recommended when you’re performing remote access in the field.

VNC allows you to share a desktop screen, but is somewhat tedious to set up on a SBC ¹.
RDP is much more straightforward to use and set up. XRDP is tested and is verified to works well as a server. You can use the built in RDP client on windows, or Remmina on a Linux system.

Footnotes

1. Single Board Computer. Think Jetson Nano, or Raspberry Pi. ↩