NEW FROM THE MAKERS OF THE NUMBER ONE LINUX MAGAZINE

INSIDE

PAGES OF EXPERT
ADVICE FROM

FORMAT

PROJECTS
» SUPERCHARGE YOUR MACHINE «

llh lllll.
tr.

xx

» Mint 20 » Smart home office » Retro games »Livestreaming

» Robotic OS » Safeguard data » Escape Google Photos
 ULTIMATE

PROJECTS
Linux is the gateway to exciting open-source software,
stimulating coding projects and, of course, impressive
Raspberry Pi machinations. In Ultimate Linux Projects, we throw
those doors wide open and explore the opportunities that
Linus Torvalds' creation can offer us.
Inside, the minds behind Linux Format magazine provide their
expertise to bring you specialist tutorials, guides and advice to
help you get some extra joy from your machine. From coding
masterclasses that will tell you how to tap into weather satellites
and more, to plug-in-and-play Raspberry Pi guides, and
open-source alternatives to popular services like Google Photos
and Plex - we’re sure that if you’re a Linux fan, you’ll Find
something to obsess over here.
So, pop that kettle on, boot up your machine and get ready to
explore the possibilities that Linux has to offer.
 ULTIMATE
LINUX
PROJECTS
Future PLC Quay House, The Ambury, Bath, BAI 1UA
Ultimate Linux Projects Editorial
Editor Drew Sleep
Art Editor Efrain Hernandez-Mendoza
Compiled by Charles Ginger & Adam Markiewicz
Head of Art & Design Greg Whitaker
Editorial Director Jon White
Managing Director Grainne McKenna
Linux Format Editorial
Editor-in-chief Neil Mohr
Art editor Fraser McDermott
Production editor Katharine Davies
Croup editor-in-chief Graham Barlow
Group art director Warren Brown
Cover images
magictorch.com
Raspberry Pi is a trademark of the Raspberry Pi Foundation.
Tux credit: Larry Ewing ([email protected]) and The GIMP.

Photography
All copyrights and trademarks are recognised and respected
Advertising
Media packs are available on request
Commercial Director Clare Dove
International
Head of Print Licensing Rachel Shaw
[email protected]
www.futurecontenthub.com
Circulation
Head of Newstrade Tim Mathers
Production
Head of Production Mark Constance
Production Project Manager Matthew Eglinton
Advertising Production Manager Joanne Crosby
Digital Editions Controller Jason Hudson
Production Managers Keely Miller, Nola Cokely,
Vivienne Calvert, Fran Twentyman
Printed in the UK
Distributed by Marketforce-www.marketforce.co.uk
For enquiries, please email: [email protected]
Ultimate Linux Projects Fourth Edition (TCB6498)
© 2024 Future Publishing Limited

We are committed to only using magazine paper which is derived from responsibly managed,
certified forestry and chlorine-free manufacture. The paper in this bookazine was sourced
and produced from sustainable managed forests, conforming to strict environmental and
socioeconomic standards.

All contents © 2024 Future Publishing Limited or published under licence. All rights reserved.
No part of this magazine may be used, stored, transmitted or reproduced in any way without
the prior written permission of the publisher. Future Publishing Limited (company number
2008885) is registered in England and Wales. Registered office: Quay House, The Ambury, Bath
BAI 1UA. All information contained in this publication is for information only and is, as far as we
are aware, correct at the time of going to press. Future cannot accept any responsibility for errors
or inaccuracies in such information. You are advised to contact manufacturers and retailers
directly with regard to the price of products/services referred to in this publication. Apps and
websites mentioned in this publication are not under our control. We are not responsible for
their contents or any other changes or updates to them. This magazine is fully independent and
not affiliated in any way with the companies mentioned herein.

FUTURE Connectors.
Creators.
Experience
Makers.

Future pic is a public Chief Executive Officer Jon Steinberg

company quoted on the Non-Executive Chairman Richard Huntingford
London Stock Exchange Chief Financial Officer Sharjeel Suleman
(symbol: FUTR)
www.futureplc.com Tel +44(0)1225 442 244

Part of the

LINUX
The #1 open source mag b FORMAT
bookazine series

Regulated
Widely
Recycled
 Tenp fCl
199.6 ACpttZ,6 | Packageld6,6 CoreO.O Corel,e |Pch_wU
I I

|0.O

12000

10

1100

|O
Power rwl
package-6,0

LCJI Fan (RPMJ

47.011.0 thtnkpad.O
47.6|
46.0|

Decode signals from weather satellites ...34

OPEN-SOURCE GUIDES
Tap into space broadcasts to decode images of Earth

Customise Mint 20........................................ 8 Sharpen your desktop publishing skills... 38

Learn how to make the versatile distro your own Design newsletters, flyers and more with Scribus

Get a next-gen media server Escape Google Photos................................ 42

up and running............................................. 16 We show you some free alternatives for your albums
Install an exciting alternative to Plex
Create, edit and use custom mapping data... 50
Stress-test your CPU.................................. 20 Get started with creating your own maps with QGIS
Harness S-TUI to monitor your computer’s stats
How to easily emulate 486 PCs
Build the ultimate audiobook collection.. 22 and run DOS................................................. 54
Compile your audio collection into one easy space Relive the PC glory days with this emulation lesson

Rise of the robots.............................. 26 How to run classic distros with QEMU.... 58

Discover the fundamentals of robotic OS Feeling nostalgic? Visit some old favourites here

Build a custom digital signage system.. .30 Build a smart home office.......................... 62
Create an electronic display using Xibo Be the envy of your co-workers with our expert guide

4 | Ultimate Linux Projects

 CODING ACADEMY L RASPBERRY PI PROJECTS

Coding a Space Invaders clone..................74 Pug & Play Pi projects 100

Create some aliens... then blow them out of the sky Discover how versatile this micro-computer really is

Build a dynamic app security pipeline... .78 Take better photos with your
How to better safeguard your project Raspberry Pi......................... 110
We put the HQ Camera through its paces
Programming a Turing Machine................ 82
Put the computing father’s concept through its paces Back up and clone your Raspberry Pi 114
Save yourself some heartache and back up
Classic pseudo-3D racing road effects.... 86
It’s not quite OutRun, but it’s pretty close Turn a Pi HAT into a Magic 8-ball project 116
Harness the HAT to see into the future... sort of
How to code diagrams,
graphs and pie charts................................. 90 Raspberry Pi streaming.......... 118
Use Mermaid to visualise data Become a livestream Pi legend

Build radio walkie-talkies with Python ... 94 Create, configure and use gamepads 126
Create some communicators with micro:bits Planning some gaming? You can’t go wrong with this...

Ultimate Linux Projects | 5

Ultimate Linux Projects

CUSTOMISE

Linux Mint is fantastic, but it’s also

flexible, malleable and tweakable.
Jonni Bidwell shows you how
to truly make it yoijjcwn

inux Mint continues to go also ideal (we say) for beginners to you how to make it work with the state-of-
from strength to strength, as tinker around with. the-art Wayland display protocol.
you’ll know if you’ve already The flagship Cinnamon desktop can be If you like things slimline, we'll show you
had a play with the latest transformed not just with swishy effects how to go minimal with the featherweight
20.2 release. If not, what are you waiting and colourful themes, but with all kinds of Sway desktop, again powered by
for? Head to linuxmint.com and witness extensions, applets and desklets Wayland. Sway is based on the i3 window
the, er, Mint-ness forthwith. See, now you (collectively known as ‘spices’ in Cinnamon manager, popular with power users and
want to install it, don’t you? And that is parlance). And MATE and Xfce, the those who cannot abide desktop bloat.
just the beginning of the adventure. One desktops featured in other editions of Mint, We’ll have you doing everything in the
of the things that makes Linux Mint so are equally seasonable. But we can do terminal and tiling like a pro in no time.
cool is its potential for configurability. better than that: why not mix it up and And just so no one gets hurt, we’ll start
It’s often said (by the brains behind install a whole new desktop environment? with a handy reminder about how you can
Linux Format) that Mint is an ideal We’ll show you how to install the use Timeshift to easily undo any
beginner’s distro, and it turns out it’s outstanding KDE Plasma, we’ll even show desktop-related mishaps.

8 Ultimate Linux Projects

 Customise Mint 20

The joy or tinkering

Sort out rollbacks so you can customise Linux Mint with
impunity and immunity (to problems).
urveyors of historic issues of Linux Format Making the menu

Q
transparent and
magazine may be able to correct this, but as
pasting Sticky
far as our research can tell, the first mention Notes are but
of Linux Mint in the core magazine came in the one way of
Distrowatch column of LXF094, when Mint 2.2 was customising Mint.
released. Even back then, Mint was notable for its
out-of-the-box experience, bundling codecs, Java and
Flash plug-ins and wireless firmware, saving users
from having to shoehorn those on there using fragile
instructions from a random forum post.
That experience remains central to Mint, and though
wireless hardware is well-supported on most distros
(and no one needs Flash any more), it still shines. Right Sooner or later, though, you’re going to want to
from the Welcome screen in fact, which will invite you to change things up. It generally starts with changing your
set up backups using Timeshift, switch keyboard layouts, desktop background and Cinnamon theme. These are
or send and receive files from another machine using important, but also quite easy - easy enough that you
Warpinator. Oh, and there are minimise buttons on don't need us to tell you how to do them. What we’ll be
windows in Cinnamon - a trend that feels like it is doing is a little more earth-moving. Tectonic stuff like
quickly disappearing on other desktops, but one which installing whole new desktop environments, swish
makes many a user feel at home. display managers, maybe even switching to the Wayland
Other desktops are going full steam ahead with display protocol. And while these aren't without risk,
Client Side Decorations (CSD, which allows applications Mint's Timeshift program allows you to back up your
to draw their own titlebars). This might allow system files (much like Apple’s Time Machine or
programs to make best use of space and provide a Windows Restore Points), affording an easy way to undo
coherent interface. Or it might make them look any desktop mishaps.
inconsistent, clumsy or other pejorative terms - it Even if nothing goes wrong, it’s handy to be able to
depends your own personal preference. At any rate, roll back to a cleaner system rather than unpick
Mint’s X-apps are refreshing in their avoidance of the changes manually: see the walkthrough below. If you’ve
CSD wave, and Mint’s substantial fanbase suggests that already got Timeshift set up, take a manual snapshot
the distro’s creators are still doing all they can to keep now before pouring in all the packages over the page.
their users happy. Go on, you know it makes sense!

EASY ROLLBACKS WITH TIMESHIFT )—

Start TimeshiFt Take a Snapshot Restore a snapshot

D Fire up Timeshift and set it up to
take a couple of daily snapshots to a local
It might spring into action
immediately if the clocks align. But don't
If something goes wrong, you can
now easily restore a Snapshot by clicking
drive with plenty of space (at least 1GB worry if it doesn’t, just hit the Back Up Now the button. You might want to examine the
more than the current filesystem size). button to take an on-demand snapshot. files within first, which you can do by
Timeshift will only back-up system files by Timeshift backs up incrementally so only right-clicking. Even if things go really wrong,
default, so files in your home directory changed files are stored. Once the and Mint no longer starts, you can use
aren’t included. There are better tools for snapshot completes, add a helpful Timeshift from a live medium. Just point it
backing these up. description to help future you keep track. to the /timeshift directory.

Ultimate Linux Projects | 9

Ultimate Linux Projects

Tweaking Cinnamon
See how easy it is to make your mark on Linux Mint’s
flagship desktop environment and beyond!

f you haven’t had a nosey around your workspaces. For even more efficient workspace

O Cinnamon’s many settings, you might be

pleasantly surprised at how configurable it

about the Mint-Y theme now having fifty shades of

shifting (at the cost of some panel estate) add the
Workspace Switcher applet. If you want to disable Expo,
is. When Mint 20 was released, much ado was made
or any other applet, just click the - button. Like themes,
third-party applets can be downloaded by visiting the
colour variations (okay, it was 32), but we haven’t appropriate tab. Downloaded themes come with no
found our favourite hue yet. Check out the palette by guarantees, so they come with an uninstall option in
opening up the main menu and going to Preferences case they annoy you.
then Themes. There are some extremely pleasant new wallpapers
Dark themes are so common these days, even in Mint 20.2, and we recommend to right-click the
Windows has them, but Mint has a corresponding dark desktop and choose Change Background if you haven’t
theme for each variation. You can download whole new already perused them. But before you click there, take a
themes from the web, too; just don't expect them to all look again at that desktop context menu. In particular,
be in line with your design preferences. Hidden away in have a gander at the Add Desklets option. There aren't
the Settings section of the Themes dialog are some many pre-installed desklets, but if you want a digital
oft-overlooked options for scrollbars, including the clock or photo frame on your desktop then you’re in
option to disable overlays. luck. If you delve into the Download tab you’ll find plenty
IF you want to To customise the main panel, go to Preferences and more, including an analogue clock as well as more
experiment with
then select Applets. Now you can add all kinds of productive tools such as the Google Calendar desklet.
XFce it’s easy to
install it and all
shortcuts and widgets. For example, select the Expo The final flavour in Cinnamon’s Spices cabinet is
its apps From the applet and click the + at the bottom to add a shortcut extensions. These change the way the whole desktop
Software Manager. (via a smooth animation) to an expo-style overview of behaves. Again, there aren’t many installed by default,
but head to the Download tab and it won’t take long for
‘Wobbly Windows’ to catch your eye. Hopefully, you have
Software Manager

better luck than us with that extension. If you’re of a

Mate-desktop-environment
MATE desktop environment - full desktop with extra components
certain pedigree, you’ll remember the Desktop Cube Installing
***** 5.0
Reviews
extension too, taking your workspace switching to a
whole new level. There are other extensions which some
The MATE Desktop Environment is the continuation of GNOME 2. It provides an intuitive and attractive desktop environment using traditional metaphors for Linux
and other Unix-like operating systems.

may write off as desktop fripperies, such as being able

MATE is under active development to add support for new technologies while preserving a traditional desktop experience.

This package installs the standard set of applications that are part of the official MATE release

to tweak window decorations, shadows or transparency,

t also suggests a few non-MATE standard desktop applications like an internet browser, a mail reader and a network management applet

Details but there's no harm trying them out.

Package
Version
Size
mate-desktop-environment
2021.05.25
66.9 MB to download, 398.6 MB of disk space required
By default, desktop effects are enabled in Cinnamon,
Reviews unless your install has fallen back to software rendering
***** Se qui m'a fait venir sous Linux il y a quelque annee mamtenant
- in which case have a look at the Driver Manager for
possible remedies. These effects aren’t the sort of
in-your-face, windows catching fire, stunts of the early
‘aughts, but have been designed to help users navigate

» MUTATING MATE AND EXTENDING XFCE

But what about Mint's other flavours, pop up in the theming options. If you’re want the core applications. These will all
surely they can be customised too? using Mint MATE or Xfce, but desire to add a session to your login screen, so
Indeed they can. You’ll find a similar try Cinnamon, then that’s easy. The you can choose your desktop from the
arrangement with themes, extensions standard desktop is available through menu to the right of your username.
and effects in both of these. All three of the mint-meta-cinnamon package, or Speaking of the login screen, you can
the Mint desktops are ultimately based you can get a minimal edition via tweak that too. Just go to Administration
on GTK3, so the fundamental desktop cinnamon-core. Conversely, if you are > Login Window from the main menu.
elements can be themed with a standard using Cinnamon and want to try Xfce or Such cosmetic tweaking can happen
GTK theme from the likes of https:// MATE, hit up the mint-meta-xfce and even earlier in the boot process, GRUB
www.gnome-look.org/browse?cat=135. mint-meta-mate (rolls off the tongue can be themed and so too can the
Extract any themes you like into your nicely that one) packages. Again, there Plymouth splash screen (https://www.
-/.themes directory, and they should are minimal packages too if you only gnome-look.org/browse?cat=108).

10 | Ultimate Linux Projects

 Customise Mint 20

the desktop. It’s reassuring (sometimes) to see where results. You’ll also find Flatpaks of Spotify
applications were called into being from, and where they and Steam so you can queue up your Rush
disappear to when they minimise. Be that as it may, you playlist and play Space Invaders like it’s the
might want to turn these off, and this you can easily do olde days.
by from the Effects option in the Preferences menu. If you do want Snaps, perhaps to get the
Besides eschewing the Gnome desktop, Mint has latest version of Blender or the PyCharm IDE,
made a couple of other choices that fly in the face of that's easy to sort out from the Terminal. We first
desktop Ubuntu. One is the absence of the Snap remove the file that prevents the Snap daemon from
daemon, which prevents installing packages from being installed, and then install it with apt:
Canonical’s Snapcraft store. Another is that there’s no $ sudo rm /etc/apt/prefs.d/nosnap.pref
Wayland support (at the time of writing) in either $ sudo apt install snapd
Cinnamon, Xfce or MATE, the three officially supported Snaps can now be searched and installed from the
Mint desktops. You might not care about next-gen, command line. You can also browse what’s on offer at
cross-distro packaging systems or banishing old X.org https://snapcraft.io, but for a complete GUI experience
from your machine. Indeed, plenty in the Linux Mint
community seem to share this sentiment. But there’s
good stuff in the Snap store, so let’s look now at how we USEFUL DESKTOP EFFECTS
might enable that now. Plus, Wayland is pretty
“These effects aren’t the sort of

I
impressive now, so we’ll look at that over the page, once
we have a desktop that supports it.
When Mint 20 was released sans Snap support, an in-your-face, windows catching fire,
immediate consequence was that there was no way to
install the Chromium web browser, since Ubuntu (20.04 stunts of the early aughts.”
and later) now only packages it as a Snap. We think
more people should use Firefox, and if our user agent you'll want to install the Snap Store too. Appropriately,
tracking on linuxformat.com is anything to go by, it it’s available as a Snap and it can be yours with:
seems they are. But it sets a potentially worrying $ sudo snapd install snap-store
precedent; if Chromium was to be abandoned by One easy and surefire way to turn heads (or
Ubuntu’s DEB packagers, then perhaps other popular whatever is the virtual equivalent) is to bling your
applications might go the same way. We don’t think you terminal with a little transparency. Not only does this
should worry, as so far there’s been no sign of that. look pleasant, but if you arrange your windows correctly,
Team Mint now packages its own Chromium DEB and get into the habit of arranging them as such, it can
package, so if you’re craving a hint of Google in your be pretty useful as well. Endowed with X-ray vision, one
browsing then fetch it from the Mint App Store or with a can make out both the terminal itself and the web
good ol’ fashioned apt incantation at the command line. browser or whatever substrata lay below this.
We've seen that software is also available as To enable the opulent opacity effect in the Terminal,
Flatpaks, and that this is enables a wealth of software to go to Edit > Preferences then select the current profile
be installed from outside the Ubuntu (and Mint) (it will be named Unnamed Profile if you haven’t given
repositories. Flatpak is actually enabled out of the box it), untick the setting about system theme transparency,
on Linux Mint, and if you look carefully you’ll find some then tick the box above it. Play with the slider to find the
Flatpak applications in the Software Manager. For optimum opacity. Or, if you’d rather more drastic
example, if you want the latest version of GIMP, the changes look over the page, in which we install the
Flatpak edition is probably the second one in the search high-fidelity KDE Plasma desktop environment.

We have fond
memories of
wobbly windows
confusing our
graphics drivers
so its good to see
this still lives on.

Ultimate Linux Projects 111

Ultimate Linux Projects

Installing KDE Plasma

Transform your desktop with the smooth, svelte, sumptuous experience
that is KDE Plasma and go complete next-gen with the Wayland too!

here’s no official Linux Mint KDE edition

O these days, but that doesn’t mean Mint users

should miss out on the wonderful experience
that is KDE Plasma. It’s modern, but still has a
traditional applications menu. It’s incredibly polished,
but is nowhere near the resource hog it used to be.
Oh, and its Dolphin file manager is a joy to work with,
especially if you’re finding Nemo a little too simplistic.
Be that as it may, installing a new desktop
environment comes with its own consequences, and
it’s good to be aware of these before you blame us for
ruining your system.
Firstly, there’s the disk space hit. The smallest KDE
Plasma metapackage provides a minimal desktop, but
according to the screenshot it pulls in some 850MB of
dependencies in 446 packages. If you go for the full-fat For some reason we Found this SDDM theme much more relaxing than
edition, with all the applications from the KDE
ecosystem, that will cost you close to 3GB. Next is the
I the austere default.

duplication of core utilities such as text editors, media Both display managers work with all major Linux
players and screenshot tools. These all start to crowd desktop environments (and lightweight window
your application menus, and if you use, say, KDE’s managers), so which you choose is a matter of personal
Dolphin file manager in Cinnamon, it looks a bit odd. preference - or whichever you can find the prettiest
Finally, it’s sometimes hard for apt to completely themes for. The default SDDM theme is probably not
uninstall a desktop. It's likewise hard to repair a broken most people’s idea of pretty, but once you’re logged in
desktop after you attempt to clear out packages it’s easy to change this from Administration > Login
manually. So don’t do that; instead, try things out within Screen (SDDM). For some reason, perhaps an attempt
a virtual machine first, or make use of Timeshift io at irony, we found ourselves using a Windows-like login
restore things to a known good state (as we theme. Never mind that, you’ve probably just found
demonstrated earlier). yourself immersed in the wonderful world of KDE
Having installed (at least) the Plasma desktop we can Plasma. Behold the cool Breeze theme, marvel at the
opt to change the display manager from the polish and feel at home with the knowledge that all your
Mint-themed LightDM to the Qt-powered SDDM favourite Mint tooling is just a click away.
(Simple Desktop Display Manager). If you KDE 4, now largely retired, received occasional
installed from the command line this will be criticism for being too configurable. In part, this was fair.
offered to you, and if you didn’t you can get Every widget (and there were a lot of widgets) could be
to the configuration by running; configured, a clumsy edit mode gave them a handle
$ sudo dpkg-reconfigure lightdm about which they could be rotated or stretched, and one
was sometimes left wondering what the point of all this
Q kde-plasma
was. Worse, successive iterations of KDE 4 got very good
Kde-plasma-desktop
at hiding all kinds of key options just when you thought
KDE Plasma Desktop and minimal set of applications
irfrtrtrti 1.0
T Rcvtews
instal
you’d got a handle on where they ought to be. That
version of KDE also faced criticism for being something
lxf(3>mintxxii: -
of a resource hog, and shipping with all kinds of

a
File Edit View Search Terminal

lxf(8>mintxxii: -
Tabs Help

X
graphical frippery enabled. Modest machines would
qml-module-qtquick-templates? probably have been fine with this, but as the graphics
qml-module-qtquick-virtualkeyboard
qml-module-qtquick-window? qml-module-qtquick? driver ecosystem of the era was far more fragile back
qml-module-ubuntu-onlineaccounts qtchooser
qtvirtualkeyboard-plugin qtwayland5 sddm
sddm-theme-debian-maui signon-plugin-oauth? socat
then, hardware acceleration was not something that
Details software-properties-common software-properties-qt
sonnet-plugins sshfs systemsettings
someone could count upon.
Package kde-plasma-desktop
S:104ubuntu4
212.4 MB to download, 867.7 MB of disk space required
unattended-upgrades user-manager vlc-data
vlc-plugin-base vlc-plugin-video-output xsettingsd
You’ll be pleased to hear, then, that KDE 5 (or KDE
to upgrade, 446 to newly install, 0 to remove and 0 not
Reviews
to upgrade. Plasma 5 as the desktop prefers to be called) is a much
Very pretty, but locked me out of updating and even uninstalling, Need to get 212 MB of archives.
Hartley
After this operation, 868 MB of additional disk space will sleeker animal. In our tests it did use up a tiny bit more
2015.09.27
be used.
[Do you want to continue? [Y/n] | memory than Cinnamon, and slightly more than Xfce
(l) ® □ A 17*4
and MATE, but what’s a hundred or so megabytes
The lightest suite of KDE applications weighs in at around 850MB, but it is quite outstanding. between friends? It makes not one iota of difference

12 Ultimate Linux Projects

 Customise Mint 20

once you start memory­

Newly installed apps appear in bold,
slayer Chromium. Plasma is
and lots of them begin with K.
certainly configurable, but in
Computer
a way that is not
overbearing. Take the
default, medium-weight
launcher menu (at the All Applications O Backup Tool

bottom-left, as it should be). r'X Accessories

r-w Discover
Right-click it and select Graphics Software Manager
Disk Usage Analyser
Show Alternatives. You will A Internet
Q kde-plasma
Dolphin
see it can be swapped for a Kde-plasma-desktop
■= Office
J Driver Manager KDE Plasma Desktop and minimal set of applications
modern, full-screen 1.0
Sound & Video 1 Reviews
launcher (sort of like
Gnome) or a more classic KSysGuard

cascading menu design. n KWalletManager

KDE comes with its own Places

U Login Window
£| Recent Files
graphical application store P Logs

called Discover (one of few

Konsole
KDE apps not to capitalise Command line access

on any opportunity for an 0 □ A 17:52

unnecessary letter K). You’ll
find this already pinned to
the favourites menu, and you might also prefer it to
Mint’s native Software Manager. One thing you'll want to » LXQT
do is sort out Flatpak support in Discover. Fire up a
terminal (try the Konsole application) and run: If you’re enamoured with the Qt toolkit, but crave a
$ sudo apt install plasma-discover-backend-flatpak lighter, nimbler desktop, you should look no further V. .
You can now, after restarting Discover, browse than LXQt. That’s what powers the current LTS edition of
FlatHub (or any other Flatpak repos) by adding them via Lubuntu, and it’s what could power your new Livingston-
the Settings option at the bottom right. Just click Show seagull-like Mint desktop. Over the page, we’ll go pretty
Contents to the right of the repo name. Flatpak is a much as far as we can go without abandoning the GUI altogether. But
much more decentralised idea than Snaps; anyone can if you want something a little more user-friendly and less gymnastic
set up their own Flatpak repository, but the only Snap keyboard shortcut-orientated, LXQt may well be for you.
outlet in town is Canonical's Snapcraft. Both forms are LXQt is the spiritual successor to the GTK2-powered LXDE desktop
potentially risky though, since there’s little to stop a that used to power Lubuntu and Raspbian. Rather than move to
scoundrel uploading a rogue Flatpak or Snap. And while GTK3, which at the time was seen as bloated, LXDE teamed up with
both have some sandboxing capabilities we have no the RazorQt effort and the result is LXQt. You can install it with a
compunction to endorse the downloading of random simple sudo apt install Ixqt openbox. If you haven’t already installed
binaries. Popular applications are easy to spot on KDE this will pull in around 400MB of dependencies, but if you’ve
FlatHub and common Snap packages have a already installed Qt et al, the footprint will be much lighter. Don’t
reassuring ‘Verified’ badge. forget to take a snapshot first, though.
We mentioned that Wayland isn't explicitly supported When you start LXQt you’ll be prompted to choose a window
by any of the Mint desktops, but that is changing. In the manager. By default it uses openbox, but it can use Cinnamon’s
latest MATE release, a great deal of the desktop now Mutter, Xfce's Xfwm4 or, if you really want to make it pretty, Kwin from
works natively with Wayland, so if you switch the Marco Plasma. Openbox is by far the lightest, and for non-scientific
window manager for Compton then you’re well on your comparison purposes a plain LXQt/Openbox session occupied
way to display protocol future. Xfce 4.18 plans to around 500MB of our memories.
introduce support, though that may be a long way off. So
it’s really desktops, rather than distros, that enable
Computer
Wayland - and as luck would have it KDE Plasma has
support built in to its Kwin window manager. There’s just
xf
a couple of packages to pull in to bring it to life: LXQt Section Sortings a

Basic Settings

$ sudo apt install plasma-workspace-wayland Basic

Window Manager

Network Settings openbox - Search....

Now if you log out, a new session called Plasma LXQt Modules
Default
(Wayland) will be available from the menu. The Accessories

Graphics
Applicationv
v
Desktop
Global Keyboard Shortcuts
Running •
Running
v
Plasma experience on Wayland has come a long way this Internet
User
Notification Daemon
Panel
PolicyKit Handler
Running
Running
Running
Office Directories

year. We’re told it even works with the proprietary Sound & Video
■j Power Management

Start
Running -

Stop
Autostart
Nvidia driver now. System Tools

Preferences
Leave Session

Environment
One thing that might strike you as jarring about About LXOt (Advanced)
v
v Ask for confirmation to leave session

Lock screen before suspendlng/hlbernatlng

Leave
Plasma in general is that your session is Lock Screen
Suspcnd/hibcmatc after lock delay: 0 ms

automatically saved. If you prefer to start each time Search...

B , LXOt Session Settings

Cl Reset x Close

1 2 P ■ 4 11:14
C N S GB

without all those stray terminals and whatever else

LXQt might be just be the lightest desktop environment that still provides all the Friendly
you left open, head over to Settings > Startup and
Shutdown > Desktop Session. I
GUI crutches we've come to rely on.

Ultimate Linux Projects 113

Ultimate Linux Projects

Embrace minimality and learn some keyboard

gymnastics with the featherweight Sway desktop.

ne of our new favourite Ubuntu-derivatives is familiar with S3, you

Regolith Linux. It’s fairly unique in its choice will quickly get the
of the ultra-light i3 tiling window manager. hang of Sway; most of
Tiling window managers take some getting used to, the default keys are the
and also a whole lot of configuration, but Regolith same, and you can even use
ships with remarkably sane defaults and your own i3status scripts. In fact, you should be able to
easy-to-learn keyboard shortcuts (i3 is very much use your i3config file without modifications. Sway is in
keyboard- driven, but converts say they never looked the Ubuntu repos, but it’s an old version from
back). Also, it still has all of the GNOME January 2020. It would take some work of the compiling
infrastructure and applications for managing variety to get the latest version working, so let’s just
sessions and settings, so all of your system install the repo version to dip our toes in:
administration can be carried out with familiar GUI $ sudo apt install sway
apps. We’re big fans of Pop!_OS too, and in particular As before, the login screen should now have a Sway
session. Dive into it and you should see the rather
fetching Sway logo and top bar. Try anything with the
WINDOW TILING IS AN ART mouse (besides moving the pointer) and you’ll realise
that you’re not in Cinnamon any more - nothing reacts
“To make the most of window tiling, to being clicked, double-clicked, dragged or any such
thing. Sway is all about keyboard commands: try
much like an Etch A Sketch you’ll want pressing Super (the brand-independent name for the
Windows key) and Enter. A terminal should spring into
to use a combination of horizontal life, so now you can at least practise your Bash
scripting for a while.
and vertical arrangements.” Now try pressing Super+2; the terminal will
disappear, but not really - cast your eye to the top-left
and you’ll see we've just moved to a new virtual desktop.
its COSMIC (Computer Operating System Main If you try to open another one with Super+3, you’ll see
Interface Components) desktop. This features a tiling that this doesn’t happen. We didn’t need a third desktop
mode that, while not having the diminutive resource because we hadn’t opened anything on our second, so
footprint of i3, offers users a gentle introduction to Sway quietly renamed the previous workspace to 3.
the joy and efficiency of keyboard shortcuts and Go back to workspace 1 and hit Super+Enter to open
mouse gestures in harmony. another terminal. Now you can see what tiling window
There’s no reason we shouldn’t have these sorts of managers are all about. The first terminal, that was
things in Mint too; the i3 window manager is in the occupying the whole desktop, obsequiously squishes
Ubuntu repositories. But we’re going to try something over to the left, making room for a new terminal to the
else. Sway is a lightweight window manager inspired right. If you like, you can start any program you want
heavily by S3, except that it is for Wayland. If you are from either of these terminals (notice the focus follows
2021-09-01 11:43:12 c
the mouse so you don’t need to click in either one).
neofetch
lxf@mintxxn: -
-[0 2 3 4]/
But Sway also has its own application launcher, after
• •• _ ••••• ••• IxfOnintxxii
. Itttttttlftttttt .
ftftl Fttff
.Ittti:.
US; Linux Mint 20.2 x86_64
Ikct: KW/QEMJ (Standard PC (Q35 * ICH3Z 2009) pc-g35-5.1)
hir«
Ixiot/
rak-OR/
a fashion. Hit Super+D and you’ll see some commands
4W M — tttHHHHtHWmi.ltM- Kernel: 5.4.0-81-generic dev/
♦FfW.rTi
♦rWH.iVTi
.rrm...................... nrrTurwu
.m.
. m. m. . nn
«nm»Fvvi»
Hnm.jWwi,
1 day, 2 hours. 21 Rins
2135 (dpkg)
SJirll; bash 5.0.17
etc/
Ikw/ in lexicographical order (some beginning with numbers,
liW
•rm.rfni
.rm.mii
•FTWi.rrm
.m.
.m.
. m.
nn
m
m
.m.
.nn.
. m.
iivu vwi»
rrrTi.fwi.
nnnnrtii.
Rr-
k
*
: sway
i.<i: 1024x768

■: Mint-Y [GTK3]
ITiba
libMP
lihx3»
and several beginning with the letter A, probably). Start
♦nWl.rTTTi .WI. . rTi. rTTTI.FWI. Iccns: Mint-Y [GTK3] lostHatid/
trwttw
•rm. rm.
ummtiin
*
-mHWi:
.rrr.rni
.fTTTI.refU
Ictwiiv,!: rxvt-unicode
LH1: Intel i7-7500U (4) 8 2.903GHz
U ': 00:01.0 Red Hat, Inc. QXL paravirttal graphic card
Media/
Mlt/
opt/
typing the first few characters of firefox and you’ll see
iiimiiiiiiiiti .ttttt-' 383MiB / 1987H1B p-oc/
•
*■ rTYTi
* ••♦• •••• ••
• IHIIIIIIIIIII ‘
'' a a a a a * *
nrm 9
a
loot/
nai/
sbinP
this list get rapidly smaller. Press Enter when firefox is
intxxii:
lxfft
*
S free -h
srv/
sys/ highlighted in blue to start it.
total used free shared buff/cache available 8/25 [0:] 2021-07-03 13:24 lrwxr-xr-x 0B
Hen:
Swap:
lxfft»intxxii:
*$
1.9Ci
l.lGi
0
357M1
7.0Mi
384M1
l.OGi
7.CMi 1.2Gi 1.4Gi
If you already had a couple of windows open, things
Ta Start Page - Linux Mint x +
by now will probably be getting a little cramped. You
C Q fl https.7/www.linuxmint.com/start/uma/ (?)
could close one of them (either with a Ctrl+D or
Latest news from the Linux Mint blog

Monthly News - Ju|y 202),

traditionally with the Close button). But now is also a
good time to introduce window resizing. With at least
Sdt. 31 Jul 2021 11:57.47 *0000

Many thanks to all our donors, sponsors and partners and all the
people who are involved in helping our project and our community.
We received 380 donations in June and more than 500 in July Not
only do your donations help us they constantly remind us you enjoy two windows open, hit Super+R to enter resize mode.
our work. On top of your feedback [...]

You’ll see this indicated in the top-left of the status bar.

Howj.QUQgra.de to LLnux_Mint_20;2
Thu. M M 2(12113 3130 *0000
Now you can use the H and L keys (like Vi) to make the
The rxvt-unicode terminal isn’t that pretty in its default state, but we’re sure you can make it so. active window (and remember you can change this by

14 | Ultimate Linux Projects

 Customise Mint 20

hovering the mouse over a new window) wider or

narrower. That covers one dimension. Press Esc to exit
resize mode and the hit Super+E while focused on the
leftmost window. Bam! Vertical windows. Be careful of
case sensitivity here, because Super+Shift+E (often
abbreviated to Super+E) is the shortcut to exit Sway.
In order to make the most of window tiling, much like
an Etch A Sketch you’ll want to get the hang of using a
combination of horizontal and vertical arrangements.
This seems straightforward at first, but there are a few
subtleties that are best experienced for yourself. Before,
the Super+E shortcut operated on several windows at
once and tiled them uniformly. They were grouped
together along a common dimension. But if you hit
Super+V on one of them, then hit Super+Enter to open
another terminal (or open any other application for that
matter), it will open in the other orientation. In this way a minimal desktop aesthetic, one has to use lighter You'll need to use
you’ll see that Super+E and Super+V act as orientation applications too. This isn’t quite the place to show how shutdown From the
login screen with
triggers, and you’ll notice that the former highlights the much stuff you can run from the terminal, but you
Sway; a nimble
right edge of window, and the latter highlights the lower should check out the nnn file manager, the w3m web Super+ShiFt+E will
edge, giving a hint as to how the next window will spawn. browser, mpv the video player and the ncmpcpp get you there.
Sway’s default configuration file can be found at front-end to the mpd music player. What we will
/etc/sway/config, but rather than edit this directly, demonstrate is how to swap the default Gnome
copy it to ~/.config/sway/config to make personal terminal for something a little lighter.
changes. For example, the line: You might have noticed when we installed Sway that
output * bg /usr/share/... it pulled in a package called Suckless Tools. Suckless
sets the background on all displays. You can change (https://suckless.org) is as much a state of mind as a
this, or indeed set a custom background for each software suite, and encompasses a range of ultra
display, by modifying this. The output directive actually low-resource utilities and daemons. These include the
controls all sorts of things fundamentally related to the dwm window manager, the suckless terminal and a few
display. For example, if you’re running Sway on a virtual more. You can read more about them in LXF254 and
machine, putting the final touches to the overdue cover they’re actually of limited use for us here because
feature, you’ll probably need to add a line of the form: most of them don't cater to
output Virtual_l resolution 1280x720 These get installed
in order to make your screen grabs have the correct primarily for the sake of
aspect ratio. You can get a list of display names and the dmenu program which
modes by running: (through Xwayland) provides
$ swaymsg -t get_outputs the handy Super+D
Sway and i3 are famed for their low memory launcher we met earlier.
footprints. But in order to keep these low, and maintain Have fun tweaking! E3

» KERNEL UPDATES
Being a derivative of the Long Term Support release shouldn't install the HWE stack unless something is
of Ubuntu, Mint by default uses the same 5.4 series broken, but it’s a safer bet than being seduced by a
kernel featured there. Don’t be put off by the fact stock kernel with a bigger number.
that the current branch of the kernel is numbered Desktop Ubuntu now gets the HWE kernels by
5.13, since Canonical backports all manner of default, and so it would seem does Pop!_OS, but not
features and fixes to the Ubuntu kernel. Also the 5.4 Mint. That's okay, because it’s easy to install:
kernel is itself a longterm branch (as you’ll see from $ sudo apt install --install-recommends linux-
kernel.org). It has always been possible, but not generic-hwe-20.04
recommended, to use mainline kernels in Ubuntu, If you are using the Nvidia proprietary driver
but a better way is to activate the hardware this is not enough, since you’ll need corresponding
enablement HWE stack. proprietary modules too. These you can get with:
This will give you a newer kernel (which recently $ sudo apt install --install-recommends linux-
bumped from 5.8 to 5.11) which has undergone modules-nvidia-NNN-generic-hwe-20.04
some Canonical patching and testing, as well as a where NNN is the version of Nvidia drivers required
refreshed graphics stack (new versions ofX.org and by your card. You can find this out by running
libdrm and what have you). There is a low-visibility ubuntu-drivers list. Be aware that lots of users have
Edge edition of Mint (nothing to do with the web encountered problems with the 5.8 HWE stack
browser) but it’s definitely not worth reinstalling just (sound, graphics, virtualisation) and the same is
to get a newer kernel. Likewise, you probably likely to be true for this one.

Ultimate Linux Projects 115

Ultimate Linux Projects

JELLYFIN
Credit: https://jellyFin.org

Get a next-gen media

server up and running
Nick Peers reveals how to install and set up a completely open source - but
brilliant - alternative to Plex, the streaming media platform.

r iant the best features of Plex and Emby without introduced features for watching the same server

w
L______ J
the cost (or closed-source components)? Then
take a look at Jellyfin (https:Z^jellyfin.org),
content in real-time with far-flung friends and family.
Jellyfin quickly followed suit with SyncPIay, available to
which has come on leaps and bounds from a simple anyone who’s logged into your server.
fork of the last open-source Emby release (3.5). While While it’s true that Jellyfin isn’t quite as slick in terms
*OUR
Jellyfin still has a similar feel to Emby, it’s carving out its of clients as its better-known siblings, it still covers most
EXPERT own unique niche in the media server marketplace. bases (see https:Z^jellyfin.org/clients for a full list).
Nick Peers It may be free, but that doesn’t mean you'll miss out What it lacks in polish is more than made up by its
is shifting his on features. On the contrary, Jellyfin includes features customisability, and unlike Plex and Emby it doesn’t
allegiance from found only behind Plex and Emby’s respective paywalls: require cloud-based authentication to unlock all its
Plex to Jellyfin, hardware GPU transcoding for one, full support for live features, making it perfect for those wanting a server
and not just TV (including DVR facilities) for another. exclusively for use over their own network. (You can still
because it’s free! It's even keeping up with some of the newer features open up Jellyfin for remote access though - see the box
added to its rivals. Early in lockdown, Plex and Emby for details, below right.)

NAVIGATING JELLYFIN’S MEDIA LIBRARIES Getting started

A Home You can install Jellyfin natively or through Docker - visit
Media https://jellyfin.org/downloads for a complete set of
instructions. We recommend a native install if you plan
■l Collections

O Movies

O TV • Comedy (Intf)
to make use of Jellyfin’s hardware-transcoding features.
O tv Comedy (uk) Click the Stable link to reveal the full commands, or save
O IV • Documentaries
time if you’re running Ubuntu LTS (16.04 or later) by
□ TV • OtdHM The Empire Strikes Back
O IV • Genre
4 1980 122 mins | GB-U | *8.7 #94 Endsat12;59
issuing the following commands:
O TV Khls Genres Adventure. Action. Science Fiction $ sudo apt install apt-transport-https
Director Irvin Kershner

Admin
Welters George Lucas, Leigh Brackett. Lawrence Kasdan
$ wget -O - https://repo.jellyfin.org/jellyfin_team.gpg.
key | sudo apt-key add -
!■ Dashboard Version: Blu-ray Version

video lUBOp 11204 SDR

✓ Metadata Audio Cnglish - AAC • 7 ch

User
--*
\ I • V 1 ( IV 1CW
■ off
$ sudo tee /etc/apt/sources.list.d/jellyfin.list
O settings
1 ne Aavei [ English - Default_____________________________________

The epic saga continues as Luke Skywalker, in hopes of defeating the evil Galactic Empire, learns the ways of the Jedi from aging master Yoda But
$ sudo apt update | sudo apt install jellyfin
Once installed, Jellyfin will set itself up a service, and
Darth Vader more determined (han ever Io capture lukr. Meanwhile, rebel tender Princess I ria. cocky Han Solo. Chrwl
*.icca. and droids C 3PO and
3 Sign Out
R2-D2 ore thrown Into various stages of capture, betrayal and despair.

will start running in the background. You can configure it

Tags: rebel, android. asteroid, spacecraft, space battle, wuwr.torni, space colony, lightsaber, jedl. rrbefion, the force. •4MCC opera, vtorrntrociper, wookle, feet master,
jedi training, droid

IMDb. TheMovieDb. TheMovleDb. Trakt

Cast & Crew from your web browser by going to http://127.0.0.1:8096

- if you installed it on a server, you can access it
remotely via http:/7192.168.x.y:8096 (where 192.168.x.y
Slide-out menu Playback controls
is Jellyfin server’s internal IP address).

O Click here to quickly jump between

libraries - including Jellyfin’s Collections,
□ Click here to play the movie, watch the
trailer, plus other tasks - for example, adding it
The first-run wizard will appear. After choosing a
username and strong password you'll be prompted to
which can be manually curated or created to a playlist or editing its metadata. set up your first media library. The process is the same
automatically via a plugin.
here as it is when adding further libraries via Jellyfin’s
Access multiple versions
Admin tools Rip different versions - say extended main Dashboard, so is worth covering.

0 The Dashboard is where you go to

monitor and administer the Jellyfin server.
versus theatrical release - of the same film and
choose which one to watch. Set up media libraries
First, choose your content type: Movies, Music, TV
Sharing options Choose audio and subtitle tracks

0 Click here to set up SyncPIay to watch

with friends and family, cast to another device
If your movie contains multiple audio
tracks - as well as subtitles - you can select
Shows, Books, Photos, Music Videos and the catch-all
Mixed Content are all available. Name your library, then
or search your library. which ones you want from these menus. click + to select a folder containing that library’s

16 | Ultimate Linux Projects

 Get a next-gen media server up and running IUTORIALS

content. While you can add multiple folders to a single -> C

* 0 ® ft 23 http$.//jeUyfn. support-pcs.co.uk veb/index htrnllSI/dirWi :?id-eOeln ••• E) & Search tfP

library, it’s best to start with just one. After it’s been fully <- A =

scanned, move on to your second folder, and so on.

Beneath the folders are your library settings, which
vary according to the type of content you’ve chosen.
The key choice here is which ‘scrapers’ you want Jellyfin Brooklyn Nine-Nine
Season 5
to use to populate your library with metadata including
artwork - thetvdb.com is no longer available by default,
1. I he Big House (1)

but you can add it as an option later via the plugins 21 mins ★ 8.5 rndsatlVPfl

Jake and Rosa assimilate to their new lives behind bars, but both are

repository (see the final Quick Tip). coping in very different ways. joke bonds with his cellmate, Caleb, and is
forced to join a prison gang led by notorious inmate Romero, in order to
gain his protection. Meanwhile, in the women s prison, Rosa puts Holt and

A quick note about filenames: Jellyfin broadly follows lerry to the test by having them complete outrageous favors for her. Back
in the precinct. Amy and Charles arc doing all they can to exonerate theif
colleagues

the same naming convention favoured by Plex and

Emby, but there are some quirks with organising movie 2. The Rig llnuse (2)

21 mins ★ 8.4 Ends at 11:28

extras - see the Server>Media section of the online When thr warden ata Jake to Investigate Romero's drug smuggling
operation, Jake and Caleb find themselves caught between the loyalty Jake
has sworn to both of them. Meanwhile, Amy Is offered a deal by a local

Jellyfin documentation (https:Z^jellyfin.org/docs/ mobster who claims he can prove that I lawkins Is guilty, but I lolt and the

general/quick-start.html) for details.

Beneath the scrapers is a section that makes it content start to appear relatively quickly, but it may take Name your media
Files correctly and
possible for you to choose how metadata is stored. several hours before each library is fully populated.
Jellyfin will scrape’
Beware of ticking ‘Nfo’ and ‘Save artwork into media online databases
folders’ - this requires write-access to your media Complete your setup to provide you with
folders, which isn’t a given. Leaving them unticked You’ll need to confirm your default metadata language all the necessary
stores the information within a central database. and country settings, and then click Next. The next step metadata.

Flick the ‘Show advanced settings' switch at the top confirms whether you want to open remote access to
to reveal even more options. These include pulling in your server (for streaming content over the internet) -
artwork and whether you want to ‘download images in enabled by default - and whether you’d like to attempt QUICK TIP
advance’, which basically means downloading them UPNP port mapping. If UPNP is disabled on your router,
when media is imported into your library instead you'll need to manually forward ports to your server’s IP Quick Connect
speeds up login
of when requested by a Jellyfin app. address. This form of streaming is insecure - for a
From selected
Once you’ve configured your library, click OK, then better solution, disable the option and follow the guide
devices. Log
repeat for any other media libraries you’d like to in the box (below).
into your
configure now (you can add these later if you’re Once configured, click Next followed by Finish and account and go
impatient to get going). Click Next when done. Note Jellyfin will start scanning your media folders for content to Dashboard>
that, depending on the size of your media folders, in the background. Quick Connect
setting up each library can take some time. You’ll see to enable it.

= A Jdhjhn Home favourites 0 S3 Qj

Take the tour Then click your
You’ll find yourself at the main Jellyfin screen, which proFile photo
My Media
offers you a way to both manage and consume your and choose
Quick Connect
media from your web browser. The main screen is split
Followed by
into different levels: at the top are shortcuts to your
Activate. Return
Next Up > media libraries, followed by ‘Continue Watching’ (if to your client
you’re halfway through any movies or shows, they’ll and tap Use
appear here, ready to resume where you left off) and Quick Connect
‘Next Up’, which is Jellyfin's equivalent of Plex’s On Deck
Fnnqr

to generate the
view for working your way through series. Beneath this code you need.
you'll see the latest additions to each library.
JellyFin’s home screen puts all your media within easy reach. Its Next If you configure Jellyfin with live TV (see the box
I Up Feature tracks your progress through favourite TV series. overleaf), this will also appear as an option on the main

» SET UP SECURE REMOTE ACCESS

Configuring Jellyfin to enable friends and to your own public IP address, which is under Advanced. Tick Enable HTTPS and
family to stream remotely is more best done using a tool like ddclient change the port number to that which
complicated than in Plex or Emby, but the (https:Z<ddcl ient.net/) or NolPDUC you chose when following Cognicom’s
upside is there’s no cloud-based (www.noip.com/download?page=linux). guide. Click Save. Now try logging on to
authentication involved. Insecure Once these are set up, security is the server through your web browser
connections are easy to set up, but you achieved via a reverse proxy working in using the following syntax, substituting
should make your connection encrypted conjunction with an SSL certificate - you 1337 with your chosen port: https:Z<
and secure for maximum privacy. can kill two birds with one stone using subdomain.domain.com:1337.
We recommend you set up a Caddy 2, following Cognicom’s guide If all is well, you should see Jellyfin
subdomain on an existing domain you (https:Z<forum.jellyfin.org/t/simpleton- throw up the login screen. Now, not only
own or sign up for a free dynamic guide-for-remote-access/2707/2). can friends and family log on to their own
hostname (free ones are available from After following the guide, open the user accounts remotely, the SyncPIay
www.noip.com). You’ll need to point this Jellyfin Dashboard and select Networking feature should work correctly too.

Ultimate Linux Projects 117

Ultimate Linux Projects

screen. All of this is customisable by clicking your profile When browsing a library you’ll see three buttons -
QUICK TIP icon in the top right-hand corner of the screen and use these to change the way content is displayed from a
choosing Home from the pop-up menu. choice of six, including banner, list and the default
One area that
JellyFin is still Browsing any of these views is self-explanatory, with poster view. The A-Z button enables you to sort your
lacking in is, plenty of on-screen navigation aids. At the top are a library differently - for example, by IMDb rating or
up-to-date range of library views, from ‘Suggestions’ to ‘Genres’. release date. The final button is for filtering the view,
documentation. Two views are customisable: Favourites will appear as with options including genres, parental ratings and
IF you run into an option on the home screen for any favourite items whether or not the show has been watched or not.
problems, you roll over and click the heart icon to highlight. Jellyfin Select a specific movie, television episode or other
use its reddit also supports Collections, which makes it possible to piece of media to go to its own page. The annotation
channel (www.
manually group related items together, whether it’s all (see the start of this article) reveals what controls you’ll
reddit.eom/r/
the James Bond or Star Trek movies, or films featuring a find on these pages.
jellyfin/J to
search For
favourite actor like Tom Hanks.
answers - or
Fix metadata
post your own
<- ft = TV • Drama It’s a good idea to browse your libraries after adding
question iF them, because Jellyfin is more prone than its rivals to
Latest Episodes
needed. Also incorrectly identifying shows and movies - particularly
check out those whose name is shared with other releases. When
https:?/Forum. you spot an error, roll your mouse over the incorrectly
Ann* KAf«ntn« (2000)

jellyFin.org/ - labelled item, click the vertical ellipsis button that

although now
appears and select Identify.
closed, you may
This will bring up a search tool - you can search by
Find additional
help here.
title and/or year (which should resolve most issues
Next Up where an identically titled show or movie from a
You can access your Jellyfin server from a range of clients - Jellyfin different year has been selected), but if this doesn’t
I Media Player works on Linux and is similar to Plex’s desktop client. yield a result, go to www.imdb.com or www.thetvdb.com
to manually locate your show and grab its ID. Enter this
into the relevant search field and you’re guaranteed to
» SET UP LIVE TV get the correct match when you click Search.
Jellyfin takes a little while to update the metadata -
If you have a HDHomeRun network TV tuner device, then adding live so don’t be surprised if the correct artwork isn’t appear
TV and DVR capabilities to Jellyfin - accessible through any client, and immediately. If you want to perform more drastic
shareable on a per-user basis - is easy. Just click Live TV on the main surgery to your metadata, use Jellyfin’s dedicated
dashboard followed by + and your HDHomeRun should appear. If you Metadata Manager instead: access this by clicking the
have a USB TV tuner you’d like you use, then you’ll need to link Jellyfin hamburger (=) button in the top left corner of the
to a compatible backend like TVHeadend via the appropriate plugin. screen and then choosing Metadata under Admin.
You’ll then need to assign an appropriate Electronic Programme The Metadata Manager reveals an Explorer-like view
Guide: Schedules Direct costs US$25/year, or $6 for two months of your media by folder. Drill down to a movie title, or
after a six-day free trial, but offers a 21-day guide and is non-profit. parent folder for a TV show, and you’ll see its metadata
XMLTV is free, but fiddly. appear in the right-hand pane, ready for editing.
Once set up, switch to the DVR section to specify where to save
your recordings - separate folders for TV and Movies, and they’ll be Admin dashboard
created as separate libraries in Jellyfin, so don’t place them inside The Dashboard is where you can both monitor and
existing library folders. Streams are recorded uncompressed in administer your media server. From here, you can see
MPEG2 format, but if you’re running ffmpeg, then Bill Thornton's what tweaks you can perform to make things run even
post-process.sh script (https:/7gistgithub.com/thornbill) will more smoothly. Your options are Server, Devices, LiveTV
convert it into MP4/H.264 automatically for you. Just invoke it via the and Advanced, with Dashboard at the very top. This
‘Recording post processing’ option under DVR settings. provides a handy overview of recent changes, which
Once configured, Live TV will appear on your home screen, with its devices are currently connected and what’s streaming
own shortcut and an ‘On Now’ section providing convenient shortcuts and where.
to shows currently on-air. Click a show and you’ll be given the
opportunity to record it as well as watch it. = Metadata Manager
o-»
" The Grand Budapest Hotel

The Green Mile TogNne:

••
• 20:30 21:00 21:30 22:00
" HampMeaid

•• WWWaal t ••• • • •• *XKa r *

WK«> »• ■• •I f Hector and th
** Search far Happln Overview.

m High Fidelity The fates of Henry - a cynical American correspondent who has tost his soul - and Teresa, one of the Republic’s censors and
A
in charoe of overseeinq the news that loumallsts can send abroad, cross in Gemika
< Ghostbusters Logan Hlqh-Rtoe
‘.IL’ Leave No Trace

Food Unwrapped Trip Hazard: My Great Brltls... The Lion in winter 01/08/2016 O
< Channel 4 News Goqqlebox m The Lost City of L
Instant Cappuccino, Tinned Tc Whitby
Once set up, The Monuments Men
Year:

Al ft * Ghost Adventures Ghost Advt 2016 |

RE4LLX < Antiques Road Trip
The Joshua Tree Inn The Chlnat
you'll have access The Motorcycle Dianes

Mr Turner

< Grand Designs Deutschland 89

to a program My Cousin Rachel
Parental rating;

.tfore GB-18
On Golden Pond
“L" The Underground House: Rev Phase Zwel
guide and can Possthenddele
Original aspect ratio: 30 format:

Dave < Room 101

QI XL Red Dwarf watch live TV * Qtwt
*

Rejoice! A Christmas Special Cured A Quiet Plate

and schedule The Revcnant

< Vlbrapower Slim 3 Blockbuste Nono Hair Removal Blockbuster H2O Steam Cleaning Launc
recordings to add
Jellyfin’s Metadata Manager is a prime example of how it enables you

I
to your library.
to fine-tune your media collection to your personal tastes.

18 | Ultimate Linux Projects

 Get a next-gen media server up and running TUTORIALS

QUICK TIP
The Server section enables you to change your x264/x265 - familiar to Handbrake users - which
server name and preferred language (General), plus enable you to fine-tune the quality of your transcodes. Select
Dashboard>
administer your own and add other users (Users) - see The Streaming tab is where you can set an
Advanced>
the walkthrough for a more detailed guide on setting up ‘Internet streaming bitrate (Mbps)’ limit. You can use
Plugins to
Jellyfin for sharing. The options revealed there can also www.speedtest.net to benchmark your home internet extend Jellyfin’s
be applied to your own user account, enabling you to connection, making a note of the upload speed. Unless Functionality
personalise Jellyfin's look and feel. you have cable or a gigabit broadband connection, you’ll using plugins.
Server also contains tools for adding libraries and need to set a reasonable limit here - 3Mbps or 4Mbps These cover
managing existing ones (Libraries) and configuring should enable users to watch 720p high-definition Authentication,
playback options (Playback). Playback has three tabs: content without forcing the server to transcode the Channels,
Transcoding is where you enable hardware-accelerated stream to reduce its bitrate. General, LiveTV,

transcoding using a supported GPU. Transcoding occurs Metadata, and

Notifications.
when a client doesn’t support your media, and the best Complete the tour
Click one For
approach is to avoid - or at least minimise - it. Find out The other sections of the software are largely
a description
more in our guide to x264 and x265 video encoding in self-explanatory - see the box (opposite) for details of
and options to
LXF272. If you must transcode, hardware-accelerated configuring live TV. Under Advanced you can access install it.
transcoding transfers the burden on to the GPU, and system logs and notifications, tweak the networking
newer chips, such as Intel 600-series or later GPUs, setup and install plug-ins. But there's no need to spend
produce better-quality results than older ones. lots of time here right now - get your first Jellyfin client
If you do go down the transcoding route, you’ll also installed, log into your server and account, and start
find advanced conversion settings for transcoding to streaming your media! E3

CONFIGURE JELLYFIN FOR MULTIPLE USERS

XL users Server
Library Access Harriet Help
■ I Ibrarles !■ Dashboard
I ] Enable access to all libraries
Access Parental Control Password
► Playback G General
Select the libraries to share with this user. Administrators will be able to edit all folders using the metadata
manager.

Devices XL IJw Edit this user's profile, image and personal preferences.
Libraries
Cd Devices Name:
■l Ubraries
Collections
.0 Quick Connett Harriet
>/| Movies ► Playback

□ Activity
| | TV Comcdy(lntl) •V Allow remote connections to this server.
Devices
EJ DLNA If unchecked, all remote connections will he blocked
■Z| TV Comedy (UK)
Eb Devices

LiveTV Allow this user to manage the server

tv - Documentaries
al Quirk Connect
(£) uve iv |___ ] TV - Drama

□ Activity Feature Access

@ DVR □ TV - Genre

<z| TV Kids E] DLNA

Advanced y Allow Live tv access

A Networking LiveTV Allow Live TV recording rnandgernenl

Save

Create new user Configure settings

O Navigate to the Jellyfin dashboard and choose Users under
Server where you’ll see your own account is already in place. Click
2 Work your way through the four tabs to determine what
level of access the user has. The default settings on the Profile tab
+ to set up your first friend or family member. Give them a suitable are a sensible starting point and largely self-explanatory, but we
username and assign them a password, which you’ll need to pass recommend setting limits on the Internet streaming bitrate and
on to them securely. Complete the initial setup by choosing which maximum number of simultaneous user sessions (five is a sensible
libraries they’re allowed to access. Click Save. limit to cover multiple devices).

Channels Display
Server

!■ Dashboard Live TV

Display
Movies
G General
Osplay language

Music
XL Users

Trailers
M Libraries
Shows

► Playback

Devices

Ed Devices Block items with tags: +

al Quick Connect

Access Schedule +
□ Activity 01 R»di«nc«

Create an access schedule to limit access to certain hours Duck

3 DLNA LtQht
Purpl* Hju*
Optionweekday • • •nx.
Live TV
18:00-21:00

Access limits and parental controls Personalise user

3 The Access tab is where you can redefine which libraries a
user has access to, plus restrict their access to specific devices
B Once the user logs in, they can click their username to
customise their own setup. Profile is where they can set a
only. If setting up a child account, use Parental Control to set a quick-access PIN code for easy access over the local network and
maximum rating (from U to R18) for content, block unrated add a photo, while Display enables them to change how the Jellyfin
content (or content you’ve add specific tags to), and set an access Ul appears to them. They can also customise playback options and
schedule to restrict overall usage. subtitles, and set their own home screen.

Ultimate Linux Projects 19

Ultimate Linux Projects

While Shashank Sharma isn’t fond of stress-testing the weighing scale,

he’s fine with tools like S-TUI, which help him monitor CPU performance.

ver the past few years in Linux Format

L* Till*: linuxlnJ«<Spiflynmund- - X

magazine, we’ve introduced a blend of I: liniixlfll/wttpl/iygrnund » x

2.00GHZ

powerful and robust as well as nifty and nimble Rodes

(X) Monitor

command utilities that help you perform a variety of ( ) Sliwsh

itrcss liner

tasks. Everything from everyday text editing, connecting 00:00:00

Contra! Options

with remote machines, performing backups and other < Sunndfles

< Stress Options >
>

« Reset >

administration tasks can be done from the terminal. « Help

< About
>
»
< save Settings >

A key matrix for determining the vitality of a Linux < Qutt

Visual Options
>

pAckagr-0,0
4.0 rare,0 iincore ,0 dram. 0

Shashank distro, or the hardware that it runs on, is system [N/A] UIF 8
ReTresh[k]:2.0

Sharma performance. Depending on your purpose, you can Sunnartes |0.0

Tenp [C] I Fan [RPM]
Acpllz ,0 47.011.0 thlnkpad.O
PackAgeTdO.fi 47.0|
is a trial lawyer in choose from a variety of dedicated tools to monitor the
Delhi and an avid different components such as CPU frequency,
Arch Linux user. temperature and memory utilisation. But if you favour Some sensors, such as Power, are only available when you run S-TUI as
He’s always on
the hunt
the CLI, like us, you’ll rather enjoy working with S-TUI.
With S-TUI, which is an acronym for Stress-Terminal
I sudo, and not as a regular user.

for geeky Ul, you can simultaneously monitor CPU temperature, installing the tool is fairly straightforward, and the
memorabilia. frequency, power and utilisation. The utility presents all project’s GitHub page describes various installation
the information graphically and can even be used to techniques. If your Linux distribution is already
export the data into CSV files. Better still, you can configured to use pip , you can install S-TUI with the
configure S-TUI to automatically launch scripts when sudo pip install s-tui command.
the values of any of the components being monitored For other installation methodologies, such as
breaches the defined threshold values. When coupled installing it from Git, you’ll have to ensure all the
with stress, another command-line utility, S-TUI can also dependencies are installed. These include tools such as
be used to stress-test your system. urwid and psutil. Although it isn't a dependency, if you
decide to use S-TUI to also stress-test your CPU, you
Don’t stress over installation should also install stress or stress-ng. Thankfully, these
Although S-TUI isn’t available in the software are offered in the software repositories of almost all
repositories of most popular desktop distributions, desktop distributions.

» MAKING USE OF THRESHOLD SCRIPTS

In addition to the s-tui.conf file, the value, you must invoke S-TUI with the tool will exit with a curt ‘Permission
~/.config/s-tui directory also contains a s-tui --t_thresh <vahie> command. Denied’ error.
directory called hooks-d. You can place You can then save the new threshold When you now open the s-tui.conf file
custom scripts you wish to execute value into the ~/.config/s-tui/s-tui.conf in a text editor, you'll find a new entry
when a certain threshold, such as CPU file by saving the settings from within showing the newly defined temperature
temperature or frequency is exceeded, S-TUI itself. threshold value:
within this directory. The name of the If you make any changes to the [GraphControll]
script must be <name>source.sh, where settings from within the S-TUI interface, refresh = 2.0
<name> is the name of the supported and wish to save them for future use, utf8 = True
source. While you can use S-TUI to track you’ll need to navigate to the Save tthresh = 70
various sources, for now it only supports Settings option on the sidebar and then While the stress testing feature is of
running scripts based on CPU press Enter. Depending on how you little use to home Linux users, there's no
temperature threshold setting. installed S-TUI, you may have to amend denying the benefit of graphical
The default threshold value for the the file permissions on the s-tui.conf representation of the collected data for
CPU temperature is 80. To change this file for it to be writeable, otherwise the administrators and programmers.

20 Ultimate Linux Projects

 Stress-test your CPU 8 UTORIALS

Unlike many other command-line utilities, S-TUI quick introduction. For a complete list of all the
requires no configuration and you can begin using it supported command options, you must run the
QUICK TIP
immediately after installation. Run the s-tui command s-tui-help command. The stress
to launch the utility. The collected data is lost as soon as you exit S-TUI, utility performs
At the top of the sidebar on the left are the details because the tool doesn’t save it by default. If you want a loop that
calculates the
about your CPU. Our Lenovo test machine was correctly all the collected information to be automatically saved
square root
identified as running an Intel Core i3-5005U CPU @ to a CSV file when you exit S-TUI, you must invoke the
of a random
2.00GHz processor. This is because S-TUI utilises utility with the s-tui-c command. The collected data
number in order
various other native tools and utilities to gather the will be stored in the users' home directory. You can then to stress the
relevant information. For instance, the same information view the s-tui_log_<TIME>.csv file in your preferred text CPU. You can
and far more details can be ascertained from running editor. You can also provide a custom name for the CSV customise the
the cat/proc/cpuinfo command. log file with the s-tui -c <path_to_CSV_file> command. stress options
When you first launch S-TUI, it displays all four Another useful command option is -j, which can be by navigating
parameters - Frequency, Utilization, Temperature and used to print on the screen the current status of the to the Stress
Power - and refreshes the data for each every second. machine in JSON format. The output generated by the Options screen
From the S-TUI
You can change the refresh rate by changing the value s-tui -j command is a record of the current status of
sidebar. The
of Refresh[s]:1.0 on the sidebar. the machine, and not a running log:
graphical
Depending on your terminal application, and the $ s-tui -j
interface
colour scheme, you may not be able to clearly see the enables you to
different elements on the S-TUI interface. Should this "Frequency": { define all the
happen, exit S-TUI, then switch to a basic White-on- "Avg": "1282.1", major settings
Black colour scheme on your terminal emulator, and run "Core 0": "1630.6", such as the
S-TUI again. You should now be able to see all the "Core 1": "1295.6", worker count
different colours used by S-TUI to display all the "Core 2": "1175.6", for the sqrtO,
collected information, and you can edit your terminal "Core 3": "1026.4" syncO, mallocO
Functions, as
profile accordingly. }/
well as choose
You can use the up and down arrow keys to navigate "Temp": {
whether to dirty
the sidebar, but S-TUI also supports the use of H and J "Acpitz,0": "48.0",
the memory.
to scroll, much like you would in Vim. "PackageId0,0": "49.0",
"Core0,0": "47.0",
Add some stress "Corel,0": "47.0",
By default, S-TUI is configured to only monitor your "Pch Wildcat Point,0": "40.5"
system. This is evident from the (X) next to Monitor on }/
the sidebar. If you installed the stress utility as well, you
can enable the stress feature by navigating to the Stress S-TUI supports a number of different temperature
entry on the sidebar and pressing the spacebar. You’ll sensors and you can choose a different one by
notice the empty brackets would be replaced with (X) navigating to the Temp Sensors screen. This is only
now. You can similarly enable or disable monitoring of needed if the default configuration fails to accurately
the different components. When you disable a graph the CPU temperature on your machine.
component, the corresponding graph will automatically All the basic settings, such as the refresh rate (in
disappear from the interface. seconds) and which components to graph, by default
Unlike most other command-line utilities, S-TUI can are stored in ~/.config/s-tui/s-tui.conf. Unfortunately,
also be controlled with the mouse. You can left-click on you must set the Stress options and the temperature
an entry/option in the sidebar to select it. You must still sensors every time you run S-TUI as the tool doesn't
hit Escape to return to the main screen and use the permit saving these settings in the configuration file. E5
arrow keys to scroll through the sidebar as the
scroll-wheel on your mouse doesn’t work with S-TUI. To 1 /1 ▼ L* c? Tilix: linuxlala@playground: *

disable the mouse, you must invoke S-TUI with the 1: linuxlala(®playground: -
Temp [C]
s-tui-nm command. Stress Options PackageId0,0 Core0,0 Corel ,0 Pch Wildcat Point

Time out [sec]: none]

You can also switch to a different temperature sensor
Sqrt() worker count: 4

from within S-TUI itself, if you believe the graph is Sync() worker count: 0 Core 0
Frequency [MHz]
Core 1 Core 2 Core 3

inaccurate. Navigate to the ‘Temp Sensors >’ entry on Malloc() / Free() worker count: 0

the sidebar, and press Enter. This opens the Available Bytes per malioc*: 256M
Util [%]

Temperature Sensors dialog, and you can then select Touch a byte after * bytes: 4096 Core 0 Core 1 Core 2 Core 3

Sleep time between Free() [sec]: none

one from the list. As before, after navigating to an entry [ ] "dirty" the memory

in the list, press Spacebar to select it. Remember to instead of free / alloc
core,©
Power W]
uncore,0 dram,©
Write() / Unlink() worker count: 0
select Apply for the changes to take effect. Byte per Write(): 1G

You must hit Escape to return back to the main Default Save Cancel Fan [RPM]
thinkpad,©
screen of the application, such as from the About> Core0,0 46.0|

Help or Temp Sensors section. Corel,0 45.0|0.0

■

While the graphical interface for S-TUI also has a You must refer to the man page and documentation on the stress utility to understand the
Help section in the sidebar, it provides little more than a I different supported functions.

Ultimate Linux Projects | 21

Ultimate Linux Projects

Credit: https://cozy.geigi.de

cozy!
Build the ultimate
audiobook collection
Nick Peers reveals how to put together your own audiobook
library using CDs, free downloads and Audible purchases.

e all love a good story - after all, telling stories ActtvitiM O rirefox Web Orowief A * O

w
UbrtVox • MoxAU Flrtfox n 9

around the fire is as old as human language © corduroy

<- -> C? 0
ah IV librtvox

Of. hccpi:, Utxfvox.org mrch?q A Tale of

4-

© O Q, Search ± b\ gj £ ::oooeoai? nn o.

J itself. Audiobooks - and radio dramatisations -

BKVW14 THt CATALOG
k g GenterSuBfec! |*Linquaoe

continue that tradition into the modern age, and thanks PontN to LIWWI
A Tate of Two Cities (in Fits! Chapter Collection 001)

to your phone and PC, give you the opportunity to VARIOUS •)

listen to your favourite books wherever you are. USA wyou

P*wc
r trw USA
In -.w'/l vUOs of
Ihrv Mih m yrr.1 own onmwy bntarv
A Talc of Two Cities
DCKkNS (JB j; UKU)

In this guide, we’ll show you how to bring all of your WMM) LOpffliW>

A Tak of TWO Cinet (version 2)

cnam iXMtha (iw - Dt/Q)

audiobooks - whether on CD or in the cloud - into one Listen to one voice

A Tale of Tao Obei (ver&ion 3)
reading the text in
Nick Peers central library. You’ll add tags to make them easy to
Librivox in the Solo
has been busy identify, plus discover how to listen to them from your audiobook versions
A Tale of Two Cities (vtc&ton 4)
uurtnocamiiiiu
C«wt« i €oe ICw*
ik/o>

building a huge PC or phone. Let’s get storytelling...

audiobook library
from his massive Set up your Audiobook library being Audible); and finally, from free websites where
CD collection, all There are three principal places to source audiobooks: classic books - namely, those now out of copyright -
powered by the on CD, with unabridged editions spanning dozens of have been narrated by volunteers can be found.
lovely Booksonic. discs; from an online vendor (the obvious example One of the best sources of free audiobooks is LibriVox
(www.librivox.org). When you find a title you like, choose
Rip audiobooks with Fre:ac the ‘Whole book (zip file)’ option to download the book
File Database Options Processing Encode Help as a series of MP3 files, one per chapter. Each file is
www.freac.org tagged with author, title and other key details, and you
Joblist Tags Logs can also download cover art from here to illustrate the
l< ►! ±
17 file(s) in joblist:

Artist Title Track Length Size

book in your library - more on tagging and artwork later.
* Alexander McCall Smi unknown U
□ Alexander McCall Smi unknown title
08
09
03:10
02:53
33.537.168
30.526.608
Where will you store your audiobooks? The simplest
I Alexander McCall Smi unknown title
□ Alexander McCall Smi unknown title
10
11
02:23
03:39
25.248.720
38.591.616
option is to create a dedicated folder - Audiobooks -
1 Alexander McCall Smi unknown title
□ Alexander McCall Smi unknown title
12
13
03:08
04:35
33.118.512
48.597.024
which can reside inside your Home folder. Books can
□ Alexander McCall Smi unknown title
Alexander McCall Smi unknown title
14
15
03:07
02:39
32.925.648
27 979 392 then be stored within the following folder structure:
X Show title info
Create playlist Create cue sheet X Encode to a single file
Audiobooks\Author\Title - for example, AudiobooksX
Artist: Alexander McCall Smith Title:
Herman MelvilleXMoby Dick. If your collection threatens
Album: Corduroy Mansions Track: 08 Yean 2008 Genre: Fiction
to get out of hand, or you’d like to subdivide your library
Cur Alexander McCall Smith • unknown title Selected filters: none 6 (say separating children's titles from your wife’s
Active CDIO Ripper Component v2.1.0 Selected encoder: LAME MP3 Encoder v3.100

File progress: 33% / 91% Time left: 00:05 / 00:07

collection of thrillers), add another layer - Genre -
Output folder: /home/nick/Audiobooks/A McCall Smith/Corduroy Mansions/ en Select between Audiobooks and Author.
fre:ac - free audio converter v1.1.2 - Copyright 020 Robert Kausch x 03:10 49:27 Z 52:37

Fre:ac controls Monitor progress

Audiobook File breakdown
The buttons provide shortcuts to
Frequently accessed tools and settings,
□ Progress bars show you how Far the
ripping process has got - both For the current
Another important consideration is how you intend to
store individual audiobooks. Audible supplies entire
including the all-important rip button. track and the overall selection. books as a single file, and whatever chapter markers are
embedded in its native file format (AAX) will be lost on
Joblist Output Folder

0 All tracks requiring processing are listed

here. Use the controls on the left to quickly
□ You’ll need to set this manually For each
audiobook CD you rip owing to issues with
conversion. Conversely, audiobook CDs split each CD
into short tracks - three- to five-minutes long - to aid
select all, deselect all or invert selection. Fre:ac's automated tools. navigation through CD players.
Neither option is particularly desirable. Your
Metadata Monitor track length

0 Although Fre:ac enables you to edit the

currently selected track’s metadata, it's quicker
When dividing audiobooks into roughly
equal ‘parts’, the Figure next to ‘X’ helpfully
audiobook player should be able to pick up from where
you left off, but it's still handy to be able to jump to a
and easier to use Kid3. reveals the combined length oF your selection. specific chapter or section of a book quickly. The

22 | Ultimate Linux Projects

 Build the ultimate audiobook collection IUTORIALS

approach adopted by LibriVox books is best - one file OpenAudible

per chapter, and this is something that OpenAudible can File Edit Controls Actions About
View In Audible Ctrl+L
OpenAudible 2.3.4
do with your Audible library by splitting books into Show AAX F2
.ibrary Status
Show MP3 F3
separate files - one for each chapter - during the Connected: No Show M4A
Region: UK
AAX-to-MP3 conversion process. Books: 13
Play Audio Book Heron Carvic

Hours: 48.7 Download CCrl+D

It’s more complicated with CDs where you need to MP3 Files: 12 Convert to MP3 Ctr 1+1
M4A Files: 0 Cancel Job
combine multiple tracks into a single file, and choose Ignored: 0
Refresh Info FS
Missing Links: 0
where to break them: by CD, so each file spans 60-70 To Download: 1 Split Selected Books *
To Convert 0 Book Report
minutes; chapter - can be fiddly to locate where each Downloading: Ignore Book
Converting:
chapter begins, and not always an option with abridged .ummary
Delete Book

audiobooks; or arbitrary break - say splitting each CD The radio dramatisation of The Hobbit became a classic when it was first broadcast on BBC Radio 4 in 1968 and it continues to delight today. Tolkien's famous saga, the prelude to the Lord of the
Rings, has all the ingredients of fantasy and adventure: dwarves, elves, goblins and trolls, a fearsome dragon, a great wizard, a perilous quest and a dramatic climax.

into two 35-minute or three 25-minute ‘parts’. St Narrated By Dural

Thankfully, our ripping tool of choice - fre:ac - can 3

ITUK.IIUCI ivM.iiiu>i c. uve a Lxsuyiiuiy imunaei ivM.iniyi e

Paul Temple and the Gilbert Case (Dramatise Francis Durbridge

iviiiiioei imimyi c

Peter Coke, Marjorie West 03:31 2020-09-29 2005-02-11

handle any of these options with aplomb. J

J
Paul Temple and the Madison Mystery (Dram Francis Durbridge
Roger Moore: My Word Is My Bond Roger Moore
Crawford Logan, Gerda Ste 03:40
Roger Moore 02:40
2020-09-29
2020-09-29
2008-07-22
2008-10-09
-J The American Future: A History Simon Schama Peter Marinker 04:55 2020-09-29 2008-11-18
FC The Hobbit (Dramatised) J. R. R. Tolkien Paul Daneman, Anthony Ja 03:43 2020-09-29 2007-11-21

Convert your Audible library Up Till Now William Shatner William Shatner 06:10 2020-09-29 2008-05-20

Let’s start with revealing what do with your Audible OpenAudible converts your Audible purchases into DRM-free audiobooks for your own
collection. You’re probably already listening to them
using an app - either on your phone or via the open-
I consumption on your choice of platform.

source Audible for Linux tool (https://github.com/cross- through FastSpring. Once you’ve received your licence
platform/audible-for-linux). This ties you into Audible’s code, choose ‘About > Activate’ to enter it, then press
DRM system, meaning you won't be able to combine Ctrl + T to convert the file to MP3 format.
QUICKTIP
your Audible titles with those sourced elsewhere. One final step: the file is converted into a single file When it comes
Until recently, there was a free solution to this in the by default, so once done you’ll need to choose ‘Actions to assigning
form of OpenAudible - it’s now shareware, but if you’re > Split Selected Books’ and wait while a progress bar genres to your
audiobooks,
desperate to produce non-DRM versions of your Audible reveals how many chapters or files will be created, plus
avoid the
books, then the £12 registration fee isn’t too prohibitive. keep you updated with how it’s getting on.
generic
By way of compensation, it supports up to three Once all this is complete, a folder window will open to
‘Audiobook’
separate Audible accounts and comes with a year’s reveal your converted audiobook inside a sub-folder to come up
worth of updates. with the title as its name. You can now copy or move this with specific
To get started, head over to https://openaudible.org into your Audiobooks library (you’ll need to create an book genres
to download a DEB package or Applmage - the latter is Author folder if you've not done so already to place the like Mystery or
the simplest to use: simply place it in your Home folder folder in). Sci-Fi. Search
and don’t forget to right-click it and choose For those with large Audible libraries, there’s some Goodreads.com to
Properties>Permissions to tick the all-important ‘Allow good news: once you've purchased a licence, any book see how other
readers have
executing file as program’ box before launching it. you subsequently download will be automatically
categorised
Once up and running, press Ctrl+K to open a converted to MP3 (see Edit>Preferences where you can
a book, if
browser window that will redirect to Audible.co.uk - also adjust the encoding quality of the resulting MP3 file
necessary.
look for the Sign In button in the top-right corner to log if you wish to change the balance of file size versus
into your Audible account. Once logged in, close the audio quality). Select multiple books at once and
browser window to return to the main OpenAudible choose Actions>Download to do so - you'll be
interface. Next, choose Controls>Quick Library Sync
and after a short pause you should see your Audible
purchases appear. » TRACK DOWN COVER ART
Next, select a title - you’ll see a summary and
artwork appear. Its State should read ‘Ready to To hunt down artwork, head to https://images.google.co.uk and
download’. Choose Actions>Download and wait for the search for the title of your book plus the word ‘audiobook’. You’ll
audiobook to download in its native AAX format. All of almost certainly get a match, but wait - is it suitably hi-res? Our
this can be done for free, but this is the point where preferred size is 600x600 pixels, although 500x500 is the size of
you’ll need that licence. If About>Purchase doesn’t artwork embedded into your Audible collection by OpenAudible.
work, head to https://openaudible.org/purchase to buy To locate higher res artwork more easily, click Tools under the
Google Search button and change Any size to Large, which will filter
frerac - free audio converter vl.1.2 X

File Database Options Processing Encode Canrei Name Q out smaller images. Hopefully at least one will remain: click it to view a
’ © a Ml ’ © O© O Gt Home © home me
* Auchobooks Alexander McCall Smith
preview. Roll your mouse over this to reveal its size - if large enough,
O Desktop Name Size Modified
joblic Toqj Logs

right-click it and choose ‘Save image as’ to save a copy to your hard
• oi - Alexander Mccall smith-corduroy MaiHiofts.mpl 12.7 MB 13:47
?3file(s)injobl.st: £, Documents 02 • Alexander McCall Smith • Corduroy Mansions.mp3 13.6MB 1350
K Artist Title OS Alexander McCall Smith - Corduroy Mansions mp) 13.3 MB 13.51
2 Downloads

drive. Use your image editor to reduce both its physical size to
Kunknown artist unknown title 04 • Alexander McCall smith • corduroy Mansicns.mp 3 13.3 MB 1358
X unknown artist unknown title Music OS Alexander McCall Smith - Corduroy Mansions.mp3 13.6 MB 14 04
X unknown iftiit unknown title
oo - Alexander McCall smith - corduroy Mansions.mpj 14.4 MB 14:10
£ Pictures

600x600 if necessary, plus its file size by saving it as a JPEG.

X unknown artist unknown tide
X unknown artist unknowntitle
8 Videos
X unknown artist unknown title
X unknown artist

If you’re struggling to find a suitably sized image via a keyword

unknown title £j bin
[x unknown arUst
unknown title
r unknown artist unknown title
+ Other Locations
T unknown artist unknown title
unknown artist
unknown artist
unknown title
unknown title
search, save the largest version of the artwork you can find, then click
Show title Info the camera icon inside the Google Image Search box and choose
Current file none

Active decoder, none

‘Upload an image’ to search the internet using the actual image
File progress:

Output folder: /home/nkK/Audlobooks/Atexander McCall Srnktyf

itself. If you’re lucky, you’ll see an ‘All sizes’ button appear next to
ItrJC - free audio converter vl.1.2 - Copyright (Q 2001-2020 Robert Kausch
the image thumbnail: click this and hopefully it’ll reveal a higher
Ignore tagging your files when ripping in frerac - your focus should be resolution image that you can use.
I on naming them in the correct sequential order.

Ultimate Linux Projects | 23

Ultimate Linux Projects

prompted about automatic conversion for the first error message stating that the freedb.org database has
QUICKTIP book, but thereafter it’ll all proceed in the background. no record of the CD. This will be true for most - if not all
Fancy turning And once that process completes, choose Actions>Split - audiobook CDs, so choose Database>Automatic
your audiobook Selected Books to complete the process. CDDB queries to remove the automatic check.
collection into At this point, you could tag your files using fre:ac's
a streaming Rip audiobook CDs Tags>Albums tab section where you can manually input
server When it comes to ripping audiobook CDs, you’ll need a the author (Artist) and book title (Album), plus add
accessible From ripping tool that can combine multiple tracks into a artwork, a year and genre. While this works perfectly, it’s
anywhere over single file - we recommend fre:ac, which you can install very fiddly - you need to add this information manually
the internet?
through the Software Centre. To enable this feature in each time you insert a new CD, and it’s much quicker to
Dig out your
the program, choose Options>General settings. Verify handle the process later on using Kid3, so for now leave
copy oF LXF259
the LAME MP3 encoder has been selected, then check everything set as ‘untitled’.
and turn to
page 64 For our ‘Encode to a single file’. Click Select under Output folder
two-page guide to select your Audiobooks folder and untick ‘Use input Select tracks to rip
to building and file folder if possible’. Ignore the ‘Filename pattern’ field Now, you need to select all the tracks you plan to rip as
maintaining for automatically naming your output files - it doesn’t your first file. If you’re ripping an entire disc, just make
the perfect work when ripping multiple tracks to a single file. sure everything’s selected; otherwise you need to locate
audiobook Spoken audio recordings take up less space than the first and last tracks that make up your selection -
server using regular music due to their relative simplicity, but you can either aim for 25 (or 35) minutes for an arbitrary break,
Booksonic.
squeeze them even smaller by switching from stereo to or use the playback controls above the track list to work
mono recordings: click Configure encoder next to the out where each chapter begins and ends.
LAME MP3 encoder to do so. Change the Use preset to Finally, click Select next to Output folder to open
Custom settings, then switch to the Misc tab and choose your Audiobooks folder, then manually create a new
Mono under Stereo mode before clicking OK. author folder (or select an existing one if applicable)
Next, insert the first disc of your first audiobook and followed by a folder named after the book title. With this
click the ‘Add audio CD contents to the joblist’ button. selected, you can now click the green ‘Start the
You’ll see all the CD’s tracks appear, accompanied by an encoding process’ button from the main toolbar.
You’ll be prompted to save the file - automatically
named Artist - Album (or Author - Book Title).mp3. Be
» ANDROID AUDIOBOOK HEAVEN sure to insert a track number at the beginning
corresponding to the chapter, part, or disc number - so
Want to listen to audiobooks on your Android phone? If you’ve ever Ol-Author-Book Title.mp3, for example. You might even
used Booksonic (covered in LXF259), then the obvious solution is to prefer to name the file Ol-Chapter One.mp3 or whatever
install the official Booksonic app (£2.49), which not only streams naming convention you like - just make sure the track
books from your server to save space on your phone, but enables number is at the beginning.
you to mark individual titles for listening to offline. This means that Once you click Save, the rip will begin. A progress
they’re temporarily downloaded to your phone’s storage, which indicator will reveal how your rip is progressing and
makes it possible for you to listen to them anywhere, then easily completed tracks will disappear from the queue. When
removed when you’re done. finished, a single MP3 file will have been created. Now
If all you want is to listen to audiobooks you've transferred to your repeat the process for the next chapter or part, and
phone’s storage - after all, you when you’ve finished with a disc, move on to the next.
can fit a heck of a lot of books on
to a 32GB microSD card - then = Smart AudioBook ID3 Tag your media
try Smart AudioBook Player Once you’ve ripped your audiobook CD, it's time to tag it
instead. When you first launch it,
stssE □ A using a tagging tool. We’ve opted for Kid3, which is
The Breakdown
simply point the app towards regularly updated and has evolved into just the tool for
Read 8:04 of 9:25:37 1% Left 9:17:33
your Audiobooks folder, then audiobook tagging. It’s best installed through the
01 - The Breakdown.mp3
refresh the library to view a Terminal to ensure you get access to the latest version:
complete list of books, sorted by $ sudo add-apt-repository ppa:ufleisch/kid3
author and then title. Tap one to $ sudo apt-get update && sudo apt install kid3-qt
access its own playback screen Once installed, launch Kid3 and choose
where you’ll find all the controls Settings>Configure Kid3. Up the ‘Track number digits’ to
you need - and then some, 2 (so 01, 02 rather than 1,2, etc), and tick Album Artist
including Characters (to help you and Composer under Quick Access Frames before
remember who's who) and dragging and dropping them in alphabetical order. Like
Bookmarks (for jumping to Artist, Album Artist will record the author’s name, while
favourite passages quickly).
After 30 days, the app reverts
to a basic cut-down version - it
has all the core functionality you
need, but the full version costs
just £1.89. Select Help> Features
to compare versions followed by Smart AudioBook Player has all the
playback controls you could ever need
Help>Version>Buy to purchase. You can create your own custom genres in Kid3, enabling you to add
(or want, Frankly).
I another layer oF organisation to your audiobooks.

24 | Ultimate Linux Projects

 Build the ultimate audiobook collection IUTORIALS

r <-> o *
the Composer field is for recording the audiobook's Activities

® II
n Cozy *

<♦ 1®^ A Man Lay Dead 02:55

29 Sep 19 00

■13:47 to & Q =
a

tf x
J A Man Uy Doad - Chapter 1

narrator. You’d expect things to be the other way round, Recent Author Reader

but go figure... Kale Mosse

Kenneth Grahame M A AGCFlY

. MARGERY. .
Use the Custom Genres section to input custom i pnny Henry
AllinchaM
ALLINGHAM
CARGO OF
EAGLES
ALLINGHAM
DEATH OF A
(iH( )S I
Lynley Dodd
audiobook genres - click Add for each one, from Horror M C. Beaton

and Crime to Sci-Fi and generic Fiction. When you’re Margery Alli ogham

Mark Billingham Mark as read

done, tick ‘Show only custom genres’ if you want to Michael Rond
Blackkerchief Dick: An
Albert Campion Mystery
Cargo of Ear Open in file browser

Remove from library

ithOfAGhost Flowers For The Judge
Phillip Franks
Michael McIntyre William Gamlnara
remove all other auto-suggestions as you fill the Genre Michael Morpurgo

tag. Once you’ve tweaked Kid3's settings to your Michael Robotham

Mick Inkpen

satisfaction, click OK. You’re now ready to tag your files Ngaio Marsh

Paul Daneman

- the step-by-step guide (below) reveals how to apply Peter Coke

consistent tags across all your audiobook’s files, and Peter Marinker

Peter Straub
Hide My Eyes Mystery Mlle Police at the Funeral Sweet Danger

add album art. Richard Briers Philip franks Philip Franks Philip Franks Philip Franks

Roald Dahl

How to enjoy your audiobooks Dedicated audiobook player Cozy works beautifully with your audiobook library - no need to play
Once your audiobooks have been ripped, organised and
tagged, it’s time to enjoy the fruits of your labours. While
I them in a music utility.

you can listen to an audiobook through any music authors or narrators (depending on the view that you're
player in Linux, it’ll be a messy process trying to using), while the right-hand pane displays a list of titles, QUICK TIP
combine music and audiobooks in the same program, again in alphabetical order, complete with artwork. Use We’ve chosen
never mind library. Instead, use a dedicated audiobooks the left-hand pane to filter the view by author/narrator if MP3 as the
player called Cozy, installed via Flatpak: necessary, then roll your mouse over its image cover to file Format for
$ sudo apt install flatpak reveal a play button to click: alternatively, click our audiobook
$ flatpak install flathub com.github.geigi.cozy elsewhere on the artwork to view the title up close. library because
$ flatpak run com.github.geigi.cozy Cozy’s user interface is nice and straightforward to spoken word
recordings
The program will launch - going forward, it can be navigate - you’ll see a series of buttons across the top,
don’t require
opened through the Launcher. Step one is to import including a handy 30-second rewind button next to the
audiophile
your audiobooks - simply select your Audiobooks folder play/pause button, plus a progress bar to
levels of quality.
to proceed and Cozy will import them into its library. navigate quickly through the current track. You’ll When you
Once complete, choose your view: Author displays titles also find playback speed, sleep timer, and search factor in the
by Composer field (meaning the narrator), whole buttons to the right. length of most
Reader displays them by Album Artist (so the author). Click the menu button for more options - you can audiobooks -
Hang on - haven’t we just organised everything the manually refresh the library after ripping new many hours
other way around? Yes, because other audiobook audiobooks, tick the box to hide unavailable books per title - the
programs and services organise them that way, as do (such as those stored on currently disconnected smaller your
Files the better.
regular music players. Don’t worry, though, because external or network storage), plus revisit the
Cozy can be configured to swap them round to avoid Preferences section, where you can add additional
confusion: click its menu button and choose folders to Cozy's library if you wish via the Storage tab.
Preferences>Behaviour tab, then flick the ‘Swap author And what about consuming your audiobook
and reader’ switch to instantly correct the view. collection on other devices? The box (opposite) reveals
Now return to your chosen view, where you’ll be all you need to know about listening to your audiobook
greeted by a two-pane window. On the left is a list of collection on your Android phone. E3

TAG YOUR MEDIA WITH KID3

• Size Dati li - uoruuiuy r
- File
I Smith - Corduroy M... 12.1 MB 29/ i - Corduroy *1 Name:
I Smith - Corduroy M... 13.0 MB 29/ Name: li - Corduroy f*
I Smith - Corduroy M... 12.7 MB 29/ li - Corduroy f 2 F
I Smith - Corduroy M 13.0 MB 29/ Format: T %{track} %{title} From:
11 - Corduroy f
Import from Tags
%{title) |*]T
I Smith - Corduroy M 13.2 MR 29/
tie} To: li - Cordurov f
I Smith - Corduroy Number Tracks 11 - Corduroy f Format: Generate Audiobook titles Add
------ 1 1----- =---------
I Smith - Corduroy
I Smith - Corduroy i - Corduroy f
v Start number: 1 Destination: Tag 2 Source: Part %{track.1} Remove
I Smith - Corduroy li - Corduroy f
I Smith ■ Corduroy Reset counter for each folder li - Corduroy f Extraction: %{title}(.+)
I Smith - Corduroy 11 - Corduroy r .-------------------------------------------
Total number of tracks: 12 C _____________ zJ
I Smith - Corduroy
li - Corduroy F Destination: Tag 2 :all Smith
Help Save Settings OK . Cancel
Help Save Settings Apply* Close call Smith
Album Corduroy Mansions TT
Album Corduroy Mansions
Comment fre:ac - free audio converter <https:/^
Comment Fre:Ac - Free Audio Converter
Composer Andrew Sachs

Set common tags Add track number Add title inFormation

O Choose File>Open to select all your
audiobook’s files and click Open - they
2 Next, you need to tag each file with
its specific track number. To do this, verify
Again, with all the tracks highlighted,
choose File>lmport from Tags. Click Add,
should appear highlighted in blue. Tick all all files are still highlighted, then choose name it Generate Audiobook Titles, and
the tags that will apply to all tracks: Album Tools>Number Tracks. Make sure the type the following string into the Source
Artist, Artist, Album, Date, Genre and Destination is set to Tag 2, click Save box: Part %{track.l} - replace Part with
Composer, and fill in each field. Add your Settings to make this default going Chapter or Disc as required. Type %{title}
artwork by dragging the file to where it forward, and click OK. Select each file (.+) into the Extraction box, and select Tag
says ‘Drag album artwork here’. Click Save in turn to verify the correct track number 2 under Destination. Click Save Settings>
to save your changes. has been assigned. Click Save again. Apply, then click Save for the last time.

Ultimate Linux Projects | 25

Ultimate Linux Projects

VI

RISE OF
o rvaq « .

I Mtn I

o«r« rar* . i

ROBOT
Mats Tage Axelsson
basics of a roboticybperating
system and reyedls what
component an be used • •

r i .'N

rxjtcr.

ssembling your own robot This isn’t something you whip up in The ROS is better described as a
and getting it to walk around your coding cave on a rainy afternoon. robotics framework, but what do you want
will entertain kids of all ages Being free and open source enthusiasts, from the ROS and what do you need to do
for a good few minutes. we know better than to believe we have to to get a robot up and running? We’ve
However, for robotics to be long-term cover every detail ourselves. There have already mentioned that many subsystems
fun it needs to be a challenge. been many projects to make robotics an control different parts of the robot. Your
A common misconception about area you can thrive in and help expand, the robot will need to navigate, move and
robotics is that you need a degree to make most successful organisation to date is the interact with its environment. That may
anything of your own. Having said that, a Open Source Robotics Foundation include interacting with you and other
robot does require many subsystems to (www.openrobotics.org). Out of this has humans, but that’s for another time. The
operate. There are legs to move, arms to developed the Robotics Operating System simplest robot will run around the house
stretch, things to see and react to. (ROS). It’s not an operating system as exploring - a more advanced version will
Basically, everything we do as humans - such, but rather a collection of tools that go to the kitchen and bring you a new
except you must design the entire system help you create your version of what a beverage. For all this you need sensors,
that can handle all those tasks. robot should be and do. micro controllers and a lot of mechanics...

26 Ultimate Linux Projects

 ?ise of the robots IN-DEPTH

It’s important to bear in mind that all these parts

must communicate with each other. This is where things
can become complex and you need an overall control
system. Using ROS, you can declare and define all the
nodes (the distinct parts of the system) and how they
communicate. Other things included in the ROS
framework are simulators and visualising software to
help you spot problems and solve them.
Knowing what the different pieces of software do
requires a fundamental understanding of the
architecture. Yet defining a robot as the sum of its
components will quickly become complex, so there
needs to be a standard method of communication -
either within the robot or from outside. This is, in
essence, what ROS is for: it establishes the standard
communications protocols. Within this standard are I You can create an entire environment in Gazebo. This includes walls, stairs and windows.
certain components that define the overall system:
nodes, services and topics. shows many useful examples of a service, client,
A node is one collection of functions that publisher and others. Everything else uses the client
communicate with other nodes using the ROS client libraries, so make sure you understand them.
library. This makes it possible to choose between many While you run ROS on your machine, you can find all
different solutions for each task, so long as they use the different message formats through using the various
ROS to communicate with the other nodes. Nodes will commands. The other parts of the ROS system are
use the other parts of the architecture - topics and specific to different functions. The turtlesim executable
services - in different ways, depending on what the demo displays some of the available functions. It shows
information is used for. how to move the robot around.
Topics are places that contain data, which many As well as snaps, you can also use virtual machines
nodes will need to access. One node will send data to for your ROS installations. The snap route to a ROS
the topic and other nodes can subscribe to the topic. In installation is an easy way to see the first examples
short, this is a broadcast-type message - information before you start creating your own code:
that many nodes may need and one can create. In $ sudo snap install ros-beginner-tutorials
contrast, services are created so that one node can With these snaps, you can run all the demos on the
request information from another node. The first node is ros.org website. The commands are even named
the client that requests information from the server. according to the activities in the documentation. A ROS
installation contains a massive amount of software. All
Component core packages are small, but dependencies can be
To run ROS, you need a number of packages. In the troublesome on your regular machine that you use for
core version, you’re provided with everything you need
to run the actual robot. These packages implement the
ROS interfaces, the middleware interface and some » YARP: A SIMILAR FRAMEWORK
specifications for the messages that you need to use
for development. YARP is the framework for communications within robotics. It can
The two that you’ll come in contact with the most are replace the ROS master as a name server. You can also do this the
the rclcpp and rclpy libraries. They both implement the other way around using the YARP as a name server. The name server
client libraries: as you may guess, one is for C++ and the will support the nodes and protocols across your system. You can also
other for Python programmers. The client libraries cover use both in a single system.
the messaging we mentioned earlier. This is where you One reason why you may want to use this is if you have a single unit
decide whether your client needs to broadcast to topics that requires a separate underlying protocol. Another reason might be
or set up a service for other nodes. This is also where because your project is in transition between the two frameworks.
you find the message formats so you can add your These protocols can be used in other fields. For example, if you have a
information for your applications. The documentation number of Kubernets nodes you can have them share information
turtlesim.node < 15.7 «C & 65°C Q37% 06.3 GB
using either YARP or ROS.
matstage@)mats-Ubuntu (192.168.1.6) - byobu The project is open source and available on httpszZ^github.com/
libignition-fuel-toolsl-1 libignition-fuel-toolsl-dev libignition-math4 libignition-
libignition-transpor14 liblgnitlon-transport4-dev libopenal_dev libqtpropertybrowser
robotology/yarp/releases/latest. The project provides ways to install
sdformat-sdf
Use 'sudo apt autoremove' to remove them.
Turtltslm (on rorfoxy)
using Debian packages, or they have their own repository at
0 upgraded. 0 newly installed. 0 to remove and 0 not upgi
ubuntuProsfoxycd ros2_bag_files
bash: cd: ros2_bag_flies: No such file or directory
www.icub.org/ubuntu. Naturally, you can always compile from source
ubuntu^rosfoxy:“$ mkdir ros2_bag_files
ubuntufcrosfoxy:cd ros2_bag_files/
using their git repository. It requires CMake, cmake-curses-gui andg/t
ubuntufcrosfoxy:Zho«e/ubuntu/ros2_bag_files$ ros2 topic J
/parameter.events This framework also has its own visualisation system and plotting
/rosout
/turtle!./cmd.vel functions. The focus with YARP is to use as much of the standard
/turtlel/color.sensor
/turtlel/pose
ubuntu^rosfoxy:/home/ubunlu/ros2 bag filesS ros2 topic e»
GNU tools as possible. There is browser port access, so you can use a
linear:
x: 2.0 browser on one machine to check the stat, along with many other
y: 0.0
z: 0.0 aspects. Discover more about the project at: www.yarp.it/git-master/
ingular:
x: 0.0 index.html. YARP has been tested and have language-specific
Controlling a turtle across the screen is ideal for learning the packages for Python, Java, Lua, MathLab and others.
I fundamentals of robot design.

Ultimate Linux Projects | 27

Ultimate Linux Projects

other tasks. You may also want to use many nodes, You also need nodes to handle things like the wheels,
possible across different types of hardware. For these moving arms and drivers for hardware.
reasons we would advise setting up a separate Advanced tasks that you’ll need to put into a node
environment for ROS whenever possible, rather than include: navigation, image processing and machine­
use your main system. learning tasks. Some machine learning will already be
You might as well start running it in different on board, while other such tasks must run on separate
machines, even if they are virtual. The communication servers, or even in the cloud - it’s cheaper and more
will be between machines; this makes simulation more doable than you think! Your main tools for running a
accurate. You can find a Linux container solution on the ROS system are roslaunch , rosrun and roscore .
ROS website. The basic idea is that you install Ubuntu In reality, you’ll start the system with the roscore
and add ROS to the image when it’s running. command and then run a package at a time with
When you use a container you won’t experience rosrun. The roslaunch command will run all your
problems with dependencies on other parts of your nodes using an XML-based file with the launch
system. See the NixOS boxout (be/ow) for more on this. extension. The API for the files isn’t stable though, so be
careful with upgrades if you decide to use this tool.
Building blocks These are the tools you’ll run while exploring the ROS
The full install includes many planning tools and the system. They'll run many other tools that are specific
emulators/simulators for testing without hardware. As for your current task. Turtlesim is one, and you run that
we mentioned earlier, the main function of ROS is to with ros2 run turtlesim turtlesim_node . If you look
establish the communication protocols between nodes. for more things to run, just type the same thing but use
tab after ...run and you’ll see what exists.
File Plugins Running Perspectives Help Once the nodes are running, you need to control
Service Caller D C R ? -OX Service Type Browser elements of the robot and manage communications.
Service: action msgs
p
Service /ComponentManager/_container/load_node Call You saw a little bit about the communication system
Tree Type Path
p Request earlier - here it is in more detail. Each node will run one
Topic Type
o /ComponentManager/_container/load_node compositionJnterfaces/srv/LoadNode
or all of the following:
package_name string
plugin_name string
node name string > Services
nodenamespace string
logjevel uint8 A service sits ready to answer a request from another
remaprules sequence<string>
parameters sequence<rcl_interfaces/Parameter> node. The content of the messages cover values such as
s extra_arguments sequence<rcljnterfaces/Parameter>
a goal, diagnostic values and the state of movements.
You can also pick up information from different sensors,
Response
y
Field Type Value
both the function of the robot and position using GPS
and the other environment sensors that help your robot
The RQT displays the Format oF all the messages that you can create, along with all available complete its task.
I services states. If your node needs this information, you need to set
up a service client that asks for this information. The
node will then process it and send other messages.
» RUNNING WITH NIXOS When there’s data that other parts of the system need
to know about, you create a publisher in your node that
For fans of the NixOS and its package manager, there's also a way to updates a topic. Any node that needs the information
set the whole ROS system up using NIX. Most of the problems with subscribes to the topic. Those nodes then receive
revisions, particularly those involving libraries, are solved with NixOS notifications all at once when the publisher sends it.
so it enables you to keep a clean system while using ROS. There's a Most of these will serve streaming data. The ROS
solution available at https:Z<aira.life and http:Z^robonomics.network. implementation isn’t designed to know what data is
You can clone this repository and pick anything from the whole ROS sent - that’s for the implementation to take care of.
project. Even if you are using other distributions, you can use this
approach to create a development environment. Learn more at > Nodes
https:Z^bitly/lxf272aira. Each node has a specific task. In your average robot,
If you want to develop with Python, you can always add that in the you’ll need to control wheels, view the surroundings and
call to the shell that you’ll eventually run. It’s as simple as using the interpret the data to take appropriate action. Each part
add option to the nix-channel command. You can also make this & 51°C Q 14% Q4.7 GB
turtlesim node < 13.8 °C

work in a directory where the nix-shell command runs. In this case, matstageQmats-Ubuntu (192.168.1.6) - byobu

you can have different libraries in different directories. It’s equivalent atstageGmats-Ubuntu: $ Ixc ubuntu rosFoxy
huntu@rosfoxyros2 run turtlesim Turtl«Slm (on rosfoxy)

raw_square mimic turtle_teleop_ke

to having a virtual environment when using Python in other projects. ubuntuC osToxy:~$ ros2 run turtlesim draw_square
[INFO] [1606051389.414215920] [draw_square]: New goal

If you want to contribute your own code, you should fork the code [INFO] [1606051391.352713512] [draw_square]: Reached g
[INFO] [1606051391.352939656] [draw_square]: New goal
[INFO] [1606051395.288713655] [draw_square]: Reached g
and clone your own fork. If you want to contribute any changes, you [INFO] [1606051395.288813303] [dr8w_square]: New goal
[INFO] [1606051397.224753652] [draw_square]: Reached g

can raise a Pull Request to the project. Under NixOS, this works from [INFO] [1606051397.224838475] [draw_square]: New goal
[INFO] [1606051401.160857518] [draw_square]: Reached g
[INFO] [1606051401.160952710] [draw_square]: New goal
any git repository. You can find the current status and progress of the [INFO] [1606051403.096844888] [draw_square]: Reached g
[INFO] [1606051403.096963506] [draw_square]: New goal

project at https:Z^hydra.aira.life/project/aira/channel/latest. The [INFO] [1606051407.032879320] [draw_square]: Reached g

[INFO] [1606051407.032994070] [draw_square]: New goal
[INFO] [1606051408.968966700] [draw_square]: Reached g
name is an acronym that spells out: AUTONOMOUS INTELLIGENT [INFO] [1606051408.969101832] [draw_square]: New goal
[INFO] [1606051412.905008999] [draw_square]: Reached g

ROBOT AGENT. Much of the technology revolves around block chain [INFO] [1606051412.905151410] [draw.square]: New goal
[INFO] [1606051414.841009756] [draw_square]: Reached g
[INFO] [1606051414.841099205] [draw_square]: New goal
and the Etherium block chain. This gives you the ability to have more □

secure communications. The turtlesim project stems from the Turtlebot company. It uses ROS

I to design its line of robots.

28 Ultimate Linux Projects

 ?ise of the robots IN-DEPTH

turtlesimnode < 29.2’C £ 62’C Q 10% C$6.1 GB £>

will have its own node. Note that you define what a node matstage(3)mats-Ubunt Turtlesim (on rosfoxy) - *

contains; there are no set rules. You must make a node rosdep
ubuntuGrosfoxy: S roslaunch
rosdistrojnigrate_torep!43 roslaunch-deps rosnode

roslaunch roslaunch-complete roslaunch-deps roslaunch-logs

that makes sense to your specific purposes. ubuntmprosfoxy:-S roslaunch

roslaunch roslauncn-complete roslaunch-deps roslaunch-logs
ubuntuf-rosfoxy: S roslaunch turtlesim

The most expected examples are the ones previously Traceback (most recent call last):
File "/usr/bm/roslaunch", line 34, in <module>
import roslaunch

mentioned. For more advanced projects, you’ll be

File "/usr/lib/python3/dist-packages/roslaunch/__ init__ .py", line 62, in <module>
from .scriptapi import ROSLaunch
File ,,/usr/lib/python3/dist-packages/roslaunch/scriptapi.py", line 42. in <module>
import roslaunch.parent
separating the hardware layer of a camera from the Pile ”Zusr/lib/python3/dist-packages/roslauBch/parent.py", line 54, in <module>
import roslaunch.server
Pile "/usr/lib/python3/dist-packages/roslaunch/server.py", line 79, in <module>

interpretation. All these things are already solved for from rosgraphjnsgs.msg import Log
InportError: cannot import name 'Log' from. 'rosgrapn_msgs.msg' (/opt/ros/foxy/lib/python3.8/site-[
ubunttM’rosroxy: S apt show ros-foxy-turtlesim

you, although you may have better solutions. All nodes Package: ros-foxy-turtleslm
Version: 1.2.5-IfocaI.20266911.221305
Priority: optional
Section: misc
communicate using topics and services, and to control Maintainer: Dirk Thomas <dthomas£osrfoundation,org>
Installed-Size: 9246 kB
Depends: Ubc6 (>= 2.14), Ubgcc-sl (>= 3.6). Hbpython3.8 (>= 3.8.2), Hbqt5core5a (>= 5.12.2), 1$ .0.2

the entire system you have the ROS Master, which ros-foxy-fastcdr, Iibqt5gul5, ros-foxy-ament-index-cpp, ros-foxy-geometry-msgs, ros-foxy-rclcpp,
os-foxy-ros-workspace_________________________
jigs,

Homepage

manages all the communication methods. Your node Download-Size: 863 kB

APT-Manual-Installed: no
APT-Sources: http://packages.ros.org/ros2/ubuntu focal/main amd64 Packages

creates the service by informing the ROS Master about

Description: turtlesim is a tool made for teaching ROS and ROS packages,

ubuntu Tosfoxy: S ros2 pkg execuatables turtlesim

usage: ros2 pkg [-h] Call ros2 pkg <co<nnand> -h’ for more detailed usage. ...

it. Using this method, you’ll write all the code to send ros2 pkg: error: argument Call ros2 pkg <command> -h for more detailed usage.: invalid choice: 'execuatables1 (choose from 'create', 'executables', 'list', 'prefix', 'xml'

and receive to topics and services, and never to a

specific IP address. In ROS2, you create components even sent to test all iterations of the system. You can To start the
simulation you
and the code that contains a string, which registers also view plots of the messages and images from any
only have to run
a node. The node code contains the protocols that the cameras. You use this system to ensure your nodes one command. All
node supports and data that it’ll transmit or receive. communicate correctly. It doesn't display the other commands
environment around the robot. need to be run
from other
> Visualisation Rviz shows the robot in action in a simulated
terminals.
You can visualise the robot for several purposes. Ensure environment, including obstacles, forces and even
safe and efficient communication between all nodes. weather. Even more powerful and included in ROS but
Show the robot in its environment and plan the developed independently is Gazebo, which enables you
movements of the body itself. There are different tools to see environments Gazebo is a separate project but is
for each of these jobs, and they come both as command included in R0S2. You can use this software to simulate
line and graphical forms. The command line tools are the robot both visually as it moves around and moves
useful for the basics inside the robot. For the most part, itself. You can also film an environment and
they're for the communication that ROS defines, but superimpose the robot on the live feed.
when you have made enough progress that your robot The ROS package is powerful, yet can also be used
is able to move, you need more advanced kits. by keen amateurs thanks to its many available tools and
When you use the turtlesim program to run the turtle examples. To get used to doing all this work is a
around and you want to log what you're doing, you can challenge worth pursuing but watch out - you’ll spend a
access many commands and have three open terminals lot of time before you can take new strides in robotics.
to do it. You have many debugging tools available, As you work with it, you'll learn many techniques and
beyond those that cmake provides out of the box. A technologies. Remember that this will involve a lot of
graphical way to do things is preferable in most cases. programming. Running your robot around the room will
The tools that are already available in ROS are rqt, rviz be just a small part of your work! E9
and Gazebo. The first gives you drop-down lists to
activate all the parts of the robot and measuring
messages. The second shows the robot while » MICRO-CONTROLLERS
navigating. Combining those two approaches is vital to
reach of your robotics goals. Make sure you practise If you want to use JavaScript and interface directly with Arduino and
these techniques as you become acquainted with ROS. other system-on-chip boards, consider these simpler systems.
They’re designed to interface directly to a large amount of boards,
> Rviz, Rqt & Gazebo including the Arduino, Raspberry Pi and other small boards.
These default packages will be installed with the full Johnny-Five is one popular such framework, which interfaces to
desktop install. They have different purposes and should these boards using JavaScript. The team behind it, Bocoup, has
be used only when needed. Rqt shows the messages partnered with SparkFun to create a kit that you can start playing with
that go between all the services you have in your on delivery. At the website (www.johnny-five.io) is a long list of
system. You can choose a node at a time and analyse examples that demonstrate how you can control and read a long list
what it does. All messages can be broken down and of servos and sensors.
Cylon is another solution - it’s a single NPM module. If you already
File Panels Help rviz2 (on rosfoxy)

(^Interact Move Camera L. J Select Focus Camera

have some JavaScript projects going, this takes minutes to set up and
Create visualization

O Displays
By display type By topic
get started with. It was built using extensions for new hardware and
~ $ Global Options
Fixed Frame map
’ IQ rvizcommon already supports an impressive list of hardware. These include boards,
Background Color ■ 48; 48; 48 IT~I Group
Frame Rate 30
- D rviz_default_plugins
/k Axes
OpenCV and even drones. The libraries are full of code samples, so for
* Q Global Status Warn
O Fixed Frame No tf data. Actual error: ...
Camera
jfl FluidPressure
a simple way to get started with any of the included platforms, this is
- Grid V
► Z Status: Ok
«S> Grid
F2 GridCells
an excellent option. Find out more at www.cylonjs.com.
Reference Frame <Fixed Frame>
Plane Cell Count
Normal Cell Count
10
0
A Illuminance
□ Image
If you’re more into the Go language, look no further than Gobot
A InteractiveMarkers
Cell Size
Une Style
1
Lines
(www.gobot.io). Installation is via the usual Go package system. Use it
Description:
Color
Alpha
□ 160; 160; 164
0.5
with the go get command. As all the others, the first example is a
Plane
► Offset
XY
0; 0; 0
flashing LED on an Arduino. The Gobot supports many other
platforms though, so you have plenty of options as with the others
You can use rviz to view environments and create obstacles For your micro-controllers mentioned here.
I robots to overcome.

Ultimate Linux Projects | 29

Ultimate Linux Projects

XIBO
Okedit: https://xibo.org.

Build a custom digital

signage system
Discover how to create a digital signage display for an open-source
conference using Xibo digital signage and the help of Matt Holder.

ost Linux aficionados will have noticed an

increase in the number of large-format screens

Xibo
in public places, displaying a range of
information. This is called digital signage. In this tutorial
we’ll be looking atX/bo, a flexible system that can be
used to show images, videos, RSS feeds, weather data,
OUR mapping data, tables of information, websites,
EXPERT embedded HTML and more. We’ll demonstrate how to Please provide your credentials
Matt Holder set up a server and client, before finally designing a
has worked in IT layout and scheduling this content.
support for over a The system comprises a server component, which is
decade and has open source, as well as a number of clients for different
always tried to display types. The Windows and Linux clients are both
utilise Linux free and open source, whereas the other platforms are
alongside the paid-for, licenced clients. The server can be self-hosted,
other installed or hosting can be provided by the team themselves.
systems. Before going any further, let’s talk about some of the Login
terminology utilised by the system. Displays is the name
of the device which runs the player software and I Enter your username and password at the login screen.
displays the content. This could be a Windows/Linux
PC, Android device or large-screen TV running Each Region can then display a number of pieces of
QUICK TIP embedded software. Display groups can be used to content within its timeline. These concepts will become
group multiple displays and content can be scheduled clearer as we work our way through this tutorial.
Using PHP
to multiple devices at once. Schedules are then used to
functions,
define when content should appear on Displays. Installing the server
more advanced
Layouts are designed by the end user to define what TheX/bo server utilises a LAMP stack (which refers to
projects can
be carried out.
content should be displayed on specific areas of the the Linux operating system, Apache web server, MySQL
For example, if display. Layouts are then split into Regions and each database server and PHP programming language) as
information is Region contains a playlist. See the diagram (top right), well as other tools to provide messaging between the
held in a dataset which explains the basic concepts of the Xibo digital clients and server. In recent years the entire setup has
about meetings signage system. been wrapped inside Docker containers to make
booked into a installation and updates as simple as possible. The
meeting room, options □ x
server we’ll use to install this on is Ubuntu 20.04, but
then the current Connect Advanced
container systems make the base OS fairly unimportant,
date and time
CMS Address http://localhost
so feel free to work with what you’re most familiar with.
can be used
The software will work equally as well on bare metal
by the CMS to
serve relevant Key 6wWLUqai or in a virtual machine (VM). When used in production,
content to however, a VM wouldn’t necessarily be the most suitable
the player. Local Library /home/matt/snap/xib' Browse choice, especially due to possible issues with video
See https:/' playback using the VM’s drivers.
community. Once the base machine has been installed, open a
Enter the CMS Address, Key, and Local Library Location and click save
xibo.org. terminal, run updates and then install Docker and
uk/t/getting- docker-compose. Commands should be run as root or
started-guide-
prefixed with sudo:
datasets/14149.
I This information is required to configure the client. apt update && apt upgrade

30 | Ultimate Linux Projects

 Build a custom digital signage system TUTORIALS

apt install apt-transport-https ca-certificates curl Layout

software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/
gpg | apt-key add -
add-apt-repository "deb [arch=amd64] https://
download.docker.com/linux/ubuntu $(lsb_release -cs)
stable"
apt install docker-ce
curl -L https://github.com/docker/compose/releases/
download/1.24.1/docker-compose-'uname -s'-'uname
-m' -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
With the prerequisites installed, there are a few steps
required to configure the docker-compose files to enable
the Docker containers to run and communicate with
one another.
mkdir /opt/xibo
This diagram
cd /opt/xibo First, in a web browser, login to the CMS using the explains the
wget -O xibo-docker.tar.gz https://xibo.org.uk/api/ default credentials of xibo_admin and password. concepts of
downloads/cms Navigate to the Settings tab and copy the key from the the Xibo digital
tar -strip-components=l -zxvf xibo-docker.tar.gz CMS Secret Key field. The player can be opened from signage system.

cp config.env.template config.env the Desktop or from a terminal, by entering xibo-player.

nano config.env The first time this is opened, the configuration screen
On the relevant line, enter a strong password for the will load. Enter the URL of the CMS (server) component,
MySQL database and configure any other required paste the value from the CMS for the Key and a location
options. Find out more about the docker-compose file that the client can use to save files to (see screenshot,
here: https:/7xibo.org.uk/docs/setup/xibo-cms-with- left). The information shown in the screenshot is
docker-on-ubuntu-18-04#create_config.env_file. required to configure the client.
Next, bring up the containers using docker-compose When selecting the Save option, the client will QUICK TIP
up -d and allow Docker to complete its work. The server contact the server, which will report back that the
has now been installed and the server can be Display isn’t currently registered. Now, back in the web The new third
version of Xibo,
accessed from your favourite browser, by entering browser, navigate to the Displays tab and one entry will
released earlier
http://IP_ADDRESS_OF_XIBO_SERVER - enter your be shown. On the right-hand side of the screen, select
in February
username and password at the login screen. the Options menu and then click Authorise. Finally, back
2021, contains
at the client click Save and the client will report that the lots of exciting
The player Display is active and ready to start. The options screen Features,
There are open source players for Windows and Linux can then be closed and when the client is opened again including
as well as paid-for options for other platforms as well, the default layout will be displayed (see screenshot, interactivity,
such as Android, Tizen and Web OS. In this article we’ll previous page). Once configured, the client will Folders to
install the player on Ubuntu 20.10. The Xibo team uses download the files required for the default layout. These store media,

Canonical’s Snap packaging system, which makes the will then be displayed. reworking of
permissions
installation of the client straightforward and updates are
and support
applied automatically. Again, back in the terminal the Conference time For sending
client can be installed by entering: The example that we’ll be walking through are displays
commands
$ snap install xibo-player --channel=stable that could be set up around a conference venue. The viaRS232.
To enable the client to communicate with the server, layout (see diagram above) will contain a title in
there are a couple of steps that need to be followed. Region 1, text in Region 2 which will relate to videos and

» LINUX PLAYER OPTIONS

Once the initial configuration of the client has option is useful because a display can be set Muninfo invaM Fites
Statui Screen

been carried out, further options are set to shut down at a certain time of day. General Info:
Date-2021-May-05 19:52:01

from the CMS. To access these options, When the client is loaded, press the I key Version -1.8-R6
Code Version -108
Content Management System - h11p://localhost

navigate to the Display Settings and either and then the information screen will load. Storage Selected - 7home/matt/snap/xibo-player/108/Xibo"
Display Name - Display
Screen Size:-1692x919
change the relevant profile or create a new This provides access to diagnostic ScreenShot Request Interval - 0 minutes

CMS Info:
one, which can be assigned to a particular information such as media that’s being Registered - true
Checked at - 2021-May-05 19.51:55

Display. Within the Display Settings a range downloaded, if there are any invalid files and Required Files - 27

Schedule Info:
of features can be changed, such as the gives the option to exit the player without it Last Update - 2021-May-05 01:03:00
Current Layout -1
Scheduled Layouts •
interval between the client collecting being reloaded automatically. Because Valid Layouts • 1
Invalid Layouts -

information from the server, the size and clients are devices that need to run for large XMR Info:
Host • tcpy/cms.example.org:9505

position of the player window (the default is proportions of the day, should an error occur Last heartbeat • not-a-date-time
Last message - not-a-date-time

full screen) and whether shell commands then the default behaviour is for the player to
can be executed by the player. The latter reload itself automatically. Pressing I when in the client brings up a

■ status screen.

Ultimate Linux Projects | 31

Ultimate Linux Projects

images in Region 3. Region 4 will contain a scrolling the changes that have been made to the layout, set a
ticker of an open-source RSS feed. light background colour or upload a background image
Before creating the example, we should investigate by using the options in the right-hand panel.
the GUI (see below). 1) Layouts are scheduled at a date Before carrying on with the setup of the digital
and time. 2) Layouts are created here. 3) Media is signage, it’s a good idea to take stock of what has been
managed here. 4) Displays are managed here. accomplished. So far, the server/CMS has been
Back in the web browser, login to theX/bo digital installed, the client has been installed and configured to
signage CMS, navigate to the Layouts section and communicate with the server, and the basic Layout has
create a new one. Once a name has been entered, the been set up with the correct number of Regions. In the
defaults should suffice. When created, the Layout editor next step, the Regions will be populated with
will open. The first step is to resize the default Region, information and finally the Layout can be scheduled and
which is created by default. Select the option to edit then viewed on the player.
Regions, which looks like an image of a pencil and
notebook, and use the drag handles to resize the orange Establish your Region
rectangle. Add further Regions to the layout, so that the To start with, the top Region will be populated with a
image in the diagram has been replicated and four title. Add the title into Region 1 by selecting the icon that
Regions exist within. shows four squares, click the plus on the Text widget
Regions can be set to loop, which is useful when they and then select Region 1 in the playlist editor. Select the
contain certain types of content. To do this, select the Edit icon on the text item and enter a name for the
Region and then read the guidance before deciding conference as well as formatting the text. When
whether to enable the loop option or not. Before saving completed, select Save (see screenshot, below right).
When editing Regions, options appear on the right-hand
There are Four
key areas in the
© D localhost/statusdashboard side of the preview. This is an example of the options
CMS' interface [see associated with the text widget.
Dashboard
below For detailsl The next step is to add an RSS feed of Linux news to
Schedule 1 the bottom Region. This is very similar to entering text,
0 but requires the usage of the Ticker widget. This widget
Dayparting
Display
is formatted from the configuration panel in the top­
DESIGN
right of the Layout editor. The defaults should suffice on
Campaigns the General tab. On the Configuration tab select the
d Bandwidth Usage (B)
Layouts 2
Feed URL field and add the link to a suitable RSS feed.
1.0
On the Templates tab, select Title Only and finally, on
0.8
Templates
06 the appearance tab, select Marquee Left. When these
Resolutions 04
changes have been made, save the changes.
0.2

LIBRARY cn 0 One of the many powerful things about Xibo is the

-0.2 ability to schedule content in two different Regions that
Playlists -0.4
-0.6
can change at the same time. This will be useful for the
Layouts are Media 3

□ scheduled at a
date and time to DataSets
-08
-1.0
March
final part of this tutorial because we’re going to
populate the final two Regions with textual information
show on a display. on the left-hand side and a video and image on the
DISPLAYS
0 Display Activity right-hand side. The textual information will relate to
Layouts are Displays A
the video being shown. When the video changes to a
created here.
Display Groups Display Logged In second piece of content, the text should also change at
Display Settings No data available in tabl
the same time.
Media is
managed here. The content that we’ll be adding is a video of Big
Player Versions
Showing 0 to 0 of 0 entries Buck Bunny as well as some information about it. The
Displays are second piece of content will be a photograph of Linus
About Manual
managed here. Torvalds, as well as some information about him and the

»D0 MORE WITH XIBO

As well as the media formats that have dataset objects. These data can be to multiple layouts. When multiple
been discussed, Xibo can utilise a large displayed by means of a ticker, table view layouts are scheduled at the same time
range of resources to create effective or chart view. Information from other they can either play sequentially or one
digital signage displays. Audio files can websites can also be embedded using can be configured to have priority. In this
be loaded as background music, calendar the Embedded HTML widget. When using way an urgent layout can be displayed for
items can be read from, for example, a this though, make sure you have a short period of time before normal
Google Calendar, countdown times can permission to display information from scheduling is resumed.
be displayed and clocks can be added to another source. Campaigns are used to group together
alert the user to the current time. While not strictly a media type, a number of layouts and these can then
Looking at more data-oriented items playlists are an incredibly powerful be scheduled in one operation, rather
now, currency trackers can be added as feature as these enable a previously than having to spend time scheduling
well as displaying data from the tabular configured timeline of items to be added multiple layouts separately.

32 Ultimate Linux Projects

 Build a custom digital signage system TUTORIALS

Linux kernel. First of all, download a Creative Commons Xibo’

licenced photo of Linus Torvalds as well as the Big Buck
Bunny film from https:Z6download.blender.org/demo/
movies/BBB. powered by...
To add the video, select the Region you wish to
display it from, and from the toolbox at the bottom, Xibo Digital Signage
hover over the video button and then use the Grab
option to drag it to the Region you wish it to appear in.
Edit this Default Layout to personalise or create your own to assign
At this stage, it’s important to know the length of the
to your displays!
video file so that you can set the timing for the text in
the adjacent Region to be the same.

Add text to your display

To add some text, grab some from a suitable source and
store it temporarily in a text file. To add this to Xibo, Once configured,
select the Region from the Region editor and then do so, click the back arrow button, which is underneath the client will
download the files
navigate to the Text button. Again, use the Grab button the Region editing preview. This will then display an
required for the
to drag this to the relevant Region. When the Text widget overview of the entire layout. Simply selecting the Play default layout.
has been added, set the duration to be the same as that icon will show a preview in the browser. Please note that These will then
of the video file and click the pencil icon on the left of not all content can be previewed in this way. be displayed.

the Options panel. Paste the content into this Region Once the layout has been completed, the final stage
and then format appropriately, before saving the Region is to use the Actions option at the top of the screen to
settings on the right-hand side. Add a marquee effect to publish the Layout. This means that the changes will be QUICK TIP
the Region if you want the text to scroll. saved and ready to be displayed. When making further
These previous steps can now essentially be changes to the layout, these can be saved part-way The default
credentials For
repeated. With the Layout design tool, select the same through and then published at a later time. Also,
the server are
Region that contains the video of Big Buck Bunny. From publishing changes can be made on a schedule, which
xibo.admin
the Widget selection tool at the bottom of the screen, can come in very handy.
and password.
select Image and use the grab handle to drag this to The final stage in the process is to schedule the The password
the selected Region. When asked, select Add Files to Layout to the display. To complete this, on the left-hand should be
select the photograph to be uploaded. When a side select Schedule and add a new entry. When the changed after
thumbnail appears in the Upload media window, click pop-up loads add the Layout, select the Display, Layout First login and
Start Upload. Now click Done and you’ll see that in the and select the date and time options for the Display. can be done
Region in question there are now two items: a video and Use the option to save the schedule addition and this so by selecting

an image (you may need to scroll to the right). Select can be seen on the calendar (make sure to select the the avatar in
the top right­
the image, click ‘Set a duration’ and set this to 60 before Display in the option at the top of the screen if the
hand corner
saving the Region. calendar appears empty).
and selecting
Now select the adjacent Region and use the grab Now, moving back to the Desktop, open the Xibo Edit Profile.
handle on the Text widget to drag it to the Region. This player and within a couple of minutes the content will be
Region will then contain two text widgets. Make sure you downloaded and displayed on the player.
check that the text widgets appear in the correct order So far we’ve merely scratched the surface of what
and therefore match the order of the content in the this digital signage system is capable of. For some more
other Region. If necessary this can be changed by advanced things to try, look at using datasets to display
When editing
dragging the order. With the final text widget selected, table data (datasets can also be used in a ticker) and Regions, options
set a duration of 60 again and then use the pencil icon the use of PHP functions to display certain parts of the appear on the
on the Region preview to enable Edit mode, where you dataset data, based on the date and time. For further right side of the

information, the Xibo team has spent a considerable preview. This is an

can paste in your content and format. As before, set a
example of
marquee effect if the text should move in your Region. amount of time crafting documentation to support all the options
Now that the content has all been added to the users with the software. This can be found at associated with
layout, this can be previewed within the web browser. To https:Z<xibo.org.uk/manual/en/index.html.E3 the text widget.

Edit Text
General Templates» Effect

Name

An optional name for this widget

Amazing Open Source Conference Set a duration?

Select to provide a specific duration for this Widget

Enable Stats Inherit

Collection?
Enable the collection of Proof of Play statistics for this Widget. Ensure
that Enable Stats Collection’ is set to On' in the Display Settings.

Library Snippets Save

Ultimate Linux Projects | 33

Ultimate Linux Projects

SOFTWARE DEFINED RADIO

Decode signals From

weather satellites
Weather satellites transmit signals that you can receive and decode
to generate images of the Earth. Mike Bedford shows you how.

atellite-based images of the Earth showing most are no longer operational, including NOAA-16 and

O cloud cover have been a regular sight in TV

weather broadcasts since the TIROS 1 satellite
NOAA-17 even though they were launched after
NOAA-15. However, NOAA-15 has been experiencing
launched in 1960. Yet while the end result is familiar,
technology that brings us those images is much less
the
operational problems since 2019 so there are no
guarantees that you’ll be able to receive and decode its
well-appreciated. If you want to learn about the transmissions, even though we had no difficulties.
technology involved, though, it’s not too difficult to get a There’s also an NOAA-20, but this is the first of a new
basic understanding. generation of polar orbiting satellites. It transmits on a
Mike Bedford However, you can gain some hands-on experience, as much higher frequency which makes it significantly
is fascinated by we demonstrate here, and a practical approach is often more difficult to receive. For that reason, decoding
receiving signals one of the best ways of learning. So, we’ll show you how software probably won’t be too plentiful, although one
from weather to receive the radio signals transmitted by these offering is reportedly available at an alpha testing stage.
satellites and satellites and how to decode that data to generate The laws of gravity dictate that any Earth satellite
processing pictures. In addition, we’ll also investigate some ways of has a velocity and hence also an orbital period, which
the data to image processing to improve that image and perhaps depends on its altitude. This means that the launch and
generate images. introduce some false colour into the inherently fine-tuning of its altitude is critical to ensuring that it
monochrome images transmitted by the satellites. orbits the Earth in the time that was intended by its
designers. Specifically, the closer a satellite is to the
NOAA satellites surface of the Earth, the faster it orbits.
Here we’re going to be looking at the NOAA polar Let’s take the example of a satellite at an altitude of
QUICK TIP
orbiting satellites - NOAA-15, NOAA-18 and NOAA-19 - 35,786km. It'll orbit the Earth every 24 hours so, if it’s in
Since the NOAA that are operated by America’s National Oceanic and an equatorial orbit, travelling in the same direction as
polar orbiting the Earth's rotation, it’ll appear to be stationary above a
Atmospheric Administration. We’ve chosen these
satellites orbit
satellites because they orbit the Earth at an altitude of particular point on the planet. This is referred to as a
at only 850km
just 850km. Since they aren't too far above our heads, geostationary orbit and there are geostationary weather
and you can
easily receive
their radio signals are quite strong and easy to receive. satellites, for example NOAA’s GEOS-15, GEOS-16 and
their radio If you’re wondering why the satellite numbers aren’t GEOS-17. Turning to our main theme of the polar orbiting
signals, you contiguous, all satellites from NOAA-6 have existed but NOAA satellites, their 850km altitude means that they
might wonder orbit the Earth just over 14 times every 24 hours. As the
if you can name suggests, the orbits of these particular satellites
see the NOAA take them over both the poles. However, most
polar orbiting importantly, because the Earth is rotating below them,
satellites by every orbit is shifted in such a way that it passes over a
looking at the
different swathe of the Earth’s surface compared to the
sky. According
previous orbit. This arrangement enables each satellite
to the NOAA,
they are
to obtain images from any point on the Earth’s surface
considered twice each day: once during daylight and once at night.
naked eye
objects but only Is it still raining?
just. In practice, That’s enough background for now, so let’s take a look at
therefore, how to receive signals from these satellites. Not too long
you’re only ago you’d have needed to buy a radio receiver that
going to see covered the frequencies used by the NOAA polar orbiting
them in dark
Launched in 1998, NOAA-15 is still mostly operational, despite it having satellites, but now you can use so-called Web SDRs,
rural areas.
I had a design lifetime of just two years. CREDIT: NASA which are radio receivers hosted on the Web. Take a look

34 | Ultimate Linux Projects

 Decode signals from weather satellites TUTORIALS

satellites will be receivable at your selected Web SDR so

Current Position of NOAA-15
Sun, 15 Nov 2020 15:05:44 GMT (15:05:44 local time) it’s a good idea to use an orbit predictor to find out QUICK TIP
Current Location 90E 71 5S
when one of the satellites will be flying close to the Although it’s
receiver - see www.amsat.org/track. Satellites don’t easy to receive
have to be flying above the receiver - they’ll be signals From the
receivable on orbits that are displaced east or west by a low-altitude
thousand kilometres or more. You’ll soon learn to NOAA satellites,

recognise a satellite signal from its shape on the you might like
to see photos
waterfall display and from its pulsing sound.
From the much
Now it’s time to acquire some data from a satellite,
more distant
so make sure you’re on the correct frequency before
geostationary
you expect the satellite to come into range. Although weather
the signal will be strongest at its closest approach, you’ll satellites.
be able to receive a reasonable signal for several Near real-time
minutes before and after that point. You’ll probably also images are
Using a satellite prediction utility means you’ll know when each of the prefer to record signals when it’s daylight at the receiver plentiFul. See,

I three NOAA polar orbiting satellites is due to Fly close to any Web SDR. location, although this isn’t essential because the
satellites are able to acquire images in spectral bands
For example,
www.star.
nesdis.noaa.
at www.websdr.org, which acts as a directory to these other than visible light.
gov/GOES,
online receivers. For each there’s information on the Once you can see and hear the signal, click Start next
which hosts
receiver’s location, a list of the frequency bands covered to Audio recording and, after the signal has been lost, images From
and a link that takes you to that receiver. The ones of click Stop. We got an error message telling us that our the NOAA’s
interest are those that cover the 137MHz satellite band, browser didn’t support downloading of recordings but geostationary
which is in the VHF part of the radio spectrum, but these this wasn't true. Having stopped the recording, click the weather
are the exception rather than the rule since most adjacent download link to grab a copy of the recording. ^satellites.______
concentrate on the amateur radio bands.
You’d probably prefer to use a receiver close to your Decoding signals
own location so you’ll be receiving images of your locale. We’re about to look at how to decode the signals you’ve
If you're based in the UK the closest we found is the one recorded from NOAA satellites, but first a bit more
at http:Z'erc-websdr.esa.int, which is based at the theory. It might seem surprising - but perhaps less so
European Space Research and Technology Centre at when we bear in mind that the current NOAA polar
Noordwijkin in the Netherlands. We only found one in orbiting satellites are the last of a series that first
the US - http:/7websdr2.K3FEF.com:8902 - which is in entered operation in 1979, well before broadcast TV
Milford, Pennsylvania. There are also Web SDRs in migrated to digital - but our satellites of interest
Germany and Russia that cover the 137MHz band. transmit analogue signals. To clarify what we mean by
Your first task is to become familiar with your Web that, like old analogue TV, the image is discrete
SDR of choice (although most share the same user vertically, but each horizontal line is represented by a
interface) and try receiving some satellite signals. The continuously varying signal. In the case of the NOAA
main part of the user interface is a waterfall display that polar orbiting satellites, the signal is encoded in a
shows signals graphically with the frequency plotted format referred to as APT, which stands for Automatic
horizontally and time vertically. The most recent signals Picture Transmission. In this format, the data for each
appear at the bottom of the display and, since the data
scrolls up continuously, you can always see the previous
few seconds of signals. You should also be able to hear » USE A LOCAL RECEIVER
any signals on the selected frequency audibly, although
with some Web SDRs you have to click a button to If using a remotely hosted Web SDR seems like cheating, it’s possible
enable audio. Note that if you’re using Chrome you to use your own hardware to receive satellite signals. You could put
might find you hear no sound, in which case you will together all the kit you need for as little as £10 plus the cost of some
have to enable sound for the website in Settings. bits and pieces to make the antenna. The secret is to use an SDR: a
To receive the NOAA satellites you should select FM software-defined radio, just like the ones that form the basis of the
as the mode and, because these signals have quite a Web SDR sites. Unlike conventional radio receivers, which need a lot
high bandwidth, you should increase the receiver of analogue hardware, an SDR is little more than an analogue-to-
bandwidth to around 40kHz. Do this by clicking “Wider” digital converter that relies on software to provide most of the
repeatedly, but it’s quicker to drag the sides of the functionality. The SDR of choice is a USB dongle called RTL-SDR, that
yellow “filter” icon just below the waterfall display. You’ll you can read about at www.rtl-sdr.com. The hardware design is open
need to know that NOAA-15, NOAA-18 and NOAA-19 so you’ll be able to find lots of sources but do shop around. The
transmit on 137.6200MHz, 137.9125MHz and software you’ll need is also open source.
137.1000MHz, respectively, and some of the Web SDRs, The other thing you’ll require is an antenna and you can build one
albeit not the one in the Netherlands, help by indicating yourself. The RTL-SDR website has a tutorial on receiving NOAA polar
the frequencies for the various satellites just below the orbiting satellites and included here are links to a few antenna
waterfall display. designs. Alternatively, lots of other antenna designs are available.
However, for best results you might need to fine-tune The designs can be as simple as a basic framework made from PVC
the frequency because the received frequencies will electrical conduit, which supports the active elements that are made
differ from the transmitted frequencies due to Doppler from coaxial cable.
»
shift. At any one time it’s likely that none of the three

Ultimate Linux Projects | 35

Ultimate Linux Projects

scan line is an audio tone at 2.4kHz, which is amplitude together with the licence key. However, given its
modulated with an eight-bit (256-level) signal questionable legal status, we’re recommending a
representing the visible brightness. In other words, the different software package which is called noaa-apt. It’s
brighter the point along the scan line, the louder the free and open source, and you can download it from
audible tone. https:Z4ioaa-aptmbernardi.com.ar.
Two such lines are transmitted each second. There You’d work it out eventually for yourself, but since it
are also periodic synchronisation pulses and telemetry took us a while to manage to display an image, we’ll
data. Taken together, this explains why the signal is provide some brief instructions on how to use noaa-apt.
audible and can be recorded as a WAV file (2.4kHz is If you want to try it out before you’ve recorded any
approximately the fourth D above middle C on a piano satellite signals, you can download a sample recording
keyboard) and why it has a pulsing sound. This audible from https:Zz’projectmarkroland.com/weather-
ATTP data is superimposed onto the 137MHz radio satellite-imaging/N18_4827.zip. Use the larger of the
signal by frequency modulation. two WAV files and note that this zip file also has some
The purpose of the decoding software is to translate images that show what you ought to see when you’ve
the data in the APT signal into an image. One of the best decoded the file.
respected tools to do this job is called WXtolMG. It’s
Here, on the
Noordwijkin
referred to as abandonware, which means that its Start decoding
WebSDR, the signal author no longer supports it and apparently has no The software will start up on the Decoding tab and here
from NOAA-15 interest in it. However, it isn’t open source and, while you need to select the audio file you recorded (or
is clearly visible there was a free version, the full version was licenced downloaded) before clicking Decode. The bar at the
in the waterfall
commercially and requires a licence key. bottom will show progress (it won’t take long) and, on
display, on a
frequency close to Today, enthusiasts are attempting to keep the completion, it'll indicate “Decoded”. Note, though, that
137.1000MHz. software alive by making it available for download, this doesn’t necessarily mean that the file contained
This is a WebSDR receiver, located at the European Space Research and Technology Centre in Noordwijk (JO22FF), Netherlands.
valid data, and if it didn’t you’ll only find out in the next
It is operated by the ESTEC Radio Club PI9ESA More information about the WebSDR project can be found on https sites googk com/ site pi9esa/. step. This is because, even if a valid signal has been
Note: you need both Java and JavaScript enabled for this page to work properly. If you don't hear anything, probably Java is disabled or its version is too old (i.e
decoded, no picture is displayed at this point. So, select
Please log in by typing your name or callsign here (it will be savedfor later visits in a cookie): the Processing tab and click Process. The image should
View: O all bands ' J others slow one band <' blind Allow keyboard:
*
U Waterfall: appear almost immediately and, in the case of the
sample recording file, it should be fairly easy to
recognise the Great Lakes and the Florida peninsula.
• I
137350
We'll describe the characteristics of a displayed
image in more detail later, but first you might like to take
Bandwidth: Waterfall view: a look at the information shown in the panel to the left
40.03 kHz a -6dB; 40.49 kHz 2 -60dB | zoom out 11 zoom in
wider CW-wide LSB j USB AM FM
max out max in
of the image. It shows the name of the satellite and
narrower CW-narrow LSB-nrw
Or dnz the passband edges on the frequency scale.
USB-nrw AM-nrw
Or use scroll wheel and dngzmg on waterfail c either the start or end time and date of the recording.
Speed: | slow v<
Size: [medium v These are noaa-apt's best guesses, based on the file’s
View: waterfall v
time stamp and its filename. For example, the name of a
file we downloaded from the Dutch Web SDR was
websdr_recording_2020-10-31T16_31_24Z_137109.
» THE AVHRR SENSOR 0kHz.wav that shows how, at least in this case, the
necessary data can be deduced. This information is
The NOAA polar orbiting satellites carry an on-board instrument used to calculate the orbit and so add coastlines and
called the Advanced Very High Resolution Radiometer (AVHRR). You national borders to the image, this being an option you
can think of this as a camera, although it’s substantially different from can select a bit lower down in the panel.
regular cameras. In particular, the sensor isn’t a two-dimensional We found that noaa-apt will often guess wrongly. If
array that captures a 2D scene in a single instant. Instead, because this happens you can alter the information manually. If
the satellite is continually moving, it’s necessary only to capture a row you change anything anywhere in this panel, though, the
of pixels at right angles to the flight path. These rows are acquired image won’t change until you click Process again. You’ll
continually and, because the satellite will have moved between any probably notice that the map overlay won’t correspond
two adjacent rows, they'll represent different strips of the Earth’s to the recorded data with the sample audio file, but it
surface. Stacking these strips, therefore, creates a two-dimensional should work correctly with data you record yourself
image. The 2D image is infinite in length, even though the image that subject, perhaps, to altering the identity of the satellite.
can be captured from a receiver at any particular location represents
a limited area due to the range of the radio signal.
Despite it only being necessary to capture a strip of pixels, the
AVHR doesn’t have a sensor containing a row of 2,600 elements, this
being the effective horizontal resolution. More recent sensors do
operate this way, and are referred to as push broom sensors, but the
AVHR, being an older design, utilises a whisk broom sensor. In a
reference to the way a whisk broom or “witch’s broom” is used, the
device scans mechanically back and forth at right angles to the
direction of movement. Using a mirror, it directs the light from
successive points along the horizontal strip to a single sensor for
each spectral band. noaa-apt output of data from the Noordwijkin Web SDR with coastlines

I added. The map is upside down because it was a north-to-south pass.

36 | Ultimate Linux Projects

 Decode signals from weather satellites TUTORIALS

to combine the two images externally to noaa-apt using

image manipulation software such as Gimp. Needless to QUICK TIP
say this will only give an interesting result if the two In addition to
images appear to be substantially different. With the APT signals
satellites that transmit images in more than two transmitted
spectral bands (for example, not the NOAA APT signal), on 137MHz,
it’s common to choose combinations of three of the the NOAA
spectral bands and reproduce them in red, green and polar-orbiting

blue. Although the end result is most definitely not satellites also
transmit a so-
realistic, is does have the potential to produce all
called HRPT
possible colours. With just two spectral bands, though,
(High Resolution
things are different.
Picture
You could choose two primary colours so, for Transmission]
By combining images in two different spectral bands a false colour example, using red and blue would give you those signal at
I image can be generated, making some features more recognisable. colours plus purples, using red and green would give
you those colours plus yellows and oranges, and using
a higher
Frequency oF
Finally, assuming the end result is something you’re green and blue will give you those colours plus shades around 1.7GHz.
satisfied with, don’t forget to save the image to file of turquoise or cyan. None of these options enables The signal

which you can do in the Save tab. white to be represented so you might prefer to go for has a higher
resolution and
one primary colour together with the complementary
dynamic range,
Image processing secondary colour. Those possible combinations are red
and all Five
Although noaa-apt offers a degree of contrast and cyan, green and magenta, or blue and yellow.
spectral bands
enhancement, depending on the lighting at the time the We’re not going to give specific instructions on how are transmitted
satellite acquired its image, and on the strength of the to combine the images in Gimp, or any other package, at all times.
signal when you received it, the image might not be but here’s the gist of it. First, you need to cut out the This signal is
perfect. In that case you could try improving it in photo­ two side-by-side images from the composite photo much harder to
editing software. Improving the brightness and contrast generated by noaa-apt and save them as separate files. receive, though.
is easy, and can make a significant difference. However, Now, convert those files from monochrome to RGB
the Curves feature that’s available in many image­ images and colourise them in your selected colours (in
editing packages can make an even more dramatic Gimp you’d do that by adding a separate layer filled with
difference very easily. If you’ve never used this feature your selected colour as the top layer and use Darken
before it would be worthwhile reading up on it. only as the mode). Finally, load the two colourised Each of NOAA’s
One thing you’ll notice the first time you decode an images as different layers and adjust the transparency geostationary
NOAA polar orbiting satellite image is that you don’t end of the top layer. satellites produce
a true colour
up with one map but two, which are displayed side by Initially you should try a transparency of 50 per cent,
image of almost
side. Both are monochrome, but they’re not identical, but if one of the two colours appears to dominate then half the planet, but
even though they both represent the same area of the you should increase or decrease the transparency of the they’re much more
Earth’s surface. This is because the satellites are able to top layer accordingly. E3 difficult to receive.
acquire images in five spectral bands covering the red/
green portion of the visible spectral, near infrared,
mid-infrared, and two wavelengths of thermal infrared.
However, the bandwidth available at 137MHz is
insufficient to transmit them all, so only two channels
are transmitted at any one time, the selection being
made by ground controllers. Normally, during daylight
hours, one of the photos will be the visible light image.
Because only one visible light band is captured - and
you probably won’t get this at night - it isn’t possible to
generate a true full colour image. However, noaa-apt
does offer a false colour option on the Processing tab
that you can fine-tune using the three threshold sliders.
In reality, it’s not false colour but artificially added colour
that aims to approximate actual colours: blue for water,
white for clouds and green for vegetation.
It’s not clear how this works and, since it’s a fairly
recent addition, information isn’t currently provided. All
we can say is that it uses a form of image analysis to
attempt to identify clouds or the type of ground cover.
Apparently it’s not as good as the false colouring feature
that was provided by WXtolMG so there might be an
opportunity to contribute to this open source project by
helping to enhance this feature.
Another possible way to create a false colour effect -
and here we genuinely do mean false since the colours
will generally bear no resemblance to actual colours - is 15 Nov 2020 15:30Z NOAA/NESDIS/STAR GOES-East GEOCOLOR

Ultimate Linux Projects | 37

Ultimate Linux Projects

SCRIBUS
Credit: www.scribus.net

Aspiring media mogul Nick Peers reveals how to design newsletters,

flyers and more with Scribus, the powerful open-source DTP tool.

ord processors like LibreOffice Writer can do a development version (1.5.7) is on the cusp of replacing

w great job of sprucing up documents, but if

J you’re serious about page design, you can’t
it, so we’ll be focusing on that version in this tutorial.
The PPA version is best for those running the
beat a dedicated desktop publishing tool. Scribus is non-LTS version of Ubuntu, currently 21.04:
capable of producing anything from brochures and $ sudo add-apt-repository ppa:scribus/ppa
flyers to full-blown newsletters, which you can print or $ sudo apt-get update
share digitally via PDF as you see fit. $ sudo apt install scribus-ng
It's packed with powerful tools and options, but in If you’re on the LTS release cycle (Ubuntu 20.04)
Nick Peers this tutorial we'll introduce you to the fundamentals of install Scribus through Flatpak if you have that installed,
has been using Scribus: from changing existing content to or use the portable Applmage if not (https://
dabbling with DTP designing your own documents from scratch. It can be sourceforge.net/projects/scribus/files/scribus-
software since he installed or run several different ways: via Applmage, devel/1.5.7). If you're using Flatpak:
kickstarted his using its own dedicated PPA, or through Flatpak. While $ flatpak install flathub net.scribus.Scribus
writing career in the stable version (1.4.x) is listed as ‘recommended’, it’s Once installed, Scribus can be launched via the Show
- gulp! -1995. been effectively abandoned because the current Applications button. It’ll be described as Scribus (Beta),
but don’t worry - it's as close to stable as you can get.
TAKE THE SCRIBUS TOUR
Fie £dit Jtem ljj
*.eft £«
*ge Table
Scribus 1.5,7

Script
* [/hocne/nkk/Documents/2021/Linux Formit/LXF280.tut_scribu$/familyhhtofynews-2021.sla

Endows fjelp
]
* U
ala *
0 First steps
o e x ■ n
kivninllifii
QStimMAdZB NwnU 5 ♦ 0 NixmjlVHion

w t J it > ii i ir4»N«ii liivimwl* in i w itltMtMitf

On first launch, you'll be taken to the New Document
a®
Text Properties
T. Bftatrearn Mera Serif|
window where you have a choice of four options:
Noinwl
Roman

IT 40.00 pt
Farpily Hist News New Document, New from Template, Open Existing
;T Fixed Linccj). th. photo*, intocviow*. nwwi AoBuit2021 • Imuo

Document, and Open Recent Document. The New

■ 48 00 pt

*X German this Issue

Pfppxtiei
X.y.z
13 (Def*ult Paragraph Style]

\ (Default Character Style]

W17LWIWWBRUW1
Al a glance Pmys war • 2
Document option enables you to create a single blank
Doiument Peue->: Nam« Key tKtS discovered ■ 2

Texin
Colour A Fffrct-.

First Line Off-^t

Supporting rntn • 2
Henry Hiron* in Africa • 3
Tlw Carwrdian connection • 3
page or ‘facing pages’ (a ‘spread’, in publishing parlance).
Geometry into

To start using Scribus, switch to the ‘New From

Orphans and Widow* More cencucd»coveri«s ■ 4
I15S27 mm Paragraph Effects Content

j 19.408 mtn Column* & Teal Distance* war Preview Settings

Y-Pos.

LVldth:
1179-300 mm Vertical Alignment
Columns:
drtaib gleaned bom J
image

Locking
Template’ tab where you’ll see a selection of templates,
117,745 mm wammaVw of Arrey *

split into categories such as books and brochures. Start

Send to
record, rndudmg nranwnl
flotation |o.o*________
Document Layout promotrorw.tr ♦ R4tse Ctrt*HOfne
TOfi!
[□Double sided X Lower Cltl.End Convert to

with a newsletter - pick Newsletter 2 and read through

Base point. Bottom:
FirU Page iv Raise to Top Home Attributes..
Left: ■ i Lower to fiottom
i Right Page Level End Edit
WTWtnoar—i
der tor Inside
the ‘About’ description. It’s a simple black and white A4
‘ a^ht: I ACbS’tf.L wc have been
* * 1 V Properties F2
I able V
to track down
torwetrturr adfpt'zing rfer Arrey Pink's war record from v Content Properties F3
Ut a sapicn Aliquam aliquot the 191418 conflict. The for foreign duty,
XMU5 molcstic dolor. record was discovered a*
part of the British Army WWI
service Records. 1914-1920.
Mote detafe of Percy's war
record along with some
recently uncovered photos
newsletter template where you right-click existing
images and text to change it to your chosen content.
also known as the ’Burnt are revealed on pages 3 anc
Records’ as 60 per cent were 4 of the newsletter. Sadly
lost during bombing raids despite finding
finding Perc/i
— . during the Bitz. record, we were unable tc
Reader for Inside J lhe record confirms much
of what was known of Percy's
locate the service record of
hrs father. Percv Thomas Click OK and you’ll be warned the file was created in
rw f- rw wWUrU. - 1 77.300 irwi x 17.74$ mm >wco\ : ';4 M- * + -X ■ ••• . :.rLneI<| X 139.7M Y. 91.M1 |n»n

Scribus 1.3.3 - click OK again. Next, if the Font

Arrange Pages Page Preview
Substitution box pops up with a warning telling you the

O Use this box to manage the structure of

your document - view, add and remove pages
Q Click the eye icon shown to show the
page without any invisible elements, such as
document’s fonts (Bitstream Vera family) are missing,
then cancel opening the document, close Scribus and
as needed. grids and frames. install the missing fonts via the Terminal:
$ sudo apt install ttf-bitstream-vera
Frame Properties Context-sensitive controls

0 This box enables you to define the frame’s

properties. Use the Shape section to flow other
□ Right-click an object for more options,
including moving it above or below other
Reopen Scribus and create the newsletter template
again - it should now work.
objects around it. elements on the page.

Edit texts
ltem Properties Navigation and view controls

Q Press F3 to tweak the properties of a

selected frame’s contents rather than the
Use these controls to zoom into and out
of the page, as well as move between pages
The main Scribus window will open to show you the first
page of your newsletter. It looks rather bare, so let’s
frame itself. [and layers within a page). start by seeing how you edit existing components.

38 | Ultimate Linux Projects

 Desktop publishing TUTORIALS

Double-click inside the ‘Newsletter Title’ text box, where

you should now be able to edit the text in the usual
manner. Replace this with the title of your newsletter,
then select all the text and look to replace the font with
something more striking.
This is done using the Text Properties box, a floating
window you can bring up via the Windows menu or by
pressing F3. Click the font drop-down at the top to try
an alternative font and size - see the box (below) for
some hints and tips involving font selection.
The Text Properties box has more options too: line
spacing will be relevant when formatting multi-column
text to ensure it all lines up correctly. Anyone who’s
used DTP software should recognise most of the
options on offer - including the tracking and word
spacing controls under Advanced Settings - but for Press F4 (or choose Edit>Styles) to open the Style Use paragraph and
character styles
most people the basics should be sufficient. Manager to define both paragraph and character styles.
to ensure your
Once you’ve formatted your newsletter text, you can Paragraph styles can be defined from scratch, or you text is formatted
move on to the rest of the text. When it comes to longer- can save time by defining common character styles and correctly and
formatted text, directly editing it in the Scribus window applying those to your paragraph styles. consistently.
can be a little fiddly. Instead, click inside the text box Start by selecting Default Character Style and
and press Ctrl+T. This opens the Story Editor window clicking Edit. This is where you can define the default
with the current text on display inside. It’s similar to font that can be used to build your paragraph styles
your word processor, with one key difference - on the down to the smallest detail. Once done, click Apply -
left you'll see each paragraph is assigned its own any existing text based on that character style will
formatting style: Article First Paragraph, Article automatically update, revealing another advantage of
Following Paragraph, and so on. styles: you can make wholesale changes without having QUICK TIP
to reformat everything from scratch.
Scribus offers
Formating text You can edit existing styles and add new ones of your
a third type of
Consistent formatting is key to creating professional­ own. After choosing your default character style, you frame: Render
looking documents, and this can be achieved by can then start to build out your paragraph styles. As Frames. These
applying styles to entire paragraphs. You can change you'd expect, these add extra elements such as line make it possible
existing styles by right-clicking the current style spacing, margins, tabs and indentation, and text to easily insert
displayed in the left-hand pane and then clicking the alignment. The Paragraph Effects tab is where you can specialist
drop-down menu that pops up to select an alternative, define bullet and number lists, as well as choose drop typesetting,
but how do you edit these styles to fit your own design? caps. The latter is a great tool to draw people’s eye to such as musical

the start of an article. notation and

b aakar medium! w oo pr 2 J 10000% 2 TT 10000% 2 = = = = = I* ♦! [Default paragraph style] • scientific
u MC T. L* K K Ok S.TIo.00% : > None - 100%.
You’ll also see a Character Style tab - you can select
formulas, into
Article First ParaGraph Are you looking for a good tool to view - and perhaps edit - your images easily? While Shotwell might your previously defined character style here, then make
seem like an obvious choice, it’s more geared towards building a library ot images rather than acting as a
guick-and-easy Image viewer. What you need is nomacs.
your document
Default ParaGraph Style The tool bills itself as an “image viewer’, but that docs it a major disservice. It's an excellent choice for adjustments (for example, to choose a different style
viewing single files, or the contents of folders, supporting a wide range of image formats (including
with the aid
and size for a header or other page element) or - if
Photoshop PSD and raw Image files from digital cameras), but It does so much more, you can edit a
photo's metadata for example, plus correct problems with photos courtesy of nomacs' Adjustments menu.
It even throws in a few clever effects, including photo mosaic and tiny planet tools. All in all it’s an of third-party
you're not bothering to use character styles - define
excellent tool to add to your Image editing arsenal.
Default ParaGraph Style
List Header Cet started programs.Visit
this paragraph’s character style from scratch.
Article 1 eadma ParaGraph As always, nomacs is available through ubuntu’s universal repos (and therefore the software centre), but
you’re tied to an older version - for example, Ubuntu 20.04 users would be stuck with version 3.12. A
better bet is to install it through flathub - assuming you have flatpak installed, simply issue the following
https:#wiki.
To speed up the generation of paragraph styles, you
command
Default Paiauiaph Style
Default ParaGraph Style
$ flatpak install flathub org.nomacs.lmageLounge
Press V twice when prompted and wait for Nomacs to install all its required dependencies. Once
scribus.net/
complete, nomacs can be launched via the GNOMF launcher On your first run you’ll be prompted to select

Default Paragraph Style

a language - only English is available, so simply dick OK to find youi self al lhe main nomacs sci een. can also base new styles on existing ones. They'll then canvas/
List Header
Article Leadina ParaGraph
Basic usage
you can view a single Image or load In a folder full of Images, which can be displayed as a slideshow or inherit all the characteristics of that previous style, Help:Manual_
viewed one at a time with the help of an optional Thumbnails panel Out that's not all - nomacs can also
Cui rent Paiaqiaph.
kaLSlii______ 48------------------
Totals:
enabling you to concentrate on defining the Renderframes
____ Chaiv____________ 202_______________ Pdiagiaphs. 40_________ Woids;_____ 2132_______ Chais;______ 12050______

for a guide to
Use the Story Editor to edit and style your text without having to worry characteristics unique to that specific style. You could,
I about the layout, too. for example, define a default paragraph style, then use it
using it.

» DESIGN TIPS AND TRICKS

When it comes to designing a document Readability is key when picking fonts. look to be a little different is your logo or
in Scribus, one rule of thumb applies: less Again, keep the number to a minimum by masthead, although again this should
is more. This means keep things simple using variations from a single font family reflect your document’s overall theme.
for your reader, and prioritising - bold, black, italics and so on - to style A key choice you’ll need to make is
readability and clarity over all else. Start different elements such as headlines or deciding between serif (traditional,
by keeping your page layouts minimal picture captions. established) and sans serif (modern,
and clean, and ensuring page elements Make sure the font family you choose clean) fonts. Which one you choose
don’t crowd each other out. Consider matches your document’s theme - depends on your content, but if you’re
restricting the number of columns on the Comic Sans is rarely the best choice for a still struggling to choose, visit https://bit.
page to just two or three, and make sure work-related or professional document, Iy/lxf280-font-advice to read some
the text flows logically between them. for example. One place where you can expert advice on the subject.

Ultimate Linux Projects 39

Ultimate Linux Projects

to generate additional paragraph styles such as the first File> Preferences>External Tools, which is set to GIMP
QUICK TIP article in a paragraph, or a crosshead - a sub-heading by default), and Embed Image. Selecting this will
Save time within the text itself. Anything specifically defined within convert the image from a link to an actual object within
recreating the new style overrides the style it’s based on. the file. You’d do this if you wanted to share the
frequently document with someone else and not have to worry
used elements: Working with images about including all the images as separate files.
group, then
Our newsletter template has space for a single image.
choose
To fill this with a new image, right-click it and choose Understanding Frames
Windows>
Content>Get image (or press Ctrl+I). The image will be So far we’ve respected the newsletter’s layout and
Scrapbook
to open the
placed full-size within the picture frame, so will require focused on populating it with content. You’ll notice that
Scrapbook adjusting. Right-click the image and expand the Image text and images reside in frames, and that these can be
window. Drag sub-menu where you’ll be able to adjust the frame to moved, resized, rotated and more - press F2 to open
your element on the image or - more likely - resize the image to fit the the Frame Properties window to access these options.
to here to store frame (choose Adjust Image to Frame). This will resize With images, we’ve already seen how we can resize
it securely. Drag the image to fit the frame, while respecting its aspect them to fit inside their frames, leaving some white space
the element out ratio, so there will likely be space below or to the side of beneath or to the side. Complete the job by right­
of the window
the image depending on its aspect ratio. clicking the image again, but this time choosing Imago
to create a
Other options you’ll see include Image Effects (add Adjust Frame to Image. You’ll see the frame now fit
copy to reuse.
up to ten different effects, then tweak each one using around the image, leaving white space beneath it.
the preview to see the effect they’ll have), Edit Image The next step is to move the caption frame so it sits
(opens the image in the image editor you specify under underneath the image again. By default, the template

WORKING WITH FRAMES

lii file £dit gem Insert £oge lable extras yiew Script Windows Help 0I8 ®
x a o Q ffl r H 88 A B / ■ □ 0 ® S D <F n <h x d m / *> e x a n * i q o h < q / # / ✓ e q e ti oa a / a Nomwi - a
ilniiaiiiilttiiiiiiJMiiiiaiiliiiiriiiliiiuiiii miiiiiilaiiinXIIMMI luilllMilli BIMI Jsnil litJl
iImhiimImiiu mIihmm duMMiJnamJamtit Jmia ibIhimiu IiumhuL hiiiiiIiui imiIhium • inmui J tmiuiJunuiUmM
Text Properties

- I Arial

Reguloi

O' VOOpt serf heading here

Insert heading here
J Fixed Linespacing 15.00
AE K ■ 3 = ■ I* *1
& English (UK) -ft Mun th at map or work grvmg the exact famine and disease
jtay. arriving locality of the Caste Dracute Count Dracula had directed me
IS [DefParagraph Stytej "/t morning: as there are no maps of this to go to the Golden Krone
Sd al 6:46. country as yet Io compere wHh Hotel which I found, to my
\ [Default Character Style]
purtete cur ow Ordanoe Survey great delight, to be thoroughly
Maps but I found that Bistntz. old fixhioood for of course I
pOe r>e post town named by Count wanted to see ad 1 coukt of the
J of it from Dracute is a fairly well-known ways of the country
Vertical Alignment Top
“tie I could ptaoo I shall enter here some At every station there wore
CotujQnv 3 4reeU I
of my notes, as they may groups of people, sometmes

MB
pr from the refresh my memory when I talk crowds, and in ail ooctc of
mm jamveo laic over my travois with Mina attire some or mom wore just
Toq- 0 000 mm inaar me 3 May bitfne --ten Munich at hke the peasants at home or
Soiwc 8:36 HM.. on let Moy. arriving those 1 caw comng tnrougn
Bottom- 0.000 mm
^htonony at Vienna cany next morning: bronco and Germany wim
left: 0.000 mm -? the exact snouw nave arrwec at 6:46, short pcKGis. ano round hats,
jc Dracuo. but train was on hour late and homo made trouoers: but
0.000 mm •pe or tw Buaa-Pesm seems a otncrc were very pKturesguo
TabuUtors Jxnparewth wonaemx place from me l read that every known
“ourvey gnmpso wfMcn I got of It from superstition m the wore is
jhat btemtz. me tram and me iiwe i coma ga re rod nto tne norsosnoe 01
Sedoy Count walk through me streets l the carpar ens. as r it were
*re«. known
J feared id 90 very far tom the the centre of some son of
!hece come statin, as we nao arrived tate imaginative wmrpod so my
Jymay and would start as near the stay may be very interesting
y wtwn I talk cur reel dm
* mi pvswblv (Muni, I must *mk ilw Count ell
Cx ■♦■H ■ ji Mina r was on mo dark side of about them>

Set up a text Frame Link text Frames

After opening a blank document, click the text frame If you want to flow text between different frames and/or
button, then click and drag on the page where you’d like the frame pages, you need to create links between them. Select your first
to appear. This can then be resized and moved as required. Press frame and press N - you’ll see the cursor change. Simply place
F3 to bring up the Text Properties box to set other attributes this over your second text frame and click to link them. Repeat the
including text columns (under Columns &. Text Distances). Be sure process for any other frames. You can unlink frames by pressing
to set a gap between columns as shown. the U key instead.
yte^diT^cem insect | [ j.at ■. view >cnpt vyiteowt fltlp

insert Nonr.il d c x a a Q. IU 1 M flf a o / ■

import...
Delete. read ttiui every krr—,
Ji A
jperstlion nmo

rt heading here
Copy-

Tsert he Move
altered into tho t
mo Carpathians, a N<W1M'
X. Y.Z

Apply Matter Page

he centre of some inwqeS
Convert to Master Page rnagmative whirlpr
' x.-Led Mu1 th at iiwpor werk Manage guides... stay may bn very l Geometry
Mey arnving nichat
Manage Page Properties (Mem . I oust ask
• "py nejfl morning as irwffl .vo driving S-Fos: 75 068 mm
‘ jimvea et 6:46. reentry at yfjt about them)
Snap to end rnaig;
Lanhuwkjtu uu mtn Ctu~
* UglSy XPOK 48 906 mm
Maps: nut 11 Snap to Guides 546.
I* F.r 119.063 mm
Is.
4» t got O< It f»o<n
He.ght. 07.801 mm
put
* I
of my notvs m 11 «uy may gi cup' uf pwplv. scmotsnirt ic flotation: *
0.0
f«y Wtfom the mv 1 tat> krowdt ar-d to an serfs of from
4 tkrJ auivvd UW QWf my UaTVIftH A<tll MUmI plUa Sotwo! tfwin wvjust ould Bosepolnf
3 Mly BlitMZ -UR Munich M ma p*asar\ts at horn
* or
:4»paMSM AJ5PM an luMay .wvmg t mw comrg through
; 9 to light on any 31 Vienna twfy Mxt mommg; nca ar>3 Oxmany. wW) m the level
.-pMngtno exact should have anvod at 6 46 pcxcB and round hab I
?d fate?
sCeMb DtecuU DU trail) was an Ituir UW «rw<nad
* but ♦ *
the
spFrm a wwm vary pciaovsti
*
11 rad tut rvwy know map or work giving the exact leads from it into Bukovina-it
jl lo cump«* wth wvrrJwfful pUcv tomthv
•new Surwvy which I get o( it fmm buparsttinn an th
* worn is 1 any locally of the Caetle Dracula has had a vary Rtormy
kjtxJtlMi Bn,btU tfw trail) and tic ItUv I wuM rod kite the liorrotov of as there are no maps of this existence, and ft certainly Dtop SJiadow
nxac.t
! named Dy Count walk tNtugh tM 1 Carpamans as < H wart
icuia country as yet to compare with shows marks of it. Filly years Shape
taivU to go vaQr tig hm thu *
ooftbu of xxnu wit of
I enter here ateton. as w« had amvad late Wht3>oa. 4 SC my this our own Ordance Survey ago a series of great fires took Siiap<- ■_ Fdit 0 00 mm
Jk they may And wood unrt n? rwvar the * w nwo'ikig
y mny rv Maps: but I found that BistrMz. place, which made terrible
ire with Text Flow, n □ n I
! pmory vAben I teX ccrract Inw m pcsirtfo |Mam . I mutt aik the Count an the post town named by Count
*y havoc on five separate
-n wtn Mr e it was on ma oart< so* of )iboutmam> F>ll Rule: O V
i »jti I had wn tut Mstritz. Dracula. Is a fairly well-known occasions. At the very Text now around contour line
twi^H wtwi) we gut to BhtnU
trie wham which is 8 usiy ihtemsMiQ dm I > Count place I shal enter here some beginning of the seventeenth

«i< K- 4- 3
*■1 -H L"
4 -4| ■&jr«ground «n. h- 4-

Make use oF guides Layer Frames

To ensure frames line up correctly, create guides to help -
click and drag from the vertical or horizontal rulers to the left and
B Frames can overlap or be placed one on top of another
thanks to Scribus’s support for layers. Right-click a layer and
top of the page respectively to create them. As you click and drag, choose Level to move it up, down or to the top or bottom of the
you’ll see their exact X or Y position is shown to help you position current pile. This affects how content in other frames is displayed
them precisely. Choose Page>Snap to Guides to help align frames - for example, to flow text around an image, place the image at the
more easily to guides. top, press F2 and set the flow using the Shape tab.

40 | Ultimate Linux Projects

 Desktop publishing 1 UTORIALS

has locked all its frames so they can’t be accidentally Scrlbus 1.5.7 - [Newsletter 1«) - □

file fdit Item Insert Page Table Extras yiew Script vyindows tjelp ;Q|C

moved. To fix this, right-click the frame and choose □ <B x

.10 .2©
lL 0 A
.«o
o C
w
X
oo
■
.70 !» PO !>: 110 n; ,140 .IW .too .100 i»c .000
OH®lil@JiBg<£> Normal • ®
210 2Jt .2>O .?<© .»• 270

Locking>ls Locked. You’ll see the frame change to reveal

ri 1 111111111 ■ 1 11 1111 11 a 11 h 11 < 1 11 11 I ■ 11 11 1 11 1111 1111 11 11 11 11 1 1 ■ 11 11 11 1111 J ! 1 I 11 11 ■ 1 11 11 a 1 11 a 1 11 1 11111111 11 11 1111 1 11 1111 11 a 111 11 11 11 1 11 1 > 11 11 H I i l i 11 1 1111 11 a 1 11 a 111 11 a 11 i 111 11 1 a 11 11 11 11 if 111 a 111 i l 1 i 1 > 11 t 1 11 ll 11 11 II 11 11 11 l 11 II 11 11II 11 II 11 l 11 11 11 11 II 11 11 11 11 I 11 II 11 II 11 11

drag handles - click and drag it to a new location, or use t I- 9"

* t—-
< > *? cjb • v • « r. s □ c y
I
when viewing the images in a
compressed or Office file -
Article 5 Hi
I_ -

the arrow keys to nudge it around the screen. when opening these, the first
image in the list is displayed,
T orem ips urn dolor sit amt
J—iconsectetuer adipiscing

Now’s the perfect time to discover how you can and you can cycle through elit. Ut a sapien. Aliquam ali-
quet purus molest ie dolor. In
them using the arrow keys.
group frames together, so they act as a single object. tis can quickly become teger quis eros ut erat posue
dictum. Curabitur dignissim.
esome, so it's time to stall
Doing so would enable you to move the image and its iloring the nomacs user Integer orci. Fusee vulputate
lacus at ipsum. Quisque in
nterface using its customisable
caption as one: just hold the Shift key as you click each Image Effects... Ctrl+E
libero nec mi laoreet volutpai
.Aliquam eros pede, scelerisq1
Locking Edit Image...
frame you’d like to group and you’ll see the selection Send to Embed Image
quis, tristique cursus, placer,
convallis, velit. Nam condi-
You can customise nomacs' panels to suit Level Update Image
box encompasses all selected frames. You could drag all on the left, with two in tabs

As always, nomacs is availa]

Convert to Adjust Frame to Image
mentum. Nulla ut mauris. Cu
abitur adipiscing, mauris non
Adjust image to Frame
this to a new location, or choose ltem>Grouping>Group through Ubuntu's universal
repos (and therefore the
:ti
Attributes...

Edit
undue pane — i •It
dictum aliquam, arcu risus
dapibus diam, nec sollicitudii
right-click any of the images
to convert them into a single object (you can undo this Software-Centre)-,-but-you'F© —
tied to an older version - for
Yr
J I
jal
Properties
Content Properties
F2
F3
quam erat quis ligula. Aeneai
massa nulla, volutpat eu, ac-
from the same sub-menu, choosing Ungroup instead). example, Ubuntu 20.04 users Microsoft Office document
ksuch as embedded graphics in j You can view
cumsan et, fringilla eget, odi<
would be stuck with version
Next, drag both the headline and the body text 3.12. A better bet is to install it : jWord or PowerPoint) too. a single image
or load in a
throuah flathub - assumino vou ' To select vour first imaae or '
frames beneath so they sit underneath your image Image Frame selected: Size = 117.889 mm x 70.002 mm 125.00% C *=< 14- 4- 2 ♦ of4«>->| ■TemplateLaye ♦ X: 79240 Y: 56.649 100%

(select both, then unlock them and finally move them Scribus makes it easy to fit imported images into an image frame. It’s also possible to embed the
into position). You now have space left over beneath the
text, so select the body text frame to click and drag the
I image directly into the document.

bottom of the frame down to fill the space. You’ll end up Once you’ve started to master page design, you’ll
with room with more text to fill too. want to incorporate those layouts in your own custom QUICKTIP
templates. The box (below) reveals how to build a Want to add
Add more pages template using a series of master pages, which are used page numbers
Once you’ve filled your first page, move on to the next. to pre-populate pages with non-editable content. to your
Each template can support multiple page layouts, and document?
Create a text
our newsletter is no exception. Choose Page>lnsert. You Share your creation
Frame in the
can insert one or more pages after the current page and Your work is complete, and you're ready to print a
usual way, then
choose different master pages for both left and right­ physical copy or export it as a PDF to share digitally. The
choose lnsert>
facing pages. For the purposes of producing a four-page best way to do this is via File>Print Preview or Character>Page
newsletter, insert three pages, choosing InnerPageLeft File>Output Preview (for PDFs). A Preflight Verifier Number or
and InnerPageRight as your page templates. Click OK. window will pop up listing all known errors - including press Ctrl+Shift
Three new pages will be created using the layouts those frames where there’s too much text to fit. Click an +AI t+P. The
you specified, ready for you to populate them with item to jump to it in the document, check over the inserted
content. This is all very straightforward, but only if problem and correct it with some editing if necessary, page number
you’re happy to work within the confines of the then click Check again. will update
automatically
newsletter template itself. In reality, you’ll want to make Alternatively, click Ignore Errors to see how the
if the page is
changes to this layout following the frame tweaks we’ve document will look - you’ll see various additional
moved around.
discussed, or look to make bigger changes by designing options depending on whether you’re printing or
pages yourself - the walkthrough (opposite) reveals exporting to PDF - and finally click Print or Export...
how to create text and image frames from scratch. to complete the job. E9

» BUILD A TEMPLATE
Armed with what you’ve learned in this page) to discover how to populate this Once you’ve got your pages and
tutorial, you can now create your own first cover page with your own design master pages in place, choose File>Save
templates. Before you begin, choose using a combination of image and text as Template, give it a suitable name and
File>Preferences>Paths to specify frames. You can then repeat the process optionally tick More Details to provide
where you’d like to store your templates. for the inside pages - remember to more information about the template.
Once done, click OK and create a new tweak the design for left and right pages.
LXF2a • lArtOmw HMtef M

blank document. Once done, choose Page>Convert to kJ ** s. Uitot I At-

Assuming it’s a multi-page document, Master Page. Give it a suitably descriptive n MH X A M

select Facing Pages, choose your basic name, verify the right type (left or right) 5^’^ © not d
A b*> <*<><• *

attributes (size and orientation) and use is selected and click OK. Master pages 2-

the Margin Guides tab to prevent text make it straightforward to pre-populate

Ar met ■«Vi jw'
yoacuetovtort
©ocumcoc
nk.c amoufi

from running to the edge of the page pages with previously created content
pwMtht tW
ir
tewvq tot ©93*
bfjwtod
Hr

(use one of the Preset Layouts such as when inserting new pages. Just select the Ox*

manc t

Gutenberg or Magazine if you’re not chosen master page from the Insert Page content n
HwcirSyefwoten#
moitoe pogeiceatC)*

sure). Choose 3 or 4 for your pages, dialog and Scribus will do the rest. Note Ton*r4Vo

leaving first page set to Right Page to that content added to master pages can’t
accommodate a cover. Click OK. be edited or removed, so use them for
You’ll be presented with a blank consistent elements, such as a magazine You can record details about your new template -
canvas. Follow the walkthrough (facing title or page numbering. I perfect if you plan to share it with others.

Ultimate Linux Projects | 41

Ultimate Linux Projects

GOOGLE /
Google's free photo storage is a thing of
the past. Jonni Bidwell has some free
software to get your albums in order.

hen invitations to Google’s Later, Google would add free, unlimited There are all manner of other free

w new mail service found

themselves in the hands of
the great unwashed, the
world of free email changed forever.
storage for all your photos and later still,
free storage for up to 50,000 audio files. A
decade later, however, Google discovered
that even with their impressive resources,
storage options, which we’ll cover in this
exhaustive feature. But there’s also no
shortage of open-source solutions that
you can self-host, either at home (for
No longer did users have to make do this was untenable - or perhaps a free) or in the cloud (for cheap). We’ll look
with a handful of megabytes of storage, potential avenue for profit. Google Play at two of these: Nextcloud and Lychee. The
obnoxious adverts and the terrible fear Music shut down at the end of 2020, and former can, of course, do much more
that at any point a connectivity failure from June 2021, users of Google Photos than just photos (it can be a full-blown
would dash the missive you were (nee Picassa) saw new photos count groupware suite) while the latter is a
currently working on into oblivion. Now towards their 15GB storage quota. lightweight solution for hosting photos
users could enjoy 2GB of storage, and At the time of writing, the relevant and hosting them well.
further enjoy watching that quota rise, support page warns that accounts Both of these work can be used locally
ever so slowly, in real time. Yes, there were exceeding their quota for 24 months face or remotely, whether on a rented VPS in
adverts, but they were small and textual. potential file deletion. So if the aggregate the cloud or a Raspberry Pi under your
They were also relevant because they of your Google Drive and Gmail inbox is desk. And if you just want to pay someone
were chosen by algorithms that fed off already approaching that, then perhaps to take care of your photos, then we’ll
the contents of your email. it’s time to take action. look at some of those services, too.

42 Ultimate Linux Projects

 r
J
y J
J
i: 11 11 I |i
Rfr.
F
.J
w
,A
?

four
y J
lit
r L

Ik ■■■
^3 >
LV
J
1

Whether at home or in the cloud, your photos deserve a new host.

et’s not catastrophise - no one’s going to

lose any photos for a couple of years. But
perhaps it’s a timely reminder that things
-X

freely given can be freely taken away.

We should note that photos uploaded in their original
quality have always counted towards the 15GB Google
quota (and will continue to do so). The new rules
concern images uploaded using High and Express
quality compression. So serious photographers are
unlikely to be bothered by this. But for millions of users,
it’s yet another iteration of a Google service becoming
less useful. Of course, if you want to pay for more
storage then Google One will be happy to take your
money (100GB of storage will cost you £15.99 per year).
If you’re willing to part with cash, then there are
much more privacy-conscious, less Google-ey photo
storage offerings. However, if you want to keep costs at
zero, and don’t fancy partitioning your massive photo This feature was
originally written
collection across several different providers (or Google always back up, and if you're serious about backups,
back when you
accounts), keeping each collection carefully within the then you should back up off-site, too. At which point you could upload 20GB
free storage tier, then you may want to consider might start looking at cloud solutions again. Instead of of photography to
abandoning cloud storage altogether. Or more precisely, falling into an infinite loop at this juncture, note that the Google for free.
run your own personal cloud at home. hybrid approach is a reasonable one. Cloud storage and
local storage can be synchronised to mutually mirror
I
> fl
tI ng the ■
□tion one another, and thanks to the Nextcloud Photos mobile

El E
•j ••

We’re all for self-hosted solutions here and it’ll come as app, it's easy to ensure new images from your phone are
no surprise that we’ll be looking at Nextcloud over the automatically added into the mix.
page. It’s easy to set up on your desktop or home server, Virtual private servers (VPSes) with 20GB of storage
and it has superb photo management facilities. If you can be rented for around £5/month. You can even rent a
like, and are prepared to do battle with your router's Raspberry Pi from Mythic Beasts at this price. This
port forwarding configuration, you can make this offers excellent value, since besides hosting your
remotely accessible and enjoy all the utility of Google photos, these offerings give you root access, enabling
Photos without worrying about quotas. Or at least if you you to burden the machine with whatever duties your Scan For Free Magazines

run out of space you can always add more. imagination allows (subject to resource constraints).
Self-hosting comes with a pretty strong caveat We’ve looked at setting up VPSes before, and we’ll cover
though: you're responsible for your data. So you should it again soon. But for now let's get on with the show.

» KEEPING IT SIMPLE
Some people, preferring to avoid looking for a bloat-free back-up solution stored regularly. So you might also
unnecessary thumbnailing, cataloguing, to SSH your photos somewhere safe, consider SyncThing, which will happily
configuring and hosting complications then Duplicity is worth a closer look. It mirror your photo, video and whatever
(and PHP applications), choose to works incrementally, so once the first else files wherever you like. Or you could
manage their photos as regular files. backup is done, only new data is stored, be Puritan hacker about it and have your
Some people feel the same way about meaning subsequent runs are much Devuan box run a Cron job that rsyncs
their music collections, and keep their quicker. It can optionally encrypt data as your local photo store to a secure server
OGGs and FLACs in directory hierarchies well for added privacy (and we’ll look at at an undisclosed location.
according to tempo, chronology, genre this with Nextcloud too). These things can be brought down by
or whatever else suits their purpose. If Duplicity stores backups as archives a stray 7' though, so always check your
this sounds like you and already have though, so you don’t have the immediate backups are doing what they’re meant to
your photos as you like them, but are access to files as you would if they were be through manual inspection.
»

Ultimate Linux Projects 43

Ultimate Linux Projects

Install Nextcloud
Discover how you can tap into the power of Docker Compose to
get Nextcloud up and running in a jiffy just like the professionals.

r i henever our perennial “Escape Google (et doing it on the Pi in LXF272’s smart home office feature).

w al)” feature graces pages, we’re always quick

J to point out the benefits of Nextcloud. It can
Most of the effort expended is in laying the groundwork
- more precisely, installing a web server, database and
handle storage (like Google Drive), chat (like Zoom) PHP and getting them all talking to each other. Once
and, with Collabora Online, even be a full-blown online that LAMP stack is in place it’s all largely plug and play.
office suite. As you may have guessed it can handle Be that as it may, we don't much care for repetition
your photos too, and we’re going to show you how to here so this time we'll look at installing Nextcloud using
get the most out of that feature. Docker. This comes with the advantage that your
It’s entirely possible to set up Nextcloud at home and installation will always be kept up to date and you won’t
access it remotely, but there are a number of reasons to have to worry about maintaining a LAMP stack (or
consider running it in the cloud (not just because it’s in setting it up in an overly permissive manner). If you’re
the name). First, your ISP might let you down at a running Ubuntu (Desktop, Server or Pi) or otherwise,
critical time (imagine trying to show off your photos at then make sure you have the Snap daemon installed.
Tarquin’s dinner party only to be met with a timeout and You could equally well use the Snap image that brings
the cold stares of your peers). Cloud providers (good the same benefits, and means you can skip this next
ones at least) take the flow of packets very seriously. section where we install Docker. Otherwise SSH to your
server (if your installing remotely) and read on.

RUN NEXTCLOUD IN THE CLOUD I Get Docker up and running

The easiest method of installing Docker is to use the
“It’s just nice to have a cloud server official convenience script (it works on Debian,
Raspberry Pi, Fedora and more):
sometimes, because you’ll never $ wget https://get.docker.com -O get-docker.sh
Before running this as root, it would be prudent to
know when they’ll come in handy.” cast your eyes over the script so you know what it’s
doing. Once you’re satisfied, run it with:
$ sudo sh get-docker.sh
Next, you don’t have to worry about your hardware This works on most distributions, and adds the
breaking, or losing your photos if your house burns appropriate repositories so that it’s kept up to date as
down. Many providers offer daily backups for an part of the regular package management process. The
additional fee (as well as having their own redundancy Docker Engine should start automatically after install on
measures to protect against hardware failure on their Debian and Ubuntu, but Fedora users will need to start
If you run Docker side), affording you some peace of mind and covering it and enable it manually with:
Compose without against your own errors too. Finally, it’s just nice to have $ sudo systemctl enable -now docker
the -d switch,
a cloud server sometimes, because you’ll never know At this point you could run:
you can see some
debugging info
when they’ll come in handy. $ sudo docker run -d -p 8080:80 nextcloud
as the containers Setting up Nextcloud from scratch is a slightly and find Nextcloud by pointing your browser at
spring into life. protracted but well-documented affair (we covered port 8080 on that machine,for example
http://localhost:8080 Using the Docker volume directly
like this is fine for testing locally, but since the image
oQo o * a v q
doesn’t provide HTTPS it's not smart to use this on a
remote server, since traffic could be intercepted. In fact,
Nextcloud will do everything in its power to stop you
Good morning, Linux Format using it this way.
We’d recommend reading the documentation at
n jonni@pop-os: ~ https:#github.com/nextcloud/docker/tree/master/.
examples that covers using Docker Compose to link the
jonni@pop-os:~ jonni@pop-os: ■ Nextcloud container (running Apache) to an Nginx
reverse proxy, a Let’s Encrypt certificate updater and a
Set the 'ServerName' directive globally to suppress
^ipp_l [Tue Apr 13 08:16:43.8836C MariaDB database (which will cope much better with
large photo collections than SQLite).
refork:notice] [pid 1] AH00163: Apache/2.4.38 (Debiar
In order to use HTTPS (or use it without generating
onfigured -- resuming normal operations
&pp_l [Tue Apr 13 08:16:43.8838< warnings) you need a domain name. You can get a free
_ __ ___ ■___ *__ -__ ___ 1_____ F__ ___ •__ 1 ai i rx rv /___________________ -_______ _ _ „_ ____ ___ ______ n___ *______ ___________ 1__ _______ ____- I-__ _ '"x i-x r-Z subdomain (of the form linuxformat.duckdns.org) from

44 | Ultimate Linux Projects

 Escape Google Photos

DuckDNS or any number of other Dynamic DNS MYSQL_PASSWORD=passwordl

providers, as well as a script. This will mean that if MYSQL_DATABASE=nextcloud
you’re running Nextcloud at home and your IP address MYSQL_USER=nextcloud
changes, your subdomain record is updated. Finally, we should be able to grab the latest images
Check the latest version of Docker Compose at the and orchestrate everything into action with
releases page (https:Z<github.com/docker/compose/ $ cd -/docker-nextcloud/
releases) and if necessary change the version number $ sudo docker-compose build -pull
below to grab it: $ sudo docker-compose up -d
$ sudo wget https://github.com/docker/compose/ You should find the Nextcloud setup screen by
releases/download/1.29.0/docker-compose- pointing your browser to your host, but don’t be too
Linux-x86_64 -O /usr/local/bin/docker-compose quick - it takes a few seconds to set up everything.
$ sudo chmod +x /usr/local/bin/docker-compose Follow the instructions there to set an administrator
The second command makes the script executable, password, and if you’re feeling Spartan uncheck the box
and so long as /usr/local/bin is in your $PATH, the that installs collaborative tools.
system will be able to run it. We’re going to copy the Note that the database and SSL certificate are all
example Dockerfiles from the official pages, and since automagically preconfigured. As an aside, getting
they span two directories we’ll need to match that. Docker working on an IPv6 only network was an
$ mkdir -p ~/docker-nextcloud/proxy altogether hellish experience when we tried it, so if you
$ cd -/docker-nextcloud/ figure out how that works please do tell us.
$ wget https://github.com/nextcloud/docker/raw/ Over the page, we’ll set up users and finally get to
master/.examples/docker-compose/with-nginx-proxy/ some photo management.
mariadb/apache/docker-compose.yml
We need to modify the reverse proxy container to
allow large uploads. The example also disables request
buffering, so let’s do that too. Create a file -/docker-
nextcloud/proxy/uploadsize.conf with these contents:
client_max_body_size 10G;
proxy_request_buffering off;
Then in the same directory create a file named
Dockerfile to source this:
FROM jwilder/nginx-proxy:alpine
COPY uploadsize.conf /etc/nginx/conf.d/uploadsize.
conf
Before we can compose all these images, we need to
edit the YAML file with the hostname of the machine
running Docker and, optionally, an email address for
Let’s Encrypt. Open the docker-compose.yml file we
downloaded earlier, populate the MYSQL_ROOT_ This problem with the Compose example almost outfoxed us. If you're reading from the future
PASSWORD variable with a strong password and set the
VIRTUAL HOST and LETSENCRYPT HOST variables to, MM
I then it’ll probably be fixed.

say, linuxformat.duckdns.org . There’s one more final

tweak to this file since the Let’s Encrypt companion now » RASPBERRY Pi REVISIONS
requires an additional volume for ACME data. So add
- acme:/etc/acme.sh If you try the above on a Pi you’ll find Docker works but Compose
to the Let’s Encrypt volumes: section and also add the doesn’t. We downloaded an x86 docker-compose binary, when the Pi
acme volume to the list at the end of the file. needs an ARM one. And sadly there’s no official ARM builds yet. To
Now, in the same directory, create a file db.env with remedy this, you can compile Compose yourself, or (much easier)
the contents, ideally using a stronger password than us install the community-composed Compose through Pip, the Python
(this one is for the user, rather than the root, account on module installer:
the database). $ sudo apt install python3-pip__________
$ sudo rm /usr/local/bin/docker-compose
You’ll also find there’s no armhf build of the official MariaDB image,
but that’s okay because the generous humans at linuxconfig.org
provide one, which you can avail yourself of by replacing
with in the docker-compose.yml.
At the time of writing, there’s a slightly bizarre Docker problem on a
few Pi distros (including those based on Debian Buster such as the
official Raspberry Pi OS) involving an outdated libseccomp, which the
Docker Engine depends on. Symptoms of this include dates in
containers being set to 1970 (the Unix epoch) and all kinds of other
things not working. A good solution is to install from the Buster
Nextcloud’s Friendly Welcome screen - note that the SSL certificate Backports repository, as described at https://docs.linuxserver.io/faq
I was generated automatically.

Ultimate Linux Projects | 45

Ultimate Linux Projects

Transfer your photos

Now that Nextcloud is installed and operational, it’s time to get
your photos into it, and out of reaching distance from Google.

ee the three-step guide below to get an 0Q0 O ■ 3 *

archive of your Google Photos. The archive is Bi AU files «

0 Recent

organised by year and includes metadata ★ Favorites

corresponding to each image in the form of Json files. < Shares

These consist of album information, descriptions and Tags

■I Failed Videos < ••• 9

geodata that have been added via Google photos, as | Photos from 1970 247

well as EXIF data from the original images stripped Il Photos from 2003 28

from their downloaded counterparts. | Photos from 7004 26

Extract the archive, taking care to ensure you have ■ Drifted files
| Photos from 200r> 97

8 V GU of 20 GU med
sufficient space. Note that if it’s a huge file and you’re Pliotos from 2006 133
O Swings

extracting it to slow, or network, storage, it’ll take a long Default Qfi a

time to extract. So either make yourself a cup of tea or Linux Format Filled up its corporate Google Drive with server backups -
make enough space on the fastest storage you have to
hand. You still have the original archive, so you can safely
I don’t let them fill up your Nextcloud, too.

delete these once they’re uploaded. password, and click the tick. You’ll be prompted to
Alternatively, you can download images in batches (of confirm with the admin password. Then log out of the
up to 500) or by album from Google Photos without admin account and log back in under your newly created
using the Takeout service. This method seems to retain persona, or repeat this process if you’re planning to
the original images’ metadata. If you click the More Info allow other users onto your instance.
button at step two below, you’ll find the option to transfer
photos to Flickr or Onedrive. There are some other Time-saving tips
commercial alternatives listed in the box overleaf. But Nextcloud’s Photos tool is included in a default
why trade one proprietary service for another when our installation and doesn’t require any further configuration.
Nextcloud container is eager to contain some photos? Any images you upload to your Nextcloud instance will
Before we do that though, it’s good practice to avoid automatically be catalogued by date. A Photos folder
using the administrator account for your data. Instead, containing some sample images is included in every
create a user account by logging in and finding the Users Nextcloud user’s account, but you may as well create a
option from the menu in the top-right. Click the New new folder to rehouse the images you liberated from
user in the top-left, fill in at least a username and Google (or wherever else you’re uploading from). Go to

GETTING YOUR PHOTOS OUT OF GOOGLE ]

sit your Google Account to explore other ways to manage your data, including deleting
2 Choose file type, frequency and destination
i Select data to include ur Account.

Delivery method Export Created on Available until Details

Products

Deselect all Send download link via email Google Photos

11 April 2021 18 April 2021 ♦ Download a,
When your files are ready, you’ll get an email with a download link. You’ll have one week to 1.59 GB
I Google Photos download your files.
’ Your photos and videos from Google Photos. More info
Google Photos
Frequency:

if Multiple formats == All photo albums Included

(•) Export once
Photos
11 April 2021 Export cancelled v
1 export
transfer to Flickr

Show more products Next step Q Export every 2 months for 1 year
Create new export
6 exports

Visit the Takeout | Customise Download

O Log in to Google Photos and then go
to the Settings page by clicking the cog
You can restrict the archive to
certain years and, if you like, download
Google will give you a link that’s valid
for a week. If you like, you can opt to
icon in the top left. Scroll down to the data from other Google Services. Takeout download over the course of a year, getting
Export your Data section, and then click it offers a choice of .zip or .tar.gz archives, a new link every two months. Hit the Export
to reveal the option to back up an archive of and if you like to be different you’ll button and be appalled that it will take
your data. Click Backup to open Google probably choose the latter. The archive, Google “hours or days” to prepare your
Takeout. It’s not an eatery, unfortunately, which you can choose to split into export. You’ll get an email when it’s ready,
but rather Google’s tool for extracting your same-sized chunks, will then be prepared so in the meantime you might want to
data from its services. by Google robots. make some space.

46 | Ultimate Linux Projects

 Escape Google Photos

Nextcloud’s Files tool and click

the + to do this. If you’re
feeling organised, you might
want to do some photo
housekeeping before you
upload, for example adding
directories according to trips
or lockdowns, repositioning
any misdated images (and
correcting their EXIF data if
you’re really keen). Otherwise
we already have them
arranged by year so you could
at this point try and drag the
whole Google Photos folder
(on your local machine) into
the newly created Nextcloud
folder (in the browser).
Once your photos
Nextcloud threw a handful of scary-looking “deadlock” user. If you’re the only user then set this to just below are uploaded, you
warnings, but despite having over a gigabyte of files how much space is actually available, so that there’s are Free to Fall into
dropped on it the progress bar steadfastly made its way some wiggle-room if the quota is reached. By default the a nostalgic image­
scrolling reverie.
to 100 per cent. tool will only upload on unmetered Wi-Fi connections,
but you can change this if you want your photos in the
Android uploads cloud sooner.
The official Nextcloud Android too\ is available from the It's not so easy to automate uploads from regular
F-Droid store, as well as Google's and Apple’s own digital cameras, but seasoned photographers will be
shopfronts. Just point it to your Nextcloud instance and used to the copying-from-the-SD-card-and-uploading
enter your credentials to get instant access to all your drill. They might also be interested in the RAW plugin for
photos (and other files). You can browse any images Nextcloud that enables RAW files to be previewed
uploaded there by date from the Media section, which is directly in your browser, rather than having to download
easier than squinting at thumbnails. them and open them with GIMP.
In the Auto upload section in the Settings page There's plenty of things you can do with your photos
(available from the hamburger (=) menu) you can opt to once they’re uploaded. First, you’ll enjoy just browsing
synchronise any media folders on your device, including through them. The Photos tool lists them by upload date
Screenshots, WhatsApp Images and the excruciatingly initially, and since they were all uploaded on the same
titled Camera Roll. If you do this then you’ll never need to day and probably not in chronological order, that may
worry about manually transferring photos off your phone not much use. That’s okay though, just choose the Your
again. They'll all be beamed up to your Nextcloud as Folders option and at least they’ll be organised according
soon as you're in reach of a network connection. to the directory structure Google provided. Thumbnails
Well, that’s the theory anyway. A few things could go are generated on the fly, so the first time you browse a
wrong. If your Nextcloud instance runs out of disk space new set of images there will be a slight delay in rendering
then it’ll probably stop working. If things go really wrong, them. You can also add comments and even tag fellow
then you might not be able to log in to the host to free up users of your instance using the ubiquitous @ mentions.
space, since logging in requires (or at least used to You can also share images internally and externally (with
require) a tiny quark of disk space. To avoid this you can users that don’t have an account on your instance). And
use the admin account to set space quotas for each of course, there’s a button at the top to start a slideshow.

» MANAGE CONTAINERS USING PORTAINER

What’s great about this setup, although Portainer is easy to install. It ships as a Docker Swarm. From Portainer you can
in hindsight maybe it’s easier to use the Docker image that you can run locally examine container logs, inspect
Snap, is that it’s highly extensible. You with the following: properties or even run shell commands
can host websites in other containers, $ sudo docker run -d -p 9000:9000 directly in running containers.
and have the Let’s Encrypt container --name=portainer --restart=always -v Portainer also makes it easy to tidy up
take care of their certificates and the var/run/docker.sock:/var/run/ after oneself. Containers and volumes
reverse proxy route traffic to them. Even docker.sock -v portainer_data:/data started in an ad-hoc manner (as you do
if you don’t do that, you could do a lot portainer/portainer-ce when you’re trying to get things working)
worse than installing the wonderful Recent releases can also handle continue to hang around long after
Portainer to manage the four containers Compose v3 files (like the ones we made they’ve stopped being useful. These can
we’ve just set up. This way you can make earlier) natively, so you can paste their be quite large so it’s good to look for
sure they’re all in rude health from the contents directly in the Stacks area, unused ones (helpfully labelled as such)
comfort of a friendly web interface. which also supports Kubernetes and and put them out of their misery.

Ultimate Linux Projects | 47

Ultimate Linux Projects

Lets look at Lychee

Get simply beautiful photo hosting with a tropical, fruity aftertaste.

ychee is a much simpler program than again. Not only that, but we’ll adapt the Docker

O Nextcloud. It only enables you to upload

photos into galleries and displays them, but
it does so very well. A VPS with 1GB of RAM will
occasionally run out of memory when doing complex
Compose configuration we used for Nextcloud.
If you’ve got the hang of Compose then you might be
tempted to add another service for Lychee to the
existing file to make a conjoined Lychee/Nextcloud
things with Nextcloud. It happened to us over the stack. This almost, but not quite, works. The MariaDB
course of this feature (it’s also quite common during container only allows one additional account to be set
the update process). Most of the time, this is easy to up by environment variables.
recover from by restarting the MariaDB service, but So you have three choices: manually add an account
it’s still annoying when you refresh the interface only for Lychee to the db container (which is bad because
to see an unhelpful HTTP 500 error. this won't persist if the container is destroyed), add a
Lychee by comparison is much more lightweight, so second database container for Lychee (which seems
you should be able to run it on even the most spartan of inefficient), or just forget about Nextcloud for now and
create a solo Lychee Docker setup.

CONFIGURE ACCESS TO LYCHEE Well go with the latter

On your Docker host create a new directory for Lychee,
“IF you also want Friends to be able to and copy the files from the Nextcloud set up:
$ mkdir -/docker-lychee
log in then it’s best to keep the admin $ cp -r -/docker-nextcloud/
* -/docker-lychee/
Now edit -/docker-lychee and replace the app:
account For administrative Functions.” service (which defined the Nextcloud container) and
replace it with this block:
lychee:
VPSes. It’s also designed with photographers in mind, image: lycheeorg/lychee
with support for viewing EXIF and IPTC metadata. It’s restart: unless-stopped
good for social types too, with easy sharing to social volumes:
media platforms and clear indications when you choose - lychee_conf:/conf
to make photos public. Lychee also enables you to - lychee_sym:/sym
upload from Dropbox. - lychee_upload:/uploads
Like Nextcloud, Lychee requires a LAMP stack to run, environment:
and since we clearly don’t have enough pages to cover - VIRTUAL_HOST=lychee.duckdns.org
setting one of those up we’ll cheat and use Docker - LETSENCRYPT_HOST=lychee.duckdns.org

Lychee — Self-hosted photo X +

© A https://lycheeorg.github.io

Self-hosted photo-management done right

Lychee’s web page
says it all really. I Lychee is a free photo-management tool, which runs on your server or web-space. Installing is a matter of

48 Ultimate Linux Projects

 Escape Google Photos

- LETSENCRYPT_EMAIL=contact@mymagazine. Settings

com 0 Settings Enable maps (provided by OpenStreetMap):

- DB_CONNECTION=mysql 2. Users

- DB_HOST=db S U2F
Enable maps for public albums (provided by OpenStreetMap): •
< Sharing
As before, if the hostname does really resolve to your
Show Logs
Docker host, then certificates will be automatically > Diagnostics Provider of OpenStreetMap tiles. Wikimedia —

generated. Before we get to starting it up, don’t forget to i About Lychee

Wikimedia

OpenStreetMap.org (no HiDPI)

edit the db.env file, changing the DB_DATABASE *□ Sign Out OperStreetMap.de (no HiDPI)

variable to something relevant like lychee . As before, OpenStreetMap.fr (no HiDPI)

Include photos of subalbums on m University of Erlangen. Germany (only HiDPI)

we could just docker run the Lychee image, but we’d be

stuck with an SQLite database and no encryption, so it
Decode GPS data into location name •
wouldn’t really be fun. Where the Compose file really
comes into its own (though we won’t see it here) is
Show location name
when you specify multiple webapps on multiple
domains and watch them all spring into life with no
further configuration required. You can use the About Album tab (the lowercase i in Lychee has some
And speaking of configurating, let’s launch Lychee by neat features, such
the toolbar in the top-right) to add metadata, such as a
as integration with
running the following code description of the album. Use the Visibility menu (the
OpenStreetMap.
$ sudo docker-compose up -d eye in the toolbar) to make the album Public or mark it
from our docker-lychee/ directory. After a couple of as Sensitive. If you make albums public, you can also
seconds you should find it running at the hostname you add a password so that only people you know can see
specified, and asking you to set up a username and them. Alternatively, you can set your friends up with
password for the admin account. Once you’re logged in accounts on your Lychee instance and explicitly grant
there’s not much to see - just the four default albums those accounts access to your albums.
on a rather empty-looking black background. Before you You can also import photos directly from the
start filling this void consider, again, creating a user server Lychee’s running on. Just place files in the lychee_
account. If you're planning to be the only Lychee user upload/ Docker volume defined above and make sure
this doesn’t matter so much, but if you also want all their permissions are set correctly. We last covered
your friends to be able to log in then it’s best to keep the Lychee back in LXF188 (unless the venerable Linux Format
admin account for administrative functions only. You’ll Archive lies to us) so it’s nice to see how the project has
find the option to create a new user by clicking the cog developed since then.
icon at the top-left and selecting Users. There are many other options for self-hosting your
Make sure that you check the easy-to-miss Allow photos, or see the box (below) if you’d rather pay
Uploads button, otherwise that blank screen isn’t going someone else to do it. There are also a number of
to get less blank any time soon. While you’re here have a companies offering a free 2GB Nextcloud hosting, if
look at the Diagnostics and Show Logs buttons. You setting it up looks scary but you want to see what all the
might see a warning about uploading large photos. The fuss is about. One project we’re certainly going to be
default upload limit seems to be set to 20MB, so most keeping an eye on in the coming months is LibrePhotos
users should be fine. (https:Zdibrephotos.com) a fork of Openphotos, which
Sign out of the admin account and notice that you’ll itself set out to replace Google Photos. Do let us know
be presented with an empty, public gallery. Users can how you fare on this mission. E3
add to this if they so desire, or they can keep things
private. Sign in to the new account from the top-left,
and then use the + in the top-right to create your first » HASSLE-FREE ALTERNATIVES
album. The Upload Photo dialog enables you to select
multiple images, and so long as they’re all less than If you want to put your photos somewhere that isn’t Google, then
20MB in size you should be able to upload lots of there are a few options. Obviously there’s iCloud and OneDrive, but
images this way. Up to 10GB if our configuration is to be these won’t be to everyone’s tastes. Dropbox has excellent photo
trusted. Tempting though it is to upload everything at management facilities, and is easy to set up on mobile such that your
once, it’s much easier to proceed one album at a time. photos are automatically uploaded to the cloud. The free tier only
allows for 2GB of storage, but if you're willing to pay £5.99/month you
Q LycM« • Ekjp* Goo. X +
can get a thousand times that. Dropbox integrates with Google
4 (? 0 A -o j(XXXJ(yil*J6>822dl7602&0 ••• O B\ CD

Photos so migrating your data across couldn’t be simpler. There’s no

shortage of other cloud storage providers, though - for example, Box
or l-Drive,. These don't really have photo-specific features, but they
have a free tier and are competitively priced beyond that.
One worthy of mention is pCIoud, which besides giving you
previews of images in RAW formats enables you to pay for lifetime
storage (500GB costs $175, with traffic limited to prevent abuse),
although we don’t really know what happens if the company fails, or is
bought by Google. Serious photographers may want to consider
Adobe’s Creative Cloud Photography plan, but for £10/month, there's
Browse through your galleries, then share your photos with friends much better value out there if you’re not beholden to Adobe’s tools.
I and family. Or create your own graveyard-based stock photo library.

Ultimate Linux Projects | 49

Ultimate Linux Projects

QGIS
Credit: https://qgis.org

Create, edit and use

custom mapping data
If you like Google Maps you’re going to love QGIS. Mike Bedford shows you
how to get started and introduces some of its functionality.

ack in 1962, archaeologists in the Czech Activities Q QGisDesktop” ?•) Jui 00:% • en, - A <

O
•Yorkshire Dales-QGIS

Republic discovered a mammoth’s tusk that Project x<j»t X'***

8 .?
actings

i K
glugant

0 ❖ Z
vector

.- ,
fiaster

Z /a
fiatabase ^eb

I
tjeih

• Z
Projes$«ng flelp

has been engraved with a geometrical design. Browser

The pattern was subsequently identified as representing GeoPackage

the hills, rivers, valleys and routes of the surrounding

Z SpatiaLite
W PostCIS
• > MSSQl
• Z DB2

area. It was dated around 250,000 BC, making it WMS/WMTS

• <exYZ Hies

probably the earliest map ever discovered. OpenTopoMap

® wcs
. WPS

In the library of Hereford Cathedral is the Mappa ows

V* ArcGisMapServer

Layers

Mike Bedford Mundi. Created around 1300, it’s the largest surviving * a

•
•. t

V y OpenTopoMap

is a big fan of medieval map of the world. The UK’s Ordnance Survey • v OpenStreetMap

QGIS. However, was set up in 1791 to help address the perceived risk
he admits to still arising from the Jacobite rising, and of invasion by
loving good old- France, and it went on to become one of the world’s
fashioned paper foremost national mapping agencies. And 1999 saw From street maps through topographic maps to aerial imagery, any
OS maps while
he's walking on
California-based ESRI release its ArcGIS graphical
information system, which would become the world’s
number of options are available as base maps.
I
the hills. most used GIS (geographic information system). ESRI’s well-respected ArcGIS isn't cheap at £1,192
These few notable dates in the history of cartography per year, including VAT, for professional use. This
illustrate 27,000 years of change and it’s clear that the reduces to £139 for non-commercial use, but that’s still
rate of change has accelerated significantly in recent a lot unless you have a fairly serious application. Our
years. This isn’t surprising since digital technology has subject here, therefore, is the free open source QGIS
had the same effect on so many other areas, but it’s which is widely used professionally and is considered to
QUICK TIP been suggested that a GIS is so different to its be on par with many professional GIS offerings.
predecessors that it’s a totally new entity. Professionals We're going to provide a hands-on introduction to
When you work point to support of multiple layers and an ability to carry using QGIS but we’re certainly not going to be looking at
on a project,
out analyses of geographically based data as just some all its features, in fact we won’t come close. After all, if
you’ll end up
of the things you can do with a GIS but not with an you can think of something you believe you ought to be
with several
files including,
ordinary map. And if you’re wondering where Google able to do with mapping data, it’s a fair bet that QGIS
For example,
Maps fits in, while we’re not going to get embroiled in can do it, either natively or via one of its many plug-ins.
Files associated the debate over whether or not it’s a GIS, we would However, we trust that our tentative first steps will be
with the layers. agree with the sentiment that a fully blown GIS is like enough to excite you about the possibilities of QGIS and
For this reason, Google Maps on steroids. start you off on your own voyage of discovery.
it’s good
practice to use Project £dit yiew py»r Jettings Plugins Vector Raster fieubese
YoriuhWl D*l«l-QGIS

web Mesh Processing Help Orientate yourself

a new Folder for D I B Ci Q K 0 ❖ Z z " , >a I ’ C
If your main experience with digital mapping has
each project and
involved Google Maps, the first thing you'll notice when
keep all of the
you start up QGIS for the first time is that you don’t see
Files organised
a map at all. Instead, unless you open a project that
together.
someone else has produced, you’ll need to create a new
project but, even having done that, you’ll be faced with a
blank canvas to which you’ll need to add data as layers.
Adding Usually you’ll want to start a project by adding a base
OpenStreetMap
data as a base
map so, let’s see how to do that, but first create a new
map couldn’t be project at Project>New. Now, in the Browser panel at
much simpler. the top-left, find and expand the XYZ Tiles entry and

50 | Ultimate Linux Projects

 Create, edit and use custom mapping data TUTORIALS

double-click OpenStreetMap. This will add the open

source OpenStreetMap as a new layer. The map will
appear in the main window and you’ll also be able to see
it listed in the Layers panel at the bottom-left.
Although OpenStreetMap is the only base map
shown by default, there are lots of others you can use,
and you might like to familiarise yourself with what’s on
offer. You’ll have to search out the URLs yourself, but as
an example, right-click XYZ Tiles in the Browser panel
and select New connection... In the Connection Details
dialog, enter https://tile.opentopomap.
org/%7Bz%7D/%7Bx%7D/%7By%7D.png as the URL,
give it a name such as OpenTopoMap and click OK.
OpenTopoMap will appear below OpenStreetMap
under XYZ Tiles and, if you double-click it, OpenTopoMap
will appear as a second layer. In fact, it’ll appear to have
replaced OpenStreetMap in the main window, but that’s
only because it’s the top-most layer: it appears above filtered out so it represents only the topography. In the Freely available
elevation data
OpenStreetMap in the list, and it’s fully opaque. We’ll UK, elevation data has been produced by the
can be added
look at opacity later but, for now, note that you can swap Environment Agency at a resolution of Im or 2m, and is to a project and
to seeing the OpenStreetMap again by clicking the tick distributed freely online by DEFRA. Over the Pond, the Formatted in so
box next to OpenTopoMap so it’s not displayed, or by USGS makes elevation data available for the US at many ways.
dragging OpenStreetMap to the top of the list. resolutions ranging from 10m to 30m, but with the aim
This method of adding base maps isn’t limited to of migrating to Im. They also provide Space Shuttle-
maps in the normal sense of the word. You can also add derived data for most of the world at 30m resolution.
satellite or aerial imagery using the same method. To Commonly elevation data is provided as a GeoTIFF file,
add Google imagery, for example, use https://mtl. which is a geo-referenced variant of the familiar TIFF
google.com/vt/lyrs=s&x=%7Bx%7D&y=%7By%7D&z=%7Bz image format, although there are other formats, and
%7D as the URL. QGIS supports most of them.
Once you’ve downloaded the elevation data, it’s time
Elevation data to import it into a QGIS project, ideally one into which
So far, we’ve seen how to add various layers to a QGIS you've already added a base map. Select Add Layer
project, although all of those layers were essentially from the Layers menu and then choose Add Raster
images of one type or another. But since a GIS is Layer... In the dialog, select the elevation data file by
concerned with far more than just images, or maps if clicking the three dots against Raster Dataset(s) and
you prefer, let’s take a look at how other types of data clicking Add.
can be added. Because the elevation data might cover a smaller
To start we’re going to add some elevation data, but area than the base map, it's possible that you won’t see
first a few words on types and sources. The types you’ll the new layer on the map, even though it appears in the
mostly find are DSMs (digital surface models) and Layers panel. If that happens, just right-click the name
DTMs (digital terrain models). DSMs include objects of the layer containing the elevation data and select
such as trees, buildings and cars, as well as the actual Zoom to Layer. Your elevation data will often appear as a
ground, while in a DTM the former types of object are rectangle, because you’ll have downloaded a so-called

» QGIS OR MGIS? TIME TO LOOK BEYOND EARTH...

If you were wondering what QGIS stands to delve into the subjects of CRSs - https://lunaserv.lroc.asu.edu, which
for, the Q is for Quantum - or at least it that’s coordinate reference systems - hosts data from the Lunar
was until 2013 but we guess now Q just although it’s a subject you really need to Reconnaissance Orbiter Camera and
means Q - and the G stands for be familiar with whatever your use of provides some information on how to use
Geographic which includes the "geo” QGIS. Needless to say, data representing it in QGIS.
suffix that relates to the Earth. As we anywhere other than the Earth won’t use
proved in our experiments, though, it any of the CRSs devised for terrestrial
might be equally appropriate to call it use. And we have to admit that we
QMIS, since we used it to display Martian struggled with one particular Martian
data. Indeed, such systems have been base map which loaded, but wouldn’t
used with data representing a wide range display. However, we did do better with
of non-terrestrial astronomical objects. elevation data so that might be a good
Interested in the wider Solar System? place to start. Search for “Mars_MGS_
Then you'll probably want to investigate MOLA_DEM_mosaic_global_463m” and
the various planetary base maps and you’ll find that it can be downloaded from
digital elevation models that are freely https:Z^astrogeology.usgs.gov. And if the From Io to Titan, maps and elevation data is available
available. However, you’re going to need moon is your thing, you might enjoy I for lots of heavenly bodies and visualised in QGIS.

Ultimate Linux Projects | 51

Ultimate Linux Projects

tile, although it’s possible it might be less than a

QUICK TIP complete rectangle because coverage isn’t always
With v3, QGIS 100 per cent.
now oFFers a 3D Initially, the elevation data might not look too
visualisation impressive. It’s just in shades of grey with white
Feature. This representing the highest elevation in the tile, and
is commonly black representing the lowest. In passing, this means
seen in online that if you have two elevation layers, they’ll be scaled
mapping
differently, but this can be solved by merging them
applications,
using Raster>Miscellaneous>Build Virtual Raster...
but considered
a novelty by
The uninspiring greyscale image is just a start and
some GDIS
QGIS has plenty of tricks up its sleeve. For a start, let’s
professionals, just change the colours: right-click the layer and select Points can be added to a project and data Fields can be defined For

The 3D view can

be manipulated
Properties. Now, in the Layer Properties dialog, ensure
that Symbology is selected on the left, under Render
I subsequent display or analysis.

by zooming, type choose Singleband pseudocolor instead of it can process elevation data in so many ways. But this
panning, Singleband gray, and select one of the options for Color is far from the limit of its data-handling capabilities.
rotating, tilting ramp. You might not find that any of the Color ramps are QGIS can work with any type off data so long as it’s
and so on.
to your liking, and none correspond to the common georeferenced. So, for example, this could enable you to
colouring of altitudes on topographic maps, but you’ll see the variation in rainfall or hours of sunshine across a
notice that you can edit each of the colours. region, or it could provide a means of visualising the
Moving away from just changing colours, Hillshade is correspondence between the geological classification of
another interesting option for Render type. It'll revert rocks and surface features.
the colours to greyscales in the process, but there's a A recent project involved showing how QGIS can
solution to that. As before, use the Layer properties to operate with other types of data, and via a brief return
select your preferred colour scheme. Next, with the to elevation data, how it can carry out calculations on
elevation layer selected, select Analysis>Hillshade... that data. The exercise involved using rainfall and
from the Raster menu, before accepting all the defaults elevation data to simulate areas at risk from flooding.
in the dialog and clicking Run. Unlike last time, the latter The simulation software could input raw elevation data,
won’t be converted to a hill-shaded version, but a new so no need for QGIS there, except for the fact that
hill-shaded layer will be created. elevation data for the area of interest was incomplete. In
As always, the new layer will be at the top of the list, particular, there were holes in the preferred Im
so drag the coloured elevation layer to the top in the resolution data, but 2m data was available for the area.
Layers panel and, of course, it will obscure the QGIS was used, therefore, to compile a file of
hill-shaded layer. However, adjusting the transparency of elevation data using lm resolution where present, and
the pseudo colour layer will give the best of both worlds. filling the gaps with 2m data where it wasn’t. This was
This option is available in Layer Properties. achieved by loading both sets of elevation data as
And as a final way of processing elevation data, a few separate layers and then using QGIS’ raster calculator
words on contours. Depending on your choice of base (Raster>Raster Calculator) to combine them. This was
map, you might already be able to see contours. done using the statement ("lm_dtm@l" = 0) * "2m_
However, if you're using a base map without contours, dtm@l" + ("lm_dtm@l" != 0) * "2m_dtm@l" having
you can generate these from elevation data at first ensured that the no data value in the lm elevation
As this example of Raster>Extraction>Contours.... data file is 0. It generates a new raster layer with values
water depth during
defined by the expression, and it’s fairly clear how it
a flood illustrates,
how geo-tagged
Beyond conventional maps achieves the desired effect.
data can be used So we’ve seen how QGIS handles data that’s basically This is only presented as an aside, but the ability to
in QGIS. an image, or in other words a map, and we’ve seen that carry out any arithmetic operation on raster data is a
powerful tool. QGIS then came into play again when the
simulation software had crunched the input data and
created a geo-referenced output file of water depths. By
importing this to QGIS, and viewing it, partially
transparent, over a base map, at-risk areas could be
clearly identified.

Lines, points, photos

Informative pushpin labels are a familiar sight on online
maps, and QGIS doesn’t disappoint here. This sort of
information can be created elsewhere and imported as
a new layer, or it can be created within QGIS, as we’re
about to see. As always, you need at least a base map in
your project before proceeding.
In the Layer menu, select Create Layer>New
Shapefile Layer.... In the dialog, give the layer a name
and choose a type, which must be Point, Multipoint, Line

52 | Ultimate Linux Projects

 Create, edit and use custom mapping data 1UTORIALS

or Polygon. Now start adding fields, and there can be as although if you took them on a camera they might not
many as you want. In our example, we’re creating a layer be. Bizarrely, given that QGIS doesn’t seem to be short QUICK TIP
that shows places at which particular minerals were on features, we could find no way to import With some
found. Our first field, therefore, is the type of mineral, so non-geotagged photos. That’s not a show-stopper, actions
we give it the name “type”, and specify that the field is though - it just means you’ve got to add the geotags that create
defined as text. Having filled in the first field, click Add to separately. There are plenty of standalone applications new layers,

Fields List and you’ll see it appear in the list below. We and web-based utilities to do that (for example, those layers will
be temporary
also added a second field, namely the date on which the www.tool.geoimgr.com), although many limit how many
scratch layers.
mineral was found, in just the same way. When you’ve photos you can process a day without paying a fee.
The method we
defined all the necessary fields, just click OK and you’ll So, with a folder full of geotagged photos at the
described For
see that the layer appears in the Layers panel, although ready, here’s how to import them into a QGIS project. In creating a layer
nothing will appear on the map, because there are no the Processing menu, select Toolbox>Vector with photos
points defined yet. creation>lmport geotagged photos. Against Input folder is one such
To add points, make sure the new layer is selected select the folder containing the photos you want to add case. These
and click the Toggle Editing icon (yellow pencil) in the and click Run. A new layer will appear in the Layers layers will be
Data Source Manager toolbar. Once you’re in editing panel and you’ll notice some small markers appear on lost when you

mode, click the Add Point Feature icon (three green the map, at their correct locations, just like the ones we close a project
(although QGIS
dots and a crosshair), and the cursor will change to a added previously.
will warn you),
crosshair. Click it on the map at the place of interest and However much you zoom in, though, they won't
but you can
the Feature Attribute dialog will appear. You might not appear as photos unless you make some changes. Bring
prevent this by
want to bother with the “id”, but fill in the various other up the Layer Styling dialog and ensure the Symbology right-clicking
fields and click OK. A coloured dot will appear on the tab is selected. Single Symbol will be shown and below the layer and
map. Now click the Toggle Editing toolbar again to turn that the marker type will be shown (expand it if not selecting Make
off editing and see how a user can interrogate that already expanded to show Simple Marker). Click Simple Permanent.
point. Click the Identify Features icon (the “i” on a blue marker and then, against Symbol Layer Type, choose
circle with an arrow cursor) in the Project toolbar. Click Raster Image Marker instead of Simple Marker. Lower
a coloured dot and a window will appear providing data down there’s an unnamed box where you can define a
on all the fields defined for the layer. particular raster image, but instead we want it to pick up
You might find it surprising that some of that data the image at that point. So, click the icon at the right,
doesn't appear alongside the point without interrogating which looks like a filing cabinet and a couple of arrows,
it, but since there’s no limit to how many fields you can to allow the Data Defined Override option to be selected,
assign, it’s fairly obvious why that doesn’t happen by and against "Field type: string”, choose “Photo (string)”.
default. However, you can choose to add labels for all Photos will replace the blobs, but they will be very small
points on a layer, which you'll do by clicking the Layer so specify a new size against Width.
Labelling Options icon (“abc” on a yellow arrow) on the QGIS is a very powerful tool and what we’ve
Data Source Manager toolbar. In the Layer Styling presented here is only a taster to what it can achieve.
dialog, ensure the Labels tab is selected (the “abc” on a Experimentation is one of the best ways of learning, so
yellow arrow again), choose Single labels in the top box what are you waiting for? E3
and choose the field you want the point to be labelled
with against Value. You’ll see the point labelled on the
map. You might want to fine-tune the options under » ANALYSIS OPPORTUNITIES
“Placement”. Also, if the size, shape and colour of the
point aren’t to your liking, this is something else you can Although the ability to analyse geographical data is considered a key
adjust in the Layer Styling dialog, this time on the feature of a GIS, we've largely ignored this feature. As you grow in
Symbology tab (the paintbrush). your confidence with QGIS, though, depending on your application
QGIS also enables you to show photos at the you might want to delve into analysis, and here the sky’s the limit.
locationqthey were taken, but only if they’re geolocated. For a start, there’s lots that can be done with elevation data. Mobile
So, if they were taken on a phone you’ll be okay, phone companies use GIS software to visualise the coverage that
would be achievable from base stations at given positions. This sort of
exercise can be used to decide where to locate base stations and
forms the basis of published coverage maps. But it goes much
beyond that, a fact that should be obvious when we think about the
Shapefile layers that we created and populated with points. There can
be any number of such layers, and the points in each of those layers
are defined by their geographical location plus data in several fields.
We can, therefore, start to think about a QGIS project as a
geotagged database and the potential starts to become clear. A
common approach is to carry out some sort of analysis and create a
new layer from the results that can be viewed on the base map. The
QGIS documentation shows an example of an exercise that involved
analysing the cause of a cholera outbreak in London in 1854. And
while that exercised used fairly simple analytical tools, QGIS can also
As an alternative to points, places of interest can be shown on a map be interrogated using SQL queries.
I using geo-tagged photos.

Ultimate Linux Projects | 53

Ultimate Linux Projects

torn

DOSBOX
How to easily emulate
486 PCs and run DOS
Relive the halcyon 32-bit years of PC computing, play your favourite games
and look back at OSes of yore with the ever-dependable Les Pounder!

his author first got their first PC back in 1994: a want to run real hardware with a subtle 21st century

a Dan 486 DX 33MHz with 4MB of RAM. It was

much more powerful than the Amiga 500, and
twist. Let’s start with emulation because it’s the
simplest route to enjoying retro content. The champion
almost three times the price. The author’s journey of
computers up to this point had been via Commodore
withretro PC emulation is DOSBox which offers a quick hit
of nostalgia with very little effort. To install DOSBox on a
machines, but this Dan 486 PC captured his heart. He Debian or Ubuntu machine, open a terminal and type
OUR— the following:
got it home and launched MS-DOS, but he had no
EXPERT manual or user guide. He taught himself MS-DOS and $ sudo apt update
Les Pounder Windows 3.1 by making lots of mistakes, including $ sudo apt install dosbox
is associate formatting his 120MB hard drive and having to reinstall With DOSBox installed, launch the application from
editor at Tom’s everything, and by installing a CD ROM drive incorrectly the terminal.
Hardware and and the machine refused to boot. $ dosbox
when not writing The mid-1990s was a crazy time for PCs. They were DOSBox is an x86 emulator for 486 and early
about Raspberry still beige boxes that held mysteries such as IDE, SCSI, Pentium computers and games. It’s dependable and
Pi he is found lots of wires and dust. This mighty bookazine is devoted works really well for a quick hit. When it first starts, we
tinkering with to Linux, but for this journey down memory lane we’ll see a familiar DOS prompt with drive Z as the active
old computers. take a look at emulating a Windows 3.1 era PC. First via drive. DOSBox provides a brief help menu - highlighting
a simple program that will enable us to run DOS-era that we’ve a Soundblaster compatible sound card
games in Ubuntu. Then we’ll learn a little BASIC with and that we can learn more about using DOSBox via the
Microsoft’s Quick Basic. Finally we’ll create our own intro command. At any time we can obtain general
Windows 3.1 PC in a virtual machine. help using help , or for more detailed help use
help /all
Emulating a retro PC What can we do right now? Well, let’s remember a
The retro PC scene has users who want to simply run few DOS commands. First we have a command to list
their old games in an emulator, and it has users who the contents of the current directly. We know this as Is
but in DOS it’s dir .
This will show all of the files in Z:. Right now there
isn't much of interest, but as we move onwards we shall
learn a few extra DOSBox features.

Writing code
The retro PC era spans decades, and with that we’ve a
fantastic choice of languages and applications with
which to write code. In this instance, we’re going to
focus on BASIC, in particular Quick BASIC (QBasic') that
was bundled with MS-DOS. QBasic is a cutdown IDE
and it can be found easily online. We’re lucky enough to
own MS-DOS 6.22 floppy disks and a hard drive with
QBasic installed.
Download a copy of QBasic and extract the contents
of the archive to a directory in your home directory.
Remember the location of the extracted files as we’ll
need that exact location for DOSBox. Launch DOSBox
from the terminal. In the DOS prompt we shall use a
command to mount the location of our QBasic

54 Ultimate Linux Projects

 How to easily emulate 486 PCs and run DOS TUTORIALS

download as another drive, C:. Our QBasic directory is

called QB45, but change this to match your own: QB64 X64

mount c: ~/QB45 1 CLS

A message will be printed to the screen, advising us 2

3
INPUT ’'What is the radius of the circle?”, R
LET C = 2 * 3.14 * R
4 PRINT ’’The circumference is : C
that C: drive is mounted to that directory. Change to C: 5 END

drive and the list the contents of the drive.

Untitled

dir Uhat is the radius of the circle?10

The circumference is 62.8

We should now see a list of files, but we’re only

interested in qb.exe which is QuickBasic, so let’s launch
it by typing the file name and pressing Enter:
qb
QuickBasic’s user interface is basic, no pun intended.
It has a simple menu at the top of the screen, and a
blank section in the centre where we can write our code,
and a shell interface, called Immediate, at the bottom
where we can test code snippets. Our first quick test of
QBasic is to write the familiar “Hello World” code, but
this time it will be a little different and use a for loop to
print the text 20 times. In the blank area of QBasic is QB64 is a modern-day version of QuickBasic, which runs on Linux, Windows and Mac. It’s also
where we write the code.
We start by first declaring that we’re creating a
I compatible with QuickBasic 4.5.

variable, “counter” and that it’ll store an integer PRINT "The circumference is"; C
(numeric) value. Then we clear the screen of any END QUICK TIP
existing data. Save the code as CIRCUMF.BAS (ALT, F, A) to your C: MS-DOS is not
DIM counter AS INTEGER drive. Then press F5 to run the code. Type in a radius case sensitive,
CLS (we chose 10) and the code will print the answer. We can unlike Linux.
We start the for loop, updating the value stored in the also make an EXE executable file from the Run menu. So QBASIC and
counter variable each time the loop iterates. It starts at This will launch our code outside of QBasic. qbasic are one

0 and ends at 20. and the same.

DOSBox has a
FOR counter = 0 TO 20 Playing a game
basic form of
The next lines of code don't need to be indented, but DOSBox will run most DOS games, even from CD-ROM.
history, which
we’ve chosen to do this to show that they are inside the We tested it with a vintage copy of LucasArts' we can scroll
for loop. We use the PRINT command to print the point-and-click adventure game Day of the Tentacle. through using
“Hello World” message to screen, then we pause the Inserting the disc into our DVD drive, srO, we opened the up and
code for one second using SLEEP . DOSBox and from the prompt entered a command to down arrows.
PRINT "HELLO WORLD" mount the CD-ROM. Note that we needed to go into the
SLEEP 1 /media/{username} directory to get the name of the
Finally we iterate the counter variable, each time directory used as a mountpoint:
adding one to the previous value. When the for loop mount D /media/{username}/{directory name}
ends, the program ends. We now have our DVD drive mounted. Change to D:
NEXT counter drive and list the contents of the disc.
END
Save the code by pressing ALT then F and A. Name
the file HELLO.BAS and save it to C drive. Use TAB to » TAKE FREEDOS FOR A SPIN
navigate through the sections. Press OK to save. This
will save the code to our host machine, our Linux PC. FreeDOS is an open-source implementation of MS-DOS that works
When ready, press F5 to run the code and you should with more modern machines. We installed FreeDOS on an Asus Eee
see a DOS prompt appear and run the code. PC 701 and it makes a great retro machine that boots in less than ten
Let’s make something a little more complex, a tool to seconds. FreeDOS was created to enable anyone to run their old DOS
calculate the circumference of a circle. Create a new games and productivity software on newer hardware. Downloading a
file (ALT, F. N) and we start the code by clearing the USB image from the FreeDOS website (www.freedos.org) and then
screen of any data. writing the image to a stick takes no time at all and the installation
CLS process on our test machine was quick and painless.
Now we ask the user a question, “What is the radius If you’d like to run FreeDOS on real 486 hardware then there are
of the circle?” and we use INPUT to read the raw many options available, such as a legacy CD-ROM image or a Boot
keyboard input, which is saved to a variable, R. floppy and CD-ROM download that has the necessary CD-ROM driver
INPUT "What is the radius of the circle?"; R for MS-DOS. FreeDOS can be used in a multiboot environment with
We then create the variable C and in there store the more recent Microsoft OS. It also comes with tools to manage
answer to the equation which will work out the archives, browse the web, play MP3/0GG and WMV files, CD-ROM
circumference of the circle using the value stored in R. support and a select suite of Linux-based tools.
LET C = 2 * 3.14 * R FreeDOS is ideal for virtual and real hardware. It’s an open source
We then print the answer to the screen, with a version of DOS that enables you to reminisce and learn new skills.
sentence explaining what the returned value, C, refers Take it for a spin on an old machine, you might just enjoy using DOS.
to. Finally we end the code cleanly.

Ultimate Linux Projects | 55

Ultimate Linux Projects

D: we need something to boot from, and this is where disk

QUICK TIP dir one of MS-DOS 6.22 is needed. We can insert a disk
We can take We can now read the drive and launch any image by going to the Settings option, then
Windows 3.1 executables that we need. Storage>Controller: Floppy and navigating to the floppy
For a spin in image. After inserting the disk, click Start and the VM
our browser. Creating our own Virtual 486 will power up and load MS-DOS. Follow the standard
ClassicReload DOSBox is great for a quick hit, but what if we want install process and when prompted to swap disks, press
has a web­ something a little more permanent? Well, we can create the right Ctrl key to unlock the mouse, click the Devices
based version oF
a virtual machine to recreate a top-spec 486 (almost) menu, then Floppy Drives, then Choose a Disk File...
DOSBox, which
machine and run Windows 3.1. For this you’ll need your Navigate to the directory containing your MS-DOS
means we can
own copies of Windows 3.1 and MS-DOS 6.22 saved as disks and select the appropriate disk. Installation will
skip creating a
virtual machine
image file (.img). Luckily for us we have these in the take less than five minutes, much quicker than back in
and start attic, together with a USB floppy drive. the day. Remove any disks, and reboot when prompted.
enjoying this We start by downloading Virtualbox from If at any time you need to reboot, you can select Reset
classic interFace: www.virtualbox.org/wiki/Downloads and then install the from the Machine menu.
https:// download. Open Virtualbox and create a new virtual MS-DOS takes seconds to boot, and the prompt is a
classicreload. machine (VM). We called our VM Windows 3.1 and this great place to learn a few commands. We can get help
com/win3x- automatically triggered the VM to configure itself for at any time by typing HELP. Our goal is to install
windows-31.
Windows 3.1. We next set the memory size to 32MB, a Windows 3.1, so now is the time to insert the Windows
html
huge amount for this era. Then we created a virtual hard 3.1 floppy disk images (Devices>Floppy Drives>Choose
disk (VHD), fixed to 1GB in size. With the machine “built" a Disk File...). Change directory to the first virtual floppy
drive and then list the contents of the disk.
A:
dir
On A: drive there’ll be a setup.exe file - this is what
we need to install Windows.
setup.exe
Follow the installation process, and swap disks just
like we did for MS-DOS. In a few minutes Windows 3.1
will be installed. Reboot the machine (Machine>Reset)
and from the prompt type the following code to
launch Windows.
win
In seconds the familiar Windows 3.1 desktop will
appear and a few memories are sure to rise to the
surface, too.

What’s on the demoscene?

Just like many other machines, the PC enjoys a rich
demoscene of artists, musicians and coders all eager to
Hello World isn't exciting, but it enables us to grasp enough of the syntax to check that share their skills and show off their talents. After
I everything is working, including our brain. researching on pouet.net we found Memories, a demo
from Desire who released this demo at the Revision
2020 demo party. This demo has no music, but it
» TAKE THINGS FURTHER WITH QB64 achieves what should be impossible: it squeezes an
entire demo into 256 bytes. That’s not a typo by the
QuickBasic was fun but firing up a VM every time we want to write way! This is a tiny demo that illustrates what great
BASIC can be time consuming. Fear not, QB64 is a modern-day coding can do.
version of QBasic that runs on Linux, Windows and Mac. Download Here at the start of 2021 the PC demoscene is still
and installation is a breeze, and in five minutes we were writing BASIC very much active. New demos that push even the most
code in Ubuntu. Code written in QB64 is compatible with QBASIC, but
DOSBox 0.74, Cpu speed: 3000 cycles, Frameskip 0, Program: DOSB
QB64 automatically compiles our BASIC code into machine code. It
can also be enhanced via extensions for OpenGL enabling eager users Welcome to DOSBox *
X).74

to build their own games and programs using this powerful tool. For a short introduction for new users type: INTRO
For supported shell commands type: HELP
The QB64 user interface looks just like QBasic and it even works in
To adjust the emulated CPU speed, use and
the same manner. We tested our circumference project in QB64 and To activate the keymapper
were amazed that every line we typed was checked for errors as we For more information read the README file in the DOSBox directory.

typed! This is great for learning and really helps the user to see where HAUE FUN?
The DOSBox Team http://www.dosbox.com
their code went wrong, before they run it.
Z:\>SET BLASTER=AZZ0 I? DI H5 T6
QB64 is a free download from www.qb64.org/portal and it’s well
Z:\>MOUNT C /home/les/Downloads/QB45
worth investing an afternoon with this editor and the great wiki at Drive C is mounted as local directory /home/les/Downloads/QB45/
www.qb64.org/wiki/Main_Page. This covers all aspects of the Z:\>
application and explains the BASIC language syntax and structure
using a series of examples. In DOSBox we can mount a directory or drive to a specific drive letter.

I It can link out Linux host machine to DOS - handy for sharing files.

56 Ultimate Linux Projects

 How to easily emulate 486 PCs and run DOS TUTORIALS

CREDIT: LucasArts
Day of the Tentacle
was a point-and-
click adventure. It
was released on
Floppy disk and a
‘talkie’ CD-ROM
with specially
recorded speech.

QUICK TIP
Windows 3.1 just
a little too retro
For you? You can
take Windows
95 For a spin in
your browser.
See www.pcjs.
org/blog/2015/
09/21.
Windows 95
had a massive
marketing
campaign,
and saw
users queuing
overnight to get
their hands on
an OS. Wowsers!

powerful hardware to its limits are being produced by The retro PC community is a strong and passionate
artists who favour the keyboard and the mouse as their place. We just have to look at Reddit’s retrobattlestations
tools of expression. subreddit to see that the 386/486 and early Pentium-era
We would think that with newer, more powerful machines are cherished by their owners. With new
hardware that the retro PC scene would be dead and community-designed and produced hardware being
buried. Oh how wrong we were. The price of 486-era created to enhance the experience for all, the future of
machines online can vary from bargains which require a retro PCs is bright and it lives on in the continued
little work to new old stock machines that are perfect success of the demoscene and the many YouTubers
specimens. The sweet spot of the 486 era was a 486 such as 8bit Guy, LGR, RMC and NostalgiaNerd who
DX2 66Mhz with 8MB of RAM and prices for those have created vast amount of content devoted to showing
machines vary wildly. Research and patience will yield off the best of this era.
the best price. Don’t just jump into the first machine Whether you just want to dabble with some retro
that you find. games, or you have a need for real antique hardware,
this era of PCs is an exciting and challenging time where
standards were created and legacies created. E3
So you have a retro machine - what do you do now?
The first thing to do is check that it’s safe for use. Are Program Manager
there any leaking capacitors, dodgy wires? Check File Options Window Help
everything before applying the power. If the machine
boots up to a DOS prompt or Windows desktop then we
can consider the machine good.
There's one thing to address and that’s hard drives. A
period perfect drive is now around 20 to 30 years old
and it will fail at some point. Fear not as the community Windows.
has your back, in the form of an IDE to Compact Flash This product is licensed to:
adapter that can be purchased for around £5. We use @biglesp
6r3665
one of these inside an Amiga 600 along with a 2GB card
which holds Workbench and our games. Your serial number label is on the inside back
cover of Getting Started with Microsoft Windows.
Using adapters and drive enclosures you can clone
your original hard drive to a CF card and replace the 386 Enhanced Mode
drive with a smaller, quieter and more reliable option. Memory: 113,352 KB Free
Versions exist both for internal and external use, along System Resources: 86% Free

with SD card versions. External versions are particularly

handy because we can swap hard drives without
opening the case. They simply fit to a rear ISA/PCI slot Windows 3.1 sat upon MS-DOS and provided a Functional means to work with Files and
and connect directly to the IDE interface. I applications. For many computer users was their first taste of a GUI. CREDIT: Microsoft

Ultimate Linux Projects | 57

Ultimate Linux Projects

QEMU
Credit: www.qemu.org

How to run classic

distros with QEMU
Where we’re going we don’t need roads, we need QEMU
and a bunch of retro Linux ISOs, reveals Les Pounder.

ack in the late

1990s, this
author chose * •

their PC magazines by
what was on the cover disc,
something that had started
OUR back in their Amiga days.
EXPERT One month, they chose a
2

Les Pounder PC magazine that had

is associate something called Red Hat
editor at Tom’s Linux on the second disc
Hardware and a which was promptly installed
freelance maker onanAMDK6-2 333MHz PC.
for hire. He blogs It's fair to say that it wasn’t
about his projects love at first sight. The sheer
at bigl.es. volume of application choices, the
differing commands and file system
was enough to scare this author back
to Windows 98. A few months later and
another coverdisc, and this time it was
something different. It was still Linux, but Corel was a Fine shade of beige
Linux 1.0 which was a little more ‘noob’ friendly. The
install went well and this was this author’s distro for Why are we installing a KVM? It’s because QEMU is
quite some time. an emulator, and so by using a KVM and having a CPU
In the 1990s, Linux was still in its infancy and the that supports Intel VT-x or AMD V we can speed up the
jump from Windows to Linux seemed massive and virtualisation to near-native speeds. Most modern
exciting. How can we experience these days again? In processors have some form of support for
the absence of a giant Tux-shaped time machine, we virtualisation - our machine is an i7 3770 from 2012 and
can use virtual machines to emulate hardware of the it supports VT-X.
era and install Linux on a virtual PC. To check if your Intel or AMD CPU supports these
QUICK TIP We’ve chosen three Linux distros from the past three features, open a terminal and type the following. For
decades of Linux and using virtual machines we shall Intel VT-X, use
Want to share a install and use each distro. Our choices span the grep -color vmx /proc/cpuinfo
USB device with
1990s, 2000s and 2010s and show the similarities, and for AMD V, type
your virtual
and differences between Debian, Ubuntu and Linux Mint grep -color svm /proc/cpuinfo
machine? You
of these eras. Now install the QEMU application with KVM
can easily
do that via $ sudo apt update
the Virtual How To Install QEMU $ sudo apt install qemu-kvm libvirt-daemon-system
Machine> QEMU is a generic and open-source machine emulator libvirt-clients bridge-utils
Redirect USB and virtualiser. In other words, it can emulate the To make managing our systems a little easier, we’ll
Device menu. hardware of many different CPUs and machines, and install a GUI manager for our virtual machines.
Handy For create virtual machines. To install QEMU we need to $ sudo apt install virt-manager
using USB Flash open a terminal and use the package manager (in our We now need to reboot our machines for the
drives with your
case Ubuntu 21.04 and the apt tool) to install QEMU, a changes to take effect. If we skip this step then the GUI
virtual machine.
Kernel Virtual Machine (KVM) and its dependencies. manager will be unable to connect to QEMU.

58 Ultimate Linux Projects

 How to run classic distros with QEMU TUTORIALS

Open the Virtual Machine Manager and take a look

debian login: biglesp
around. In the top left we have an icon - a monitor with Password:
a yellow star - to quickly create a new virtual machine. Linux debian Z.0.34 #Z Thu Jul 9 10:57:48 EST 1998 i686 un
We shall be using this icon quite a lot in the tutorial.
Copyright (C) 1993-1998 Software in the Public Interest, a
Virtual machines are listed in the main section of
the window and we can select and run machines from Most of the programs included with the Debian GNU/Linux sy
here. Selecting a machine and then clicking the Play freely redistributable; the exact distribution terms for e
button will start the machine in the background. are described in the individual files in /usr/doc/
/copyri
*
Clicking Open will open a new viewer window - our
Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the
interface with the virtual machine. Launching a machine permitted by applicable law.
will launch a player window, where we interact with No mail.
the virtual machine. In this player window we can $ whoami
biglesp
administer our virtual machine: redirect host USB
$ df -h
devices to the virtual machine, configure the system Filesystem Size Used Avail Capacity Mounted
with more RAM or a better CPU, insert CD/DVDs and /dev/hdal 991M Z0M 9Z0M Zz /
configure our networking. $ f ree -m
totalused free shared buf
Mem: 61 44 16 4
The 1990s - Debian Linux -/ + buffers/cache: 6 54
Linux in the 1990s was the new frontier. New distros Swap: 1Z7 0 1Z7
appeared that took advantage of 486- and Pentium-era
machines, while downloading the ISO images took From these humble beginnings, Debian rose to become one oF the most important distros in the
hours, if not days over a dial-up connection. Luckily for
most of us in this modern time, we have much faster
I history of Linux.

broadband-enabled internet. without the existence of Debian the Linux landscape

Debian Linux was created by Ian Murdock in 1993 would be totally different.
QUICK TIP
and the first version (0.01) was released that year. But it We could download and install our own version of Need to quickly
wasn’t until 1996 that we saw the first stable release Debian Linux, or we can download a hard drive image use a live CD
(1.1). Today, Debian is the backbone for many popular that we can use with QEMU. The latter is the most or DVD image?
With QEMU
distros including Canonical’s Ubuntu and the Raspberry simple, being ready to go with little configuration. That
we can quickly
Pi Foundation's Raspberry Pi OS. It’s fair to say that said, the Debian installation process is sublime, more so
start the ISO,
in recent years. The installation process takes us by the
or a real disc
New VM hand through partitioning, user setup and then we can with 1GB of RAM
Create a new virtual machine configure the system for our intended use. using qemu-
We downloaded the Debian 2.0 image from system-x86_
https:Z<github.com/palmercluff/qemu-images and then 64-boot d
Connection: QEMU/KVM
extracted the qcow2 file from the archive. -cdrom image.
Open Virtual Machine Manager and click File>New iso -m 1024.

Choose how you would like to install the operating system Virtual Machine or click the icon of a monitor with a star.
Local install media (ISO image or CDROM)
In the first screen Create a New Virtual Machine, select
Network Install (HTTP, HTTPS, or FTP)
Import Existing Hard Disk Image and click Forward. In
O Import existing disk image the next screen navigate to the location of the extracted
Manual install qcow2 file by clicking Browse, and then Browse Local.
Once you’ve selected the volume select Choose Volume
and then type in “Generic OS” under Choose the
operating system. Click Forward. Set the RAM to 64MB
and the number of CPUs to one. This is more than
enough for Debian 2.0. Click Forward and in the next
When creating a new VM we can insert an ISO image or CD/DVD ROM. screen name the machine “Debian2” and click Finish to
I We can also use a qcow2 or img disk image For a ready-made system. set the configuration and start the machine.

» OLD PC HARDWARE
Emulating old PC hardware with QEMU collector, it often needs lots of work to Capacitors may need replacing, and
is cheap - it only costs us a little hard make them ready for use. there may be leakage damage to the
disk space. But what if we want to use But say you do buy an old PC - what motherboard, so read up on how to fix
real hardware? This is where things do you need to do? First, make sure you this and test on a non-visible area before
become expensive. know your stuff before starting the job. moving on. The old beige cases may need
Looking online, we can see incomplete Take care with electrics and chemicals some Retrobright which requires UV light
486-era machines trading hands for for restoring a machine. If in doubt, seek and hydrogen peroxide in order to bleach
hundreds of pounds. So that 486 DX2 the knowledge of an expert. Older the plastic to the desired colour. Older
66MHz you fancy is now just out of machines used AT power supplies: it’s hard drives are also prone to dying, so
reach. Old PC hardware is expensive to possible they're broken, so make sure perhaps consider an IDE to SATA or IDE
ship and unless it’s in the hands of a you have a known working supply to test. to compact flash/SD card solution.

Ultimate Linux Projects | 59

Ultimate Linux Projects

On first boot we go through a typical Debian our user has no access to the sudo group; rather, we
configuration process. And yes it does say LILO: this need to switch user to root in order to make any
author remembers having to learn how to configure that system-wide changes.
to get their system to boot. Debian was a refreshing distro at this time. It was
The Debian configuration process starts by setting a easy to install and a joy to use. But our virtual time
root password, then we create a new user account for machine is ready to make a leap forward, to a time when
general access. When prompted to set up shadow the GUI installer was a big deal to sell the distro.
passwords, you can select yes or no - it makes no
difference. Do remove PCMCIA drivers if prompted. The 2000s - Ubuntu 6.06 Dapper Drake
Next we’re asked if we’d like to set up PPP, used for The first LTS (Long Term Support) release of Ubuntu
connecting to the internet via a modem. Answer N. was a big deal in 2006. It saw Canonical take a stance
The next screen asks if we’d like to run the dselect as a serious player in Linux, and saw many adopting the
program, used to automate installation. Select No and Debian-based distro as their main OS. In 2006 this
press Enter. If the dselect screen appears anyway, press author had just been playing with 5.10 for a few months
Q and Enter to drop into a Debian login. Enter your and was ready to make the switch from SUSE. Dapper
username and password and start using a few Drake came along, and despite being a shade of brown
commands to mess around with the system. Note that they adopted it for their daily workflow. Let's take a look
at it all over again. The Ubuntu installation process in
6.06 is barebones and really effective. Fifteen years
after it was released it still feels fresh and new.
Download the 32-bit ISO from httpiZ^old-releases.
ubuntu.com/releases/6.06.0 before opening Virtual
Machine Manager and creating a new machine.
In the first screen Create a New Virtual Machine,
select Local Install Media and click Forward. In the next
screen navigate to the location of the downloaded ISO
image by clicking Browse, and then Browse Local. Once
you’ve selected the volume the operating system name
should auto-populate to Ubuntu 6.06. Click Forward. Set
the RAM to 1024MB and the number of CPUs to two.
This is more than enough for Ubuntu 6.06. Click
Forward and in the next screen click Finish to set the
configuration and start the machine from the Live CD.
Now we follow a typical Ubuntu install.
Ubuntu 6.06 should run fine on the default settings,
but should we need to tweak them we can break out of
the virtual machine by pressing Ctrl+Alt+G and click the
blue information icon in the viewer window to open a
Ubuntu 6.06 “Dapper Drake” was the First LTS From Canonical. It changed how Ubuntu was configuration menu. We can change the RAM, CPU type
I perceived and it set the standard for many future releases. and insert virtual/real devices into the virtual machine.
Note that every change must be applied before moving
to the next item in the configuration. Changes to the
» VIRTUALBOX configuration take effect the next time the virtual
machine is power cycled.
QEMU isn’t the only way to create virtual machines. VirtualBox from Installing software and getting online is tricky. Most
Oracle is a tried and trusted means to create virtual machines, but it of the software repositories are now unavailable, so we
can’t emulate older hardware as effectively as QEMU. Installing need to install programs by compiling the code. Getting
VirtualBox is a simple task of downloading the latest version from online is possible, but this version of Firefox is no longer
www.virtualbox.org/wiki/Downloads and then following the supported and so we can’t access any HTTPS sites. But
installation guidance. We’ve successfully virtualised many Linux we can still relive the glory years of Ubuntu’s rise to
distros, including Linux Mint and Fedora with VirtualBox, and we have dominance, and that lovely shade of brown.
also virtualised Windows installs for projects.
VirtualBox has a straightforward process in which we create new The 2010s - the rise of Linux Mint
machines. During the process we can create virtual hard disks that Ubuntu had been the darling of the Linux distros for
are either a fixed size, for example an 8GB image file, or we can some time, but in the 2010s some grew upset with the
dynamically create a file hard disk file that will grow to the maximum introduction of Unity and an aubergine-based colour
that the host OS expects. Once a virtual machine has been created, scheme. Linux Mint was seen as an alternative. It had a
we’re free to tweak the RAM, number of CPU cores, VT-X or AMD-V similar back-end to Ubuntu, but a more traditional user
acceleration and add ISO images for boot. We can also create shared interface. Linux Mint also offered pre-installed codecs
folders with the host system, enabling easier file transfer. Networking for popular music and video formats. So via the super
is also handled for us, with no configuration necessary. simple installer, we can quickly get up and running. We
VirtualBox is proprietary software and as such it may not be for you. downloaded a suitable ISO from https:/7mirrors.
If not, then as we have shown in this feature, QEMU is more than up to evowise.com/linuxmint/stable/17.3.
your virtualisation needs. Setting up QEMU for Linux Mint is the easiest of
them all. In the first screen choose Create a New Virtual

60 | Ultimate Linux Projects

 How to run classic distros with QEMU TUTORIALS

Debian2 on QEMU/KVM
New VM File Virtual Machine View Send Key
Via the hardware
details menu we

—Create a new virtual machine II can tweak the

settings oF our VM.
Step 3 of 4 Overview Details xr More RAM, better
@ OS information Basic Details CPU and inserting
Performance discs, all via this
Name: Debian2
handy interFace.
Choose Memory and CPU settings: ® CPUS
UUID: 3bb0fa79-ec42-4fe3-aa0e-02f2cfa8fe92
Memory Status: Running (Booted)
Memory: 1024 — + Boot Options
Title:
IDE Disk 1
Up to 15958 MiB available on the host Description:
NIC:98:a9:55
Tablet
CPUs: 1 - + Mouse
Up to 8 available Keyboard Hypervisor Details
Display Spice Hypervisor: KVM
Sound ich6 Architecture: x86_64
Serial 1 Emulator: /usr/bin/qemu-system-x86_64
Channel spice Chipset: i440FX
When creating a new virtual machine we can set the RAM and CPU. IF Firmware: BIOS
I the OS is detected during the process, it’ll suggest the ideal values.
Video QXL

Machine, select Local Install Media and click Forward. In Pressing Enter will run this command and start the
QUICK TIP
the next screen navigate to the location of the boot. For a first boot we recommend running a live
downloaded ISO image by clicking Browse, and then session to test that everything works. After that you can By default,

Browse Local. Once you've selected the volume, set the reboot the virtual machine and install to the virtual hard Virtual Machine
Manager will
operating system name to Generic Linux 2016 and click disk.
store all of
Forward. The RAM and CPU will be set to 2GB and two
the hard disk
cores - this is based on our choice of “Generic Linux Linux today: The Undiscovered Country images in /
2016” in the previous screen. This configuration is more Today, we're truly spoilt for choice. New Linux distros var/lib/libvirt/
than enough for Linux Mint 17. Click Forward and in the are coming out at an accelerated pace, including images, but
next screen click Finish to set the configuration and specialist distros for media production, networking and we can also
start the machine from the Live CD. scientific projects. Older hardware is supported by specify our own
Now we follow a typical Linux Mint install, but there is lightweight distros such as MXLinux, which prolongs the destination
a possibility that you might hit a snag. During our install life of older equipment. Power users aren’t forgotten: we when creating
process the live CD refused to start the X server. This have bespoke gaming distros that use Wine, Proton or an image. Using
the terminal
required us to click the blue information icon in the DOSBox to run Windows games with the latest RTX and
it’ll default to
viewer window, navigate to Video/QXL and change the RX GPUs. By looking to the Linux distros of the past we
the current
video option to VGA. Apply and then power cycle the can see how our much-loved distros have grown. From
directory from
virtual machine. Everything went smoothly after this the humble text-based installer of Debian to the slick which command
and we were even able to install software and browse guided installation process of modern distros, our Linux is invoked.
the web via Firefox. experience is very different now - but we can still see
the rock-solid foundation under the hood. E9
Running QEMU From the terminal
Linux rorrndi • Muzina rirerox — ▼
So far we’ve created hard drive images and installed
Linux Format x ♦
distros using the Virtual Machine Manager. We can do the
;ttps linuxformat.com »
same thing using the terminal and Crunchbang++
(https:Z^crunchbangplusplus.org), a modern version of Most Visited ▼ Linux Mint 3 Community ’£ Forums £ Blog

Crunchbang Linux.
First, we need to create a virtual hard drive. In this Linux Format
case it’ll be a 10GB .img image called cbpp.img and it’ll
Archives About Linux Format Buy Linux Fori
be stored in the current directory: I

qemu-img create -f qcow2 cbpp.img 10G

We have a blank image ready for our install, so now Cinnamon 32-bfc
we need to configure our machine. This is a long Linux Format 278
command, so we’ll go through each option.
Buy it now! Read a sample
The first command invokes QEMU with 64-bit
support, then we use the -cdrom option to tell QEMU
where to find our Crunchbang++ ISO. Using -hda we tell
QEMU that we wish to use the cbpp.img virtual drive,
which is in the current directory. We then set the RAM to
2GB using -m 2048 , before setting up networking,
enabling the virtual machine to access the internet.
qemu-system-x86_64 -cdrom /path/to/iso -hda ./cbpp. Z O 14:40

img -m 2048 -netdev user,id=mynetO,hostfwd=t Linux Mint 17 is a great balance oF Form and Function. It looks great, and it came with everything
cp::8O8O-:8O -device el000,netdev=mynet0 I we needed to enjoy our computer.

Ultimate Linux Projects 61

Ultimate Linux Projects

Wiseguy Jonni Bidwell has some tips on making

our homes and home offices smarter,
with the latest FOSS offerings.

C reative ingenuity and the

ability to cram a network
stack into the smallest of
assistant can do all the good bits of these
voice devices, but without the more chilling
data-collection aspects. Best of all, you can
into unwitting makeshift extensions of the
workplace, and depending on your line of
work, that may be the case for the
things have gifted us, run Mycroft on a Raspberry Pi. foreseeable future or maybe even
over the past few years, some pretty But there’s more to smart homes than permanent fixtures from now on. So we’ve
funky home innovations. Legacy shouting at small robots. Once the colder got a couple of projects for smartening
(classical?) home dwellers may see little months settle in, good citizens will be your home office setup, too. Recuse
merit in upgrading to a smart home, but collectively donning long johns and firing yourself from Zoom meetings and banish
we have some uniquely Linux ideas that up their boilers, heatpumps and sacrificial Google’s office suite with the open source
may persuade them. pyres. Some may find themselves having powerhouses Jitsi Meet and Collabora
Having a smart home needn’t mean to shoulder the expense of a new boiler, Online. And since Docker is all the rage
having Alexa (the voice of Amazon’s Echo) others will want to see if their current one these days, we will look at how we can
eavesdropping on your every word. Nor can be hacked and tweaked to make for a harness its power better using the
does it mean the nameless entity within a more economical winter. Through the Portainer management engine. This will
Google Assistant reporting back to the magic of OpenHAB, we’ll show you how. make it easy for you to add any service you
mothership whenever you leave the For many of us, the COVID-19 pandemic can imagine to your self-hosted smart
bathroom light on. The Mycroft home has seen our homes shift and transform home office, so let’s get started!

62 Ultimate Linux Projects

 Build A Smart Home Office

A smart home office?

Take a look at some great tools that can make a smart home
smart, and a home office, er, official.
o the cynic, all this new smartification of In theory this could happen with open source
everyday items seems to involve putting projects too, but if it does, then at least the code is all
networked computers in places where there for someone else to take the reins.
they’re not needed, and needing so many companion
apps on one’s smartphone to keep tabs on all these Hot smart stuFF
smart things. In so doing, one opens all these devices Utility companies are keen for everyone to have smart
(and possibly your phone too) up to attack. meters now, and these go in tandem with smart boilers,
Some manufacturers are better than others at smart thermostats, smart fridges. In theory, these can
keeping their loT things secured, and many attacks save you money, and it’s certainly satisfying being able
could be prevented by users changing default to pre-warm your house as you travel home.
credentials. Since 2016, Raspberry Pi devices no longer We’ll show you how you can connect all of these
ship with the SSH service enabled because it’s too easy together through openHAB, the open source Home
to spot them when they're exposed to the internet. Automation Bus. Additionally, no smart home would be
But there’s a lot of smart home projects that are fun, complete without a Voice Assistant, so we’ll revisit our
safe and will bring some degree of joy to your home. old friend Mycroft over the page.
Lots of these are variations on standard Pi maker We’re also embracing Docker for this feature so we’ll
projects, we really liked, for example Elio Struyf's look at using that to smarten up your home office set
offering documented over at www.eliostruyf.com/diy- up, using the Nextcloud cloud productivity suite. Then
building-busy-light-show-microsoft-teams-presence. we’ve got some tips on containing this container
This project utilises an LED array as a status indicator overload with Portainer, which is a management engine
for outside your home office. used to constrain your container overload! The Unicorn HD,
We’ll also show you how to set up your very own with its 256 RGB
LEDs and Python
Watch this! video-conferencing service with Jitsi Meet. It’s going to
interface, could
The pandemic has gotten lots of us quite used to video be an action-packed few pages, so brew yourself a make an excellent
conferencing, and with that comes the terrible fear of nice cup of tea and get settled! warning light.
children (or grown up children) interrupting your work
chatter. Perhaps a brightly coloured warning light, that
in this case hooks in to your Microsoft Teams account
(it could be easily adapted to other services) to
see if your status is “busy”.
Home security systems are
all the rage too. Again, the
Raspberry Pi is
excellent at this, you
could adapt our
Motion tutorial
from LXF266 to set
this up, rather than
going with an
off-the-shelf product.
Besides security
concerns, such
products could at any
point stop being
supported by the
manufacturer, which makes
them useless. This happened
when Google bought Nest in
2014. Then in 2019 they
announced they were shutting
down the Works With Nest
program, effectively bricking all
the legacy Nest hardware that
wasn't produced by Google.

Ultimate Linux Projects 63

Ultimate Linux Projects

Use the power of Ubuntu’s openHAB appliance and the Mycroft

Voice Assistant to voice-enable your home.

he open Home Automation Bus (openHAB) go to the SSH keys section. Paste the contents into the

O can connect all the diverse loT appliances that

may or may not be beginning to proliferate

own, often proprietary applications, but often under the

Public SSH Key box and hit the import button. You can
now SSH into Ubuntu services and appliances (from
this machine only) using this key. But we still need to log
around your home. Typically, these devices all have their
our appliance into Ubuntu’s cloud to fetch it, so follow
bonnet they use open-source protocols - and when the steps below and do that.
they don’t, people have figured them out enough to plug Once setup is complete, take a note of your Pi’s IP
them into openHAB. We’ve covered installing it (and address and connect to it from a browser by entering,
indeed Mycroft over the page) in the pages of for example, http://192.168.0.2:8080. The openHAB
Linux Format before, but this time we’re going to do it a interface is a little confusing at first, especially given
little differently because Canonical has released the that the first step is ‘choose an interface’. You can
openHAB Ubuntu Appliance for the Raspberry Pi. This always return to this index page to explore the others.
means we can write an SD card image, boot it and have Choose PaperUI and peruse what Bindings (in the
a fully functional web-based home automation server. Add-ons section) are available, and if any of them
In order to use these Ubuntu Appliances (at the time match your hardware.
of writing, there were four others besides openHAB and From here, your best friend is the openHAB
more are on the way), you’ll need to sign up for Ubuntu documentation at www.openhab.org/docs. You can
SSO (Single Sign On) at https://login.ubuntu.com. It's customise your appliance however you like. It’s running
free and you can use it all over the Ubuntu web Ubuntu Core so you can add Snaps from the repos.
ecosystem. Once you’ve done this, you’ll want to Instead of following our later section on Nextcloud, you
generate an SSH keypair and upload the public key so can get a working install by SSHing into the appliance
that you can use your SSH-reinforced SSO to login to (the username is the first part of your Ubuntu SSO
your appliance. You may already have generated an email) and running:
SSH key, in which case you probably don’t want to $ snap install nextcloud
overwrite it. Check by running Visit the Snapcraft store (https://snapcraft.io) and
$ Is ~/.ssh/id_rsa.pub let us know how you augmented your appliance. Oh, and
If no such file exists, generate it with do check out the others; currently Plex, Nextcloud,
$ ssh-keygen -t rsa Mosquitto and AdGuard have been applianced, and
and press Enter to accept the default location. Once the more will surely follow.
key is generated, run cat ~/.ssh/id_rsa.pub and copy You might already know that Sherlock Holmes had
the contents to the clipboard. Log into Ubuntu SSO and an older brother called Mycroft - and that’s where the

INSTALL OPENHAB)
(Q OpenHAB R^pbetry Pi J & 4 mtd HUC

U9UHTU AFFUANCC

By opcrHAB Fcunotioc eV Home

■ Audio Multiroom • o z

Download Write the image to SD card | Boot your Pi

O Visit http://bit.ly/LXF268openhab
and download the image. It’s about
At least a 4GB card will be required,
and possibly more if you go all out with
I Connect a monitor, keyboard and
network cable (optional) to your Pi, insert
500MB, but compressed. You’ll need to extensions. On a Debian-based distro the freshly minted card, and fire it up. You
decompress it with xz -d openhab-corel8- (including Ubuntu) you can download the will see some configuration choices and
pi.img.xz if you’re going to write it out Raspberry Pi Imager from https:// eventually will be asked for your Ubuntu
manually with dd in the next step, but the downloads.raspberrypi.org/imagerand cloud email address (see above) so that the
official Raspberry Pi Imager program can install it with dpkg-i or graphically with appliance can be authenticated against
do this for you. Gdebi. Use this to write out the image file. your SSH keys.

64 | Ultimate Linux Projects

 Build A Smart Home Office

Mycroft Home Assistant gets its name. The Mark I

device was a friendly, ET-looking voice assistant that
was powered by a Raspberry Pi 3. We were big fans, but
sadly that device is no longer available, and its
successor has not yet been released. But that’s fine,
because Mycroft’s brains (or perhaps we should say
OS?,) are open source, and you can run them right now
on a Raspberry Pi 3 or 4.

Buster rhyme
It’s based on the official Raspberry Pi Linux Buster The HomeBuilder Ul allows you to build your own virtual LXF Towers,
image, and you can download it ay https://github.com/
MycroftAI/enclosure-picroft. Use the Raspberry Pi
I complete with mysterious library.

Imager again (or use something else, if you like) to write

the image to an SD card. This time you’ll need at least
an 8GB card. When it’s done, put the SD card into the Pi
and fire it up. As with the openHAB appliance, you’ll
need a display and keyboard connected to the Pi to run
the initial setup, but afterwards these will not be needed
unless something goes wrong. On first boot, Picroft will
resize its partition to use all available space on the SD
card. When it finishes booting a second time, it will ask
if you would like some help setting up your system,
which you may as well accept.
You'll need a microphone and speakers, and there’s An openHAB skill is available For MycroFt, so you can have your whole
a list of supported hardware over at the Mycroft wiki
(http://bit.ly/LXF268picroft). Some of this will work
I house respond to your vocal utterances and edicts.

out of the box, but some devices will need manual install. If you want to get back into the CLI, run
intervention. We used a Seeed Respeaker 4-microphone $ mycroft-cli-client
array HAT, which was easy to set up. Other devices will There’s a custom audio setup script called
follow a similar pattern. Just run audio_setup.sh and don’t forget to check the excellent
$ git clone https://github.com/respeaker/seeed- documentation at https:Z4riycroft-ai.gitbook.io/docs.
voicecard.git Mycroft can be installed on a regular Linux PC either as
$ cd seeed-voicecard a Snap Package, through Docker, or straight from their
$ sudo ./install.sh GitHub. The wake word engine, known as Precise, uses
If your network works (try rebooting if it doesn’t!) TensorFlow for cutting edge accuracy, which
you could also SSH into your Pi to do this (the default requires the host to have AVX extensions; most
username is ‘mycroft’ with password ‘pi’, which you machines from the last decade will.
should change soon).
Then, if you’re using the 3.5mm jack for audio, you
may need to run sudo raspi-config , select 7. Advanced » POWER AND PRIVACY
Options’, ‘A4 Audio’, and finally ‘1. Force 3.5mm jack’.
Now reboot to enact the changes. If you run into There’s still a couple of first generation Raspberry Pis keeping things
difficulties with the Respeaker (or other Seeed models), ticking over here at Linux Format. These older models are great - such
the driver documentation is at https://github.com/ as our Pi 2 running Volumio - but lots of projects (such as Mycroft)
respeaker/seeed-voicecard. will require more CPU power, so for a lot of projects you’ll see at least
Reboot and you can pair your device to the Mycroft a Pi 3 is recommended. If you have a Pi 4, you can even run a Jitsi
Home service. You need to set up an account here to instance that can handle a few callers with no problems. The trouble
use the software, but hey, at least it’s not Facebook. is, these later models require much more power, so it’s important to
Only your queries are collected, and these are used to use a power supply (ideally the official model) that can provide a
better train speech recognition. Just follow the prompts steady 5.1V supply at up to 2.5A. Cheap USB power supplies can
to set this up at https://home.mycroft.ai from another cause all kinds of hard-to-diagnose problems, so if something's
device; if your audio is working, you should hear some behaving oddly, the power is a good thing to check.
actual verbiage at this point. If not, you can rerun the Also we’re doing a lot of setting up of web services here, which has
setup wizard at any time with mycroft-setup-wizard . the potential to invite the whole world into your machine. So beware
Once everything’s working, the Mycroft CLI client will of leaving things running with default credentials, and do look at
start, and you can talk and type at it to your heart’s firewalling things that only need to run on the local network. You may
content. Shout the magic wakeword ,“Hey Mycroft,” to want to run things in a virtual machine, or on a ‘disposable’ virtual
prick up it’s digital ears, then try, “Tell me a joke”, “What private server to get a feel for them first.
is my IP address?” or “How much wood would a It’s your responsibility to maintain these services and keep things
woodchuck chuck if a woodchuck could chuck wood?” up to date, too. The journey is far from over once things are up and
He likes it when you say “Thank you”, too. Responses are running. Many companies offer, for example, hosted Nextcloud
again both verbal and on screen/terminal. You can quit storage, and this may be a better option for small businesses that
the CLI at any point with :quit and then you can run don’t want the burden of administering a server.
anything you’d run on a normal Raspberry Pi Linux

Ultimate Linux Projects | 65

Ultimate Linux Projects

Jitsi Meet
Set up, secure and self-host your way to video conferencing
nirvana, and you’ll never again have to use Zoom.

itsi Meet is a completely free, open-source just use IP addresses directly. But it’s probably easier in

O video conferencing program that you can

connect to via a browser or smartphone app.
You can use it right now by visiting https://meet.jit.si
and choosing a name for your virtual meeting (or indeed
that case to have an in-person conversation rather than
involving the machines... but where is the fun in that? If
you have a domain, the install process can automatically
generate Let’s Encrypt certificates, and then no one
accepting one of the amusing ones the website needs to see any security warnings.
randomly generates). There are no downloads or A Jitsi install is, in fact, a collection of several
configuration required by clients, they just require a link components, all working in harmony to bring bright
to be clicked which you can share by email from within smiley faces closer in a world that grows ever more
the meeting room. Or attendees can dial in and connect distant. Firstly, it relies on a web server (and some pretty
with a PIN. Simple. wild JavaScript) to provide the web frontend. You can
Obviously, Jitsi’s free service has some limitations, use Nginx or Apache here. Most of the software is
but these will be gone when we self-host our own Jitsi written in Java, so keen-eyed dependency spotters will
installation. You don’t need any particularly special note the OpenJDK runtime making an appearance.
hardware to do this, and thanks to the excellent Debian The magic of connecting more than two participants
and Ubuntu packaging, you don’t really need to do much is handled by Jitsi VideoBridge (JVB). This uses the
in the way of configuration at all. You will need a domain XMPP (like Jabber) and WebRTC (like Google Meet)
name, though; a free one from a dynamic DNS service protocols to swiftly route video to call participants.
such as DuckDNS or Dyndns will work. Deciding which participant is the speaker, and hence
As you can imagine (and we’ll look at this in a who users see ‘focused’ on their screens, is handled by
moment if you can’t), under the bonnet Jitsi is a rather Jicofo (Jitsi Conference Focus). Note that this is as close
complicated affair. Not only does it have to wrangle the to video processing as Jitsi gets - all the encoding and
vagaries of streaming through NAT gateways (such as decoding is handled on the user side. At the heart of it
home routers), it also needs to keep all this secure with all, the Prosody XMPP server keeps all these
SSL, so if you cheat and use a self-signed certificate, components and users connected. You’ll find more
your users will see scary warnings. information about these and everything else Jitsi in the
If you’re happy for you and your users to see these Handbook at https:Z^jitsi.github.io/handbook.
warnings (or brave enough to add an exception to your
browser), and your users are all local, you can get away Jitsi? Probably too much coffee
with using a bogus domain name and fudging users' In order for Jitsi to work for users stuck behind NAT,
/etc/hosts files to resolve this to your machine. Or even firewalls or other obstacles in the stack, XMPP messages
and web traffic must be able to flow freely to your server.
So you’ll need to open UDP port 10000 and TCP ports
» WHAT IF IT DOESN’T WORK? 80 and 443. TCP port 4443 can be used for fallback
communications (if UDP connections are blocked for a
If you can join a room from multiple locations but don’t see any other user). If you're doing this behind a home router, you’ll
participants and are stuck with a message telling you you’re the only need to forward these ports.
one here, port forwarding is almost certainly the culprit. In some In an ideal world, one-to-one calls should bypass the
configurations, the extra port 4443 will be necessary. Your next stop JVB, and connect directly to one another (so-called p2p
should be the log files. JVB and Jicofo’s are located in /var/log/jitsi mode), but this may be tricky to negotiate - as anyone
and Prosody’s is in /var/log/prosody. It’s handy to delete these after who ever tried to share files over MSN Messenger in the
a configuration change so that you don’t get confused by previous early aughts will tell you. Prosody can work with a TURN
logs. Alternatively, use tail to view the last few entries. After any (or STUN) server to facilitate this, but we won’t cover
configuration change, you’ll want to ensure that you restart all the this setup here.
services, which is a matter of: We will, however, get started with a simple setup after
$ sudo systemctl restart jitsi-videobridge2 jicofo prosody one final, but pertinent, warning: the default Jitsi
You might want to add nginx to that list, particularly if you’ve configuration allows anyone to start or join a meeting on
changed anything that will affect the frontend, such as the your server. If you leave your server running in this way
authentication we added earlier. And if it all goes wrong, you can for any length of time, sooner or later people or bots
purge all Jitsi data and configuration with: may discover your machine and potentially cause
$ sudo apt purge jigasi jitsi-meet jitsi-meet-web-config jitsi- trouble. The handbook covers how to set up
meet-prosody jitsi-meet-turnserver jitsi-meet-web jicofo jitsi- authentication, which you should do. You should also
videobridge2 check the philosophy behind this openness at https://
jitsi.org/blog/security. You’ll be fine using this guide to

66 | Ultimate Linux Projects

 Build A Smart Home Office

Jitsi is Free, easy

A meet.jit.si
to use, and its
random name
generation
5$ jitsi.org algorithm has been
a constant source
of amusement
Secure, fully featured, and throughout
otherwise
completely free video conferencing unamusing times.

Go ahead, video chat with the whole team. In fact, invite everyone you know. Jitsi Meet is a
fully encrypted, 100% open source video conferencing solution that you can use all day,
every day, for free — with no account needed.

Start a new meeting

GO
CharacteristicLiberalslllust

Connect your calendar to view all your meetings in Jitsi Meet. Plus, add Jitsi meetings to your
calendar and start them with one click.

Connect your calendar

get things up and running, but just make sure you stop skip this for now (just this once) and you will be greeted
the services when they're no longer needed. by the Jitsi welcome screen, from where you can start a
And now we can get on with installation. We’re more new meeting. Your web browser will ask for permission
or less following the Self-Hosting Guide in the Handbook, to use the camera and microphone, and you should see
so do check there if you run into difficulty. First add the a message saying that you are the rightful moderator of
Jitsi repo with: this room.
$ https://download.jitsi.org/jitsi-key.gpg.key | sudo sh Being alone in a room is no fun, so on another device
-c 'gpg --dearmor > /usr/share/keyrings/jitsi-keyring. (or get a friend to do this, if you have such a thing) visit
gpg' the meeting by appending a slash followed by the room
$ echo 'deb [signed-by=/usr/share/keyrings/jitsi- name to the server’s URL.
keyring.gpg] https://download.jitsi.org stable/' | sudo With that working, we can now address our server’s
tee /etc/apt/sources.list.d/jitsi-stable.list slightly too Open for Business attitude and add some
$ sudo apt update authentication. Edit the prosody configuration at
Then let the fireworks begin with: /etc/prosody/conf.d/meet.yourdomain.com.cfg.lua
$ sudo apt install jitsi-meet (replacing the domain name as appropriate). In the
During package configuration, you’ll be asked for your section beginning VirtualHost "meet.yourdomain.com"
Pi’s hostname, and whether you want to generate a new, change the authentication line, currently set to
self-signed certificate or use an existing one. Choose the anonymous, so that it reads:
first option if you don’t already have a valid one for this authentication = "internal_hashed"
domain. We’ll replace it with a Let’s Encrypt certificate Then add (and adjust the domain in) the following at
later. At this point, you should be able to log in to your the end of the file to set up a guest domain:
server using your web browser. Just point it to VirtualHost "guest.meet.yourdomain.com"
https://meet.yourdomain.com and you’ll see the scary authentication = "anonymous"
certificate warning we warned you about earlier. You can c2s_require_encryption = false
Don’t worry, the extra subdomains configured here
(’) Logout Language English
are only used internally so they don’t need a bona fide
DNS record. Now we’ll go from Lua to JavaScript and
Port forwarding add the guest domain to the frontend. Edit /etc/jitsi/
meet/meet.yourdomain.com-config.js and add the
This function allows for incoming requests on specific port numbers to reach web servers, FTP
servers, mail servers etc following lines to the hosts section:
anonymousdomain: 'guest.meet.yourdomain.com',
Create a new rule Finally we should make focus requests only available
to registered users, which is done by editing /etc/jitsi/
Local External
jicofo/sip-communicator.properties and adding:
IPaddress Port range Port range Protocol Enabled Delete
org.jitsi.jicofo.auth.URL=XMPP:meet.yourdomain.com
10000-10000 UDP / Now restart the services and add a user with the
192.168.0.9 443-443 443-443 TCP (?J
prosodyctl register command. You can now generate a
Let’s Encrypt certificate with:
192.168.0.9 4443-4443 4443-4443 TCP
$ sudo /usr/share/jitsi-meet/scripts/install-
I IF you don’t get your ports right, Jitsi will not play nice. letsencrypt-cert.sh

Ultimate Linux Projects | 67

Ultimate Linux Projects

Nextcloud
We’ve been relying on Nextcloud to keep our files in sync for
ages, and we think you should too.

egular Linux Format readers will be familiar ephemeral, fungible thing), so migrating the service just
with our ranting and raving about how great involves copying those volumes and connecting them to
Nextcloud is. And it keeps getting better - a new instance of the container.
the latest edition of the self-hosted storage and First on the agenda is to install the Docker engine
sharing platform, Nextcloud 19, sees it transformed which requires adding their GPG key to the apt keyring:
into a complete Collaboration Hub. $ curl -fsSL https://download.docker.com/linux/
If you already have a LAMP (Linux, Apache, MySQL, ubuntu/gpg | sudo apt-key add -
PHP) or equivalent stack set up on a home server or $ sudo apt-key fingerprint 0EBFCD88
VPS, you can easily add a Nextcloud instance to it, You should check the fingerprint of that key matches
either by extracting an archive to your web server’s root the one beginning 9DC8 and given in full in the
directory, or by copying the Web Installer PHP file there documentation at https://docs.docker.com/engine/
install/ubuntu (where you can also copy and paste
these lengthy commands). Next add the Docker repos
CONTAINERS ARE GREAT (change focal to bionic if you’re using 18.04), update
caches and install Docker with:
“Multiple instantiations of the same $ sudo add-apt-repository "deb [arch=amd64] https://
download.docker.com/linux/ubuntu focal stable"
container aren’t really a space issue, $ sudo apt update
$ sudo apt install docker-ce docker-ce-cli containerd.io
since the layers of the union filesystem Check that it’s working by running the Hello World
image, then fire up the Nextcloud image:
are shared between them.” $ sudo docker run hello-world
$ sudo docker run -d -p 8080:80 nextcloud
and running it directly. Setting up a LAMP stack (or The first switch tells Docker to run the container
indeed a LEMP stack with Nginx and MariaDB) is easy detached (in the background), and the second tells it to
enough (although it’s a bit of a faff having to create expose the container’s port 80 (where the webserver is
databases by hand) in Ubuntu or Debian - we’ve running) to port 8080 on our server. So now - once a
covered it before and there are countless guides a mere few hundred megs are downloaded and the container
DuckDuckGo search away. This time around, we’re springs in to life - if you browse your way to
IF you’re already going to install Nextcloud differently, via Docker. In http://yourserver: 8080 (with your address or
running an theory, this will mean our instance will be portable, so hostname) you should find the Nextcloud welcome
older edition of you could go from running on your VPS to running on a screen. You'll see a warning about the container using
Nextcloud you can
upgrade from
home server, or vice versa, with relative ease. Data and SQLite; this lightweight database will be fine for a few
the comfort of the configuration are stored in volumes outside the Docker users, but more popular setups will need a proper
web interface. container (which you should consider a fairly MySQL or MariaDB instance. Go back to the terminal,
find your container’s name (from the last column of
□ Hub 3.0 x © https://zembla.duckdr x +
the first command) and stop it with:
-> C A zembla.duckdns.org/nextcloud/updater/
$ sudo docker ps -a
Updater $ sudo docker stop yourcontainername
At this point, we could connect Nextcloud to a
v' Initializing MariaDB container and have both store their data in
Current version is 18.0.6. named volumes, which will provide portability. The
Update to Nextcloud 19.0.1 available, (channel: "stable")
Following file will be downloaded automatically:
resulting volumes will be available in the /var/lib/
https: //download. nextcloud. com/server/releases/nextdoud -19.6.1. zip docker/volumes/ directory. We can also add boring
names to our containers.
v' Check for expected files $ sudo docker run -d -p 8080:80 -name nextcloud -v
•y Check for write permissions nextclou d:/var/www/html nextcloud
'' Create backup
$ sudo docker run -d -v db:/var/lib/mysql -name mydb
-e MYSQL_ROOT_PASSWORD=secretl mariadb
Downloading
Getting these two containers to talk to each other is
Verifying integrity tricky, so we'll refer you to the Docker Compose section
Extracting in the documentation here, but we'll return to this idea
Enable maintenance mode
soon. Containers still continue to exist after they have
been stopped. Multiple instantiations of the same one

68 | Ultimate Linux Projects

 Build A Smart Home Office

Jazz up your
Nextcloud install
with a dizzying
X Your apps
array of add-ons.
Were big fans of
v' Active apps
the News app,
O Collabora Online
X Disabled apps which is making
RSS great again.
+ Updates

H App bundles Appointments Calendar

Book appointments into your calendar A Calendar app for Nextcloud

via secure online form.
Featured *
Z' Customization

Download and enable

Dashboard Download and enable
Featured

M Files
by Collabora Productivity based on work of
Frank Karlitschek, Victor Dubmiuk
i Games
AGPL-licensed_________________________

aren’t really a space issue, since the layers of the union One way or another, you’ll find your way back to the
filesystem are shared between them. But it’s nice to tidy Nextcloud setup screen, and then all further
up after yourself, so check your containers occasionally configuration will be free of terminal commands. You
with docker ps and clear unwanted ones, such as our just need to choose an admin password, use db for
database above, with: the database name (it uses Docker’s internal
$ sudo docker rm mydb networking so doesn't need a domain name) and wait a
If you want to get rid of everything (danger, beware), few moments for everything to be initialised. Your first
you can do so with: step should be to create a new user, which you can do
$ sudo docker rm $(sudo docker ps -aq) from the Users section in the drop-down menu in the
You could at this point go back to the web installer top-right of the display. It’s better to keep the admin
and enter some administrative credentials, doggedly account for, well, admin. While you’re here, you can use
proceeding with the SQLite database, and reusing the your useful administrative privileges to see how apps
first volume. But we’re going to borrow from the are added to Nextcloud. Select Apps from the user
community and use the example Docker Compose menu in the top right, and you’ll find a categorised
setup, skimming over a few details which you should list of them.
check in the documentation. Running Docker this way It’s good practice to keep your containers updated
uses four containers, one of which is a reverse proxy with the command:
running Nginx, which can provide SSL encryption $ docker-compose pull
(which is essential if you make this installation available from the directory with the docker-compose.yml file.
to the internet at large). Also existing here is a Let’s
Encrypt host to auto-update certificates. So if you’ve got
a domain name setup, the whole thing will be seamless. » COLLABORA ONLINE
Grab the Compose recipe and environment from the
Tutorials download, or fetch it from the nextcloud/ At the time of writing Collabora has released the latest version of its
docker repo on GitHub. Edit the docker-compose file, enterprise edition of LibreOffice: Collabora Office 6.4 (see
setting in particular the MySQL password, the virtual www.collaboraoffice.com). Alongside that offering is another
host (your domain name) and Let's Encrypt variables. enterprise release, Collabora Online, which provides an online version
Then follow the official documentation to install of the office suite that can be plugged into a file sync and share host
Docker Compose at https://docs.docker.com/ via the Web Application Open Platform Interface (WOPI).
compose/install, as this process may change. If A free version of Collabora Online - the Development Edition,
something doesn’t work, you can peer into the logs of aimed at home users - is available, and it can be connected to
each container, for example: your Nextcloud instance to provide functionality not entirely dissimilar
$ sudo docker logs compose_proxy_l to Google Docs.
<- c ft Secure http /nextdoud.\ipps;file^7dir-/Docurr.ent$&fi eid= 16
The easiest way to set it up is to use the Docker image and follow
the instructions at https://nextcloud.com/collaboraonline. The
•Zew

*= |
Instr: Format

liberation Sans * |
Sneet

10 ’]|
Data

B I
Took

U
Help

5ll‘ ^|E "S I S

burndc
CODE docker image listens on localhost:9980, so for this to be
$ % QD 01 °9 °. h

L37 E = accessible to the outside world the instructions use an Apache

reverse proxy. It’s recommended to have this proxy run on a different
4
5
domain (the same machine is fine) than your Nextcloud host, which is
6
7
8 a little complicated because for this to work smoothly you need to
9
10
11
12
have valid SSL certificates for both.
It’s possible to use the same domain (at a cost to security), or
13
14
15
16
17
18
self-signed certificates, but you may have to be creative in your
19
20
21
approach here. Once you’ve done the hard work, install the Collabora
22
23
24
25
Online app using your Nextcloud admin account, and then configure it
26
27
28
with the domain where the proxy is listening.
We haven’t heard the term ‘groupware’ since Novell Netware, but
Spreadsheets and charts within web applications and without Google. we're glad Collabora is bringing back the term with such style.
I We’re pretty sure Collabora is onto a good thing here.

Ultimate Linux Projects | 69

Ultimate Linux Projects

Portainer & Docker

Contain your sprawling smart home office with Portainer, then
ruminate on a fully featured email server with Mailcow.

I hen you’re running a home server or VPS, containers together. We'll start by creating a volume for

w I Docker is pretty great because you can add

" services without messing (too much) with
data, and then firing up the image.
$ docker volume create portainer_data
the underlying system configuration. As we saw with $ docker run -d -p 9000:9000 --name=portainer
Nextcloud though, even with just four Docker -restart=always -v /var/run/docker.sock:/var/run/
containers things were starting to become unwieldy. docker.sock -v portainer_data:/data portainer/
portainer
Note that images can be added according to their
EMAIL MADE EASY listing on Docker Hub, so you can find out more about
the Portainer image at https:Z^hub.docker.com/r/
“It’s often been said [including by us) portainer/portainer. You should find Portainer’s admin
panel now waiting for you on port 9000, so point your
that setting up an email server properly browser there, choose a password, select ‘Manage the
local Docker environment’ and enjoy the friendly
is hard. This is true, but we can set interface. If you installed Nextcloud through Docker
earlier, you should see all those containers listed in the
up a rough and ready container.” Local Endpoint on the Home screen. If you click
Containers on the menu on the left, you’ll see these
Portainer is a Docker management system that aims (and our latest Portainer container) in more detail. The
to restore order to your containers. quick actions column allows you to see each container’s
It comes in two parts, server and agent, which both logs, info, stats and also log in to each one directly from
ship as Docker containers. We’ll only need the server the browser. This is a great way to do some
image for this initial foray. The agent is used to marshall troubleshooting, but recall that containers in general are
Docker Swarms, which are another way of connecting quite minimal, so you won’t find any fancy utilities.
Adding a new container is easy. For example, if you
want to add Collabora’s CODE and connect it with a
Nextcloud install, hit the Add Container button and
» JITSI Pi IN THE SKY/CLOUD enter a meaningful name. In the Image field, enter
collabora/code , and in the ‘Manual network port
If you’re feeling adventurous, it is possible to install Jitsi Meet on publishing’ section enter 127.0.0.1:9980 in the host field
a Raspberry Pi 4 with 4GB (the 8GB version will perform better and 9980 in the container field. In the Advanced
though). This isn’t officially supported and setup is a little container settings below, go to the Env section and set
complicated. When we were writing this feature, our Pi 4s were all the following environment variables:
locked up in head office until such time as it was deemed Covid-safe. domain: shareWyourdomainW.com
We were feeling extravagant so we took advantage of Mythic username: admin
Beasts’ commitment-free, per-second billing and rented ourselves a password: yourpassword
remote Pi 4. Mythic Beasts' offerings use PXE booting and mount the Finally in the Restart policy column select Always, so
root filesystem via NFS from their own storage arrays. This means the container restarts on configuration change. Hit
you’re not at the mercy of unreliable SD cards, and also allows you to ‘Deploy’ and the container will spring into life. For
rent up to 250GB of storage. We were more frugal, and went with the guidance connecting it to your Nextcloud instance,
minimum 10GB; this costs just over £10 if it’s provisioned for a whole
month. With monthly billing it’s £7.50. JO
If you’re setting up Jitsi on your own Raspberry Pi locally, you might
have to do a little detective work (or plug in a monitor) to find your Pi’s Connect Portainer to the Docker environment you want to manage.

IP address on your LAN. And if you use Mythic Beasts' offering, be 4k Local
Remote J Agent 81 Azure
Manage a remote Docker Connect to a Portainer agent Connect to Microtoft Azure

aware that its Pi servers are connected by IPv6 only. A gateway is Manage the local Docker
environment
environment ACI

available so that IPv4-only users (that is, a large chunk of the UK’s Information

population) can still connect to it, but you’ll need a real DNS record Manage tne Docker environment where Portainer is running.

G Ensure that you have started the Portainer container with the following Docker flag

(DuckDNS doesn’t count here) to use it for anything other than as a v "ZvArZr uh/docber. nvcfc :/var/ri>n/4<K;ker %ocbM (Linux).

or

standard web host. We were a bit embarrassed that it took us a while •v \\.\pipe\4ocker engine:\\.\»XpeXdocker engine (Windows).

to figure this one out. ♦ Connoct

If you’re keen you can find a recipe to get everything working on the
Jitsi GitHub at http://bit.ly/LXF268jitsi. Besides running locally, Portainer can be used to manage remote

I systems running its agent.

70 | Ultimate Linux Projects

 Build A Smart Home Office

Mailcow:
portainer.io
= Containers CD Columns $ Settings dockerized
involves about 20
Home
+ Add container containers, but you
▼ LOCAL can disable a
Dashboard ft
Few oF them.
Q. Search...
App Templates

Stacks
State IS Quick
Q Name Stack Image
Filter T actions
Containers

Images □ mailcowdockerizGd_ipv6nat-mailcow_1 running Ej O -l** >_ mailcowdockerized robbertkl/i

Networks
Q mailcowdockerized_acme-mailcow_l running E O >_ mailcowdockerized mailcow/ac
Volumes

Events
Q mailcowdockerized_netfilter-m... running 6 l*s. >_ mailcowdockerized mailcow/n<

Host Q mailcowdockerized_nginx-mailcow_l running Ej O l*s. >_ mailcowdockerized nginx:main

SETTINGS
□ mailcowdockerized _rspamd-mailcow_l running I O >_ mailcowdockerized mailcow/rs
Extensions

Users EJ mailcowdockerized_php-fpm-mailcow_l running b O >- mailcowdockerized mailcow/pl

Endpoints
EJ mailcowdockerized_dovecot-mailcow_l running mailcowdockerized mailcow/d'
Registries

Settings
Q] mailcowdockerized_postfix-mailcow_l running Ei O 1* >_ mailcowdockerized mailcow/p'

Q mailcowdockerized_mysql-mailcow_l running Ei O l*i >_ mailcowdockerized mariadbHO

□ mailcowdockerizGd_redis-mailcow_l running Ei O l*i >_ mailcowdockerized redis:5-alpi

£I nnrtninAr in 1.24.1

check the documentation at https:Z^nextcloud.com/ should. The script generates mailcow.conf which you
collaboraonline. All going well, you should be able to may wish to tweak. We’ll just plough right ahead. First, in
specify it from Nextcloud, specifically from the case they get in the way, stop Nextcloud and any other
Collabora Online section in Settings. You may need to containers now. In Portainer do this by choosing
tweak the reverse proxy container to direct traffic to the Containers from the menu on the left, selecting all of
new container, if you used the Docker Compose them except Portainer (because that would be silly),
example on the previous page. and pushing the stop button. There’s a Kill button next
In that case you’ll find that example in the Stacks to it in case they don’t shut down gracefully, and you
section with a warning about it being created outside of can also remove them entirely if you don’t like them.
Portainer. In Portainer parlance, groups of containers Now return to the terminal (still using the root
are called Stacks, and it can only do limited things with account) and let’s fetch and unleash the Mailcow:
externally created Stacks. However, it’s easy to create a # docker-compose pull
new Stack; just paste, upload or point Portainer to the # docker-compose up -d
URL of a docker-compose.yml file. At this point, you technically have a working mail
Nextcloud’s own groupware, its Calendar, Talk and server. You should now be able to log in from the web
Mail applications, can be used for collaboration among interface, using the credentials admimmoohoo. But
users. The Mail app is just a client, so you set it up with a there’s still a lot of configuration to do. Not least of this
provider just as you would in a desktop email client. It’s involves changing that password, which can be done by
often been said (including by us at Linux Format) that clicking Edit next to the admin user to do this. If you
setting up an email server is hard. This is true, but we want to receive mail you’ll need to properly set up MX
can set up a rough-and-ready container running Postfix, records for your domain(s) with your DNS provider,
Dovecot and Roundcube and have a working (but not otherwise mail won’t be routed correctly.
necessarily well-configured) email set up in just a few Once you’ve done that, you can configure them from
keystrokes thanks to the Mailcow:Dockerized image. Mailcow’s Domains section, then you can configure the
Setting this up might offend the sensitivities of those actual addresses in the Mailboxes section. In a world of
adverse to running things as root, but the image uses endless spam, it’s important to do your bit by enabling
extended attributes and requires it. So let’s be a DKIM (Domain Keys Identified Mail), which signs
superuser and check our umask is set correctly (it messages originating from your server. DKIM-enabled
should print 0022). servers will verify this key when they receive mail from
$ sudo -i your domain, preventing malfeasance. E3
# umask
FRIDAY

Now we’ll clone the repository into /opt: AUGUST

2020

alhazred
# cd/opt J (tan ft Q, inbox C

# git clone https://github.com/mailcow/mailcow- [email protected]...

* uttd co 3077 M3
0
• 2 messages =" Order Received
"Personal Address Book" has been created
Friday. August 28. 2020 1109 UTC
airwnrd n 09

dockerized □ inbox
alhazred aitattfjjgjtaujiaxaikMffl abwa
alhazred 1107
Drafts

# cd mailcow-dockerized > Sent

-PersonalCalendar Ms free
* created UK<
The 'Personal Address Book
* folder has been created.

# ./generate_config.sh g Trash

You'll be asked for your domain name; this is the host Junk

Bi Archive

that it’s running on, not the domain of any email

addresses you want to set up. If your machine has
limited memory the script will suggest you disable Solr Once you've set up your mailboxes, you and your users can log into the
(the heavy-duty Java search platform), which you I SOGo webmail client by adding /SOGo to Mailcow's domain name.

Ultimate Linux Projects | 71

CODING
PROJECTS »
Coding a Space Invaders clone................ 74

Build a dynamic app

security pipeline.................................... 78

Programming a Turing Machine............... 82

Classic pseudo-3D racing road effects.... 86

How to code diagrams,

graphs and pie charts............................. 90

Build radio walkie-talkies with Python.... 94

Ultimate Linux Projects

PYTHON
Coding a Space
Invaders clone
Calvin Robinson will always extend the hand of friendship - unless
menacing aliens are descending from the skies, in which case... blast 'em!

pace Invaders is probably the most famous around, but it’s a module worth exploring further. To

B space shooter of all time, released way back in

1978 for arcades. Designed by Tomohiro

iconic fixed shooter and paved the way for shooting

install pyxel, open a terminal and run pip3 install pyxel.
Let’s begin by importing the random module built
Nishikado for Taito in Japan, Space Invaders was an into Python, along with our newly installed pyxel toolset,
and then declare and initialise all of our global variables:
games as a viable genre. The idea being that the player from random import random
controlled a space ship at the bottom of the screen and import pyxel
it was their job to move left and right to avoid enemies,
Calvin Robinson while shooting ordnance up the screen to destroy them. SCENE_TITLE = 0
is a former Nice and simple fun, so let's have a go at creating our SCENE_PLAY = 1
assistant own take on this retro classic. SCENE-GAMEOVER = 2
principal and We’ll be using Python to code our game, since it’s STAR_COUNT = 100
computer science one of the most versatile, accessible high-level STAR_COLOR_HIGH = 12
teacher and has programming languages on the market. Python is STAR_COLOR_LOW = 5
a degree in completely free and should be installed on most distros PLAYER_WIDTH = 8
Computer Games by default. However, there are multiple versions of PLAYER_HEIGHT =8
Design and Python, so let’s make sure we’re running the correct PLAYER_SPEED = 2
Programming. version by launching a terminal and typing sudo apt-get BULLET_WIDTH = 2
install python3 if you’re on a Debian based distro. For BULLET_HEIGHT = 8
other distributions, check your software download tool. BULLET_COLOR = 11
Once installed, we can either use a text editor or the BULLET_SPEED = 4
built-in Python IDLE to code. If using Python IDLE, ENEMY_WIDTH = 8
An intro screen,
remember to press File>New File to start an editable ENEMY_HEIGHT = 8
ready For the script document because by default Python IDLE opens ENEMY_SPEED = 1.5
game to begin. up a shell window, which won't save any changes. If BLAST_START_RADIUS = 1
you’d prefer to use your favourite BLAST_END_RADIUS = 8
SCORE Li text editor, just be sure to save the BLAST-COLORJN = 7
file with the .py extension, and it can BLAST_COLOR_OUT = 10
be run from terminal with the enemy_list = []
command python3 filename.py. bulletjist = []
We often use PyGame in these blastjist = []
tutorials because it offers a toolset We’ve set up some placeholders and basic settings,
that enables us to begin coding our most of which are self-explanatory. We have set values
Start Shootar game pretty much immediately, for our scene, points, the player, ammo and our enemies.
without messing around creating Sticking with best practice, we’ll be using Object
basic fundamental shapes or Oriented Programming throughout this tutorial. Not
physics. This time, we’re using a only will we be using classes from pyxel, but we’ll be
retro game engine called pyxel. pyxel creating our own functions so that we don’t need to
is an advanced toolset, complete repeat code. OOP is considered the most efficient way
PRESS EFlTER - with image banks, tilesets, and of programming video games.
editors for images and sound. It’s Let’s get our code sorted for drawing, updating and
fantastic for creating retro games. erasing lists, since everything in the game will be run
We’re not going too deep this time through arrays we declared and initialised earlier:

74 | Ultimate Linux Projects

 Coding a Space Invaders clone DING ACADEMY

def update_list(list): self.y += PLAYER_SPEED QUICK TIP

for elem in list: self.x = max(self.x, 0)
elem.update() self.x = min(self.x, pyxel.width - self.w) You can create
a standalone
self.y = max(self.y, 0)
executable
def drawjist(list): self.y = min(self.y, pyxel.height - self.h)
version of your
for elem in list:
space shooter.
elem.draw() if pyxel.btnp(pyxel.KEY_SPACE): Run pip3 install
Bullet( pyinstaller
def cleanupjist(list): self.x + (PLAYER_WIDTH - BULLET.WIDTH) / to get the
i=O 2, self.y - BULLET_HEIGHT / 2 dependencies
while i < len(list): sorted, then
elem = list [i] pyxelpackager

if not elem.alive: pyxel.play(0,0) shooter.py to

turn shooter,
listpop(i)
py into an
else: def draw(self):
executable.
i+=l pyxel.blt(self.x, self.y, 0,0,0, self.w, self.h, 0)
Now we can begin setting up the game environment. Upon initialisation we’re setting the x and
Let’s add a new class for the background: y-coordinates. We’re pulling the width and height in
class Background: from the global variables we set earlier, and most
def init(self): importantly, we’re declaring our player character to be
self.starjist = [] alive. Like in the other class, we’re setting a function to
for i in range(STAR_COUNT): draw and then update our player character. The update
self.star_list.append( function will move our player character when the
(random() * pyxel.width, random() * pyxel. appropriate key is pressed, at a speed based on the
height, random() * 1.5 + 1) speed variable we declared at the beginning.
That's our player sorted, let’s get our bullet ammo
set up, much in the same way as our player class:
def update(self): class Bullet:
for i, (x,y, speed) in enumerate(self.starjist): def init(self, x, y):
y += speed self.x = x
if y >= pyxel.height: self.y = y
y -= pyxel.height self.w = BULLET_WIDTH
self.star_list[i] = (x,y, speed) self.h = BULLET_HEIGHT
self.alive = True
def draw(self):
for (x,y, speed) in self.starjist: bullet_list.append(self)
pyxel.pset(x,y,STAR_COLOR_HIGH if speed > 1.8
else STAR_COLOR_LOW) def update(self):
Upon initialisation, we’re randomising the self.y -= BULLET_SPEED
appearance of the stars with a for loop and the
random module, appending them into our star list. if self.y + self.h -1 < 0:
We’ve also added functions and drawing and updating self.alive = False
the stars in our background.
def draw(self): Our player controls

Player one has entered the game pyxel.rect(self.x, self.y, self.w, self.h, BULLET­ the rocket ship
at the bottom
Next, we need to introduce our player character: COLOR) of the screen,
class Player: We’ll need a class for our enemies, too. The beauty of shooting the aliens.
def init(self, x, y): using classes, in an Object Oriented
self.x = x Programming methodology is that SCORE Llr-
self.y = y we can spawn multiple instances
self.w = PLAYER_WIDTH (objects) of the same thing, without
self.h = PLAYER_HEIGHT duplicating any code.
self.alive = True class Enemy:
def init(self, x, y):
def update(self): self.x = x
if pyxel.btn(pyxel.KEY_LEFT): self.y = y
self.x -= PLAYER_SPEED self.w = ENEMY_WIDTH
self.h = ENEMY_HEIGHT
ifpyxel.btn(pyxel.KEY_RIGHT): self.dir = 1
self.x += PLAYER_SPEED self.alive = True
self.offset = int(random() * 60)
if pyxel.btn(pyxel.KEY_UP):
self.y -= PLAYER_SPEED enemyjist.append(self)

if pyxel.btn(pyxel.KEY_DOWN): def update(self):

Ultimate Linux Projects | 75

Ultimate Linux Projects

if (pyxel.frame_count + self.offset) % 60 < 30: 0,

QUICK TIP self.x += ENEMY_SPEED [
Create your own self.dir = 1 "00088000",
image sprites else: "00eel200",
in the pyxel self.x -= ENEMY_SPEED "08e2bl80",
engine editor self.dir = -1 "02882820",
by running
"00222200",
pyxeleditor.
self.y += ENEMY_SPEED "00012280",
It’s an intuitive
"08208008",
pixel image
editor, useful
if self.y > pyxel.height -1: "80008000",
not only For this self.alive = False
project, but any
retro creation def draw(self): Likewise for the game sounds:
you might be pyxel.blt(self.x, self.y, 0,8,0, self.w * self.dir, self.h, 0) pyxel.sound(0).set("a3a2clal", "p", "7", "s", 5)
working on. The last of these series of classes is the destructive Pyxel.sound(l).set("a3a2c2c2", "n", "7742", "s", 10)
blast itself: The image sets and sound effects are completely
class Blast: customisable, but it does take further experimentation
def init(self, x, y): with the pyxel game engine.
self.x = x
self.y = y Background information
self.radius = BLAST_START_RADIUS Set the scene and draw a background and our player:
self.alive = True self.scene = SCENE-TITLE
self.score = 0
blastjist.append(self) self.background = Background()
self.player = Player(pyxel.width / 2, pyxel.height -
def update(self): 20)
self.radius += 1 pyxel.run(self.update,self.draw)
This will need updating - as with everything we draw
if self.radius > BLAST_END_RADIUS: onto the screen - in order to ensure the player always
self.alive = False sees the latest version when something changes:
def update(self):
def draw(self): if pyxel.btnp(pyxel.KEY_Q):
pyxel.circ(self.x, self.y, self.radius, BLAST-COLOR- pyxel.quit()
IN) self.background.update()
pyxel.circb(self.x, self.y, self.radius, BLAST-COLOR- if self.scene == SCENE-TITLE:
OUT) self.update_title_scene()
That’s all of our game elements set up, we can now elif self.scene == SCENE.PLAY:
begin coding the application window itself, by tapping self.update_play_scene()
into the pyxel module. The rest of the code features in elif self.scene == SCENE.GAMEOVER:
this tutorial belongs in the App class, so let’s create it: self.update_gameover_scene()
class App: Updating our title scene is simple:
def init(self): def update_title_scene(self):
pyxel.init(120,160, caption="Retro Shooter Game") if pyxel.btnp(pyxel.KEY_ENTER):
Of course, we could change the caption to anything self.scene = SCENE.PLAY
we like, and that would appear in the titlebar of our Updating our main game content, on the other hand,
Killing unfriendly
aliens results
game window. is a little more complicated:
in explosions. We’re now going to use the pyxel image sets to create def update_play_scene(self):
our sprites: if pyxel.frame_count % 6 == 0:
pyxel.image(0).set( Enemy(random() * (pyxel.width - PLAYER­
0, WIDTH), 0)
0, for a in enemy .list:
for b in bullet.list:
"OOcOOcOO", if (a.x + a.w > b.x
"0c7007c0", and b.x + b.w > a.x
"0c7007c0", and a.y + a.h > b.y
"c703b07c", and b.y + b.h > a.y):
"77033077", a.alive = False
"785cc587", b.alive = False
"85c77c58", blast_list.append(Blast(a.x + ENEMY.WIDTH
"OcO88OcO", 12, a.y + ENEMY_HEIGHT 12))
]/
pyxel.play(l, 1)
self.score += 10
for enemy in enemy.list:
pyxel.image(0).set( if (self.player.x + self.player.w > enemy.x
8, and enemy.x + enemy.w > self.player.x

76 Ultimate Linux Projects

 Coding a Space Invaders clone JDING ACADEMY

Finally, we need to code the draw functions. It’s

usually easier to draw something than to keep it QUICK TIP
updated, so these are the program’s shortest functions: Pyxel github
def draw(self): page Features a
pyxel.cls(O) comprehensive
wiki guide on
how to use the
self.background.draw()
game engine.
Try playing
if self.scene == SCENE_TITLE:
around with
self.draw_title_scene() different image
elif self.scene == SCENE.PLAY: sets and sound
self.draw_play_scene() effects to
elif self.scene == SCENE.GAMEOVER: altar the game
self.draw_gameover_scene() experience:
https:#github.

pyxel.text(39,4, "SCORE {:5}".format(self.score)z7) com/kitao/

pyxel
We’ll also need to draw the title scene, play scene
and ‘game over’ scene.
def draw_title_scene(self):
pyxel.text(35,66, "Start Shooter", pyxel.frame_
count % 16)
pyxel.text(31,126,"- PRESS ENTER -",13)
That’s the text to display on the start screen, but we
can change the text to something more suitable:
Roam the screen with the arrow keys to shoot those pesky aliens. “Shooter Game - Press Enter to begin”, for example.
The final two functions will prepare our bullets, enemies
and self.player.y + self.player.h > enemyy and blast effects for the game and game over scenes:
and enemyy + enemyh > self.player.y): def draw_play_scene(self):
enemy.alive = False self.player.draw()
blast_list.append( draw_list(bullet_list)
Blast( draw_list(enemy_list)
self.player.x + PLAYER_WIDTH / 2, draw_list(blast_list)
self.player.y + PLAYERJHEIGHT/ 2,)) def draw_gameover_scene(self):
pyxel.play(l,l) draw_list(bullet_list)
self.scene = SCENE_GAMEOVER draw_list(enemy_list)
self.player.update() draw_list(blast_list)
update_list(bullet_list) And finally, the text for our game over screen, again,
update_list(enemy_list) entirely customisable:
update_list(blast_list) pyxel.text(43,66, "GAME OVER", 8)
cleanup_list(enemy_list) pyxel.text(31,126,"- PRESS ENTER -", 13)
cleanup_list(bullet_list) That’s it. One more line left, make sure this one isn’t
cleanup_list(blast_list) indented. App() will call the App class we’ve just
A lot is going on here. We’re spawning enemies at finished, and kick everything off. Now press F5 to save
random locations, creating blasts when they’re and run our program, and if all went to plan we should
destroyed and cleaning up the sprites (remove the have a functioning graphical retro shooter game. Good
resources) when they’re no longer visible. luck, have lots of fun! E3
We’ll need to update our game over scene, too:
def update_gameover_scene(self):
. .SCORE HO
update_list(bullet_list)
update_list(enemy_list)
update_list(blast_list)
cleanup_list(enemy_list)
cleanup_list(bullet_list)
cleanup_list(blast_list)
if pyxel.btnp(pyxeLKEY_ENTER): I

self.scene = SCENE.PLAY
self.player.x = pyxel.width / 2
self.player.y = pyxel.height - 20
■5 HUE 01.1 E R •
self.score = 0
enemy_list.clear()
bullet_list.clear()
blast_list.clear()
Here we’re just doing some housekeeping, restoring
the lists, deleting unused sprites, and waiting for the They think it’s all
enter key to be pressed so we can restart the game. over... it is now!

Ultimate Linux Projects | 77

Ultimate Linux Projects

DAST

Build a dynamic app

security pipeline
Dynamic Analysis Security Testing takes centre stage in this coding
tutorial with Tim Armstrong.

he battle between developers and malicious

O
Create New App Initial Scan Environment
hackers is one that developers have been Configure initial scan environment. You can add more later.

losing. A lot of the time, it comes down to App Details

Development

mentality and company priorities. Hackers, like burglars, The environment your app is running in

only need to find a single open window or unlocked door •<£ Environment Host

OUR to get in. You wouldn’t check that you’ve locked your http://localhost:8000|

YAML
door only once every few months, yet this is the exact
EXPERT approach many companies take to security.
The uri ofyour running application to scan

Tim Dynamic Analysis Security Testing (DAST) is perhaps Adding an app in StackHawk is pretty straightforward, with a clean
Armstrong
is a former
the most overlooked stage of any security pipeline,
frequently relegated to a check-up every six months by
I
workflow and Ul.

Lead Engineer an outside consultancy that does an automated scan you just want to dive in at this point, then you can pick
turned with Burp Suite or Zed Attack Proxy (ZAP) and provides up a copy of the progress so far at https://gitlab.com/
Developer you with a (hopefully short) report and an invoice in the plaintextnerds/web-app-security-tutorial2-lxf280.
Advocate range of £3,000-30,000, mostly depending on the
specialising in scope. In most cases, the consultants don’t go further Too many acronyms
networking, than the automated scan because at that point they When it comes to DAST there are a growing number of
software already have enough to write a multi-page report. solutions in the market. Most of them use hosted
development, But here’s the thing: when malicious actors (aka scanners that run on a periodic schedule, so either you
and security. hackers) attack your web app, site or API, they aren’t need to expose a test environment to the internet and
You can find checking if your code is neatly formatted, they’re have the app scan that, or you need to set it up to scan
him on essentially doing dynamic analysis. They’re looking for a production - which is a bit late (and could lead to
Twitter as place where you’ve not validated the input, an endpoint instability of the production environment).
@omatachyru that you’ve forgotten to protect, cookie slack, a The goal here is, as it was when you added static
or via his vulnerable login system, leaked credentials and analysis and software composition analysis to the
website at hundreds of other things that are very difficult to detect pipeline, that you know about any vulnerabilities
www.plain statically. If you’re relying on a spot test every six before the code goes live so that you can fix them
textnerds.com. months then odds are you’ve got security holes that before it gets deployed.
you’re not aware of. What you need, then, is something that can run
Building DAST into your CI/CD only takes a few inside the pipeline to test the service on commit. So
minutes and gives you effectively that same information what are your options? Well, you could build your own
that you’d get from a pen-test where all they did was run solution around an open-source tool like ZAP, or you
an automated scanner. The main difference is that could pick up an off-the-shelf solution. Unfortunately,
instead of it only occurring every six months, the scan there aren’t many DAST solutions that you can build
happens every time someone merges a PR to the main directly into your Cl pipeline, with the leaders in this
branch - meaning you find out about the vulnerability space being StackHawk and GitLab. Both based their
when it gets merged. Ultimately this means that when scanners on ZAP, meaning that they can run in a Docker
you do bring in the external consultants for the six- container in your pipeline (or even locally).
month check-up, you actually get your money’s worth! StackHawk’s scanner, HawkScan, is a little more
In this tutorial, you’ll be adding DAST to a GitLab 01/ advanced than GitLab’s version and has support for
CD pipeline. We have covered this before in Linux multiple authentication methods and makes it easy to
Format magazine (LXF279 & 280, if you have them to customise the scanner. While StackHawk holds the lead
hand), and it’s a good idea to check those out first, but if in scanning capabilities, GitLab is ahead in pricing (for

78 Ultimate Linux Projects

 Build a dynamic app security pipeline DING ACADEMY

proprietary/closed-source software) as it’s included in Make sure you

Create New App YAML Download download the
GitLab Ultimate, and obviously, it’s also ahead in its Application Created! Download the stackhawk.yml config file and put
it in your application codebase. stackhawk.yml File
integration with the rest of the GitLab platform. App Details
and make a note oF
applicationld: 335cb406-03db-409c-9acO-883261bl65df ©
What really separates these two solutions from This Is your unique identifier for your app
the App ID as you’ll
0 Environment
others in this space, however, is their dedication to need it later.
Download stackhawk.yml
open-source, as both companies have decided to make
• YAML
their solutions free to open-source projects. Which, Bash PowerShell

considering that they are both built on ZAP (which itself Run the following Docker command to start your scan.

is an open-source solution), should perhaps not be a // load your StackHawk API key in the shell environment (9
S’ oii! -/. hawk/hawk. rc
surprise. Unfortunately, however, it is not that common, // execute Docker command to kick off scan

as even though a number of their competitors are also Sdocke run -e API KEY=${HAWK API KEY} --rm -v :(pw :/hawk

likely based on ZAP, the vast majority of them do not

extend the same offer. Looking for more information?
Check out our Documentation Back Finish

Street - er, StackHawk

Kicking things off with StackHawk, the first thing you’ll know how to run your app so that it can test it? The QUICK TIP
want to do is register an account over at answer to that question of course is that it doesn’t,
CI/CD pipelines
http://stackhawk.com so that you can set up your app so that's what you’ll need to define next.
can be
and get an API key-pair for your HawkScan instance To run the app in the CI/CD pipeline, you’ll need it optimised by
with which to push the scan results. running in a Docker container. This means you need to adding rules
When you open a Developer account, you get to use define a build stage that makes a Docker image from that dictate
it for free for one app so you can follow along even if the source code of the merge request. To do this, you’ll when a stage
you’re not working on an open-source project. If you are need a Dockerfile to build and a stage in the pipeline or job is to be
working on an open-source project, make sure you that will build it. run, which can
contact the StackHawk team to unlock that free When it comes to building a Dockerfile for a Django reduce costs
and improve
upgrade for your own team (they also help out start-ups project you only really need it to be a handful of lines
the developer
with special deals). long, like this:
experience.
With an account set up, make sure you’re on the FROM python:3.9
Applications dashboard and hit the ‘Add an App’ button. WORKDIR /usr/src/app
This will open up a modal dialogue box where you can COPY requirements.txt./
give it a name, configure the environment type, set the RUN pip install -r requirements.txt
hostname, and generate the Application ID and COPY ./i_am_vulnerable/..
stackhawk.yml config file.
Next, you need to generate your API key. Do this by EXPOSE 8000
clicking your profile picture at the bottom-left and then CMD ["python", "manage.py", "runserver",
going to Settings. From here go to API Keys and create "0.0.0.0:8000"]
a new key and copy it into your clipboard. Then, head Place this Dockerfile in the project’s src directory
over to the Settings page for the CI/CD in your GitLab next to the requirements.txt.
project and add it as a new variable with the key HAWK. To build this Docker image in the CI/CD pipeline
API_SECRET and with both the ‘Protect variable’ and you’ll need to add a new stage called build to the list of
‘Mask variable’ boxes ticked. While you’re on this page stages, placing it directly before the dynamic-analysis
you’ll also want to add the appjd as HAWK_APP_ID; stage. Then you’ll need to add a build job, that will look
however, you don’t need to tick the boxes for this one. something like this (code on the next page):
Next, you want to edit the .gitlab-ci.yml to add a new
stage and of course, the new job. To do this add the line
- dynamic-analysis » DEFENCE IN DEPTH
to the stages section, then add the job as follows:
hawkscan: Modern security practice involves accepting that, at some point, you
stage: dynamic-analysis will be breached. That doesn’t mean that you give up: it means that
image: docker:20 you plan for the eventuality. Once you have been breached you need
services: to detect and prevent lateral movement through the system so that
- docker:20-dind you know what has been leaked.
before.script: If you’ve been hit by ransomware, you’d better hope that you have
- docker pull stackhawk/hawkscan off-site backups. If your administrator credentials for your hosting
script: provider get stolen, you’d probably wish you had your infrastructure
■I defined as code so that it can be rebuilt quickly. If your database gets
docker run -v $(pwd):/hawk:rw -t \ leaked, then you’d want to be certain that you’ve encrypted sensitive
-e API_KEY="hawk.${HAWK_API_ID}.${HAWK_ data so that your customers don’t get exposed.
API-SECRET}" \ This kind of planning for disaster is essential in today’s world, and
-e NO_COLOR=true \ it’s not going to change any time soon. Laws won’t stop criminals and
stackhawk/hawkscan to put salt in the wound, at the moment governments around the
Something you might notice is that this job is quite world seem to be single-minded in making it easier for them (with
different from those defined in previous instalments of proposals like backdoored encryption, and online ‘real identity’
this series; this is because HawkScan needs to run in a verification being promoted by politicians).
DinD (Docker in Docker) environment. But how does it

Ultimate Linux Projects | 79

Ultimate Linux Projects

build-docker: «- Linux-Format-Demo mm scan Report a

» Development httpJ/djongoapp^OOO

stage: build Completed On Duration Hawkscan version

image: docker:20 Aug 06, 2021 atOO'MBST 49 secs 011 8

services:
- docker:20-dind
script:
- cd src
- docker login --username $CI_REGISTRY_USER
-password $CI_REGISTRY_PASSWORD $CI_

From the scan results view, you can see how many of the issues are
-tag $CI_REGISTRYJMAGE:$CI_COMMIT
SHORT.SHA
I new and how many still remain since you last triaged the results.

- docker pull stackhawk/hawkscan

- docker push $CI_REGISTRYJMAGE:$CI_ variables:
COMMIT_SHORT_SHA APP_HOSTNAME: $CI_REGISTRYJMAGE
So what does this do? Looking through the script script:
section of this job, you can see that it will login to the - docker login -username $CI_REGISTRY_USER
GitLab Docker repository for the project, then build the -password $CI_REGISTRY_PASSWORD $CI_
Dockerfile found in the root of the project directory REGISTRY
tagging it with the current commit tag, after which it - docker run -name djangoapp -d $CI_REGISTRY_
pushes the container up to the GitLab Docker IMAGE:$CI_COMMIT_SHORT_SHA
repository for the project. ■I
This is good to go, so you’ll need to make it available docker run -link djangoapp -v $(pwd):/hawk:rw -t \
to HawkScan. To do so, you’ll want to replace the script -e API_KEY="hawk.${HAWK_APIJD}.${HAWK_
section of the HawkScan job with the following code: API_SECRET}" \
- docker login -username $CI_REGISTRY_USER -e NO_COLOR=true \
-password $CI_REGISTRY_PASSWORD $CI_ stackhawk/hawkscan
REGISTRY build-docker:
- docker run -name djangoapp -d $CI_REGISTRY_ stage: build
IMAGE:$CI_COMMIT_SHORT_SHA image: docker:20
■I services:
docker run -link djangoapp -v $(pwd):/hawk:rw -t \ - docker:20-dind
-e API_KEY="hawk.${HAWK_API_ID}.${HAWK_API_ script:
SECRET}" \ - cd src
-e NO_COLOR=true \ - docker login -username $CI_REGISTRY_USER
stackhawk/hawkscan -password $CI_REGISTRY_PASSWORD $CI_
When you’ve finished, the first few lines of your REGISTRY
.gitlab-ci.yml should look something like this: ->
stages: docker build
- static-analysis -tag $CI_REGISTRYJMAGE:$CI_COMMIT_
- composition-analysis SHORT_SHA
- build
Once you’ve - dynamic-analysis - docker push $CI_REGISTRYJMAGE:$CI_
generated your hawkscan: COMMIT_SHORT_SHA
StackHawk API stage: dynamic-analysis Then you’ll need to add the stackhawk.yml file that
secret and APP
image: docker:20 was generated at the start to the root of the project.
ID you need to
put them where
services: Finally, you'll need to edit a couple of lines in that file,
HawkScan can - docker:20-dind so change the host field of http://djangoapp:8000
Find them. before_script: to http://djangoapp:8000/bad_sql and uncomment
the antiCsrfParam field and set it to be
Variables Collapse csrfmiddlewaretoken . Then git add , git commit and
Variables store information, like passwords and secret keys, that you can use in job scripts. Learn more. git push those changes up to the GitLab project.
Variables can be: This will trigger the pipeline which, in addition to
• Protected: Only exposed to protected branches or tags. running the SAST and SCA stages defined in previous
• Masked: Hidden in job logs. Must match masking requirements. Learn more.
instalments, will now build a Docker image, push that to
Environment variables are configured by your administrator to be protected by default.
the GitLab project’s Docker Registry and then run
Type t Key Value Protected Masked Environments HawkScan against the image, posting the result up to
Varable HAWK_API_SECRET ********★★*★***★★**★★
All (default)
your StackHawk account when it’s complete.

Variable HAWKAPPJD *********************

All (default)
Scan results
Add variable Reveal values
Results are broken down into three main categories.
High category should be fixed immediately as they pose

80 Ultimate Linux Projects

 Build a dynamic app security pipeline DING ACADEMY

FoIm Positive / HTTP Data Stream Protection

Piaintexrnerds •• Scans > Scan Details > Findings unr
**
https://djangoapp:443/1/vote/ Validate

<- Development ht(pJ/dj4ngo4pp.8000

HTTP Only Site medium

Evidence Activity » MAKING A POINT EFFECTIVELY
Request Rttponw
Category: HTTP Data Stream Protection

I he Me rs only served under nr IP and not Hi IPS

Cheatsheet
Headers (»)
If you're struggling to advocate for fixing a particular vulnerability, one
POST http^://djangoapp:443/l/votc/ HTTP/1.1 £)

of the best tools is learning how to demonstrate the risk. If you can
https:<7g<thut>.com.’OWASP/Ch«.«Sheet$ene$>t>''XVmattefr<neattheett/Transport
tayvi Protection Cheat Sneet.md User Agent: NttiUa/M (windows hi le.t: win
*
4: xM; rv:W.e> Gecko/2eie
Pidyma. ituiachf
Cathv Contfol: oucac-hv
• Arttoi ■ • Display AH ’ 1 -1 of 1
Content-Type: application/
*
-www-tor»-ur
Content-Length: 10J
I encoded
show the vulnerability in action and the damage that can be done, you
Hr 1 rrer•. h1fp: f/6)nngaapp • RON/1 /
Path Method Host: djnngnappTROftft
Cookie: csrftokcn-GK7CkSlr€XES8vwenMgx05VclDdCM3uwyEnoo€PRSww)IaSJ3AA4I will find the conversation shifts very quickly to how quickly you can fix
httpsy/dHngoopp.443/1/vote/ POST •

it. If it doesn’t, you might need to speak to someone higher up in the

organisation. If even that doesn’t help, then the organisation as a
The finding details view provides a very useful overview of the issue, whole has a serious culture problem and will likely have a big breach
the evidence, and the paths where it was detected so that you can in the future.
tackle it efficiently.
Demonstrating vulnerabilities is a far more effective way to get time
to fix vulnerabilities than just discussing them because it makes
an immediate danger to business continuity; Medium things far more tangible for someone who isn’t as capable or
are generally issues with known exploit paths, but might knowledgeable as you are.
not be a direct risk to business. Low category tend to be This is one of the main reasons that hacker conferences like Black
informational leaks (such as server versions) that could Hat and DEF CON are important, as they disseminate both defence
make an attacker’s job easier. and attack strategies, giving a more rounded exposure to the field.
Clicking one of the findings brings up a summary of After all, without knowing how to exploit something, understanding
what the specific vulnerability is, including some notes the potential risk and work out how to protect it is very difficult, and
on how a malicious hacker might abuse it. expressing the risk to others effectively is even harder.
Next to the findings is a complete list of the paths
scanned, so you know if HawkScan was able to find and
scan a particular path in your application. This can be normally as big of a problem as the high-risk ones, when
really helpful for ensuring that you have full coverage of coupled with other vulnerabilities they can be just as
the application. Web crawlers are rarely perfect, and the bad as a high-risk vulnerability. However, if you attempt
one utilised by HawkScan is no different; however, if the to treat everything as a sprint-breaking priority then
application you’re scanning has a GraphQL or OpenAPI/ management might start to ignore you as if you were
Swagger schema (or even a SOAP descriptor) then crying wolf - ultimately leading to the opposite of the
HawkScan won’t need to use a crawler and should hit desired outcome.
100 per cent of the paths every time.
It should be noted that just because a vulnerability Making a plan
isn't detected doesn’t mean that it isn’t there. At the If you’ve followed this series thus far, you now have a
time of writing, the SQL Injection vulnerability in the pipeline containing SAST, SCA and DAST. Once all three
bad_sql_practices Django app that is used as the base stages do not find any vulnerabilities, you should be in
example for this example was not detected by good shape moving forward.
HawkScan (or any of its competitors). However, it’s important to remember that this just
means there are no vulnerabilities found - not that they
Triage and False positives aren’t there.
Once we know of a vulnerability we need to triage it. The This is why it's important to take time to make a
first step to a good triage process is to discard known security breach response plan and to build your defence
false positives. When testing developer environments, in depth. When developing a complex stage to a CI/CD
like the one configured in this tutorial, it’s common pipeline, it can be a good idea to comment out the
to exclude things like TLS/SSL certificates. It’s no existing stages - otherwise, you can find yourself
surprise then that HawkScan detected it as an spending a lot of time waiting. E9
‘HTTP Only site’.
Because of this, the StackHawk Ul wishes to inform
you of the dangers of HTTP Only websites. However, as
this is a development-grade deployment this is not
actually a concern. To mark this finding as a false
positive, open up the finding, and at the top-right of the
page you’ll see a button labelled Validate and a
drop-down called Actions. From the drop-down you can
select ‘False Positive' and provide a description as to
why it should be ignored.
Once you’ve filtered out known false positives, the
next step of triage is to ensure that you have tickets in
your project management for all of the remaining risks.
Any high-risk vulnerabilities should be expected to
break sprint and receive immediate attention, as failure
to do so would mean knowingly leaving the door wide
open to attackers.
Medium-risk vulnerabilities are commonly scheduled A completed pipeline can take up to 15 minutes to run (or longer in more advanced projects), so
into the next sprint. This isn’t ideal as, while they aren’t
I combining stages can sometimes be necessary.

Ultimate Linux Projects 81

Ultimate Linux Projects

TURING MACHINES

Programming a
Turing Machine
It was the computer that started it all, albeit in theory. Mike Bedford
shows you how to program a Turing Machine and put it through its paces.

(Credit: www.turingarchive.org/viewer/?id=521&title=4 )
Ian Turing is probably best known for his
pioneering work on code breaking at the
Government Code and Cypher School at
Bletchley Park. In playing a key role in developing the
electro-mechanical Bombe device that was used to
OUR crack the Enigma cipher, Turing had a major impact on
shortening World War II by an estimated two years and
EXPERT saving as many as 14 million lives.
Mike Bedford Despite having been dubbed the “Father of Modern
is fascinated by Computing”, however, his contributions to
how simple general-purpose computing are less well-appreciated.
computer And here it’s interesting to note that his design for the
architectures - ACE computer, a cut-down version of which was
such as a Turning eventually built by the National Physics Laboratory in
Machine - can do 1950, predated the Manchester Baby, the world’s first Alan Turing’s Famous Turing Machine was never intended as a physical
anything the
most powerful
stored program computer, by three years. Arguably,
though, his biggest contribution to computing was his
I computer, although today’s simulations have brought it to life.

supercomputers vision for a machine that was never actually built, and instructions in the normal meaning of the word. So,
can do. would have been totally impractical had it ever become possibly for the first time ever, you’d be writing
a physical reality. This was the so-called Turning programs that aren’t sequences of instructions. Instead,
Machine and here we look at this model of computing a Turning Machine is a special type of Finite State
and see how to program it using a couple of simulators. Machine, as we’re about to see.
QUICK TIP A Turning Machine (TM) operates on an infinite tape,
Alan Turning Turning Machines divided into squares that we can think of as memory
might not have Alan Turing's concept of the computing architecture locations, each of which can contain a symbol from the
built a physical that now carries his name dates back to 1936, which machine’s alphabet of symbols. We can think of this as
realisation of was almost a decade before anyone figured out how to the equivalent of the memory in a PC, because the TM
his theoretical build a universal computing device. But since this was a can read and write symbols on the tape, albeit only at
computer, but so-called thought experiment, a theoretical concept the position occupied by the TM's read/write head.
Mike Davey
that he used to develop his theory of computability, it At any time, the TM is in one of a finite number of
has. See www.
didn't matter that it only ever existed on paper. What states. These can be as numbered, although it makes
aturingmachine.
com. It works
makes it so interesting to today’s programmers, though, more sense to give them names. Although TM’s don’t
on a real tape, is how simple it is compared to modern day computers, execute instructions, they do operate sequentially. Each
erasing old despite being capable of computing any function that operation involves reading the symbol at the current
symbols and the PC on your desk could compute. position of the read/write head on the tape and then,
writing new If you’ve ever delved into historic computers you’ll no depending on the combination of that symbol and the
ones as it doubt have encountered some extremely minimalistic TM’s current state, it writes a specified symbol to the
goes. Behind instruction sets. The Manchester Baby, for example, tape (which can be the same as the symbol it had read),
the scenes despite being a universal computing device, had just it adopts a new state (which can be the same as the
it’s controlled
seven instructions, compared to many hundreds or current state), and it then moves its read/write head
by a Parallax
thousands in today’s processors. Turning Machines are one position left or right along the tape.
Propeller
microcontroller.
even simpler, not in having even fewer instructions, but So, a particular TM is defined by its alphabet of
in using an architecture that doesn’t really have symbols, its number of states, and a transition table that

82 | Ultimate Linux Projects

 Programming a Turing Machine DING ACADEMY

Antoine Taveneaux, CC BY-SA3.0 https://commons.wikimedia.Org/wiki/File:Pilot_ACE3.jpg

defines the action in each step depending on the tape
symbol and the state. With this information defining the
TM, it can then operate on an initial sequence of symbols
on the tape -which is its input data, and the start
position on the tape. So, following that brief introduction,
we can try out a TM in our first simulator.

The Tursi simulator

To start, download the Java code for first TM simulator,
which goes by the name of Tursi, at https:/7github.com/
schaetzc/tursi. Although a TM can be designed to
perform any function that can be expressed logically,
even the simplest examples can take a huge amount of
time to execute, with the machine appearing to move
almost endlessly back and forth along the tape. So to The TM predated Turing’s ACE computer - initially built at the National Physics Laboratory in
limit the number of steps required to execute our first
example, we’ll carry out an arithmetic addition but, to
I 1950 as the Pilot ACE - by 14 years. Photo by Antoine Taveneaux.

keep things as simple as possible, we’re going to use can’t do any arithmetic on an infinite string of asterisks
unary instead of binary arithmetic. so ensure that the Head Position is 0, type 01110111110
You might not have come across the unary in the Tape box, and press the Enter key.
numbering system before so here’s a quick introduction. You’ll notice that your data - which represents the
Otherwise known as base 1, it follows the same rules unary numbers for 3 and 5, each delimited by zeros -
we've learned for interpreting decimal (base 10), binary appears on the tape, starting at position 0, with the
(base 2) or hexadecimal (base 16) numbers. So, starting head on the left-hand zero. Now try executing the TM
from the right-most digit and moving left we have one step at a time using the “find and execute next rule”
positions for one to powers of zero, one, two, three, etc. button which is the third button above Current State,
Uniquely among number systems, these all equate to and is the one that looks like a footstep with a forward
the same number, specifically one, which means that
the equivalent in unary of a decimal number is that
number of ones. So, for example, decimal 3 equates to » 2D TURING MACHINES
unary 111, and decimal 6 equates to 111111.
Although Tursi’s interface allows the operation of a Although 2D Turing Machines are no more powerful than the original
TM to be controlled, including writing the initial pattern ones, they're an interesting diversion. That’s because the grid of cells
to the tape and specifying the initial position, the enable graphical patterns to be calculated and displayed, especially
remainder of the definition is done externally. So, here’s if colours are written to those cells instead of letters or numbers.
the definition for unary addition, which you should enter Most of what we’ve learned about ordinary TMs applies to 2D
using a text editor: TMs, the only difference being that, instead of moving only left or
# ! start 0 right, the read/write head is able to move left, right, up or down. In
# ! end 4 some implementations the movement is defined absolutely, so we
# ! fill * can think of it as N, S, E and W, while in others it’s relative to the
000R1 current direction of the head so the angle of a turn is defined as 0,
101R2 90,180 or 270 degrees, after which the head moves forward. If you're
111 R1 looking for simulations of 2D TMs they're often called Turmites and,
L3
*
2O while there are plenty online, there don’t seem to be too many native
211R2 Linux applications so that could be an opportunity for you.
300L3 To get a feel for Turmites, go to https:Z/mdciotti.github.io/
310L4 turmites and try out the Turmite defined by {{{lz8,l}z{lz2z0}}z{{lz4zl}z{lz4z2}
The first two lines define the start state and any }/{{},{0,4,0}}}. This is intended as a curiosity as opposed to for serious
states that cause the TM to halt, and the third line coding, and it seems to be used mostly to try out random definitions
specifies a symbol to be written to all positions on the to appreciate the range of behaviours that can result from just
tape as an initialisation. The remaining lines, of which repeating a simple set of rules.
there should be one for each combination of the state
and read tape symbol (but only those that are expected
to be encountered), dictate the symbol that should be
written to the tape, the direction to move along the tape
(L or R), and the new state. So, for example, the line 2 0
* L 3 means that whenever the TM is in state 2 and
reads a 0 from the tape, it should write an asterisk to
the tape, move one space to the left, and enter state 3.
Now start up Turi and load your unary addition
program, and you’ll then see the transition table shown
as the various rules at the left of the screen. At the top
you’ll see that every position on the tape contains an
asterisk,and a couple of lines below, the Current State is
shown as 0, both of which we defined. However, we

Ultimate Linux Projects | 83

Ultimate Linux Projects

pointing arrow. As you execute steps, or enable Tursi

QUICK TIP automatic execution - that’s the green triangle button -

File View Help

"How Fast is a you’ll see the steps listed as they’re executed. For each
Turing Machine?” step, you’re shown the initial state, the symbol read
is surely a daft from the tape, the symbol written to the tape, the
question since direction moved and the new state. Hopefully you’ll find
it's a theoretical that it halts on step 12, having changed the zero
computer. For between the two numbers to a one, the final zero to an
a mechanical asterisk, and the final one to a zero. The result is,
implementation,
therefore, 0111111110 , which is the unary representation
though, Mike
for eight, again delimited by zeros.
Davey (see
page 92) came
up with some Vizualisation machine
estimates about Our second TM simulator is an online utility that you can The Tursi simulator offers an excellent way of creating a Turing
his creation
- From 3.1
find at https:Z<tu ringmachine, io and which calls itself
Turing Machine Visualization. This simulator has the
I Machine and putting it through its paces.

operations per benefit of a built-in editing facility so you don’t have to the binary arithmetic examples, namely the one for
second to use a separate text editor, it shows the TM as a state addition? Even with the two four-bit binary numbers
6.2 seconds diagram, and it has lots of example TMs that you can try defined in that example, it takes no fewer than 92 steps
^per operation.
out. The state diagram is interesting, and represents a to carry out the addition!
graphical alternate to the transition table as the Before moving on, we'll suggest an example for you
definition of a TM, as well as enabling you to follow to try yourself from scratch with little in the way of
progress graphically. Arguably, though, Turin provides guidance. The only bit of advice we’ll provide is that,
more information that could be useful in debugging, so below the state diagram and the editable code panel,
there might be some benefit in using both. That would the syntax for defining the TM is described. The exercise
involve maintaining two versions of the source code, we're suggesting is a traffic light controller. The one we
though, and keeping them in step with each other, implemented followed the sequence used in the UK
because the syntax used to define their TMs is different. (red>red+amber>green>amber>red ...) but you could
To get a feel for the operation of the Turing Machine implement the sequence used in other countries.
Vizualization, we suggest you start with a simple Although your Turing Machine might venture into a
example and, although it uses binary arithmetic instead blank cell, depending on how you implement it, your
of unary, it's still trivially simple. This is a TM to machine should write to just four positions on the
increment a binary number which is the second tape - the left-hand one which defines the phase of the
example from the menu in the title bar. Since we’re now lights, IE which combination of lights should be lit on
into the realm of binary numbers, and therefore we need the next change, and three others that can contain
both zeros and ones, the number to be incremented is either a zero or a one to represent whether the red
delimited by spaces. (top), amber (middle) and green (bottom) lights are
If you step through this example you’ll notice that the illuminated. This TM shouldn't halt, but should execute
current state is always highlighted on the state diagram forever, as do real traffic lights.
and the arrows representing the transitions are The traffic light problem makes a nice change from
highlighted as they occur. You can easily change the arithmetic operations, but it isn’t a particularly difficult
start pattern on the tape - that is, the binary number to exercise. After all, despite rarely having delved into TM
be incremented - by editing the code in the panel at the programming previously, we soon got it up and running.
This might be a right and clicking Load Machine. It should be fairly However, at the expense of being accused of coming up
somewhat Fanciful
obvious how this TM works. with something we didn’t have the time or confidence to
representation of
a Turing Machine,
To understand how laborious it can be to carry out try out ourselves, we're suggesting a more taxing
but it illustrates on a TM what would be trivially simple on any problem: adding together two decimal numbers. We’ll
the key principles. conventional processor, how about trying out another of give a bit of advice though. The normal solution involves
decrementing one number until it reaches zero and, for
each such decrement, increment the other number.
There’s an example for incrementing a binary number in
the Turing Machine Vizualization, and that could provide a
starting point for incrementing a decimal number and,
although there's no binary decrement, they’re not in
short supply so you’d easily be able to find one.

Universal machines
So far we’ve seen several examples of TMs that were
designed to do a particular job. But although you can
define a TM to execute any logical or arithmetic
function, this isn’t the same as the general purpose
computers we’re all familiar with. However, Alan Turing
did envisage exactly such a device, long before such a
machine ever materialised. The machine that did that -

84 | Ultimate Linux Projects

 Programming a Turing Machine DING ACADEMY

another hypothetical thought experiment - was the

Universal Turing Machine that we’ll refer to as a UTM. » ATM-ISH PROGRAMMING LANGUAGE
A UTM is a TM, in just the same way as all the other
TMs we’ve seen so far. Where it differs, though, is that If you fancy trying out another minimalistic form of computation you
the tape isn’t initialised only with the data on which it **
could try Brainf
k (we've censored the official name). It differs from
would operate, but also with data that defines the a TM in that it’s a programming language so you don’t have to deal
function of a particular TM that will operate on that with states, but in common with TMs, it operates on a
data. The parallel with today’s stored program one-dimensional list of memory locations that a pointer can move
computers is evident. Just as a PC stores its data and a along, one location at a time. Like a TM, it has just eight instructions,
program in memory, a UTM holds both data and the which are represented by single ASCII characters. The instructions
definition of a TM (a close parallel to a program) on its move the pointer left or right, increment or decrement the value at
tape. UTM simulators have been written but, given how the pointer, output or input the value at the pointer, and implement a
many steps it took on a TM to add two four-bit binary loop. Despite its simplicity, like the TM, this language is universal.
numbers, you can probably get a feel for how laborious **
Brainf
k interpreters for Linux are common, as are compilers, both
a UTM would be in its operation. For that reason, we’re as source code and executables, which can be smaller than 200
not going to recommend that you try one out yourself, bytes. However, one of the easiest solutions is to head over to
but simulators do exist if you really want to delve more https:/7bit.ly/lxf271bf and enter the program ,>,[<+>-]<------------------
into the hypothetical machine that paved the way to ----------------------- . which prompts for two single digit decimal
pretty much all today’s computers. numbers, adds them together and outputs the result, but only for
It’s interesting to think about how a TM, including a single digit answers.
UTM, could be improved to make it more efficient and To help you understand it, the commas are inputs, > and <
various people have done exactly that. One example is a increment and decrement the pointer respectively, + and - increment
two-tape TM. We can imagine that this would be an and decrement the value at the pointer respectively, a [] paring
effective approach for a UTM since the data could be executes the instructions between them until a zero result is
held on one tape and the program on the other, thereby encountered, and a full stop is the output instruction. Oh, and the 48
reducing the amount of stepping back and forth minus signs are needed because the values input and output are ASCII
between the data and the program areas of a single characters, in which code the figure zero is 48, one is 49, and so on.
tape UTM.
Going one stage beyond multiple tape TMs is the 2D
TM which, instead of operating on a one-dimensional therefore, if you had a utility that analyses a program and
tape, operates on a two dimensional grid. This takes us its data and indicates whether it will halt or run forever. QUICK TIP
a bit closer to random access memory, as opposed to The Halting Problem is supposed to answer this Go to www.
the original TM's sequential memory, and again it would question using a TM, which analyses the definition of redFrontdoor.
result in a significant reduction of the movement of the another TM and its data. And it wasn't just that Turing org/turing-
read/write head on the tape or grid. If you fancy trying couldn’t figure out how to solve the problem. Using a mandelbrot.
out a 2D Turning Machine, be sure to take a look at the rather clever logical argument, he proved that it’s to see how
Try a 2D Turing Machine box (box on page 83), but uncomputable. So, you couldn’t solve the Halting the Mandelbot
Set has been
there’s one important thing we need to stress. Problem for a TM on your PC, and nor could you
plotted on a TM.
The fact is that a multiple tape TM or a 2D TM is no determine whether a program written in Python or Java
Amazing stuFF!
more powerful than the original single tape TM. All other will get stuck in an infinite loop. In at least one sense,
things being equal, these derivations and others would therefore, we’d have to conclude that we’ve really not
be faster, perhaps considerably so, but they wouldn’t be progressed since 1936. Or, more positively, we surely
more powerful. And going even further, your PC or even have to recognise how future-looking Alan Turing’s
the world’s fastest supercomputer, the 514 PFLOP/s concept was when he devised it all those years ago. E3
Fujitsu Fugaku with its 7,299,072 cores, is no more
powerful than a standard TM. An apparently bizarre
Turing Machine Visualization binary addition edit*

statement, you might think, but in the realm of the

theory of computation, power refers to what a computer LOAD MACHINE REVERT T<

architecture is cable of doing. And the fact is that the 1

2
S Adds two binary numbers together.

3’ s Format: Given input a

*
b where a ano D are binary numbers,

humble Turing Machine can solve any problem that can 4

5
6
s leaves c b on the tape, where c • a«b.
« Example: ’11’1’ -> ’100 1’.
*
11001
input: •1011 1
7 blank: ’ ’

be solved by the world’s fastest supercomputers. 8

9
start state:
- table:
right

10 s Start at the second number's rightmost digit.

As we draw to a close, however, we should point out 11’

12
13
right:
]:
*
[0,1,
’ •: {L:
R
read}

the corollary of our last statement, namely that if a TM

14
15 * s Add each digitfrom right toleft:
16 « read the currentdigit oftne second number,
17 ’ read:

can’t solve a given problem then it couldn't be solved on 18

19
20
0: (write: c, L: have0}
1: (write: c, L: navel}
♦: {write: ’ ’, L: rewrite}

a multi-million core beast of a machine. What’s more, 21

22
23
s and add it to the next place of the first number,
2 marking the place (using 0 or I) as already added.
have©: {[0,1]: L, «•: {I: add0}}
24 have!: {[0,1]: L, ♦: (L: addl}}

Alan Turing came up with a problem - the so-called 25 •

26
add0:
[0,1 ']:
:
(write: 0, R: back©}
(write: I, R: back©}
27 1

Halting Problem - that can’t be solved on a TM. Today, of 28

29 ’
30
addl:
[0,’
[0,1]

']:
: L

{write: I, R: backl}
31 1 : (write: 0, L: carry}

course, most PC applications run forever until the user 32

33 ’ carry:
[0,1] : L

34 [0/ ’]: (write: 1, R: backl}

chooses to close it. If you’re a programmer, however, 35

36
37 ’
1 : {write: 0, L)
s Then, restore tne current digit, and repeat with the next
back©:

you’ve no doubt written code that’s supposed to solve a

38 [0,1,0,1,’]: R
H 39 c: (write: 0, L: read}
RESET RUN
STEP 40’ backl:
41 [0,1,0,I,.]: R

particular problem and then halt. If you get it wrong, 42

43
44
c: (write: 1, L: read}

s Finish: rewrite place markers back to 6s and Is.

however, it’s all too common for that code to run forever, 45’
46
rewrite:
0: {write: 0, 1}

never halting, at least for some combination of input The Turing Machine Visualization provides a different representation to Tursi by showing the
data. So it might be quite handy for debugging, I TM’s state diagram.

Ultimate Linux Projects | 85

Ultimate Linux Projects

PYGAME
Classic pseudo-3D
racing road effects
With a bag of silver coins in hand, Andrew Smith whisks us back to
the classic arcade days to recreate pseudo-3D racing games.

ue the budget wibbly-wobbly ‘going back in

Q time' special effects, as for this coding tutorial

we’re going to look at some the old-school
techniques used in some of the classic racing video
games such as Road Rash (1991), OutRun (1986) and
Pole Position (1982). Designed to work smoothly on
low-powered hardware, these are smart visual tricks
that create a fake 3D effect.
Andrew Smith What is known as pseudo-3D techniques were used
is a software to create a simulated 3D racing effect. The games would
developer® NHS often be played by a single player or two players against
Digital, has a computer opponents. The Pseudo 3D Road project
Bachelors degree (created by Ray Tomely) that we will be looking at, even
in Software though not a full video game, is a selection of examples I The absolute classic racing game Pole Position by AtariSoFt.
Engineering and of pseudo-3D techniques demonstrating ways to
an MSc in generate the 3D effect. You will see that once the specific such as Notepad++, PyCharm or VS Code. The
Computer project has been downloaded, these programming choice is entirely up to you. For this tutorial, we will be
Networks. techniques are located in different folders that each usinggedit to view and edit the source files. When using
demonstrate a pseudo-3D effect. this method to view/edit source files, it maybe helpful to
open up two console windows where one will be used
Getting started for editing/viewing source files and the other is a
To get started, we will need a few things: Python, terminal window for executing the PyGame code.
PyGame and the Pseudo 3D road project. To install Within the simple_road folder, the source code file
Python, open a terminal window (Ctrl+Alt+T) and type that we want is simple_road_curve_segment_demo.py.
sudo apt-get python3 followed by sudo apt-get install Before we look at the source code, navigate into the
pip3 . Then install the PyGame module by typing pip3 simple_road folder and type the following to
install pygame . execute the script.
Finally, grab a copy of the Pseudo 3D road project $ python3 ./simple_road_curve_segment_demo.py
from https://raytomely.itch.io/p by clicking the On successful execution you should get the output
Download button towards the bottom of the page. Once as seen in the image on page 88. The script executed
everything has downloaded, extract the contents of the has only been implemented with a forward control using
pseudo_3d_road_collection.rar file into an accessible the Up cursor key, and you will need to close the
location on your system. program with a mouse to end the program. As you hold
As an example, the whole project has been put into a down the Up cursor key, you will see the generated road
folder called PythonProjects which was created before go from being straight to having a bend in it and then
downloading the project. If you are already an LXFfan, back to being straight again.
the source code and project can be retrieved from the
LXF281 DVD (find it here bit.ly/lxf281). This tutorial will Getting curvy
focus on the source code located in the folder called To view/edit this source file type the following into
simple_road. Type cd simple_road to get into it. another terminal window:
To edit and view the source code, you can either use $ gedit ./simple_road_curve_segment_demo.py
a default text editor installed on your flavour of Linux You will see that it’s commented throughout to
(Ubuntu, for example) or you could use something more indicate what the variables are used for. As with any

86 | Ultimate Linux Projects

 Classic pseudo-3D racing road effects iDING ACADEMY

other Python/PyGame script, at the top of the source A andrew@dell-ubuntu-01: ~/PythonProjects/pseudo_3droad The Final Folder
andrew@dell-ubuntu-01:~/PythonProjects/pseudo_3droad$ Is structure once the
code the libraries needed to run the script are declared. floorcasted_road projected_road readme.txt simple_road z_map_ project has been
Also notice that continuing on from this, global variables andrew@dell-ubuntu-01:~/PythonProjects/pseudo_3droad$ Is -I
downloaded.
total 20
for the script are declared to define the colours for the drwxrwxr-x 2 andrew andrew 4096 Aug 30 2020 orcasted_road
drwxrwxr-x 2 andrew andrew 4096 Aug 30 2020 projected road
other parts of the road. See the following below: -rw-rw-r-- 1 andrew andrew 147 Aug 30 2020 readme.txt
import pygame,sys drwxrwxr-x 2 andrew andrew 4096 May 15 10:17 impleroad
drwxrwxr-x 2 andrew andrew 4096 Aug 30 2020 zjap^road
from pygame.locals import * andrew@dell-ubuntu-01:-/PythonProjects/pseudo_3droad$ []

BLACK=pygame.color.THECOLORS["black"]
WHITE=pygame.color.THECOLORS["white"]
RED=pygame.color.THECOLORS["red"] def main():
GREEN=pygame.color.THECOLORS["green"] pygame.init()
BLUE=pygame.color.THECOLORS["blue"] #Open Pygame window
YELLOW=pygame.color.THECOLORS["yellow"] screen = pygame.display.set_mode((640,480),) #add
SCREEN_WIDTH=640 RESIZABLE or FULLSCREEN
SCREEN_HEIGHT=480 #Title
HALF_SCREEN_HEIGHT=int(SCREEN_HEIGHT/2) pygame.display.set_caption("simple road")
The screen resolution settings SCREEN-WIDTH #font
and SCREEN-HEIGHT are set to relatively low values font=pygame.font.SysFont('Arial',30)
in regards to today’s device screen capabilities. Please #images
feel free to change these for a higher resolution screen light_road=pygame.image.load('light_road.png').
setting if you’re not happy with them. In addition to convert()
changing this, you will need to add two lines of code to dark_road=pygame.image.load('dark_road.png').
ensure that the images loaded will always meet the convert()
screen resolution specified. light_strip=pygame.Surface((SCREEN_WIDTH,l)).
Add the following lines just after the images convert()
light.road.png and dark_road.png have been loaded, dark_strip=pygame.Surface((SCREEN_WIDTH,l)).
as shown below. convert()
light_road=pygame.image.load(Tight_road.png'). Iight_strip.fill(light_road.get_at((0,0)))
convert() dark_strip.fill(dark_road.get_at((0,0)))
light_road = pygame.transform.scale(light_road, #variables
(SCREEN-WIDTH, SCREEN-HEIGHT)) texture_position=0 #this is used to draw the road
dark_road=pygame.image.load('dark_road.png'). As with all PyGame scripts, PyGame is initialised with
convert() a pygame.init() function call as can be seen from the
dark_road = pygame.transform.scale(dark_road, above code. Also notice that when the screen display is
(SCREEN-WIDTH, SCREEN-HEIGHT)) set up, where there is the line:
You will also need to alter the following line of code in screen = pygame.display.set_mode((640,480),) #add
the script. Change RESIZABLE or FULLSCREEN
bottom_segrnent={'position':240,'dx':0} it misses out using the variables SCREEN-WIDTH and
to SCREEN-HEIGHT declared above. Replace the value of
bottom_segment={'position':SCREEN_ 640 with SCREEN-WIDTH and the value of 480 with
HEIGHT/2,'dx':0} SCREEN-HEIGHT so that the screen resolution can be
If the SCREEN-WIDTH and SCREEN-HEIGHT adjusted to suit your device.
are changed and the above changes are not done, the Notice that there are just two images loaded to
display will look odd when running the program. create the intended effect and the rest of the effect is
The main operation of the script is carried out in a created by use of internal colour schemes to create
defined main() function which is shown in part here: alternating strips.

» CREATING THE ROAD

The road is created with a combination of screen.blit(light_road, (curve­ the same time the road is. What is also
two images loaded near the beginning of value,i+HALF SCREEN worth pointing out is that when the strips
the script, light_road.png and dark­ HEIGHT),(0,i,SCREEN_WIDTH,1)) are drawn, they stretch from one side of
road.png, and also two colour strips else: the window to the other: the road is
created with light and dark tones for the screen.blit(dark_ overlaid on top of the strips to give the
grass area outside of the road. The colour strip, (0,i+HALF_SCREEN_HEIGHT)) illusion the grass is at each side of the
of the grass is picked from the light and screen.blit(dark_road,(curve­ road. To help create the curve effect in
dark images respectively for the grass value,i+HALF SCREEN the road (left-hand bend), only a part of
colour. Let’s look at the code that HEIGHT),(0,i,SCREEN_WIDTH,1)) the image for light and dark road are
generates the graphics for the road. As can be seen, when rendering the redrawn with an offset x-position by
if texture_position<half_texture_ road, an if/else statement is used to curve_value . Each image segment which
position_threshold: determine whether to render a dark part is rendered on the screen is incremented
screen.blit(light_ of the road or a light part of the road. The slightly more than the last to give the
strip,(O,i+HALF_SCREEN_HEIGHT)) grass outside of the road is rendered at road a left-bend.

Ultimate Linux Projects | 87

Ultimate Linux Projects

In every PyGame program there needs to be a exceeds the value of texture_position_threshold

main loop that renders the graphics used in the (currently set to 300), the value of road_pos is set back
program and that also controls input for the game via to 0 and the process is repeated. If you think of a
keyboard and/or mouse depending on the PyGame conveyer belt or treadmill mechanism where the track
application being developed. Let us have a look at the used is on a continuous cycle or loop, this is a very
main loop implemented in simple_road_curve_ similar idea here for the pseudo-3D effect. The road is
segment-demo.py. continually re-generated after a certain point is reached.
while True: To help control when the bend on the road appears,
#loop speed limitation there is the following line of code after that which deals
#30 frames per second is enough with the Up cursor key and after the initial road
pygame.time.Clock().tick(30) processing code:
for event in pygame.event.get(): #wait for events curve_mapjndex+=curvejncrement
if event.type == QUIT: Initially, the value of curve_map_index is set to -1,
pygame.quit() however the value is incremented by curvejncrement
sys.exit() (currently set to 2) on each cycle that the player has the
#Movement controls Up cursor key pressed.
keys = pygame.key.get_pressed() As the Up cursor key is pressed, you should start to
if keys[K_UP]: see the road go into what looks like a left bend and then
As can be seen from the code above, the main while back to being a straight road again. Let’s look at the
loop ends on a Boolean condition to identify when the code that controls this.
program has finished. In the case of the above, the loop if curve_map_index>=curve_map_lenght:
ends when a False condition is raised. Continuing on curve_map_index=curve_map_lenght
from this, the frame rate is declared at 30 frames a curve_increment
=-l
*
second and further on from this the input/keyboard #if we exit, we invert its incrimintation to enter again
control is set up. #we invert the curve's direction to change the way
Finally, after doing all this, we come to the final part elif curve_mapJndex<-1:
of the loop as shown below: curve_increment
=-l
*
pygame.display.flipO =-l
*
curve_direction
From the above we update the contents of the entire The point at which the left bend appears and goes
display. The main focus of the render processing is done back to being a straight road again is controlled by an
in the PyGame main while loop as shown below: if else statement, or in Python if elif, as the Up cursor
while True: key is pressed. The first part of the if statement deals
# Setup / Control code with the situation where if the curve has reached its
#Movement controls maximum curvature it starts to make the road look
keys = pygame.key.get_pressed() straight again. The second part of the statement
if keys[K_UP]: (elif) deals with the case of making the road bend to
road_pos+=road_acceleration the left.
if road_pos>=texture_position_threshold: For those that are new to incrementing variable
road_pos=0 values in Python, it may be worth pointing out that
top_segment['position']+=curve_speed curvejncrement *= -1 is equivalent of writing
#if we reach the curve's end we invert it's curvejncrement = curvejncrement * -1. This is again
incrementation to exit it the same with the variable curve_direction = curve_
if top_segment['position']>=curve_map_lenght: direction * -1.
top_segment['position']=0
bottom_segment['dx']=top_segment['dx'] Graphics rendering
top_segment['dx']-=0.01 #+0.01 to exit a left curve To help learn about how this program works further, you
and -0.01 to exit a right curve may find it useful to play around with the following
=-l
*
top_segment['dx'] variables:
This is what
As can be seen from the above code segment, when road_pos=0 #remembers our position on the road
a successful
execution of
the Up cursor key is pressed, the road position is road_acceleration=40 #the speed we traverse the road
program should increased as per the road_acceleration value texture_position_acceleration=8 #strip "stretch" value
look like. (currently set to 80) and when the value of road_pos texture_positionJhreshold=300 #strip division value
halfjexture_positionjhreshold=int(texture_position_
*ubuntu-01:
andrew^dcll ~/PythonProjccts/pseudo_3droad/slmple_road

'andrew@dell-ubuntu-01:~/PythonProjects/pseudo_3droad$ Is
threshold/2) #define drawing light or dark road
simple road
readme.txt simpleroad z_map_road
andrew@dell-ubuntu-01:~/PythonProjects/pseudo_3droad$ cd simpleroad
To save time scrolling through the code in getting to
andrew@dell-ubuntu-Gl:'/PythonProjects/pseudo_3droad/simple_road$ Is
bush.png simple roadback.py simpleroadcurvesegmentdei
what you want, use the IDE search facility usually
simple road sprite.py
darkroad.png simple road curve demo.py simple roadhill demo.py
brought up by pressing Ctrl+F and then type the name
o.py
light road.png simple road curve formula.py simple road hill.py
of the variable or function you are looking for.
pal in _ t ree . png simple road curve. py simple roadhill segment dem<
ment demo.py
The two variables that might first be of interest to
andrew^dell-ubuntu-01:~/PythonProjects/pseudo_3droad/simple_road$ python3 simpleroad curve demo.py
pygame 1.9.6
play around with values first could be road_acceleration
Hello from the pygame community, https://www.pygame.org/contribute.html
simple road curvedemo.py:113: DeprecationWarning: an integer is required (got type float). Implicit co
and texture_position_acceleration .
nversion to integers using int is deprecated, and may be removed in a future version of Python.
screen.blit(dark_road,(curve_value,i+HALF SCREENHEIGHT),(0,i,SCREEN WIDTH,1))
Change the values of each variable and then run the
simple road curve demo.py:110: DeprecationWarning: an integer is required (got type float). Implicit co
nversion to integers using int _ is deprecated, and may be removed in a future version of Python.
program as shown before to see the effect this has on
screen.blitdight road,(curve value,i+HALF SCREEN HEIGHT),(0,i,SCREEN WIDTH,!))
the running of the program. You may want to do this a

88 | Ultimate Linux Projects

 Classic pseudo-3D racing road effects DOING ACADEMY

» GENERATING HILLS
An example of how to create a hill effect is given in the Python
script file simple_hill_road.py. From viewing the code, you will see
that new variables have been added to create the hill effect, hill­
position , hill_velocity , hill_acceleration and hill_sharpness are the
main ones which have been added. The code that deals with the Up
arrow key event is the same but the rendering process is slightly
different even though similar in some ways to how the left-bend was
created in simple_road_curve_segment_demo.py.
Again, you will see that a for loop is used for rendering the graphics
to the bottom half of the screen. The hill effect for the road is created
with the following code.
*
hill_position+=hill_velocity
hill_sharpness
To increase how steep the hill is, increase the value of hill_sharpness
which is currently set to the value of 4. To make the road appear flat
Our retro road running the basic straight road effect. again, set the value to 0. The position of the hill is continually tracked
as well to determine whether to regenerate a light part of the road or
number of times to get used to the effect of using a dark part of the road.
different values. There is currently recorded a current position of the hill and old
In every PyGame program there has to be a part that position which the difference between the current hill position and the
is written to render all the graphics so after user input old hill position is continually worked out.
they can be updated. This is done with a for loop
situated in the second half of the while loop as seen in
part below: As can be seen in the script, the acceleration value is
for i in range(HALF_SCREEN_HEIGHT-l,-l,-l): set to a constant 80 per Up cursor key press. Those of
if top_segment['position'] < i: you who from a physics background may want to create
dx = bottom_segment['dx'] a more realistic acceleration algorithm where the rate of
else: acceleration may gradually increase and decrease.
dx = top_segment['dx'] Even though it may involve some planning and some
ddx += dx re-construction of the existing code, since components
current_x += ddx of a race track have been demonstrated - straight
curve_map[i] = current_x roads, bends and hills - it maybe a good exercise to
curve_value = curve_map[i] build a small race track.
if texture_position<half_texture_position_threshold: In other source code examples, images of vehicles
screen.blit(light_stripz(O,i+HALF_SCREEN_ have been added. It maybe a good idea to take the
HEIGHT)) existing image(s) and modify them in an image editor to
screen.blit(light_road,(curve_vahiezi+HALF_ create an image of a vehicle turning left or turning right
SCREEN_HEIGHT)z(OzizSCREEN_WIDTHzl)) and implementing into the script, writing code that will
else: handle the left and right cursor keys. Instead of scrolling
screen.blit(dark_strip,(Ozi+HALF_SCREEN_ through the code line by line looking for what you want, With a bit of maths
HEIGHT)) instead press Ctrl+F which will usually bring up a search the basic road can
screen.blit(dark_roadz(curve_value,i+HALF_ facility and type in a variable or function name. E3 be made to bend.
SCREEN_HEIGHT)z(OzizSCREEN_WIDTHzl))

Going Further
The rendering of the graphics is by default set to take
place in the bottom half of the screen and not the top
half, hence the use of HALFMMSCREEN- HEIGHT. The
above code renders both the dark and light sections of
the road onto the bottom half of the screen. The top half
of the screen is kept clear for the blue sky effect.
After you have gained more confidence with the code
shown, you may want to add further functionality to the
existing code. As you’re currently forced to close the
program by closing the window with a mouse, it may be
a good idea to end the program when the Escape key is
pressed instead.
The colour of the sky is currently a plain blue. A
possible addition here would be to create an image of a
white cloud in an image editor such as Gimp and then
create an animation of clouds moving across the top
half of the screen.

Ultimate Linux Projects | 89

Ultimate Linux Projects

MERMAID
How to code diagrams,
graphs and pie charts
Mihalis Tsoukalos explains how to use Mermaid to create beautiful
technical graphs and diagrams you can reuse and update anywhere.

he subject of this tutorial is Mermaid, which is

This is a Mermaid example
O a Markdown dialect. Put simply, Mermaid code
looks like Markdown code and enables you to
create flows, diagrams, charts and more. It's based
JavaScript that renders the Markdown as code to
on

generate the output, because Markdown doesn’t offer

support for drawing. Mermaid is supported by many
editors including Microsoft Visual Code, typora and online
Mihalis editors which we’ll cover here.
Tsoukalos Mermaid code is delivered in blocks. The first line of a
is a systems Mermaid block specifies the type of the plot. Valid
engineer and a values include graph, pie, sequence diagram and This diagram shows
technical writer. flowchart. Each plot type has its own syntax, and it’s the output of a simple
He’s also the much easier to include Mermaid code in Markdown files Mermaid block of code that
creates a graph with four
author of that use the md file extension (filename.md), which is
nodes and is embedded in
Go Systems what we’ll be using for the examples of this tutorial. a Markdown file. The use of
Programming and A Mermaid block in a Markdown file begins with Markdown enables you to
Mastering Go, '"mermaid and ends with '" - this is the Markdown add context to the graph.

with a third book way of telling that the embedded code has a given
in the works! property, which in this case is Mermaid. However,
Mermaid code can also be saved on its own in files graph that’s going to be rendered from the top to the
that use the mmd file extension (filename.mmd). bottom (TD: Top-Down) of the page. Next, we add nodes
You can find the code used in this tutorial at and we connect them with other nodes. The -->
https:Z<www.linuxformat.com/includes/download. notation shows that the node on the left is connected to
php?PDF=LXF274.code.tgz. the node on the right. The graph contains four nodes,
QUICK TIP named Al, S2, A3 and A4. If you want to include more
IF Mermaid isn’t Installing Mermaid... or not! nodes and connections between them, just declare
to your liking, You don’t need to install Mermaid. All you need is an what you want - Mermaid takes care of the output.
try Vega and editor that supports Mermaid to see the output from a This example illustrates one of the simplest uses of
Vega Lite, which Mermaid block. The following is a Markdown file, saved Mermaid; it can do many more tasks. However, it also
enable you to as mermaid.md, with a block in Mermaid format: illustrates the simplicity of the Mermaid dialect.
create graphs
## This is a Mermaid example The output of the previous code can be seen in the
and plots. Both
diagram above with the help of Microsoft Visual
grammars are
"'mermaid Code - more on this next.
based on D3.js
and JavaScript. graph TD;
Learn more Al—>A2; Microsoft Visual Code
about Vega and A2—>A4; Microsoft Visual Code has a extension for rendering
Vega Lite at A1->A3; Mermaid files and previewing Mermaid output inside
https:#vega, A2—>A3; Visual Code. Go to the Extensions tab, search for the
github.io/ and A3—>A4; “Markdown Preview Mermaid Support” extension and
at https:#
install it. It would also be helpful to install the “Mermaid
github.com/
The first line is plain Markdown and generates a title Markdown Syntax Highlighting” extension so that you
vega/vega.
in the output. Then, we declare that we’re creating a can see your Mermaid code beautifully coloured.

90 Ultimate Linux Projects

 How to code diagrams, graphs and pie charts DING ACADEMY

Next, we render the Markdown file vscode.md inside mpRoview tex • pie_ch.art.md ? Mennaid.txt • vscodr md x es Preview vscode.md X

pniMxl I XF?74 cixiw ) • vstoii

** rnd } F
*1 *
A MriibdirAn fih with Mw niaidt

Microsoft Visual Code: 1

2
A Markdown file with Mermaid I A Markdown file with Mermaid!

## A Markdown file with Mermaid! 3

4
mermaid
graph lr;
5 Root--> a & b & c
6 A—>A1—>A2-—>A3
7 B-->B1-->B2-->B3
'"mermaid B C >C1 ->C2 ->C3
9
graph LR; 10

Root--> A & B & C

A->A1->A2—>A3
B->B1->B2->B3
This shows
C—>C1->C2->C3 C - UNIX -> E{Linux or macOS?}
\\\ Microsoft Visual
E -- Linux --> G{Good Choice!} Code rendering
This code presents an alternative way of creating E -- macOS --> Hfapple.com!} a Mermaid
graphs. Instead of writing multiple A--><node> lines, B - No —> FfEnd]; document. The

you can simply write A--><nl> & <n2> & <n3> or code is previewed
in a separate
A--xnl>--xn2>--xn3> in order to make multiple node When rendered, the code generates a flow chart that window from the
connections. Using — > instead of just --> creates can help you choose an Operating System. The diagram Markdown file.
longer edges between nodes, as in C—>C1. on the next page shows the flowchart generated by this
The screenshot opposite shows the preview of code with the help of Microsoft Visual Code.
vscode.md using the Mermaid extension for Visual Code.
Sequence diagrams
Creating a pie chart A sequence diagram describes interactions and how
Mermaid can easily plot pie charts and can even do the things are carried out. They’re helpful when you want to
calculations for you so that the percentages of the pie describe situations that depend on many factors.
chart are correct. To create a pie chart, you need to A sequence diagram begins with the
begin the Mermaid block with pie . The next line should sequenceDiagram keyword followed by the list of
begin with title followed by the title text. After that, you participants, which are defined using the participant
need to write the dataset that’s used for generating the keyword (each participant is defined in a separate line).
pie chart. Each line of the dataset is a different entry After that, you need to define the connections and
and contains a label, followed by a colon, which is interactions between participants, which in Mermaid
followed by a positive numeric value. Note that the label terminology are called Messages.
text should be included in double quotes, which isn’t the This Mermaid code produces a sequence diagram -
case with the pie chart title text. it’s part of the seq_diagram.md Markdown file:
The following block shows the definition of a pie sequenceDiagram
chart in the Mermaid dialect: participant User
## This is a Pie Chart in Mermaid participant CTC
participant CSV
"'mermaid participant Auth as Authorization
pie loop Every minute
title Linux Distributions CTC-->CSV: Keep updating!
"Debian": 42.96 end
"Ubuntu": 50.05 User->>Auth: Send Authorization details
"Arch": 10.01 Auth-->>User: Get back authorization token
"CentOS": 5

The previous code is saved in the pie_chart.md file - » MERMAID VS GRAPHVIZ

render it on your own to see its output.
Another useful tool that can help you create graphs and plots is
Creating a Flowchart Graphviz (http:Z<graphviz.org). It’s is a collection of tools for
Flowcharts in Mermaid start with the flowchart keyword, manipulating graph structures and generating graph layouts that
followed by their orientation (LR or TD). Then you add supports both directed and undirected graphs. It offers both graphical
the nodes of the flowchart as you would with graphs. If and command-line tools. Graphviz uses its own language.
you want to add text in an edge, you should use the <nl> The good thing is that Graphviz is open source and its language is
-- Text -> <n2> notation. You can add text to any node by easy to learn and use. As with Markdown, you can write Graphviz code
including it after the node name. If you include the text in using a simple plain text editor such as vi. A wonderful side effect of it
square brackets, the node is drawn as a rectangular; use is that you can easily develop scripts that generate Graphviz code!
curly braces to draw the node as a diamond. So, Mermaid and Graphviz have many things in common including
The following Mermaid code, which can be found as using plain text files and producing output in various formats.
flow_chart.md, describes a flowchart: However, with Mermaid, you don’t need to install anything whereas for
## Flow chart Graphviz, you need to install the Graphviz suite of tools and learn its
language. Furthermore, Mermaid uses Markdown, which is more
"'mermaid popular than the language of Graphviz and very handy if you’re already
flowchart TD using it for blogging or writing. As is usually the case with most tools,
A[Choose OS] --> B{Do you want?}; only after using both Graphviz and Mermaid for some time will you
B - Yes -> C[UNIX or Windows]; know which option is best for you.
C -- Windows --> D[Good Luck!];

Ultimate Linux Projects | 91

Ultimate Linux Projects

There are four participants: User, CTC, CSV and Use Cases in Mermaid

QUICK TIP Authorization. The Authorization participant is accessed csv CTC/Auth

User CTC

The official web as Auth inside the Mermaid code but is displayed as
[ _par [Get Data]
site for Mermaid Authorization for clarity - this is implemented with the
A Database that keeps Usage data
is at https:# Auth as Authorization statement. The loop block 30 __________
mermaid-js. represents actions that happen continuously. Return Usage data
github.io/ - 0
You should be able to see the output of
mermaid. Logs in
seq_diagram.md either in Microsoft Visual Code, typora F
—

The GitHub Returns Security Token

or any other online Mermaid editor such as - ...... < )

repository for Opens CSV Window

https://mermaid-js.github.io/mermaid-live-editor.
(
F
the Microsoft (
Asks for system \isualisations
>----------------------------- --------------------------

Visual Studio Query Internal Database

o--.

Mermaid Use Cases in Mermaid Displays Viswilisations

extension is Let’s see how Mermaid can describe the use cases of a :.............................................. ft
Y _______ I

at https:# project. Use cases are implemented using sequence User CTC csv CTC/Auth

github.com/ diagrams, which means they're defined using the

vstirbu/vscode- sequenceDiagram keyword. We want to use the This shows how Mermaid can describe use cases and therefore offers
mermaid-
preview. Learn
Mermaid code to describe how a user interacts with a
program and the components involved in the process.
I a handy way of generating documentation for your software projects.

more about
This is shown in the following Mermaid code: embed Mermaid code into a Hugo blog post that we
the Markdown
language
sequenceDiagram publish. In order to support Mermaid rendering in Hugo,
at https:# participant U as User you need to add a small shortcode inside the layouts/
en.wikipedia. participant CTC shortcodes directory - Hugo uses shortcodes to add
org/wiki/ participant CSV extra functionality that can’t be implemented in
Markdown. participant CTC_Auth as CTC/Auth Markdown. The name of the shortcode file should be
autonumber mermaid.html and must have the following content:
rect rgb(0,100,0) $ cat layouts/shortcodes/mermaid.html
par Get Data <script async src="https://unpkg.com/[email protected]/
CSV-»CTC_Auth: A Database that keeps Usage dist/mermaid.min.js"></script>
data <div class="mermaid">
Note right of CSV: REST API {{.Inner}}
CTC_Auth-»CSV: Return Usage data </div>
end The previous file defines a shortcode named
end mermaid - in order to use that shortcode you should
embed Mermaid commands in {{<mermaid>}} and {{</
U-»CTC: Logs in mermaid>}} blocks. A part of the Markdown code for the
CTC—»U: Returns Security Token Hugo blog post is as follows:
CTC-»CSV: Opens CSV Window Using [Mermaid](https://mermaid-js.github.io/
U-»CSV: Asks for system visualisations mermaid/) in Hugo.
CSV-»CSV: Query Internal Database
Here’s a flowchart CSV->>U: Displays Visualisations {{<mermaid>}}
generated in The autonumber keyword that’s shown here graph TD;
Mermaid, which
can be drawn from
attaches a sequence number to each arrow in the A—>B;
left to right or top sequence diagram. The rect rgb(0,100,0) command A->C;
to bottom. puts colour in the output using RGB values and colours B—>D;
a rectangle. Inside that rectangle, C->D;
Flow chart
you can write the Mermaid {{</mermaid>}}
Choose OS
commands you want. The par block The first line is Markdown code. After that you need
shows actions that happen in to put all Mermaid-related code in a block that begins
parallel. Both with {{<mermaid>}} and ends with {{</mermaid>}}.
Do you want? rect and par blocks end with the The diagram on the next page shows the code inside
end keyword. the Hugo blog post - the entire Markdown file for that
The diagram above displays the blog post is called useMermaid.md. You can see the
output of the previous Mermaid blog post live at www.mtsoukalos.eu/2021/01/using-
code - the Markdown source file mermaid. Bear in mind that the Mermaid code is
with the Mermaid code is called rendered with the help of the JavaScript library used in
use_cases.md. The use of the shortcode file (https:Z<unpkg.com/mermaid@
autonumber enables you to specify 8.2.3/dist/mermaid.min.js) and not by Hugo itself.
the part of the sequence diagram
you want by using a number. Go scripts
This section presents a Go utility that generates
Mermaid and Hugo Mermaid code, but you can use any programming
The Hugo (https:Z<gohugo.io) language you want to produce Mermaid code. The utility
framework offers support for reads a CSV file with two columns and creates a
Mermaid code. This section Markdown file with a title and a pie chart in Mermaid
presents such as example where we format. The first column in the CSV file is the label and

92 Ultimate Linux Projects

 How to code diagrams, graphs and pie charts DING ACADEMY

the second column is the value, which should be an

integer. The filename of the input file becomes the title » USING TYPORA WITH MERMAID
of the Markdown document as well as the title of the pie
chart and the contents of the file generate the elements Typora is a stable and easy-to-use Markdown editor and reader that
of the pie chart. also supports Mermaid and works on many operating systems
The most interesting code of pieChartgo is including Linux. On an Arch Linux machine, you can install typora by
for line := range lines { running sudo pacman -S typora . Adjust the command to match your
_,err := strconv.Atoi(line[l]) Linux variant to install typora on your own Linux machine.
if err != nil { The biggest advantage of typora is that it’s an editor. You can see
continue the real output as you write it without needing to take any extra steps
unlike Microsoft Visual Code. Additionally, you get to see syntactic
fmt.Printf('\t\"%s\": %s\n", line[0], line[1]) errors in your Mermaid code as soon as possible and you can export
your files in various formats including PDF, LaTeX and HTML.
The input file is read all at once and kept in the lines However, you can’t run typora from the command line because it’s a
slice. The previous code processes the elements of the graphical application, which means that typora can’t be used for
lines slice one by one to obtain the data and print it on automation tasks.
the screen. The presented code ignores all rows that The screenhow below shows typora in action when rendering
don’t contain a valid integer with the help of the strconv. Mermaid code - the Ul of typora is simple and without distractions
Atoi() Go function. which makes it a pleasure to use. Therefore, if you want something
The input file that’s processed by pieChartgo has lighter and faster than Microsoft Visual Code, typora looks like a
the following format: sensible option. Additionally, typora is much more elegant than Visual
Code. However, if you’re already using Microsoft Visual Code on a daily
basis then you might want to stick with it - the choice is yours! Find
more about typora at https:ZQypora.io.
Running pieChartgo with the aforementioned input
file produces the following output:
work. The presented Python 3 script saves the output
into a file that’s named nodes.png - the name of the
output file is hardcoded.
The core functionality of the script.py Python 3 file
can be found in this code:
img = Image.open(io.BytesIO(requests.get('https://
mermaid.ink/img/' + base64_string).content))
plt.imshow(img)
The easiest way to collect the output is to redirect it plt.savefigfnodes.png', dpi = 300)
into a file: run pieChartgo data.csv and then The first line uses an external web site
filename.md. After saving the output you can process it (https:Z4nermaid.ink/img) to render the Mermaid
in Microsoft Visual Code or typora and obtain the type of input. The second statement displays the image
output you’re looking for. output - if you’re running the Python 3 script from the
The key takeaway here is that once you understand command line, then this statement might not generate
the format of the Mermaid file you want to create, you any output on screen - and the final statement saves
can generate Mermaid files dynamically using input the generated image into a PNG file. The biggest
from multiple data sources, including plain text files, difference between the Go script and the Python 3 one
database servers and web services. is that the Python 3 script generates the output image
by itself whereas the Go script generates Mermaid code
Python 3 scripting that needs to be rendered first.
Finally let’s look at how Python 3 utility that generates Don’t get fooled by the use of Markdown and plain
Mermaid output on the fly using an external service. For text files and think that Mermaid is limited in function.
the purposes of this tutorial, the Mermaid code is It’s a professional tool that can help you create
hardcoded and kept in a Python variable. If you have beautiful technical diagrams and plots, and include
experience in the Python programming language, you them in your blog posts, documents or reports.
can add some Experimenting with Mermaid is going to make you more
Using Mermaid in Hugo. versatility to the productive -
presented utility play around
and write code with it a little
that reads the before using
Hugo renders
Mermaid code
Mermaid code it in real
and includes from a plain text projects. LXF
the generated file or a database
output in the server instead.
respective
Note that you Here’s typora in action, which can render
static web page,
might need to Mermaid code as well as any other
provided that
Markdown code and works on most
you’ve created install some popular operating systems including
the required Python 3 modules Linux. IF you’re not a Fan oF Microsoft
Hugo shortcode.
for the script to Visual Code, give typora a try.

Ultimate Linux Projects | 93

Ultimate Linux Projects

MICR0:BIT

Build radio walkie-

talkies with Python
Using a pair of BBC micro:bit devices, Calvin Robinson
creates walkie talkies in Python.

he BBC micro:bit is an open-source micro adaptable, and a fraction of the size, ideally to be used

O computer. Launched in 2015/16, the BBC gave

UK secondary schools the opportunity to apply
alongside a PC or Raspberry Pi.

for one free unit for each Year 7 pupil. The idea was that
every child could keep their micro:bit for free and
The micro:bit features 25 LEDs, two programmable
buttons, as well as a non-programmable button, an
accelerometer, magnetometer, Bluetooth Smart
OUR .7 develop a taste for coding. Technology and five Input/Output rings that are ideal for
Certain UK readers might remember the original attaching things like motors and buzzers with crocodile
EXPERT BBC Micro from our school days (1981-1994), an Acorn clips. The unit is specifically designed for Blocks (a
Calvin Robinson computer used for programming in BASIC. The JavaScript editor) and Python, although it is also
is a former micro:bit is its spiritual successor, designed to be cheap, possible to program it with Free Pascal, Simulink, C_ ,
assistant Forth, Lisp, Rust, Ada and Swift. You can even run
principal and Zephyr OS on it.
Computer For this tutorial, we're going to be coding in Python.
Science teacher There are a number of editors available for the micro:bit,
with and a degree including some simulators that will emulate the
in Computer micro:bit hardware, so owning a unit isn’t a barrier to
Games Design entry. Visit https:Zfmicrobit.org/code/ and click Let’s
and Code’ at the top of the page for access to the Python
Programming Editor. The editor Mu is a great native GUI interface
BSc (Hons). (https:Zfcodewith.mu/), whereas uFlash and
microrepl are command line options. There’s also a
mobile app for iOS/Android from the official micro:bit
website. For this tutorial we’ll be using the platform at
https:Zfcreate.withcode.uk/ as it provides a fancy
simulated micro:bit tool to check if our code is
functioning before exporting it onto the physical device.
We're going to program some basic walkie-talkie
devices that send messages from one to the other. We
can send pre-coded images and lines of scrolling text
between micro:bits at the press of a button.
QUICK TIP The micro:bit supports Bluetooth (BLE) and radio
IF you make
transmission, but BLE isn’t supported by MicroPython
a mistake in (the version of Python running on the micro:bit), so for
your code, keep that reason we'll be using radio implementation to make
an eye on the our micro:bits communicate with each other. There’s no
LEDs. Micro:bits limit to the number of micro:bits that can send/receive
have their over radio transmission, other than the usual 2.4GHz
own debugger signal traffic congestion. We would therefore
built in, so the
recommend experimenting with no more than a handful
error will scroll
of micro:bits to begin with (two is fine), and perhaps
across the LEDs,
keep them in the same room until the code is fully
starting with the
line number.
functioning, so you can rule out the possibility of walls
or objects interfering with the signal.

94 | Ultimate Linux Projects

 Build radio walkie-talkies with Python DING ACADEMY

Create with code X +

Coding For the micro:bit C o a create.withcode.uk

To get started on withcode, we’ll need to import the create.with

mycode.py H4
micro:bit module and the specific functions for from microbit import *
displaying images and using the two buttons, labelled 2
3 LEDS = Image(”00000:11111:22222:33333:44444 ”)
4
‘a’ and ‘b’: display.show(LEDS)
6
from microbit import display, Image, button_a,
button_b
Now, to display text, we can either ‘scroll’ or ‘show’ a
string of text. The display function contains two options,
scroll and show, which will display the text accordingly -
either from left to right, or one letter at a time:
display.scroll("Hello")
Ths micro bit sirrulator is an unofficial alpha test version Create withcode uk b not affibatcd wrth
or endorsed by the BBC

display.show("world") >_ REPL

Displaying images is a similar process. There is a

whole host of built-in images that the micro:bit will | Lighting up your life and LEDs, row by row.

recognise, including basic emojis:

display.show(Image.HAPPY) if button_b.was_pressed():
QUICK TIP
sleep(lOOO) new_value = counter +1 The micro:bit
display.show(Image.SAD) uses Micro

sleep(lOOO) # reset to 0 if you touch pin 0 Python.

More info
But to draw your own images we’ll need to highlight if pin0.is_touched():
and tutorials
precisely which LEDs we’d like lit up, and how bright new_value = 0
are available
we’d like them on a scale of 0-9 - 0 being off and 9 at https:#
being full brightness: # stop counter from going less than 0 microbit­
i = Image("00000:" if new_value < 0: micropython,
"22222:" new_value = 0 readthedocs.
"44444:" io - including
"66666:" # scroll new value if it's changed help with
"88888") if new_value != counter: text, images,

display.show(i) counter = new_value buttons, I/O,

music, gestures,
sleep(lOOO) display.scroll(str(counter))
directions, and
For an easy life, or to save space, we can narrow this
also storage.
down to a single line. The colon remains in place sleep(50)
between lines of lights, but we narrow the code down to
one pair of speech marks:
LEDS = Image("00000:11111:22222:33333:44444") » MORSE CODE
display.show(LEDS)
sleep(lOOO) Micro:bits are perfect for Morse code communication. Instead of
Here we've used a slightly brighter LED on each line to using images or strings to light to LEDs, we can use the flash
highlight the difference in hue. command to light up the entire LED grid for a set amount of time. The
Since this article was originally written in December following code will display a full flash for 10ms:
in a festive mood, why not design a Christmas tree for display.show(flash, delay=10, wait=False)
our first image to send to another micro:bit later: We could then take this and introduce a selection to make the
xmastree = Image("00500:00500:05550:55555:00500:") micro:bit flash for different lengths, depending on what letter we want
display.show(xmastree) to represent. We can represent dots with short flashes and dashes
It’s all well and good being able to display our images with slightly longer flashes. For the purposes of this example, a dot is
on the LEDs, but before we’re able to send them to 5ms and a dash is 10ms:
another device we’re going to need to work out the if incoming == 'A'
buttons. Here’s a basic counter that can be used as an display.show(flash, delay=5, wait=False)
example of how the buttons function. We’ve used an display.show(flash, delay=10, wait=False)
infinite loop, with a small pause (sleep) so as not to elif incoming == 'B'
cause a heavy load on the processor. display.show(flash, delay=10, wait=False)
from microbit import * display.show(flash, delay=5, wait=False)
display.show(flash, delay=5, wait=False)
counter = 0 display.show(flash, delay=5, wait=False)
new_value = 0 After developing Morse code statements for each letter of the
alphabet, we can then set up a loop to recognise each incoming letter,
while True: or only send single letters at a time. As we only have two buttons on
the micro:bit, perhaps use one button to rotate through the 26 letters
# decrease by 1 if button A was pressed of the alphabet, showing them on the LEDs, and the other button to
if button_a.was_pressed(): send the letter. This way we’d be able to send messages on the fly,
new_value = counter -1 without having to re-program the micro:bit every time we want to say
something new.
# increase by 1 if button B was pressed

Ultimate Linux Projects | 95

Ultimate Linux Projects

QUICK TIP
Using crocodile
clips on 0 and
GND, you can
attach a pair
of headphones
or speakers
and introduce
sound to your
micro:bit.
Import the
music module
and play music.

Setting up the radio if incoming:

In order to send these images or strings with our display.scroll(incoming)
buttons, we’ll need to connect the radio. Alter the top sleep(lOO)
of your code to reflect the following: If you’re using two micro:bits for this tutorial, don’t
from microbit import * forget to set a different handle on each device for a
import radio real-world example of two-way communication. If you’re
radio.on() using more than two micro:bits, however, you may need
Now that the radio is turned on, we can send or a way to change channels on the fly, while the device is
receive messages over it. However, we might also running. While we don’t have any more programming
want to be more specific and set a channel before buttons, we do have the accelerometer functionality.
turning the radio on: Using the following code, we can shake the micro:bit
radio.config(channel=10) to randomly change channel between 1 and 10, in
iterations of 1:
Sending messages while True:
Let's start off by sending and receiving some basic if accelerometer.was_gesture('shake'):
messages. We’ll set our A button to ask for a handle, and newChan = random.randrange(l,10,l)
the B button can reply with it - a throwback to CB display.scroll(str(newChan))
radios, if you will. radio.config(channel=newChan)
import radio if button_a.was_pressed():
from microbit import * display.show('A')
radio.config(channel=0) radio.send('What's your handle?')
radio.on() if button_b.was_pressed():
display.show('B')
while True: radio.send('My name is Calvin)
if button_a.was_pressed(): incoming = radio.receive()
display.show('A') if incoming:
radio.send('What is your handle?') display.scroll(incoming)
if button_b.was_pressed(): sleep(lOO)
display.show('B') Of course, we could change these strings to say
radio.send('My handle is Calvin') anything, or swap them out for variables. If we were
incoming = radio.receive() going to replace them with our Christmas tree, it’d look
something like this:
import radio
from microbit import *
radio.config(channel=0)
radio.onQ

xmastree = Image("00500:00500:05550:55555:00500:")

while True:
if button_a.was_pressed():
display.show('A')
radio.send(xmastree)
As basic as pixel
if button_b.was_pressed():
art goes - a 2-bit display.show('B')
pine tree. radio.send(xmastree)

96 | Ultimate Linux Projects

 Build radio walkie-talkies with Python JDING ACADEMY

» SIGNAL STRENGTH
Micro:bits transmit some specific information every time we send or
receive data over the radio. If we use radio.receive_full() instead of
radio.receive(), we’ll get the message as a tuple, including the
message content, signal strength and a time-stamp. The signal
strength (RSSI) will be displayed as a value between OdBm and
-255dBm, with 0 being the strongest and -255 the weakest signal.
Now we can create all kinds of treasure-hunt games by triangulating
the radio signal. By setting one or multiple micro:bits up so that they
constantly send a radio message on low power, we can create a
receiver that can parse the incoming message and then display
the signal strength:
Simulation of two-way communication over the micro:bit radio. while True:
message=radio.receive_full()
incoming = radio.receive() if message:
if incoming: strength = message[l]+100
display.scroll(incoming) displaystrength = (int((strength/10)+l))
sleep(lOO) display.show(str(displaystrength))
Our ‘while’ look is constantly looking out for an A or B sleep(200)
button press but also for any incoming messages. We’ve else:
set these messages to automatically scroll across our display.show(Image.NO)
LEDs. It might be beneficial to clear the screen first with Now, the closer we get to the transceiver the higher our signal
display.clear(). You may also decide to display.show() strength will be. We could make this into a game by designing an
the message instead of scrolling it, depending on image for hot and another one for cold, then displaying these images
whether you plan to show images or text. We’ve found as we move around. Every time the number rises we could display the
that text scrolls nicely but images are usually better to hot image, signalling that we’re getting closer, then displaying the
just pop up straight away with a display.show(). Again, cold image when we’re moving away. The build-in commands
add a sleep timer to the end of our loop to save Image.YES and Image.NO would display a tick and a cross, to help
processing power. make things even easier.
To take things to the next level, we could introduce a Display.show(Image.NO)
transition - a message to let the user know an incoming
message has been received, before showing it. That way,
the user has less chance of missing the message, which extremely limited storage capacity and only room for
could easily happen if the text starts scrolling over the one single HEX file.
LEDs without prior warning. As soon as the copying process is complete, the
if incoming: micro:bit will be running your Python code. Either keep
display.show(alertlmage) the micro:bit plugged in via USB or provide power with
sleep(lO) a portable battery pack. Then press either the A or B
display.scroll(alertText) button to begin. E9
sleep(lO)
This would require a little setting up, before the
‘while’ loop:
alertimage = Image("00500:00500:00500:000000:009
00:")
alertText = "Incoming message:"
If you haven’t got two micro:bit devices, you can test
all of your code on the https:77create.withcode.uk
website, simulating communication both ways. Provided
your code has imported the micro:bit module, turned on
the radio and has a loop waiting to receive and
display the incoming message, you can send yourself a
message with the radio test tool. Make sure you’re using
the same channel number (anything between 0 and
100), and send some test data (preferably a simple
string). It should scroll across your simulator micro:bit
LEDs. You can also press the fake buttons on the
micro:bit image and they should function as intended.
When you’re happy with your code, download the
HEX file. Once that’s done, plug your micro:bit device
into your computer using a Micro USB cable; it should
automatically mount. Next, simply drag the HEX file
onto your micro:bit’s drive space. It should override any
previously installed HEX file, since the micro:bit has

Ultimate Linux Projects | 97

Turn a Pi HAT into a
Magic 8-ball project........................... 116

Raspberry Pi streaming....................... 118

Create, configure and use gamepads.... 126

Ultimate Linux Projects 99

Ultimate Linux Projects

Pi PROJECTS
Jonni Bidwell with the help of Tom’s Hardware
bring you the best in Raspberry Pi-based fun.
e do love the Raspberry your desktop, and small enough that

w Pi at Linux Format, and

so do our digital
colleagues at
tomshardware.com. So with their
you can hide it behind the back of
your monitor. If that’s not small
enough, there’s always the Pi Zero,
which is perfect for budding ‘Internet
help we’ve selected the finest Pi of Things' enthusiasts. And now
projects for you to enjoy. We’ve got there’s the Pi 400, where the
something to inspire everyone, keyboard is the computer.
from retro gaming to home Of course, there’s no need to stop
security, or even artificially at these projects, or any others you
intelligent object classification. might find online. We want you to
The Raspberry Pi is the perfect boldly go exploring new physical
device for learning and getting computing frontiers, and we hope
familiar with Linux. Its official that this offering inspires just that.
operating system is based on Debian With a bit of practice and experience,
Linux and there’s even a build of you'll be soldering up your own
Ubuntu for it. The Pi 4 is powerful hardware, controlling robots and be
enough that it can happily replace limited only by your own imagination.

In association with
tom’sHARDWARE

100 Ultimate Linux Projects

 Raspberry Pi projects

Get your kit ready

Prepare your USB cables, SD cards and a cup of tea.
It’s Raspberry Pi project time...
r ith more than 34 million units sold, the

w " '^1
Raspberry Pi is not only one of the world’s
most popular computers - it’s also one of
the most important. Originally designed to help kids
learn about technology, this inexpensive, single-board
system is the leading choice for makers, developers
and hobbyists who want to do everything from
building industrial robots to setting up retro arcade
machines. Whether you’re aged eight or 80, if you
love technology then the Raspberry Pi is made for
you - and there are models ranging from £5 to £65
to suit any budget.
Whatever you do with your Raspberry Pi, you're
going to need an SD card with an operating system on Cheap power supplies are another cause of errors. The latest
it. The official Raspberry Pi OS (formerly Raspbian) is a For older model Pis these are less of a problem, but the incarnation of the
Pi, the 400 model,
popular choice and in many cases is a great start for Pi 3 and above really do need a good 5.2V or they'll be
embodies a Pi 4,
many projects. It’s available in Desktop and Lite flavours subject to CPU throttling and instability. The Pi 4 has also pictured,
at www.raspberrypi.org/software/operating-systems. switched its power input from micro USB to USB-C, and within a keyboard.
There’s an official Raspberry Pi Imager utility that you unfortunately this new port isn’t USB-C compliant. So if
can use to write this (or a selection of other OSes) to an you use a fancy smart charger, it probably won’t power
SD card, or you can use the NOOBS tool. We favour the device, and might possibly damage it.
Balena Etcher, which has the advantage of being able to You won’t run into these issues if you use the official
handle compressed images. charger, so do that. If you’re opposed to that, we’re told
that cheaper USB-C cables (ones that lack the smart
Troubleshooting charge chip) work fine. Cheaper chargers should work
Throughout this feature we’ll use a few different OS too, but they may not be so reliable, so caveat emptor.
images, so we’ve made a handy guide to writing them We’ve handpicked some fun, useful and interesting
below. If you run into difficulties, it’s always worth projects to showcase the tremendous scope of things
remembering that a faulty SD card might be to blame, that can be achieved with the humble Pi. From retro
so it’s worth trying a different one if things go wrong. gaming to machine learning and Bitcoin, the possibilities
are truly endless...

WRITING SD CARDS WITH ETCHER ]

c- C © A https://wwbalena.io/< □ ••• ® & £ M\ CD 1 tffl ■■
Etcher - SOX Decompressing- >

O boienoElcb«f O Q
ft balena Etcher
Q 2O21Ol..Jte.Jme
WNk rou het WMrtf ov. tc/ne projects

Flash. Flawless.
(boot, roods)

« t-

Flash OS images to SD cards & USB drives, safely and easily. Decompressing... Su
* ■■ r I
g|
■ — —-

Looking for new project ideas?

I ■rJc-'c rorrmwtv d t» 'tto n

Browse projects

Select drive
r

Download Etcher Prepare the target Write the image

O You’ll find Linux, macOS and
Windows builds at https://etcher.io. On
2 Insert your SD card, select the Flash
from file option and navigate to your
3 Hit Flash, enter your password and
wait patiently for the progress bar. You’ll be
Linux it ships as a zipped Applmage, so downloaded image. Click Select target and offered the chance to write the same image
once you’ve unzipped it, run chmod 755 a menu will show available devices. Hard again, which you might want to do if you’re
on the file (or select Properties> drives are hidden to prevent you from preparing a fleet of Pi clones. But otherwise
Permissions and check the box to allow accidentally overwriting them. Select your your SD card is ready for action. Move it
execution). You can now double-click the SD card reader, and check to make sure from your PC to your Pi, power on and let
Applmage to run it (or do so from the CL). there’s nothing important on the card. the adventures begin!

Ultimate Linux Projects 1101

Ultimate Linux Projects

Image recognition
Get into machine learning and train your Pi to recognise and classify
other Pis, without having to write a single line of code.

r e’re going to train our Raspberry Pi to

YOU NEED
w identify other Raspberry Pis (or other
objects) with machine learning (ML). Why is > Raspberry Pi 3,4 or 400
this important? An example of an industrial >8GB (or larger) microSD card
application for this type of ML is identifying defects > Raspberry Pi Camera or a USB webcam
in circuit boards. As circuit boards exit the assembly > Power supply for your Raspberry Pi
line, a machine can be trained to identify a defective > Smartphone for taking photos
circuit board for troubleshooting by a human. > Selection of Pis or other objects
Tom’s Hardware has some neat machine learning for classification
and artificial intelligence tutorials, including facial
recognition and face mask identification. In those collection site. You won’t need to download an app to
projects, all of the training images were stored locally on collect images.
the Raspberry Pi and the model training took a long Accept permissions on your smartphone and tap
time because it was also performed on the Pi. In this Collecting images? in your phone’s browser screen. Tap
tutorial, we’ll use a web platform called Edge Impulse to Label and enter a tag for the object that you'll take
create and train our model to alleviate a few processing photos of. Take 30-50 photos at various angles. Some
cycles from our Pi. Another advantage of Edge photos will be used for training and other photos will be
Impulse is the ease of uploading training images, which used for testing the model. Edge Impulse automatically
can be done from a smartphone (and without having to splits photos between training and testing. Repeat the
involve an app). process of Entering a label for the next object and taking
We’ll use BalenaCloudOS instead of the standard 30-50 photos per object until you have at least three
Raspberry Pi OS since the folks at Balena have objects. We recommend three to five identified objects
prebuilt an API call to Edge Impulse. This project for your initial model. You’ll have a chance to re-train the
eliminates all terminal commands and instead utilises model with more photos and/or objects later on.
an intuitive GUI. From the Data Acquisition tab in the Edge Impulse
browser window, you should now see the total number
Training on the Edge of photos taken (or uploaded) and the number of labels
Head over to https:/7edgeimpulse.com and create a free (type of objects) you’ve classified. (You may need to
account (or login if you already have one), from a refresh the tab to see the update.) You can click any of
browser window on your desktop or laptop. Select the collected data samples to view the uploaded photo.
Data Acquisition from the menu bar on the left. You can
either choose to upload photos from your desktop or Impulse design
scan a QR code with your smartphone and take photos. Next, click Create impulse from Impulse design in the
In this tutorial, we’ll opt for taking photos with our left column menu. Click Add a processing block and
smartphone. Select Show QR code and a QR code select Image to add an image to the second column
should pop up on your device’s screen. Scan it and from the left. Click Add a learning block and select
select Open in browser and you’ll be taken to a data Transfer Learning. Click the Save Impulse button on the
far right. Click Image under Impulse design in the left
4 Collect data menu column. Select Generate features to the right of
Parameters near the top of the page. Click the Generate
You can collect data from development boards, from your own devices, or by uploading an existing dataset.
features button in the lower part of the Training set box.
Connect a fully supported development board This could take around five to ten minutes (or maybe
Get started with real hardware from Nordic, Arduino, OpenMV, ST, Eta
Compute, Himax and SiLabs - fully supported by Edge Impulse.
Browse dev boards
even longer) depending on how many images you
have uploaded.
Use your mobile phone
Use your mobile phone to capture movement, audio or images, and even run Show QR code
Select Transfer learning within Impulse design, set
your trained model locally. No app required. your Training settings (keep the defaults, check Data
Data from any device with the data forwarder
augmentation box), and click Start training. This step
Capture data from any device or development board over a serial connection, Show docs
will also take five minutes or more depending on your
in 10 lines of code.
amount of data. After running the training algorithm,
Besides collecting Upload data
Go to the uploader
you will be able to view the predicted accuracy of the
Already have data? You can upload your existing datasets directly in WAV, JPG,
images from your
PNG, CBOR or JSON format. model. For example, in this model the algorithm can
mobile device,
Edge Impulse can Integrate with your cloud
only identify a Raspberry Pi 3 correctly 64.3 per cent of
connect to all kinds The enterprise version of Edge Impulse integrates directly with the data stored Contact us the time and will misidentify a Pi 3 as a Pi Zero 28.6 per
in your cloud platform.
of data sources. cent of the time.

102 Ultimate Linux Projects

 Raspberry Pi projects

X Axis Y Axis Z Axis the service named EI_PROJECTJD and paste the
Visualization layer 1 v Visualization layer 2 v Visualization layer 3 Project ID value from the Dashboard.
Select Devices from the left column menu in your
• apple
• bird BalenaCloud, and click Add device. Select your Device
• cat
• plant type (Pi 4, Pi 400 or Pi 3).
• raspberry pi 3 <
• raspberry pl 4 Select the radio button for Development. If using
• raspberry pi zero w
• vase
cd
c.
o
□
Wi-Fi, select the radio button for Wi-Fi+Ethernet and
Once you start
cu
enter your Wi-Fi credentials. Download your customised
gathering datapoints balenaOS image and write it to an SD card (you can do
(images). Edge Impulse this using our guide to Balena Etcher on the first page)
can explore and graph
the so-called Features
oF the data. Connect the hardware
Remove the microSD card from your computer and
insert it into your Raspberry Pi. Attach your webcam or
Select Model testing in the left column menu. Click Pi Camera and then power up your Pi. Allow 15 to 30
the top check box to select all and press Classify minutes for your Pi to boot up and BalenaOS to update.
selected to test your data. The output of this action will Only the initial boot requires the long update. You can
be a percentage accuracy of your model. If the level of check the status of your Pi Balena Cloud OS in the
accuracy is low then we suggest going back to the BalenaCloud dashboard.
Data Acquisition step and adding more images or Identify your internal IP address from your
removing a set of images. Select Deployment in the left BalenaCloud dashboard device. Enter this IP address in
menu column and select WebAssembly for your library. a new browser Tab or Window. Place an object in front of
Scroll down (the Quantized option should be selected the camera. You should start seeing a probability rating
by default) and click the Build button. This step may for your object in your browser window (with your
also take three minutes or more, depending on your internal IP address). Try various objects that you
amount of data. entered into the model and perhaps even objects you
didn’t use to train the model.
Setting up BalenaCloud
Connection over BalcnaVPN O
Instead of the standard Raspberry Pi OS, we’ll flash balena Cam + • edge impulse

BalenaCloudOS to our microSD card. The

BalenaCloudOS is prebuilt with an API interface to Edge
Impulse and eliminates the need for attaching a
monitor, mouse and keyboard to our Raspberry Pi.
Create a free BalenaCloud account at
https://dashboard.balena-cloud.com/signup and once
you’re in, go to https://dashboard.balena-cloud.com/
deploy to open the Create and Deploy page and create
our balena-cam-tinyml application. Click Deploy to
Application. After creating your application, you’ll land
on the Devices page. Don’t create a device yet!
In Balena Cloud, select Service Variables and add label value

two variables. First, add to the service edgeimpulse­ apple

bird
0
0
cat 0
inference a variable named EI_API_KEY and in the plant 0 We can Forgive the machine For thinking
raspberry pi 3 0.09375
this Pi 3 was more likely to be a Pi 4. At
Value field paste the API key from the Keys section of raspberry pi 4 0.84375
raspberry px zero w0.0625
least it was certain it wasn’t a house plant.
the Edge Impulse Dashboard. Add a second variable to vase 0

» REFINING THE MODEL

If you find that the identification isn’t very accurate, first check your
CREDIT: Pimoroni

model’s accuracy for that item in the Edge Impulse Model Testing tab.
You can add more photos by following the Data Acquisition steps and
then selecting Retrain model in Edge Impulse. You can also add more
items by labelling and uploading in Data Acquisition and retraining the
model. After each retraining of the model, check for accuracy and then
redeploy by running WebAssembly within Deployment.
If you want to go further with machine learning, you might want to
check out the Pimoroni’s new BrainCraft HAT for the Pi 4. It features a
240x240 TFT IPS display for inference output, slots for camera
connector cable for imaging projects, a five-way joystick, two
microphones, audio outputs and much more. Most importantly, it has a
controllable fan to keep the thing cool, what with all the never-ending
TensorFlow computations.

Ultimate Linux Projects 1103

 Ultimate Linux Projects

Multi-room Pi audio
Get your Raspberry Pis in sync, audibly throughout your home.

□ ulti-room audio systems can cost a pretty

penny, but who needs to buy an expensive
set of wireless speakers when you can use
some Raspberry Pis and any 3.5mm wired speakers
to achieve the same effect? We’ll use our Pi 4s and
YOU NEED
> Raspberry Pi 4 or Pi 400 (one unit per room)
> 8GB (or larger) microSD card, U3 cards
recommended. One per room
speakers/receivers (with 3.5mm audio inputs) to play > 3.5 mm audio cables
music from a streaming service perfectly in sync via > Amplified speakers or a receiver with
Bluetooth from our phone, tablet or computer. We’ll 3.5mm/phono audio input
show you how to do this with a single speaker and > Power supplies for your Raspberry Pis
Raspberry Pi and then replicate it in other rooms. This > Optional: Smartphone or tablet
is an excellent project for repurposing old receivers. If
01 you have a non-Bluetooth receiver with a 3.5mm jack menu in your Balena-Sound Dashboard. Click Add
input, you can connect your speakers to your receiver device and choose Raspberry Pi 4, Raspberry Pi 400 or
I.IT and your receiver to your Raspberry Pi. Raspberry Pi 3. Select the radio button for Development.
Instead of Raspberry Pi OS, we'll use BalenaSoundOS If using Wi-Fi, select the radio button for Wi-Fi+Ethernet
to make the Bluetooth connection visible (to our other and enter your Wi-Fi credentials. Click Download
devices) and eliminate the need for a monitor, keyboard balenaOS and a zip file will start downloading. Write
and mouse for our Raspberry Pi. Create a free this to an SD card, using Balena Etcher or otherwise.
BalenaCloud account at https://dashboard.balena-
Connect and update
Scan For Free Magazines

cloud.com/signup and log in. Open the Deploy a Balena-

Your musical Pi
sound application page at https://sound.balenalabs.io/ Remove the microSD card from your computer and
can be monitored
at all times
docs/getting-started. You must already be logged into insert into your Raspberry Pi. Connect the speaker to
through the Balena your Balena account for that link to work. Click Deploy to your Pi via the 3.5mm audio cable. Power up your Pi.
Cloud dashboard. Application and select Devices from the left column Allow 15 minutes for your Pi to boot up and BalenaOS to
update. Only the initial boot requires the long update.
You can check the status of your Pi Balena Sound OS
botonaCtatto + GiHiiig; Stilted *!
!■ Qi Fciiiiftu jULui. CjfciQbrtt Dlhi- f
*■

Q I llLil ■ I.' l ’ J i. ► © r© in your BalenaCloud dashboard. If you’re using a

O ■ Mk ■ .• i .1
Raspberry Pi 400, connect a USB speaker instead of the
rough-wind

LL'Ll
■■ ■ I 3.5mm audio jack. Wait for your Raspberry Pi BalenaOS
5TWi
11 'wlW

Pevi^r
■J^dlEln-g 111 C
£
Logs jl ■ • a
update and confirm all systems are running.
5*
ITtvKt MUffSt
ViriAbteii
Ltfiiui Kiji
C
From your smartphone, tablet or computer, navigate
On|i fr. iEtl

lanr<|uinti»n to your Bluetooth settings and look for BalenaOS XXXX

L'-BWJ, I 4&AW iMbl I BJXaH

ft
A4EICH1.TU

&■.!£ nriMhr’i
■ .vtarv hudi!
and pair it to your device. Connect the device as the
La.PEI licitJ-.Sil

Locition
St.fl,I fl © HaUA-lSa J I

L IP
sound output for your smartphone, tablet or computer.
il ,HTJH’|F yrl
Nn 1.ip7i i r*
Go to your streaming service and play a song. The music
WfjTl ‘i
should stream via Bluetooth to your Raspberry Pi and
play from the attached speaker.
4

» MULTI-DEVICE/MULTI-ROOM SYNC
For multi-device sync, repeat the setup DJing from your smartphone, tablet, or
stages we described above for each extra computer like a pro.
device. You can flash the same image from If you’re an audiophile you probably won’t
earlier if you’re using the same model of care much for Bluetooth audio, or indeed the
Raspberry Pi. With the same Bluetooth headphone output on the Raspberry Pi.
device connected as mentioned earlier, Fortunately there are a variety of DAC (digital
music can now stream to all Raspberry Pis analogue converter) HAT boards that enable
and their connected speakers. You will only faithful audio reproduction for not much
need to connect one Pi via Bluetooth to your money. IQaudio has been part of the Pi
phone, tablet, or computer to stream to all community since 2015 and we've long been
Raspberry Pi Balena Sound speakers. a fan of its range of DAC and amplifier
That’s it! You can now create multi-room/ boards. Now IQaudio is part of Raspberry Pi Breathe life into unused bluetooth speakers
and old amplifiers with Balena Sound.
multi-device sound experiences in your and those boards are being added to the
home with your Raspberry Pi devices while range of Raspberry Pi products.

104 Ultimate Linux Projects

 Raspberry Pi projects

Pi-based KVM over

Use your Pi as a remote control for your PC, even if it won’t boot to an OS.

hose of you who have needed to access a PC

YOU NEED
O remotely will probably have tried VPN or
other applications such as TeamViewer.
However, this kind of software only works within the
remote computer’s OS, which means that it can’t
> Raspberry Pi 4 or Zero
> 16GB or larger microSD card
> HDMI-to-CSI bridge or HDMI-to-USB capture dongle
access the BIOS, reboot, install an operating system > USB female-to-dual male Type-A splitter
or power on the computer. There are several solutions > USB C to Type-A cable
that make it possible for you to remote control a PC > 5V, 3 Amp power supply with USB Type-A output. You’ll
independently of its operating system, but using a be plugging a type-A cable into it so the official Raspberry Pi
KVM over IP is one of the most convenient and power supply won’t do
affordable approaches.
While a store-bought KVM over IP device can cost 5V pin then it'll back feed the power from your wall
hundreds of pounds, it’s easy to use a Raspberry Pi to power to the PC, possibly causing damage to its USB
create your own. A developer named Maxim Devaev port in the process.
designed his own system, Pi-KVM (https:Z/’pikvm.org/), Connect the USB C-to-A cable to the Type-A female
which he's planning to sell as a $130 kit. However, if you connector on the splitter. This will provide power to the
have the right parts, you can use the software he’s Pi. Connect the USB-C cable to the Raspberry Pi 4’s
developed and your Pi, to put it together for far less. USB-C port and connect the unmodified Type-A male to
Here, we’ll show you how to build your own Raspberry your power supply. Attach the USB Type-A connector
Pi-powered KVM over IP that can output full HD video, and HDMI to the PC that you wish to remote control.
control GPIO ports and USB relays, configure server
power using ATX functions and more. You’ll be able to The Pi-KVM software
control the whole setup via a web browser from another At this point we're ready to start using the Pi-KVM. On
device on your local network. first boot it’ll take longer then expected due to the initial
process for enlarging the microSD card. Just be patient
Download the image - it’ll boot eventually. Navigate to the Pi’s IP address
The first thing we will need is to download the SD card (you can look it up in your router’s control panel or use
image from pikvm.org. Note that there are different Nmap) in a browser on your client computer (the one
versions, depending on which Raspberry Pi you use and you’re using to control the other PC). You’ll be redirected
whether you use the HDMI-to-CSI bridge or an HDMI-to- you to the login page, which you should log into using
USB capture dongle. The file is bz2-compressed, but admin for both username and password.
Etcher can handle this automatically, so follow the guide Click the KVM icon. You should now be presented
from earlier and write it to an SD card. with a screen providing you with access to the remote
Now we can move on to installing the HDMI-to-CSI PC and a number of other menus. Further options and
bridge or USB-to-HDMI dongle and prepping the OTG instructions are available from the Pi-KVM GitHub.
USB-C cable. Connect the CSI
ribbon cable from the HDMI-to-CSI
bridge to the Raspberry Pi’s CSI
camera port. Make sure that the
blue marking faces the black clamp.
If you're using an HDMI-to-USB
dongle instead, connect it to a USB
port on your Pi. If you’re using a Pi
Zero then you’ll need a
microUSB-to-USB Type-A hub.
Disable the 5V pin on one of the
USB Type-A male connectors from
your splitter. The easiest way to do
this is to place a small piece of
Kapton tape over the right-most pin
on the connector. You could also try
cutting the lead to that pin, but
that’s more complicated. This will be
the connector that attaches to a
USB port on the PC you wish to
control. If you don’t disable that

Ultimate Linux Projects 1105

Ultimate Linux Projects

Gaming on RetroPie
Turn your Raspberry Pi 4 (or 3 or Zero) into a retro gaming rig
with RetroPie and dubious internet downloads.

ack in the 1980s and 1990s, the arcades grab the latest image from https:Z'retropie.org.uk/

D were the place to be. The latest video games

from Namco, Sega, Konami and more ate our

days are now sadly behind us, but retro gaming has
download and use Etcher. Either way, there are separate
editions for first-gen devices (the original Raspberry Pi
and Pi Zero), multicore devices (the Pis 2 and 3) and the
ten-pence coins as we pursued that high score. Those
latest Pi 4 or 400 models. Eject the microSD card and
seen massive growth in the past decade. insert it into your Raspberry Pi 4. Next, plug in a
Using a Raspberry Pi, you can run a variety of controller. Xbox One and PlayStation 4 pads are
emulators that enable you to play not only old-time compatible with RetroPie via Bluetooth, but require a
arcade games, but also your favourite titles from many USB connection until Bluetooth is configured.
old consoles, including the Atari 2600, NES, Power on the Raspberry Pi and wait for your
Nintendo 64, Sega Mega Drive and Game Boy. There are controller to be detected. Configure your controller.
Note that you probably will have fewer buttons on your
controller than RetroPie asks you to configure. Just hold
TUCK INTO A SLICE OF RETROPIE I down a button that you’ve already configured to skip
past any options you don’t need. Press the A button on
“Using a Raspberry Pi, you can run a your controller to close the configurations menu and
open the main menu.
variety of emulators that enable you to
Adding games To RetroPie
play arcade and console games.” I All the games exist as files called ROMs, which are
dumps of real boards or cartridges. The easiest method
a number of emulation platforms available, but RetroPie to add games is to use a USB stick to transfer the files
is by far the most popular and arguably the best. from your computer to your Raspberry Pi. It's important
Up until recently, installing RetroPie on a Raspberry to note that games from retro consoles are under
Pi 4 was a pain. Even though Raspberry Pi 4 came out in copyright no matter their age. If you don’t personally
June 2019, RetroPie didn’t officially support it for nearly own the cartridge/board and rip a copy of your own,
a year and there were some manual steps you needed downloading and distributing these ROMs may violate
to take to make it work. Now, not only can you install laws in your country, so proceed at your own risk.
RetroPie on a Raspberry Pi 4, but you can do it using the On your computer create a folder called retropie on a
Raspberry Pi imager. It couldn’t be easier. You can also FAT32/exFAT-formatted USB flash drive. Plug the USB
flash drive into the Raspberry Pi 4 and RetroPie will
create a folder structure inside the retropie/ folder on
» WELCOME TO THE PICADE the stick. Remove the flash drive and insert it into your
computer. Copy your games to the correct system or
Pimoroni’s Picade arcade cabinets have a long history of quality. console folder in retropie/roms/. For example, put
Coming as a laser-cut, self-assembly kit in eight- or ten-inch screen Atari 2600 games in the Zatari2600 folder. Eject the
sizes, Picade is easy to build and can be used with all models of flash drive and place it back into a USB port of the
Raspberry Pi, but for best results you’ll want a Raspberry Pi 4. Raspberry Pi 4. How long this will take depends on how
Because Picade uses common arcade components, it can be many games are transferred over: a matter of minutes
customised to meet your playing style and aesthetics. If you like for a few games; hours if transferring a large amount.
microswitched buttons and joystick then When complete, remove the USB flash drive and
you can easily swap to get the edge in press START. From the menu select Restart
your favourite game. The Picade X HAT Emulationstation/Restart System. The games list will
attaches to the GPIO of your Raspberry Pi now update and show the available computers/consoles
and provides connections for the controls, for which there are now games. Bear in mind that, when
USB-C power management and an audio it comes to playing retro arcade games from actual
DAC connected to a 5W speaker for arcade machines, not all ROMs are compatible with all
authentic arcade audio. Everything you emulators. RetroPie can run with ten different versions
need to build your own arcade cabinet - of MAME (Multiple Arcade Machine Emulator), the most
just add a Raspberry Pi! A DIY kit with popular arcade emulator, and some ROMs will run on
step-by-step instructions to build, wire some versions of MAME and others will work on others.
and configure a custom cabinet offering a The Picade is the perfect desktop RetroPie maintains a handy chart over at https:/''
slice of retro gaming heaven. I
or bookshelf distraction. retropie.org.uk/docs/MAME, but if your arcade games
don’t load in one MAME, try another.

106 Ultimate Linux Projects

 Raspberry Pi projects

Environment sensors
With sensors and data and neat tidy cables, that’s how our garden grows.

ou can use your Pi to display your PC’s CPU

temperature and graph it on an LCD display. YOU NEED
However, for this project we’ll take that idea > Raspberry Pi (any model)
a step further, and measure a range of environmental > GrovePi or GrovePi Zero
variables. Thermistors and most other components > Adafruit 1.3-inch Bonnet (or other display)
that measure such factors, are analogue in nature. So > GrovePi Sensors (temperature, moisture, light)
they’re not immediately suitable for the Pi, which
Stack the display
only has digital (GPIO) inputs. However, thanks to atop the GrovePi
HATs like the GrovePi, it’s easy to get your Pi talking daughterboard,
to analogue sensors. We used a high accuracy plug in some
temperature and humidity sensor, a soil moisture sensors and you’ll
be monitoring the
meter, a light sensor, but much more are available
environment in
and getting them working with GrovePi is super easy. no time.
We won’t cover setting up the Pi (any model will do),
but you’ll probably want to get it set up for SSH and
Wi-Fi access, especially if you’re planning on installing
this in your greenhouse. One thing we will note is that
you might have to coerce your Pi into using Python 3 by
default (if it doesn’t already). This is a matter of
$ sudo update-alternatives -install /usr/bin/python
python /usr/bin/python2.71
$ sudo update-alternatives -install /usr/bin/python from digitalio import DigitallnOut, Direction
python /usr/bin/python3.7 2 from PIL import Image, ImageDraw, ImageFont
Now we can set up the GrovePi board, and Dexter import adafruit_rgb_display.st7789 as st7789
Industries provide a script that will do this in one line: Then you can use regular PIL image and text
$ curl -kL dexterindustries.com/update_grovepi | bash commands to draw the info on screen
height = disp.height
Vision on width = disp.width
You’ll need to reboot once everything’s done, at which image = Image.new("RGB", (width, height))
point we can start setting up our display. There are a rotation = 90
huge range of TFT, OLED or LCD screens available for image.draw = ImageDraw.Draw(image)
the Pi so this depends on your hardware. We used For this project to be useful, we need the display to
Adafruit’s 1.3-inch Pi Bonnet display and to set that up continuously update. So we’ll make a loop, which clears
we had to install Pip and then install its Blinka library, the screen, updates readings, pauses and repeats:
which enables interfacing with their CircuitPython APIs: fnt = ImageFont.truetype("/usr/share/fonts/truetype/
$ sudo pip3 install -upgrade adafruit-python-shellwget dejavu/DejaVuSans.ttf", 30)
$ https://raw.githubusercontent.com/adafruit/ while True:
Raspberry-Pi-Installer-Scripts/master/raspi-blinka. moisture = grovepi.analogRead(l)
pysudo python3 raspi-blinka.py light = grovepi.analogRead(2)
Then reboot and you should be ready to go. draw.rectangle((0,0, width, height), outline=0, fill=O)
Adafruit’s Blinka
Reading from our combined temperature/humidity draw.text((2O,12O), "Light {}".format(l), font=fnt, library enables
sensor required a bit of copying and pasting from fill="#FFFFOO") Python to talk
httpsiZ'github.com/ControlEverythingCommunity/ draw.text((2O,21O), "Moisture {}".format(m), font=fnt, CircuitPython,
TH02, since the bit-banging is a little complex. But our fill="#OOFFFF") a variety of
MicroPython used
moisture and light sensors can be read with one liners: disp.image(image)
in tiny gadgets
import grovepi time.sleep(0.5) and robots.
moisture = grovepi.analogRead(l) You can go further with
light = grovepi.analogRead(2) this project, such as
Having got the data from the sensors, we need to get logging and graphing
it on the display. The Adafruit Python libraries enable temperatures with
images to be sent directly to the display, so we can use Gnuplot. Or you could
the Pillow libraries to help us. Then there’s some connect a watering
boilerplate to initialise the display (which we’ll omit system via a relay and
here, but you’ll find it at httpsiZ'learn.adafruitcom/ never have to worry
adafruit-l-3-color-tft-bonnet-for-raspberry-pi/python- about your peonies
stats-example). drying out again!

Ultimate Linux Projects 1107

Ultimate Linux Projects

Bitcoin Node wi
Make the Bitcoin network a bit bigger and
better with a Pi and a large storage device.
ou’re not going to get rich mining Bitcoin on

D a Raspberry Pi. Even with dedicated ASIC

mining hardware it’s hard to compete with
industrial operations in countries with subsidised
electricity supplies. The story is the same for other
You'd be hard pushed to Find a large enough SD card to store the

I
blockchain, so get yourself an external SSD.

a heatsink to avoid throttling or damage from

cryptocurrencies too - see www.tomshardware.com/ overheating. Fetch the SD card image from https://
uk/how-to/mine-cryptocurrency-raspberry-p. github.com/rootzoll/raspiblitz, write it to an SD card
Yet you can still use RaspiBlitz to turn your Pi into a (minimum 16GB), and use it to boot your Pi. Don’t
full Bitcoin node. This helps the Bitcoin network be more bother connecting a monitor (it won’t work), but
decentralised, and by extension more secure. If you run do connect an Ethernet cable. If you have the
your own node, and store your bitcoins locally, then recommended XPT2046 display then this will be used
you’re essentially self-sovereign - you haven’t entrusted automatically and will display the device’s IP address. If
your keys to others and you aren’t relying on other not you can use a tool like Nmap to get this information
nodes to supply correct information. To quote the and then connect from another device with, say
RaspiBlitz manual: “Not your node, not your rules”. $ ssh [email protected]
and using the default raspiblitz password.
Put some storage in place The setup wizard will walk you through setting up
Running a full node involves regularly syncing the passwords and storage, and ultimately syncing the
Bitcoin blockchain, which at the present time is 350GB blockchain, which will take hours. Once you log in again
and growing, so you’ll need some large external storage you’ll be presented with the options screen where you
before you begin. You can get away with a mechanical can tweak settings and, optionally, set up as a node on
hard drive, but life will be much easier if you can get the Lightning Network (see box, below). You can also
hold of a 1TB or larger external SSD. Ideally, you want see the status screen that would be displayed if you had
your node to be online all the time, but if you have a fast a display attached. Note that for others to connect to
internet connection then it’s easy enough to catch up your node, you’ll need to open port 8333 on your router
after some downtime. Bitcoin nodes verify new (and use a dynamic DNS service if you don’t have a
transactions before sending them to miners, and record static IP at home). For Lightning you’ll also need ports
new blocks as they’re mined, so they can't do anything 9735,10009 and 8080 to be open. You can also open a
useful until they’re synced. command prompt from the main menu, but don’t be
It's recommended to use a 3.5-inch LCD touch tempted to run apt update or such. There are
display to run RaspiBlitz, to display status information, instructions for updating RaspiBlitz on the project page
but you can also run it headless. It’s also advised to use and if you don’t follow them there will be tears.

» THE LIGHTNING SEEDS

Besides running a Bitcoin node RaspiBlitz mechanism of the main network, you channel is open, then you may initially
enables you to run a node on the could operate a rogue node and attempt lose funds, but these can be reclaimed
"layer 2" Lightning network. The to double-spend coins or otherwise (subject to both party’s approval) once
Lightning network permits Bitcoin cheat the system. As such there are your node is back online.
transactions to take place off the main ominous-sounding Watchtower services
RaspiBlitz vl.6.0 terst
blockchain so they can be confirmed that detect improperly operating Bitcoin Fullnode + Lightning Network + Tor

instantly rather than subject to the Lightning nodes and penalise them. CPU load 4.19, 3.59, 2.42, temp 58’C 136’F
Free Mem 1483M / 1939M HDDuse 316G (37%)
median six-minute confirmation time Lightning nodes are connected to SSH [email protected] dl4.0MiB u5.7MiB
that is part of the Bitcoin fabric. blockchain wallets, and these must bitcoin V0.20.0 mainnet Sync OK 100.00%
It’s possible to generate some income contain sufficient funds to cover any Public dhqukwv5cgy2r45w.onion:8333 11 peers

by running a Lightning node, but not off-chain business. If malfeasance is LND 0.10.4-beta wallet 0 sat
0/0 Channels 0 sat 0 peers
necessarily something you should jump detected, a so-called Justice Transaction Fee Report; 0-0-0 sat (D-W-M)

into unawares. Since the network lacks is initiated and funds are docked. If your You can use Onion (Tor) routing to keep the IP
the democratic (but lengthy) consensus node accidentally goes offline while a I address of your Lightning Node a secret.

108 Ultimate Linux Projects

 Raspberry Pi projects

YOU NEED
> Raspberry Pi 3B+, 4 or Pi Zero W
> 8GB (or larger) microSD card
> Raspberry Pi Cam, HQ Camera, Infrared
Camera or webcam
> Monitor/power supply/HDMI cable
Learn how to build your own
motion-triggered home security camera.

ome security camera systems have exploded PorchCam meye-6fb2cO1f Apply

Don’t rely too
much on SD cards
in P0PularitY while decreasing in price over
for storage. Cloud
k J the past few years. Yet there are some rile Storsgo ▼
saves will make
drawbacks: first, vendors often charge a monthly Storage Device Custom Path
files easier to
Root Directory /data/output/Camera!
fee to store your data; and second, you might not access too.
want video and photos from inside your home being Disk Usage 0.0/13.2 GB (0%)

shared with a third party. Upload Media Files ON

MotionEyeOS is a distro that enables you to turn a Upload Pictures ON

Upload Movies ON
Raspberry Pi with a camera into a home
Upload Service ✓ FTP Server
video-monitoring system, where the photos and videos Server Address SFTP Server
can either stay on your device (and home network) or, if Server Port I Google Drive
Location Google Photo
you choose, be uploaded automatically to a cloud­ Include Subfolders Dropbox
storage service such as Google Drive or Dropbox. Username
Password
Here, we’ll show you how to set up a Raspberry Pi
Test Service
security camera with MotionEyeOS. This software
works with almost any Raspberry Pi (connected to the
internet) and almost any webcam or Pi camera. There’s on the Pi screen. Alternatively, you can find this out
no fancy coding to be done in this project; it just works. from Nmap or your router’s configuration page.
Download the latest version of MotionEyeOS Enter your internal IP address into a browser window
corresponding to the model of Pi you’re using from and MotionEye should start streaming.
https:Z<github.com/ccrisan/motioneyeos/releases and
write it to the SD card. When the process completes, Configuring MotionEye
physically remove and then reinsert your microSD card. Click the Profile icon within your browser menu to pull
We do this because the software automatically ejects up the Login screen. Log in using the default credentials.
the microSD card when the process completes, but we The username is admin, and the password field should
need to add one file before the next step. be blank. Select your Time Zone from the drop-down
Create a new file named wpa_supplicant.conf with menu in Time Zone. Click Apply. MotionEye will reboot
the this text, replacing "YOUR_NETWORK_NAME" and which will take a few minutes. This step is important as
"YOUR_NETWORK_PASSWORD" with your details: each photo and video is timestamped.
country=gb The Frame Change Threshold setting determines the
update_config=l proportion of pixels that change before recording starts.
ctrl_interface=/var/run/wpa_supplicant The intent is to set your percentage low enough to pick
network={ up the movement you’re tracking, but high enough to
scan_ssid=l avoid recording a passing cloud. In most cases, this is
ssid="YOUR_NETWORK_NAME" achieved through trial and error. Start with your default
psk="YOUR_NETWORK_PASSWORD" 4% Frame Change Threshold and then move up until
you reach your optimal setting. Click the down arrow to
Save the file, eject the SD card and insert it into your the right of Still Images to reveal extra settings. Do the
Pi. Connect your camera, monitor and power supply to same for Movies. Set Capture Mode and Recording
your Raspberry Pi and power up. If you have a monitor Mode to Motion Triggered and choose an appropriate
connected, your Pi’s internal IP address will be displayed period to preserve both. A week is reasonable if you’re
working with an 8GB card. Click Apply to save changes.
Set your Camera Name, Video Resolution and other
options in the Video Device section. Click Apply to save
your changes. On the live feed view you’ll see new
buttons for viewing saved images and video.
In the current setup this media won’t leave your local
network. But if you’re okay having your media in the
cloud then it’s easy to set MotionEyeOS to upload to
Google Drive or DropBox. Alternatively, you may want
to enable remote access to your Pi security cam. You’ll
need to configure port forwarding on your router to do
This Raspberry Pi security camera can be used to record porch pirates, this. If you do this there are official iOS and Android
I monitor children or pets, or to watch out for burglars. apps so you can check your home when you’re out. B3

Ultimate Linux Projects 1109

Ultimate Linux Projects

Mike Bedford explains how to get the most from the Raspberry Pi HQ
Camera and learn the basic principles of photography at the same time.

hen Raspberry Pi launched its HQ Camera in

k
w 2020 (which we scored a commendable 8/10
J in LXF264), it introduced something very
Unlike RPi’s
previous
cameras, the HQ

CREDIT: Raspberry Pi Foundation

different from their previous two cameras. While the
Camera doesn’t
other two camera modules are made up of a sensor and have an integral
its interfacing electronics together with a lens, the HQ
OUR Camera doesn't have an integral lens. This means that
lens, although
compatible
EXPERT you need to buy one or more lenses separately, and lenses are
available from
Mike Bedford Raspberry Pi offers a couple of alternatives that we look several sources.
has embraced all at here. In that way, it’s similar to digital SLR (DSLR)
that digital photo cameras, but different from the cameras in
techniques bring, smartphones or compact standalone cameras.
but does I ike to Our aim here is to introduce the HQ Camera for
play with manual those who haven’t yet taken the plunge, and to follow
controls, so the this up by investigating how to use some of its less- will form the basis of some fascinating new projects that
HQ Camera is familiar features, and at how to choose lenses as you can formulate yourself.
surely a winner. alternatives to those provided by Raspberry Pi. Armed The new sensor has a higher resolution - specifically
with this information, we trust that many of you will 12MP, which compares to 5MP for the original camera
decide to try your hand with the HQ Camera, and that it module and 8MP for the second iteration. But although
that megapixel figure is the one that most users
concentrate on, the size of the sensor is also significant
» FOCAL LENGTH EXPLAINED because the larger the sensor, the more light it gathers,
and this also improves the image quality. So we should
The focal length is proportional to the magnification provided by the point out that while the original and v2 camera modules
lens and is inversely proportional to its field of view. However, direct both had 1/4-inch sensors, the HQ Camera has a
comparisons can’t be made between different lenses if they’re used in 1/2.3-inch sensor. These figures don't relate directly to
conjunction with differently sized sensors. For that reason, a 35mm the sensors’ width, height or diagonal, but the area
equivalent focal length is commonly quoted because it’s familiar to of the sensor in the HQ Camera is about three times
photographers and provides an easy way of making comparisons. greater than that of the earlier RPi cameras. For
The 35mm equivalent focal length is calculated by multiplying the reference, consumer DSLRs have sensor that has a
focal length by something called the crop factor, which depends on 12-times larger area again, and that increases by a
the sensor size. For the HQ Camera this about 5.5. This means that factor of another 2.3 in professional full-frame DSLRs.
the 35mm equivalent focal lengths of the 6mm and 16mm lenses are The HQ Camera supports lenses with C or CS
36mm and 88mm, respectively. A lens with a 35mm equivalent focal mounts, which are standards commonly used in CCTV
length of 50mm is considered to be a “standard lens”, which means cameras. While these are widely available - although
that it has roughly the same field of view as the human visual system, not always affordable - Raspberry Pi has picked a
so the 6mm lens is a slightly wide angle lens, and the 16mm lens is couple of third-party lenses that are the “official”
slightly telephoto. offerings. One has a focal length of 6mm and the other
Beyond these two official lenses, some Raspberry Pi dealers offer 16mm - see the boxout (on the left) for more details.
other lenses - for example the £36 8-50mm f/1.4 zoom lens from the
Pi Hut or the £15 2.8-12mm f/1.4 zoom lens from Pimoroni - but Manual controls
knowing that the crop factor of the HQ Camera is 5.5, and bearing in All cameras except the most basic point-and-shoot
mind that there are lots of C or CS mount lenses available, you should models offer a degree of manual control over focusing,
be able to choose other lenses that will meet your needs. shutter speed and aperture. The HQ Camera’s lenses,
on the other hand, don’t support automatic focusing or

110 | Ultimate Linux Projects

 Take better photos with your Raspberry Pi TUTORIALS

CREDIT: Raspberry Pi Foundation

automatic aperture control. This might sound like a Raspberry Pi’s
drawback, but being forced to use manual controls HQ Camera
product offering
means the user learns about some of the basics of
comprises the
photography and gains the artistic benefits that aren’t camera module,
available by using a fully automatic alternative. a 6mm lens and a
Next up, we need to consider exposure and this is 16mm lens, which
can be bought
controlled by three factors: shutter speed, aperture and
independently.
ISO rating. Shutter speed is exactly what it sounds like,
how long the shutter remains open. Typically this can
vary from as little as a thousandth of a second to several
seconds, and the amount of light admitted into the QUICK TIP
camera is simply proportional to the shutter speed.
Next is the aperture, which can be thought of as the The HQ Camera
has a blanking
effective diameter of the lens, and which is controlled by
cap that you
an iris shutter. This is specified as a so-called f-number
have to remove
and might vary from f/2.0 through f/2.8, f/4, f/5.6, f/8,
to attach a lens,
f/11 and f/16, to f/22. To cut a long story short, the but when there’s
larger the number the smaller the aperture, and each scene is quite different, and while this is usually a bad no lens attached,
f-number in the above sequence represents a halving of thing, there are exceptions. For example, if you’re replace the cap
the amount of light admitted. (See below for more) shooting a waterfall, you might choose to use a shutter to prevent dust
Finally there’s the ISO rating. This is a measure of speed of 1/30 or slower so the blurring of the water contaminating
how much the camera’s electronic circuitry amplifies imparts a feeling of motion. the sensor.
the signal. It might range from 100 to several thousand, Aperture effects something called depth of field, with The lenses
are supplied
but to 800 for the HQ Camera. the depth of field increasing as the aperture decreases
with Front and
- in other words, as the f-stop figure increases. A small
rear lens caps
Balancing act depth of field means that only objects close to the
which have to
Since there are three factors that affect the exposure, distance you’re focused on will be in focus, but a large be removed
there will be several combinations that will provide a depth of field means that objects over a greater range of when the lens
correct exposure. So, for example, if a correct exposure distances will be sharp. A large depth of field would in use and these
is achieved with 1/60 seconds, f/8 and ISO 100, it will often be suitable for landscape photography, so that should also
also be correctly exposed with 1/120 seconds, f/5.6 and everything from the foreground to the far distance is in be replaced
ISO 100, or with 1/240 seconds, f/5.6 and ISO 200. focus. Conversely, a small depth of field might be whenever
However, the results of these various combinations will preferred for portraits, to ensure that the subject is in possible to
guard against
not all be the same because these factors each impact focus while a distracting background is blurred.
damage or
the photo in various ways. Finally, we come to the ISO rating, and here the rule
Fingerprints on
Shutter speed is probably the most obvious. The is that the greater this figure, the more noise - which
the glass.
slower the shutter speed, the more likely it is that there manifests itself as a graininess to the image - is
will be some blur due to motion, either because you imparted to the picture. While there are pros and cons
moved the camera while the shutter was open, or to slow/fast shutter speed, and large/small aperture, it’s
because something in the scene moved. The likelihood hard to think of a reason that you wouldn’t choose the
of blurring due to camera shake is almost eliminated if smallest ISO rating required to enable your ideal shutter
you use a tripod, although as a rule of thumb if you’re speed/aperture combination.
shooting handheld you need a shutter speed faster than While the aperture is controlled manually using a ring
1/60 second with a standard lens, and faster with a on the lens, the shutter speed and ISO rating are
telephoto. Blurring due to something moving in the controlled by the raspistill software, albeit as specified

» F-STOPS EXPLAINED
It’s easier to remember something if you 16mm lens, at f/4 the iris shutter will odd-looking sequence f/1.4, f/2, f/2.8,
understand the principles, rather than have a diameter of 4mm. This, of course, f/4, f/5.6, f/8, f/11, f/16, f/22.
just learning by rote. Because f-stops, explains the apparently contradictory The fact that the f-stop is a ratio of the
which are the measure of aperture, aren’t fact that a large f-stop number implies a diameter to the focal length means that,
immediately understandable, here’s what small aperture and vice versa. Because to have the same aperture, a telephoto
you need to know. the amount of light a lens can admit lens must have a greater diameter than a
The way f-stops are written might depends on its area, and the area is wide-angle lens. You can see this by
seem strange. However, it’s really very proportional to the square of its diameter, comparing the two official HQ Camera
simple. An aperture of f/4 means that the we can now see why at f/8 a lens admits lenses. Despite the 6mm lens having a
diameter of the lens - as reduced by the a quarter of much light as f/4, and why slightly larger maximum f-stop of f/1.2
iris shutter - is the focal length divided the sequence of f-stops relating to a than the 16mm lens's f/1.4, the 6mm lens
by 4. So, in the case of the HQ Camera’s halving of the amount of light is the is smaller in diameter.

Ultimate Linux Projects | 111

Ultimate Linux Projects

by the user in the case of ISO. In the default automatic

QUICK TIP mode, therefore, the HQ Camera will operate in what’s
Many C and CS generally referred to as aperture priority automatic
lenses have a mode. This means that you select the aperture to
megapixel rating achieve a desired depth of field, and the camera
and it might software will adjust the shutter speed to ensure the
sound odd that correct exposure.
the 6mm official Many cameras also offer a shutter speed priority
lens has a 3MP
automatic mode, but this isn’t possible with the HQ
rating whereas
Camera. That is because, although you can specify the
the camera is
shutter speed in raspistill, the software isn't able to
12MP. However,
although
adjust the aperture accordingly because it can only be
optimal controlled manually on the lens. However, although you
performance can’t choose a specific shutter speed and expect the
is achieved if aperture to change to compensate, knowing that
the lens has a reducing the aperture will decrease the shutter Motion blur is controlled by the shutter speed. Left: sharp image/Fast
rating at least
equal to that
speed - assuming the default auto exposure hasn’t
been overridden in raspistill - you can change the
I shutter speed, Right: motion blur/slow shutter speed.

of the sensor,
shutter speed by altering the aperture. This might into a casing as part of a project, it makes sense to think
it would be
involve an element of trial and error, but you’ll soon about mechanical stability.
wrong to believe
learn how to achieve the effect you want, and don’t The HQ Camera has a tripod socket, and it would be
that12MP
sensor will only
forget that the shutter speed selected by raspistill's good to mount it on a tripod. A small cheap tripod might
provide 3MP automatic exposure will be recorded in the EXIF data be perfectly adequate for use on your desk while
performance in the image file. testing, although if you want to use it in the great
when used with outdoors, as discussed later, you’ll need a taller one. If
a 3MP lens. Getting started the HQ Camera is mounted on a tripod, the associated
Setting up your HQ Camera to work with a Raspberry Pi RPi will end up dangling from the ribbon cable.
board involves plugging its ribbon cable into the camera Since that cable is nowhere as robust as a USB or
socket of the devoce and HDMI lead, and nor are the associated on-board
enabling it using the sockets, this is best avoided by bolting the camera
raspi-config utility. This is module and the Raspberry Pi board together. Hardware
all well described in the is available to achieve that and it doesn’t cost much -
official user see, for example, mounting plate from The PiHut that
documentation so we’ll costs £3 - but if you order the camera from a supplier
If you’re limit our advice to what that doesn’t have the mounting hardware it might not
experimenting
might not be as well be difficult to make one yourself, depending on what
with the HQ
Camera, it makes documented. If you’re you have available. You’ll need a small sheet of plastic,
sense to attach it going start out using the onto which you can mount the HQ Camera on one side
securely to your HQ Camera on your and the Raspberry Pi on the other. You’ll also need eight
Raspberry Pi to
desk, perhaps as a short bolts, eight nuts, and spacers of some sort - you
prevent strain on
the ribbon cable,
learning exercise or to can see the one we made in the photo (on the left).
and to mount it on get to grips with the This will be enough to get the camera up and running
a tripod. camera before building it on your desk, where you’ll have access to a mains power

» CLOSE-UP PHOTOGRAPHY
CREDIT: Joe Ravi.

Commonly, lenses will focus to infinity, but is a misnomer because it’s a simple lens that
they won’t enable you to focus on close-up enables you to focus on closer objects. They
objects, which makes photographing small come in various strengths, measured in
things difficult. We tested out the two official diopters. 1,2,4 and sometimes 10 diopter
lenses. The 6mm was a surprise since it’ll filters are common and can be bought in sets
focus down to just a few millimetres from the of the three or four strengths, which can
front of the lens. That’s not very useful, used singly or in combination. The 16mm
though, because you can’t illuminate lens needs filters with a 37mm thread. We
anything so close to the lens, although tested out the 16mm lens with a combination
focused to a practical minimum distance of of a 2 and 4 diopter close-up filter - because
10mm, the field of view is 15mm wide. The we had them at hand - and were able to
16mm lens is more typical, having a focus down to 11mm, at which point the
minimum focus of about 55mm, and at that horizontal field of view was about 5mm. A set of close-up filters makes it possible
to photograph small objects. This set has
distance the horizontal field of view is 22mm. Yet another option is to use C/CS
too large a thread for the official 16mm
Like most C/CS lenses, the official lenses extension tubes, which separate the lens lens, although if you already have larger
have filter threads at the front which means further from the sensor, thereby decreasing filters for use with a DSLR, you could use
that you can screw on a close-up filter, which the minimum focussing distance. a converter.

112 Ultimate Linux Projects

 Take better photos with your Raspberry Pi TUTORIALS

or shorter as it focuses on near and far objects,

respectively. The other ring controls the aperture and QUICK TIP
has f-stops from f/1.4 to f/16 marked on it. To see how it We explained
works, remove the front and rear lens caps, screw on how moving
the C/CS adapter, hold the lens by that adapter and from an
then try rotating the aperture ring while looking through aperture of f/8
the lens from the rear. You’ll be able to see the iris to f/5.6 doubles
shutter open and close. the amount of
light entering
You might expect the 6mm lens to work in the same
the camera, and
way but it doesn’t. Specifically, the focus ring isn’t a ring
moving from a
in the sense that it can be rotated independently.
shutter speed
Instead, it’s immovable from the thread that screws into of 1/60 to 1/120
the camera. Trying to rotate it will actually tighten or halves it. Such
unscrew the lens from the camera. Instead, to adjust changes are
the focus, tighten the thumbscrew on the aperture ring often described
Depth of field is controlled by the aperture. Left: large depth of field/ - the one labelled with OPEN and CLOSE - and in terms of

I small aperture, Right: small depth of field/large aperture. unscrew the thumbscrew on the focus ring.
Now, while holding the thread or the aperture ring,
EVs (exposure
values] or,
colloquially,
supply and a monitor, and room for a keyboard and rotate the aperture ring. As with the 6mm lens, this
stops. A change
mouse, but if you want to start photographing the world focusing action will cause the lens to become longer or
of 1 EV involves
at large, you’ll need to devise a more portable solution. shorter. To adjust the aperture, tighten the thumbscrew
a doubling or a
For a start, you’ll need a small LCD panel that will act as on the focusing ring and unscrew the thumbscrew on halving of the
the viewfinder, and you’ll need some sort of battery the aperture ring. Now rotate the aperture ring but this amount of light.
power supply. All of that will need building into an time, it’ll adjust the aperture and again you can observe
ergonomic case, of course, and you’ll probably want to that by looking through the lens. Unlike the 16mm lens,
connect a push-button to act as the shutter release. the f-stops aren’t labelled, and the minimum aperture is
Many such projects have been published based on the with the iris shutter fully closed.
earlier camera modules, and you could adapt one of Once you know how to operate the lenses, you can
these, the main change being the mechanical attach them to the HQ Camera so you can see how
arrangement required to house the larger HQ Camera. adjusting the focus alters the distance at which objects
The other thing you need to know is how to use will be sharp, and how the aperture adjusts the depth of
raspistill, the command line utility that enables you to field. Both these effects can easily be seen if you use the
control any of the official Raspberry Pi cameras. There’s preview facility in raspistill. However, if you have both
no shortage of documentation, but to start we suggest lenses, we suggest you start with the 16mm to better
using raspistill -t 0 which won’t actually take a photo see depth of field in action, because telephoto lenses
but which will display a preview so you can try out the have a smaller depth of field than wide-angle lenses. You
manual controls on the lenses. You can terminate the won’t be able to preview blurring due to the
preview using Ctrl-C. consequential change in shutter speed this way though,
because the preview window shows a moving image.
The official lenses This is quite different from the still images that raspistill
Of the two official lenses, the 6mm one has a CS mount, can capture. To see motion blur in action, therefore,
while the 16mm one has a C mount. Confusingly, they you’ll have to capture some still images. E3
both have the same thread, so it’s quite possible to
attach either directly to the HQ Camera. However,
because C and CS lenses focus to a sensor at a different
distance behind the lens, if you’re using a C mount lens
you must use the adapter that’s supplied with the
camera. Failure to use the adapter with the 16mm lens,
or using it with the 6mm lens will mean that you can’t
focus properly.
Before attaching either of the lenses to the HQ
Camera, you’ll probably find it useful to get some
practice using the lenses’ manual controls. We’ll start
with the 16mm lens which is the most intuitive. You’ll
notice there are two rings, each of which has a
thumbscrew. Unlike an ordinary camera such as DSLRs,
with which you’ll regularly be changing the aperture and
focus, these lenses are intended for CCTV use, so they
enable the rings to be locked to prevent accidental
adjustments. Unless you’re using it for some
unattended application, though, it makes sense to use
the 16mm lens with both the thumbscrews unscrewed,
but not so far that they’ll fall out.
The focusing ring is the one with the FAR and NEAR lf you look through a lens while you adjust the aperture control, you’ll clearly see the iris shutter
labels, and as you rotate it, the lens will become longer I open and close to increase or decrease the amount of light admitted to the camera.

Ultimate Linux Projects 1113

Ultimate Linux Projects

BACKUPS

Back up and done

your Raspberry Pi
From disk cloning to backing up specific directories and partitions, keeping
your Pi backed up saves time and heartache, says Christian Cawley.

hile a flexible, affordable and much-loved

F------------ 1
This approach isn’t without its shortcomings,

w
k_______ J
piece of computing hardware, the Raspberry Pi
isn’t without its problems. One particular
however. For a start, there’s the volume of storage space
required for multiple images. You should also consider
bugbear is the device’s reliance on flash storage - the amount of time required for the initial image
potentially unreliable SD and Micro SD cards that are creation. Simply having a clone of a fresh Raspberry Pi
prone to data corruption following an unscheduled OS install is pointless, because that’s essentially what
shutdown or restart. you can download directly from raspberrypi.org.
One way to avoid this is to ensure that the Pi is shut Instead, the image should be the underlying operating
Christian down carefully. But it also pays to have a backup of your system together with the key software that you want to
Cawley data, just in case the worst happens. Raspberry Pi has use, along with the data you have saved to the device.
is known as The several options for backup, from cloning the Micro SD Some challenges might be faced with cloning your
Gadget Monkey card to remotely backing up over SSH. Raspberry Pi. For example, a 16GB disk image can't be
because he eats a cloned and then written to an 8GB SD card. However,
banana for Clone Wars you may also run into problems cloning a 16GB image
breakfast, The ability to switch Raspberry Pi projects simply by to another 16GB SD card, because of differences in
microwave chips swapping Micro SD cards means that if a card is found quality-control standards.
for his lunch, and to be corrupt, you can flash an image of its contents to a There may also be some difficulty booting a
a Raspberry Pi replacement. Cloning the SD card is a smart option that cloned disk image on a different system. For example, a
for dinner. enables you to keep a library of ready-to-use Pi images backup that’s been created on a Raspberry Pi 4 will
on your PC’s hard drive, ready for deployment. almost certainly not work on the Raspberry Pi Zero.
Just think of the time you can save. All your favourite However, if you keep in mind basic issues of
software installed just once; Wi-Fi networks already compatibility and file size, then cloning your
Rather than fiddle configured; SSH enabled, ready to use. Where once you Raspberry Pi for back-up purposes should be plain
around with the would reinstall and reinstall, changing numerous sailing. Cloning the SD card can be done on a desktop
odd command
settings to get things just right, cloning the SD card PC or on a Raspberry Pi.
in the terminal,
you can clone means that you can customise Raspberry Pi OS, get
Raspberry Pi SD things working how you like them, and then make a The clone heads
cards with Etcher. copy to use over and over again. To create a clone of your Pi’s SD card on a desktop
computer, all you need is the cross-platform flashing
CUMr tool, balenaEtcher (http:Z^bit.ly/LXF287-etcher).
Download and install this on your desktop system and
then insert the Pi’s Micro SD card into the PC's reader.
You should also have a second Micro SD card
connected ready to write to. Failing this, a USB flash
stick. Writing to a system drive isn’t possible without
first creating a dedicated partition.
Click Clone drive and select a Source. Click Select,
rluM
(WCAL9C0Q ...RCCALBCOO
then Select target to choose the target drive. This
should be the second Micro SD card. Once again, click
Select to confirm, then Flash to commence. Wait while
the software writes and verifies the data. You’ll notice
that it’s possible to flash the data to multiple devices if
you need to. You can also clone the Pi’s SD card directly
to your HDD. This is useful if you only have one SD card
but plan to run multiple Raspberry Pi projects.

114 Ultimate Linux Projects

 Back up and clone your Raspberry Pi TUTORIALS

With the SD card inserted in your desktop computer, The Raspberry Pi

open the terminal, and enter the following: Mipb«rry PI vlA.1 Imager tool has
various hidden
sudo fdisk -1
Features. Among
Identify the SD card and make a note of its name. them is the
This can be tricky, but it should be obvious from the size ability to write
of the SD card. It will typically be sda or sdb followed by any IMG File to a
Thr cfcgft W prwi <A
microSD card.
a number.
Next, use the dd command to create a clone. You WMr Q9
Opribng Wend
can name the target file however you like, but it should
have the .img extension:
sudo dd if=/dev/sdb of=~/raspberry_pi_clone.img QUICK TIP
Wait as the process completes. When you’re ready to Use the Fastest
write the disk image to a new Micro SD card, insert a rated microSD
fresh card and enter the following: cards For your
sudo dd if=~/raspberry_pi_clone.img of=/dev/sdb Pi, with Al
You might also use the Raspberry Pi Imager tool, the performance.
mouse-driven Raspberry Pi disk imaging software This will ensure
Fast, reliable
available from raspberrypi.org (you can find it here: Remote backups using SSH will save time and wear
system cloning,
http://bit.ly/LXF287-piimager) for Ubuntu, macOS, and and tear on the Pi’s SD card. It’s also a useful option if
which will help
Windows. After installing the program, click Choose OS, you run multiple Raspberry Pis.
when it comes to
then scroll to Use Custom and browse for the cloned . writing a Fresh
img file before writing it to a fresh SD card. When in clone... disk image. Also,
Backing up your Raspberry Pi files through cloning can avoid unknown
Clone your Home take up quite a bit of disk space, especially if you’re brands and stick
For a simpler approach that’s less time-intensive, making regular disk images. By default, the disk images to well-known
archive the Pi’s Home folder. This method enables you are the exact same size as the disks, rather than the names: SanDisk,
to browse and then restore directories and files to a data used. So, an 8GB cloned SD card would take up Kingston and
Samsung, say.
reimaged Raspberry Pi as and when required. Open a 8GB of hard disk space. Fortunately, the files can be
terminal and enter: compressed. All you need to do is pipe the output from
cd /home/ dd togzip to create a compressed .gzip file.
sudo tar czf pi_home.tar.gz pi sudo dd bs=4M if=/dev/sdb | gzip > raspberry_pi_clone.
With the archive created, copy pi_home.tar.gz to img.gz
another device for safekeeping. The next time you need To restore:
to reimage a Micro SD card, once complete simply gunzip -stdout raspberry_pi_clone.img.gz | sudo dd
unzip the /home/ directory and copy the files you need bs=4M of=/dev/sdb
to the Raspberry Pi. The cloned file is smaller using this technique and
will take up less space on your HDD. This, of course,
Network backup means you can make even more Pi backups... E3
If you prefer using the Raspberry Pi remotely and have
SSH enabled, then it’s possible to back up the device
across your network. » JUST BACK UP THE CONFIG FILE
This isn’t ideal for backing up the entire SD card,
however. Some files that are in use while the If your Raspberry Pi setup is unusual, perhaps due to the hardware
Raspberry Pi is running won’t be correctly cloned, you’ve connected to the device, but you don’t feel the need to
leaving you with a disk image that may not boot regularly back up, there is an alternative. Instead of backing up the full
correctly. The best option with this network approach is SD card, or even archiving the /home directory, why not simply make
to back up only data that you deem is vital, such as the a copy of config.txt? Existing in place of a system BIOS, config.txt
home directory. stores various system parameters required for the correct running of
Begin by starting an SSH session and connecting to the Raspberry Pi. Every Raspberry Pi operating system features a
the Raspberry Pi. Then enter the command: config.txt file, which is read by the system’s GPU as the device boots.
ssh pi@[IP_ADDRESS] "sudo dd if=/dev/mmcblkO While the Raspberry Pi is running, config.txt can only be edited as
bs=4M | gzip-" | dd of=~/Desktop/[BACKUP_NAME].gz root. You’ll find it in the /boot directory as /boot/config.txt. With the
Be sure to replace [IP_ADDRESS] and [BACKUP, microSD card inserted in other systems, config.txt can be edited
NAME] as appropriate. using a standard text editor. A whole bunch of options can be
Wait while the backup completes. Of course, the stipulated in config.txt. It enables the use of options for every
backup cannot be restored across the network. The Pi possibility, from RAM use to camera settings, display options,
would lose connectivity part-way through. To restore the overclocking, GPIO, and much more. For example, if you used a
disk image, you would need to insert the blank SD card Raspberry Pi Zero with a small display, you would need to make some
into your computer’s card reader and then use the dd changes to the default options in config.txt. By backing up the file
of command: after the changes are saved, you can save time after a reinstallation
gzip -de -/Desktop/[BACKUP, NAME].gz | sudo dd of=/ by simply replacing the default config.txt.
dev/rdiskl bs=4M conv=noerror,sync

Ultimate Linux Projects 1115

Ultimate Linux Projects

SENSEHAT

Turn a Pi HAT into a

Les Pounder blasts off with another tutorial showing how a versatile
HAT board can answer all your questions, and even be run in space!

he Raspberry Pi Foundation released its Sense

O HAT add-on back in 2015. Yet this board still

packs a full scientific platform and an 8x8 RGB
LED matrix for a little fun. In this tutorial we’ll introduce
the board, show text on the LED matrix and learn how to
read accelerometer data for a classic game of chance.
Installing Sense HAT is straightforward. With the
Raspberry Pi powered off, connect the Sense HAT to all
Les Pounder of the GPIO pins, ensuring that the Sense HAT perfectly
is associate overlaps the Raspberry Pi. Use the included stand-offs
editor at Tom’s to securely mount the SenseHAT. Now attach your
Hardware and a keyboard, mouse, HDMI, micro SD and finally power to
freelance creative boot the Raspberry Pi to the desktop. Because we’re
technologist. using the latest version of Raspberry Pi OS, there’s no Designed for all 40-pin models of Raspberry Pi, Sense HAT is an old
need to install any software or Python packages. ( board that's still relevant in the classroom and space station!

Project 1: Hello World Inside the loop we have a single line of code that will
The first project with any new piece of tech or software scroll our message, with red text and a white
is “Hello World”. It proves that our kit is working, and background. Each step in the scroll lasts 0.1 seconds.
that everything is ready for us to move further. The first sense.show_message(message,text_colour=red,
project is a simple scrolling message that will prove our back_colour=white,scroll_speed=0.1)
software and hardware works. In your preferred Python We now reach the except part of the code. This is an
editor, Thonny IDLE, Mu or a text editor, create a new file exception handler that is activated if we press Ctrl+C to
and call it text_scroll.py. Remember to save often! end the code. When that happens we instruct the Sense
Our first two lines of Python are an import that HAT board to clear:
imports the sense_hat class from the SenseHat module. except Keyboardinterrupt:
We then create an object that enables us to easily use sense.clear()
the class. Save the code and run via your Python editor. Thonny
from sense_hat import SenseHat and Mu have a run/play button. IDLE uses F5 or via the
sense = SenseHat() Run menu. ‘Hello world’ should now scroll across the
The next two lines are tuples - data storage LED matrix. When finished, press Ctrl+C - this
structures which can be created and destroyed but clears the matrix.
YOU NEED never updated. These tuples store the RGB colour
> Any 40-pin values for a particular colour, in this case red and white, Project 2: Magic 8-Bal I
Pi model red = (255,0,0) The Magic 8-Ball is a classic child’s toy. Ask a question
> SenseHAT white = (255,255,255) out loud (“Will my online delivery be left in the hedge
> Raspberry The message to scroll across the screen is stored as again?”, “Am I the only one who can empty the
Pi OS a string inside a variable called message. dishwasher in this family?” or “Is there anything worth
> Code: message = "Hello World" watching on TV tonight?”), then shake the 8-ball. In a
https://github. We now enter a loop, and to start the process we few seconds a message floats to a viewing portal, ready
com/lesp/ start a try and except handler. Any code inside the try to read. With the Sense HAT we can make a modern-day
LXF273- section of the loop is what our project will attempt to version, which uses raw data from the accelerometer to
SenseHAT/ run. In this case it’ll launch an infinite loop. determine that the 8-ball has been ‘shaken’.
archive/ try: Create a new Python project in your favourite editor,
main.zip while True: call the project 8ball.py and remember to save often.

116 Ultimate Linux Projects

 Turn a Pi HAT into a Magic 8-ball project TUTORIALS

We start by importing two modules. The first is our

Sense HAT module, and the second is called random
and from it we import a function that will be used to
pseudo randomly choose a response:
from sense_hat import SenseHat
from random import choice
Next we create the sense object to enable the ease of
handling with the Sense HAT module:
sense = SenseHat()
Again we create two tuples to store the RGB colour
data for the text and background:
red = (255,0,0)
white = (255,255,255)
The next line of code is a list, sometimes known as
an array in other programming languages. A list stores
data using an index that starts at zero. The first item in
a list is at position zero, and subsequent items have A simple if conditional test checks the value stored
their own numerical position. Lists can be created, inside the three variables x,y,z and if any of the values Sense HAT is
packed with
destroyed and updated. The list we are using stores are greater than 1 then the indented line of code is run:
sensors and is a
five text strings that are the answers to our eager if x > 1 or y > 1 or z > 1: capable platform
player’s questions. The indented line of code is a scrolling message, the for scientific
answers = ["Not likely","Chances are answer to our question. But this time, instead of using a experiments and it
can be used with
slim","Maybe","Quite possibly","Certainly"] static message in a variable we set the message to be a
many different
Another try and infinite loop process handles running random choice from the answers list. Then we set the programming
the code: text colour to red, background to white and speed up languages.
try: the scrolling text speed a little.
while True: sense.show_message(choice(answers), text_
We obtain the raw accelerometer values from the colour=red, back_colour=white, scroll_speed=0.05) QUICK TIP
Sense HAT and store them in an object called If the Sense HAT hasn’t been shaken, or the player IF you intend to
“acceleration”. From that object we create three has put it down on a table, then the else condition is use the official
variables that store the data for each axis: activated and the LED matrix is cleared. Raspberry Pi
acceleration = sense.get_accelerometer_raw() else: camera with
Sense HAT, you’ll
x = acceleration ['x'] sense.clear()
need to thread
y = acceleration ['y'] The final two lines of code handle the user pressing
the flat flex
z = acceleration^'] Ctrl+C to end the game. The LED matrix is cleared ready
cable through
The values stored inside the variables x,y,z can be for use again. the slot next
positive or negative values. It all depends on the except Keyboardinterrupt: to the joystick
orientation of the Sense HAT. Our code won’t need to sense.clear() before attaching
understand negative numbers, just that the Save aLnd run the code. Pick up the Sense HAT and it to the
numbers can go over a threshold that will trigger the give it a little shake. The answer to your questions is but Raspberry Pi.
answers to appear. a shake away. E3
Using abs() we can update the variable to store an
absolute value that ignores the value if it’s either
» PiS IN SPACE!
The Sense HAT is packed with sensors for temperature, humidity,
acceleration, orientation and air pressure. And we have a great RGB
LED matrix and a joystick that can be used in projects. To control the
Sense HAT we used Python, but we can also use Scratch and
Node-RED. Sense HAT was developed alongside a project called
AstroPi which saw two Raspberry Pi B+ boards being sent to the
International Space Station. These two Pis had their own Sense HAT
boards, official Pi cameras and a custom aluminium case designed to
protect and cool the Pis in space. Projects written by children across
the world were run on those two Raspberry Pis and that project still
exists today and you can take part via https:/7astro-pi.org.
The power of Sense HAT lies in its simplicity and flexibility. In our
time working with the Raspberry Pi Foundation for its Picademy
training courses, we used the Sense HAT to control robots via the
joystick and accelerometer, and one bright spark created a Minecraft
world that would change as the temperature changed. A cold room
produced snow across the realm. Sense HAT retails for around £30
and while this is quite expensive for a HAT, you will get plenty of use
The 8x8 LED matrix is bright and easy to control. Shown here is a out of this great board.
I message across the matrix.

Ultimate Linux Projects 1117

Ultimate Linux Projects

RASPBERRY Pi
STREAMING
Camera-shy Jonni Bidwell conquers his fears
as he harnesses the power of OBS Studio to
stream live to his. er. three followers.

emg an online broadcaster is an expensive undertaking, but you world. You can even run it on a Raspberry
has been a legitimate really don’t need any fancy hardware at Pi, and it works great in tandem with the Pi
profession for some years. all to get started. Many a YouTuber Foundation’s High Quality Camera.
But the pandemic fuelled a started out using just their laptops. But why stop there? Thanks to Owncast,
surge in aspiring home streamers. And Software-wise, the open source OBS it’s remarkably easy to self-host your
despite the ongoing relaxation of Studio is by far the most popular choice. It streaming. All you need is enough
measures, the home streaming wave provides an intuitive interface that makes it bandwidth to support your audience. With
shows no sign of breaking. Whether it’s easy to manipulate scenes and add effects even a modestly fast upload speed you’ll
repairing washing machines on YouTube, during recording. And it can stream to all be able to host a few dozen viewers. And if
playing Doom on Twitch or just ranting the most popular platforms (as well as a you don't, then take Owncast off-world and
on Facebook Live, there’s abundant whole bunch we’d never heard of, and run it on a virtual private server. As long as
diversity in the things people are some we could have done without hearing your stream can get from OBS to Owncast
broadcasting, and tuning into. Setting up about). We’ll show you how to get the most smoothly, then the mass transport all
a professional recording studio at home out of that and start broadcasting to the takes place in the cloud.

118 Ultimate Linux Projects

 Raspberry Pi streaming

The hardware and infrastructure you’ll need to get your stream live.

dam Curtis’s seminal 2002 documentary OBS 27.0.0-modlfied (llnux) - Profile: Untitled - Scenes: Untitled

The Century of the Self highlighted how File £dit View Profile Scene Collection Tools Help

rampant consumerism in the west, driven by

careful marketing, has engendered a society focused
Linux Format livestream
on the individual. Curtis’s production was prescient,
given that the decade that followed saw the rise of Live from the terminal dVWMy
: Utontu 30
I ■W/QD1U
; 5.1.0 5)
UTS >66 64
K (QJ

Im m'rvuvwddddy : 16 hours. 11 RtAt

social media, selfies and targeted advertising. And in

hRHRM hyyyyfMMMNMNfe *6
: 3.4 (dpkg), II
! .6 1/
*
hKhyNHXN, yMWy : 1266«72O

Not for everyone hPRRh

: wer

the past decade we’ve seen this appeal to the ego hbhyNRRNy

hWWM hyyyyMMWMh
jrHRfWy
hHNRlM
: Adwat?*
: Va»w [GTK7/1]
1 Yatu [GT12/1]

• , w IJ *, •0>.| t / K •, : *M) tottroft 63xx cUsj (4)

used to direct not just purchases, but politics too. We I am not a robot 0-HKHy
yyy
w.ei.e rnc qji

offer no salve for this societal narcissism, and as the

old saying goes: if you can’t beat em, write a feature No source selected

all about live video streaming. kene

Scenes -
T
Sources
Text (FreeType; O
~
A
Audio Mixer % Controls
Desktop Audio 0.0 de Start Streaming
T
Well, maybe our list of old sayings suffered a T
Text (FreeType «
Text (FreeType i
O
O
A
A Start Recording
• □ Window Capture O A

misprint. And just because we’ll show you how to put a T Text (FreeType2 O A Mic/Aux
• ———
0.0 dB
Studio Mode

Settings

camera and a microphone in front of yourself and Exit

» LIVE: 00:00:00 • REC: 00:00:00 CPU: 29.8%. 30.00 fps

broadcast signals to the internet at large, it doesn't
mean we want you to become a product-placing, you want to appear super-imposed on a funky backdrop Even if you don’t
falsehood-selling influencer type. There are plenty you’ll need a green screen. Basically, there's no shortage have a camera,
you can livestream
already, and we would rather you didn’t contribute to of directions to invest in this field, but let's not get
your terminal
the further erosion of society. Indeed, you could use this ahead of ourselves. We still haven’t covered how this tutorials using
power to foster community values instead, sharing arts streaming thing works. just a microphone
and crafts and stories of the old country. OBS sends video streams (whether they’re from your or a text-to-
speech engine.
desktop, a camera, or the internet) to a streaming
Hardware considerations platform. This platform (whether it’s YouTube, Twitch,
Whatever you’re planning to broadcast, you’ll probably Facebook, or a server in your basement) sends the
need a camera and a microphone. Your laptop’s livestream to viewers, often recompressing it on the fly
ensemble will be just fine to get started. If the hardware to accommodate different viewers’ bandwidth
works elsewhere in Linux then it will work on OBS (Open situations. So OBS only needs to have sufficient upload
Broadcasting Software) Studio. This gem of open source bandwith to get the data to the streaming platform,
software is hugely popular, both on Linux and which ought to have more.
proprietary OSes. Streaming platforms often incorporate some kind of
As you get more into this you may want to upgrade interactivity, such as chat windows, so your viewers can
your hardware. Microphone pops are annoying on the express their approval or otherwise through colourful
ears, and poor lighting makes your skin look bad. For language and hundreds of emoji. We’ll see later how to
high-quality game streaming you might want a video set up our own self-hosted streaming server too,
capture card, if you’re streaming live audio you might sticking it to the tech giants. But for now let’s turn the
want to invest in a mixing desk or better soundcard. If page and get started with OBS.

» STREAMING VS RECORDING
We’re going to concentrate on ‘live’ recording simultaneously. This is mostly a Audacity

Audio software foi inulti-t(ack recording and editing

livestreaming in this feature, but you might concern for patchy Wi-Fi connections.
prefer to record your show, do some edits The OBS setup wizard can optimise for
install

and retakes, then upload it. OBS Studio is recording from the get-go, which means it’ll
just at home recording as it is streaming - drop frames from the stream before it does
you just need to make sure you have enough so for the recording. Once you’ve got your
disk space. At the default bitrate video recorded, the non-linear video editor
(2,500kbits/sec) an hour of video will KDEnlive is great for editing it. You’ll need
occupy just over a gigabyte (plus more for plenty more space for this though as
audio). If you're recording to another working with large videos tends to produce
machine (say, over your LAN via Samba ) lots of temp files, as well as the finished Never let an opaque data collection policy
then make sure there's enough bandwidth product. You might also want to treat audio get in the way of a quality audio editor.
for this, especially if you’re streaming and separately, using Audacity, for example. Audacity is widely available.

Ultimate Linux Projects 1119

Ultimate Linux Projects

The gold standard for home streaming software is open source,

powerful and really easy to learn. It’s a triple whammy threat!

ets start by trying desktop OBS before Well, that’s not strictly true. In order to talk to the

O moving on to running it a Raspberry Pi.

Largely as OBS is in the Ubuntu
repositories, and probably in those of whatever
you’re using too. But it’s always worth getting the
appropriate interfaces and hardware, the Snap needs to
be connected, like so (this happens automatically if you
install from Ubuntu's Software Centre)'.
distro
$ sudo snap connect obs-studio:{alsazaudio-record,avahi-
latest version (27.0.1 at the time of writing). OBS controlzcamera,jackl,kernel-module-observe}
maintains its own Ubuntu repository (the wiki covers If you don’t like Snaps there’s a Flatpak available too.
this, as well as distro-specific instructions, over at That’s what we used, with great results, on our Pop!_OS
https:Z<obsproject.com/wiki/install- laptop. Pop supports installation from Flathub straight
instructions#linux), but since there’s a Snap from its own software centre (Pop/ Shop), and so might
package you’d probably do well to use that. The your distro. But if it doesn’t, then install the Flatpak
Snap package includes support for hardware-assisted daemon and then install and run OBS with:
video encoding, virtual cameras and all sorts of other $ flatpak install flathub com.obsproject.Studio
treats you probably wouldn’t get if you compiled it $ flatpak run com.obsproject.Studio
yourself - something Pi users will have to do as we’ll When OBS starts you’ll be greeted by a setup wizard
see over the page... You don’t have to be on Ubuntu (and if you use the Snap, some weird questions about
to use Snaps (but if you are, you’ll find the OBS Snap resetting the Ul and setting a password for the
in the Software Centre), so once you’ve got the Snap Websocket server, which you shouldn’t worry about).
daemon installed it’s just a matter of: Choose “Optimize for streaming”, and go with the
$ sudo snap install obs-studio default Base resolution of 1280x720, unless you have

GET TO KNOW THE THE OBS INTERFACE

Preview window Sources Scene transitions

O This displays the current Scene.

Set the scene by dragging and resizing
0 These might be cameras, microphones,
desktop windows or something else. Each
B Here you can figure a stylish effect, for
example a fade, to make switching between
sources with their frames. scene has its own sources. scenes look pleasing to the eye.

Scenes Audio controls Stream controls

0 A Scene is a template for a section of

your broadcast. Different Scenes might use
Q The VU meters will react to audio input.
They shouldn’t go into the red. If they do then
Start or stop your stream (or recording)
with these buttons, or jump into Studio Mode
different sources, layouts or captions. use the sliders to bring levels down. if you feel like some live VFX.

120 | Ultimate Linux Projects

 Raspberry Pi streaming

output resolution. If your computer handled it

during set up it’ll be the same as the base
resolution (the size of the canvas), otherwise
it will be less.
You might be planning on doing a purely
audio stream (for example, to Mixcloud) in
which case there's one less class of media to
worry about. Either way, make sure that your
recording levels are good and be sure to familiarise
yourself with the ways of muting the microphone. Given
the pandemic and its plethora of virtual meetings, you
might already know this particular drill.
OBS saves your sources and scenes automatically,
The Snap version of Open Broadcasting Software Studio comes so it's easy to jump back in after a streaming break.
I with all kinds of additional bells and whistles. Still, it’s worth coming up with a better name than
“Scene” for your first scene, which you can do by right­
strong feelings otherwise. Unless you're confident your clicking and selecting Rename. You might want to
machine can handle it (and your viewers will notice the rename some of your sources, too.
difference) dial down the FPS to 30, at least for now. In addition to getting hold of the stream key, your
Next you’ll need to choose a streaming platform. This platform will offer options for your broadcast from its
will require you to have an account, and bind you to the dashboard. Twitch, for example, enables you to mark
terms and conditions of that platform. A key is used to your content as mature, set latency settings or store
make sure it’s you and not a stranger connecting their
camera to your streaming platform. Click the Get AUTOMATIC CONFIGURATION
Stream Key button, log in to your platform, copy the
private stream key from the web page and paste it into “OBS will see what it thinks
OBS. Leave the Estimate bitrate checked. OBS will see
what it thinks of your bandwidth situation and CPU of your bandwidth situation
power and set the encoder settings accordingly. Your
platform will then take this stream and serve it, as well and CPU power, and set the
as offering lower bitrates, to the masses. Go with the
settings OBS suggests (you can always change them encoder settings accordingly."
later) and you’ll find yourself in OBS’s main interface. If
you have a Linux-friendly camera and microphone
attached, then these will be automatically set and you broadcasts. YouTube's Studio section makes it possible
will see what the camera sees in the preview window. for you to edit your video online, or add a soundtrack.
See the next page for a guide to what’s going on here. We won’t tell you how to make a good broadcast. To
be honest, we don’t know, but if it's anything like making
Getting started with your hardware a good feature, then plan what you’re going to cover and
It’s good to keep things simple to start with, at least probably don’t wing it all at the last minute. Clicking in
until you’re sure everything's working. So start with just the Scene Collection box is easy during live broadcasts,
a camera and microphone. These will be listed as Video so if your Scenes are all set up nicely before you start
Capture Device (V4L2) and Audio Input Capture you won’t have to fumble around switching between
(Pulseaudio) in the Sources section. We set the base sources and clumsily repositioning them on the
canvas resolution to 720p earlier, which might be fly. Once you’ve got the hang of Studio View then it's
different to your camera’s native resolution. You can easy to create smooth and professional-looking
change this by right-clicking the V4L2 source and inter-scene transitions too.
choosing Properties. You might not want to fill the
canvas with camera input, in which case choose a lower
resolution here. You can put some decorations in the
blank bits of canvas later.
The currently selected source appears surrounded
by a red frame (unselected ones have a blue frame) and
it’s possible to drag and resize this (even during a live
broadcast) using the handles. Bear in mind that
rescaling video is an expensive operation, and if you’re
planning on using the same source at different sizes (to
go fullscreen with a game, say) it’s more efficient to
make use of Scenes. That way you can set the source
up at different resolutions for different Scenes.
Sources Audio Mixer Scene Transitions
If you’re only interested in one video source, you 0 Browser & A Audio Input Capture (PulseAudio) -9.1 dB Fade
T Text (FreeType 2) <•>
can right-click its preview frame and choose Resize □ Window Capture (Xcomposite): <•>
« * 50 45 M> £> 30 25 » IS 10 5 0
Duration 300 ms
► Media Source 2 <•> A
Output (source size). This will set the base and output Ks] Video Capture Device (V4L2) <•> A Desktop Audio -3.1 dB
□ ProjectM O A I I I I | I I I I | I I I I | I I I I | I I I I | I I I I | I I I I | I I Si | I I I I | I » I J I . (I 111j

resolutions to that of the camera, so that it appears full Pl Window Capture (Xcomposite) O
_ 40 46 M

A____________________________ —_____
Jb -36 Xi -25 30 15 10 K 0

screen. Video is sent to the streaming platform at the I In no time you’ll be adding beagles and interdimensional portals to your livestream.

Ultimate Linux Projects 121

Ultimate Linux Projects

Use one of your many spare Raspberry Pis as a remote camera

or go crazy and run everything from a Raspberry Pi 4.

r hile we were planning this feature, a little Pi from scratch, the SSH service is disabled by default.

w voice at the back of our head muttered, “Can

we get a Raspberry Pi angle in?”. We like to
If you're running wirelessly, you’ll need to tell it about
that too. This you can do by putting an empty file named
keep that little chap happy so we’ve come up with a ssh and another file full of wireless network info
couple of ways to quieten his screams for (wpa_supplicant.conf) on the boot partition of your Pi’s
Raspberry Pi streams. SD Card. Then you’ll need to run raspi-config on it to
We’re always looking for new Pi camera projects, so enable the camera in the Interfaces section. Again, a
first we reached for our trusty Pi Zero and attached a quick search engine query will help you if you get stuck.
camera - you can read more on the HQ camera back on The raspistill and raspivid programs which ship with
page 110. Remember that if you’re setting up a headless the Pi are commonly used to test that camera-related
things are working. But it turns out you can use raspivid
to make your Pi into a rough ‘n’ ready network source in
OBS. Just SSH into it and run:
$ raspivid -t 0 -1 -n -w 640 -h 360 -o tcp://<ip-
address>:3333
replacing <ip-address> with that of your Pi. There are a
thousand and one options for the program, and the
ones we use tell it (in order) to keep streaming forever,
listen on a TCP socket, not display a preview (although
that would be tricky without a monitor) and serve a
640x360 stream on port 3333 the interface specified.
You can specify all interfaces with tcp:Z<0.0.0.0:3333,
and it’s also possible to stream over UDP, too. In order
to use this in OBS, add a Media Source, uncheck the
local file box and use the same tcp://<ip-address>:3333
URL that you used in the command above in the input
box. Once you’ve added the source it'll initially be blank
for a few seconds, and then you should see the video
stream. If you’re like us and using a Pi Zero (or even an
The HQ Camera OG Pi from nine years ago), this delay will be significant
has a standard because the Pi’s SoC has to do some work encoding the
tripod mount. stream to h.264. This effect is compounded over
Handy because
wireless, so if you were hoping to perform some kind of
clumsy cabling
will easily topple
multi-camera choreographed line-dancing routine, this
whatever else you probably isn’t the best solution for you. However, that
balance it with. said, it can make for some pretty amusing and

» TAKE THE DIY Pi WEBCAM APPROACH

Obviously, neither Pi camera is a latency is certainly reduced, but not to Hunt’s blog post at www.davidhunt.ie/
microphone too, so on its own it’s not zero. You can compensate for this in OBS raspberry-pi-zero-with-pi-camera-as-
much use if you want audio in your by clicking the cog next to the Audio usb-webcam has all the details. Or, if you
streams. Dell recently moved the Input Capture meters, going to Advanced want a more automated approach see
webcam on its popular XPS13 laptops Audio Properties and adding a delay Jeff Geerling’s GitHub for an Ansible
to the top centre. But if you're like us, using the Sync Offset box. This might be playbook at https:Z<github.com/
and using an older model with its unique tricky to get right, since the actual geerlingguy/pi-webcam.
up-the-left-nostril focal plane, then latency might vary quite a bit depending Another approach is to use Ubuntu
you might be tempted to use the Pi on the compressibility of the current Core to stream using MJPEG, and
Camera as a surrogate, and use your scene, as well as network conditions. Canonical has an excellent blog post at
laptop’s microphone. But all is not lost. Thanks to the Pi Zero https://u bu ntu .com/blog/how-to-
If you use our slightly Heath Robinson and Pi 4’s OTG ports, you can set those stream-video-with-raspberry-pi-hq-
esque raspivid method on the Pi 4, then models up as USB webcams. David camera-on-ubuntu-core.

122 Ultimate Linux Projects

 Raspberry Pi streaming

occasionally paradoxical
multi-room antics.
Next, we approached the
Raspberry Pi Foundation which
kindly sent us an 8GB Raspberry
Pi 4, a High Quality Pi Camera and a
6mm lens. There’s another official
lens (and a whole bunch of unofficial
ones): the telephoto model, which is
slightly pricier, but also less suited
for streaming unless you are
shooting distant objects. It’s easy
enough to set all this up (again,
check out page 110) but if you're
using the 6mm lens then remember
to remove the CS-mount adapter
that comes attached to the HQ
camera module, otherwise you’ll
never be able to get it in focus.

Stay Focused apt-dance and machine reboot. Welcome to the future. Media Sources has
all kinds of options.
This lens has two manual adjustment rings - focus and Now download the build.sh file from the GitHub, make it
We couldn’t get
aperture - which lock closed with the helpfully provided executable, and run it with the hardware
screwdriver. If you’re not used to manual lenses, it can $ wget https://github.com/xbelanch/0BS4Pi/raw/ acceleration box to
be tricky to get the hang of, but you can set up raspivid main/build.sh work, though.

exactly as we did earlier and see if you’re going in the $ chmod 755 build.sh
right direction. Our advice is to start by pointing the $ ./build.sh
camera in the direction of where you want to film, then Your Raspberry Pi will take an awfully long time to do
adjust the aperture ring until it looks like enough light is this, and you might find that it gets fairly hot. Besides
getting in (and do take care to ensure that there's OBS, the script compiles custom versions of FFMPEG
enough light, too; it's not a night vision camera). Then (SRT transport support isn’t included in the regular
screw the aperture ring to fix it in place and adjust the
focus until it’s crystal clear.
Speaking of focus, remember that it’s possible to THINKING BIG WHILE GOING SMALL
adjust the focus on the standard Pi camera, too. On
older models you need to be a bit brave scraping off the “There’s no official build of OBS Studio
glue around the lens, but then you’ll find it rotates quite
freely. Then you can get it focused right up close for a for the Raspberry Pi, but it’s open
macrovision stream of your bird box. Pimoroni sells a
handy lens adjustment tool for this, as well as all kinds source so we figured let’s just have
of lenses for both camera models.
To finish, we thought we’d do something a little a go at compiling it ourselves”
adventurous. After all, we had one of the most powerful
Raspberry Pis in the known universe in our possession. version) and all the associated codecs. If it completes
There’s no official build of OBS for the Pi, but it’s open without error, you should be able to start OBS from the
source so we figured let’s just have a go at compiling it command line. We didn’t download the launcher from
ourselves. You might be able to do this on a Pi 3 as well, Xavier’s GitHub, so the instructions to use it won’t work.
but you’ll need a swap file because 1GB of RAM isn’t Try running the obs command directly,
going to cut it. And it’ll take a very long time. There's a though - you’ll see an error about invalid
thread all about this on the OBS forums at https:Z^ OpenGL contexts, because OBS isn’t
obsproject.com/forum/threads/obs-raspberry-pi-build- familiar with the Pi’s video capabilities. To
instructions.115739, so check there if you run into any get around this, force the OpenGL version
difficulties. Things tend to break often, because updates to something respectable with
in both Raspberry Pi OS and the OBS source code itself $ MESA_GL_VERSION_OVERRIDE=3.3 obs
stop the two from playing nicely together. or indeed download Xavier’s launcher.
An awful lot of packages need to be installed before And there you have it - streaming from a
we can begin, and it wouldn’t be terribly useful (for our credit-card-sized mini-computer. Why not
paper readers who can't copy and paste) to list them see if you can get it working with a
here. Instead we’ll use Xavier Alonso’s rather excellent microphone HAT. Or a thermal camera. Oh,
script which you can find at https://github.com/ and big thanks to Alex Blake and The Raspberry Pi
xbelanch/0BS4Pi. You’ll need to upgrade to the just- Foundation for sending us all that useful equipment. If
released Bullseye edition of the Pi OS to start. To do this we become a famous influencer streamer-type we'll be
edit /etc/sources.list and change all references of sure to give you some exposure and a shout-out in any
buster to bullseye . Then do the ol' update, upgrade upcoming awards ceremony.

Ultimate Linux Projects 1123

Ultimate Linux Projects

Further, faster,
free-er streaming
Discover what else OBS can do, then cut the corporate
cord and host your own stream with Owncast.

ow that we’ve got basic streaming covered

O
it’s time to look further at what OBS can
do. We won’t tell you how to make a good
broadcast. Like we mentioned before, we’re far from
experts, so we’d encourage you to watch some
popular streamers yourself and take some notes on
what they do well that you enjoy.
We’re big fans of DistroTube on Twitch, so if you’re
planning a Linux-themed channel you could do a lot
worse than following his example. Clicking in the Scene
Collection box is easy during live broadcasts, so if your
Scenes are all set up nicely before you start you won’t It’s so easy to get started with Owncast - even your garden variety
have to fumble around switching between sources and
clumsily repositioning them on the fly. Once you’ve got
kitchen goblins can do it.
I
the hang of Studio View then it’s easy to do smooth name (the text of the caption itself is reasonable),
inter-scene transitions on the fly, too. and then type in some text. And format it to your
To see what that’s about, hit the Studio View button heart’s content. If you use Comic Sans then someone
and you’ll see two panes. Preview, on the left, shows the somewhere will judge you for it, but please, stick to your
Scene that you’re planning, and Program on the right guns. The chat log mode enables recent IRC (or other)
shows what you’re streaming (if indeed you’re doing logs to be displayed, but if your streaming platform has
that). Some basic transitions (Cut, Fade and Fade to its own chat platform, this can be added through
Black) are available by clicking the cog icon next to the View>Docks>Custom Browser Docks. Alternatively, if
Transition button. Add some transitions, then rearrange you set up Owncast (which we’ll get to in a moment)
some sources in the preview window. Use the slider to then that has its own chat interface.
overlay the new scene manually, or hit the button to do It’s also possible to capture your desktop, or a
Adding a it smoothly. Simple. We haven't covered what kind of particular window and use that as a source in OBS. To
transparent other media sources you might be fading into or out capture the whole screen, use the Screen Capture
BPYTop window of, so now would be a good time to look at that. (XSHM) source. You can capture individual screens or (in
to your stream is the advanced settings) a separate X server entirely. To
You can add sources by clicking the + in the Sources
perhaps not the
best monitoring
panel. The simplest source is Text (Freetype2) which capture a window, use Window Capture (Xcomposite).
solution, but it enables you to add captions to your videos. Choose that You can crop captures arbitrarily, which is useful for
looks cool. option, select Create New, give the source a sensible showing the currently playing Scene. Remove any
Filters for ’Window Capture (Xcomposite)'
sources you don ’t need with the minus button, and use
the Scene Collection to collate sources into chapters.
Menu BATl

Thanks to OBS’s plugin architecture, it’s easy to add 17-7589U

CPU
HHHMM HtSaHllSSFSIHlEsXhBHSUUEHHtteHHnft 58* C C
BpfTOP

16:29:32
custom features too. If you wanted to jazz up your game
20Mmt
nHESFr 57*C C

i7-7seeu 2.S GHz

lilllB»3liRWjlnMIRl’t: :i;.* ci 24B

27«
SR’C C3
57’C C4
stream have your favourite search engine look up “OBS
23X "::s:==
mm 24k
fsudcn 36%
59’C
Sfl’C
57’C
Hsraph •proc I liter reverse
15.3 GiB Rid: Program: User:
overlays”, which will provide you with all kinds of jazzy
IAV 3.47 3.22 2.78
9.82 G
nmimiii 5.53 G U 47.4 G
136122
134843
obs
5Sh
jonni
jonni
|disksHio- swap .everse tree cpu lazy > 6.59 G swap 9.99 G 3210 firefox jonni
IS.3 G1B
9.82 G
root 49.9 6
116122 obi
User:
jonni
borders for your sources. You might be concerned that
t 835 M U
tfi
18.7
496
M
M
69591
2879
bpytop
xorg
jonni

:a 5-53 G ■NBni 47.4 G 13*843 ssh jonni IBM

6482 Web Content
all these sources sound very X-centric and might not
jonn
iisuntiiiiiiiii 6-59 G tap 9.99 C 3210 firefoi jonni 898M
835 M ie.7 N 69591 bpytop jonni 25M
i 496 ■ 2879 Xorg jonni 1 »•.
web'content auto ero <u wlp58so
work on Wayland. In the latest release you don’t need to
6482 jonni 7 ISM
764 m 75R5 •5VM Download jonni
▼ 562 KlB/$ Ion'll
net £UtO ero <b wlp58s0 n>;

worry about this. OBS runs using XWayland, but behind

6 2.79 KiB/t
Download
▼ 562 K1B/S
Upload
a 2.79 KiB/s
Upload
the scenes Pipewire (and the slightly mythical sounding
Desktop Portals) is used to make the magic happen.
Key Colour Type Green

Similarity (1-1000) 400

Host your own stream
Smoothness (1-1000) Proprietary streaming platforms (and their copious
Key Colour Spill Reduction (1-1000) 100
bandwidth) are all well and good, but we're fans of
Opacity 0.8911
self-hosting here. So we went hunting for something

124 Ultimate Linux Projects

 Raspberry Pi streaming

that would enable us to take our broadcasts in-house,

and it didn’t take us long to find Owncast, which is
fantastically simple to use. The demo on its website
(https:Z^owncast.online) shows how you can be up and
running in less than a minute. We’re more than happy to
show you something similar here.
Owncast comes with its own online installer, which
you can invoke with
$ curl -s https://owncast.online/install.sh | bash
It’s good practice to check scripts before running
them, but since this one installs locally and doesn’t use
the root account it’s less of a concern. The script will NA u»urre

% Suutur* * Audiu Mixof % SCWW Trarnilmn* * Control*

► Mtd<a Source 2 Audto Input ( nptixr (PuliaAirt*) 0 1 tin |

also install FFMPFG if it’s missing, because that’s

Fade Starr Streaming
□ PtOjeOM O a rTTri" r i i j1
K Video Capture Device (V4L2) O Durabon UM) ms Start According
|O Window Capture (Xcomposrtel c£>
Studio Mode

what’s going to be doing all the transcoding. Owncast

► hq ram <•> DeiAtop Aud»u 3.1 <18
4* AjdK> input Capture (PulseAud-<•> Sernngs

Exit

will now be installed in your home directory and you can •J LIVE 00.00.00 • REC 00.00 00 CPU. 12.3%, 30.00 tps

start it as follows:
$ cd owncast In order for viewers to connect to your stream, port Use ProjectM to
$ ./owncast 8080 of the machine running Owncast will need to be produce glorious
visualisations
Now you can point your browser to http:Z^ open. This means that you’ll need to brave your home
(a la Winamp] For
localhost:8080 (or the hostname or IP of the remote routers settings here. Port 1935 needs to be open for your audio.
machine you installed it on). You should see the Owncast OBS to connect to it over RTMP You can change these in
interface, complete with chat. The first thing you should the settings, but remember that we’re running
do is change the default streaming key (it’s abcl23 ), Owncast as a user here, so you’re not allowed
otherwise anyone on your network could hijack your to claim port 80.
channel before it’s even begun. Or anyone on the If you want HTTPS - and you probably do
internet if your machine is accessible from there. So go for anything other than testing purposes -
to the admin page at http:Zdocalhost:8080/admin and then it’s a little complex. The recommended
change the stream key (which is also the password) in way is to use a reverse proxy. You might
the Server Settings section. You can also change the already have one set up, but if not you’ll find
site’s name, logo and description to suite your instructions for doing so on Apache and Nginx
personality or purposes. at https:Z^owncast.online/docs/sslproxies. It’s
In order to get OBS talking to it, go to OBS's Settings, also possibly to use the Site.js server
and in the Stream section set the service to Custom. For administration tool to install Owncast as a
the server use rtmp:Zdocalhost/live (replacing localhost service with a simple flourish at the command line.
with wherever Owncast is running) and use the stream Exactly how many users you can stream to depends
key you set up earlier. Now if you start streaming in OBS, on your bandwidth and chosen resolution. We found that
and head over the Owncast page, you should see a 1,500kbps (kilobits, not kilobytes) stream was
yourself. Plus you’ll get some idea of the latency you’re sufficient for our purposes, and since we allegedly have a
dealing with. 20Mbs upload speed (fibre is good, traffic-shaping
Speaking of which, you can configure latency in policies might not be) that should accommodate a
Owncast’s settings panel - it’s tempting to turn dozen or so users. That turned out fine for our party, but
everything down to microseconds, but unless you have if you have more than 12 friends (lucky you!), or would
a very low-latency connection to your viewers this will like to stream more bits to them and faster, then you can
result in buffering. For most purposes it really doesn't install Owncast on a VPS and have OBS connect
matter that things happen a few seconds before the remotely to it. Owncast also supports object storage
internet sees them. You’ll get used to people in the chat providers, so (for a small investment) you can outsource
taking a while to respond to your superbly delivered the heavy lifting to the likes of Amazon S3, Backblaze or
jokes and witticisms (we’re still waiting). Digital Ocean Spaces. E3

» COPYRIGHT CONCERNS
Budding disc jockeys, mix masters, but the hope of being vindicated in a broadcasting Major Lazer on repeat
selektas and soundpeople may be couple of days is little recompense for would very much be public performance.
tempted by the self-hosting option your broadcast being shut down. And if you look on Major Lazer (or
because it obviates the problem of We're not lawyers, but if you host a anyone’s) CDs it says “not licenced
automated DMCA takedowns that stream and only tell people you know for public performance”. In the UK
plague other platforms. Many a Twitch about it (and certainly if it’s password you’d need to apply to PPL PRS for an
streamer has found their streams muted protected) then that seems pretty much appropriate license. In the US ASCAP,
or stopped altogether because they had like an extension of your front room and BMI and SESAC hold performance
something that sounded like copyrighted you’d expect to be able to play what you rights to most pre-recorded music.
music playing in the background. There like there. But setting up a massive Oh and there's different licences for
are fair use exceptions to these things cluster of Owncast instances, publicly performance and synchronisation. Did
and copyright strikes can be contested, advertising it on Facebook and then we mention that we’re not lawyers?

Ultimate Linux Projects 1125

Ultimate Linux Projects

GAMING

Connect, configure
and use gamepads
Planning some Raspberry Pi gaming? Christian Cawley shows you
how to set up a game controller either natively or with an emulator.

lanning to play some games on your [bluetooth]# agent on

Q Raspberry Pi? Minecraft: Pi is far easier to play

with a game controller, but you might have
your eye on Doom or other shareware classics.
Alternatively, you could be hooking up a controller to
Agent is already registered
[bluetooth]# default-agent
Default agent request successful
[bluetooth]# scan on]

your Raspberry Pi-based retro gaming system. Configure Bluetooth to accept connections from Bluetooth game
A good selection of game controllers can be
connected to your Raspberry Pi using USB.
■ controllers, then trust the MAC address to enable easy reconnection.

Christian Furthermore, some well-known controllers can also be this is a well-designed, multi-purpose controller that can
Cawley linked up using Bluetooth. be easily connected to a Raspberry Pi, either using USB
A freelance writer In theory, all controllers should work with a or Bluetooth.
and editor Raspberry Pi. This covers everything from generic USB To connect the Xbox One controller to your Pi using
specialising in joysticks and joypads to the latest Bluetooth devices. USB, start by updating and upgrading Raspberry Pi OS:
consumer So, you can expect to be able to connect an Xbox One sudo apt update
electronics, who controller and a PS4 controller to your Raspberry Pi. sudo apt upgrade
is still finding pine Controllers designed for the PlayStation 3 and Next, connect the controller. Try it out with a game,
needles in his Xbox 360 will also work, as will Nintendo gamepads. perhaps Minecraft: Pi. The driver for Xbox One
Raspberry Pi. Own a PlayStation 5? The new Sony console features controllers should be built in - if not, use
a major revision of the much-loved game controller. But sudo apt install xboxdrv
despite being fresh out of the box in 2020, the PS5 Follow the instructions to install the driver, reboot the
controller will easily connect to a Raspberry Pi over Raspberry Pi, and try again.
Bluetooth, just like its predecessor. Using a wireless Xbox One controller with the
Meanwhile, Xbox Series S and X controllers are Raspberry Pi is a little more complicated. Two types of
YOU NEED backward compatible, and can be used on an Xbox One wireless Xbox One controller have been released. One
> Raspberry console. The new controller design should also work uses wireless, while the second requires Bluetooth. How
Pi 3 or later with the Raspberry Pi. can you tell which is which?
> Popular In this tutorial, we'll look at what you need to do to If your Xbox One controller has Wi-Fi, the plastic
game connect the most widely used game controllers to a around the Xbox button is the same colour as the top of
controller Raspberry Pi: those intended for the Xbox One, PS4, the controller where the triggers and shoulder/bumper
> Raspberry Xbox 360 and PS3 consoles. We’ll begin with the Xbox buttons are. Bluetooth Xbox One controllers, meanwhile,
Pi OS One, which boasts one of the most popular game have a single-coloured face. So, the plastic around the
> USB cable controllers available. Also compatible with PC games, Xbox button is the same colour as the rest of the
controller face.
To go in-depth you can open the battery
compartment. Here, the model number is listed: 1697
means it is a wireless controller, whereas 1708 indicates
a Bluetooth model.
Most game
If you have the 1697 wireless model, you’ll need to
controllers will
connect to the
connect the official Microsoft Xbox Wireless Adapter to
Raspberry Pi using your Raspberry Pi. This is a standard USB dongle that
Bluetooth or USB. should work out of the box. Simply hold the pairing
For wireless Xbox buttons on the adapter and the Xbox One controller to
One controllers,
sync, then start playing.
however, you’ll
need a USB For the 1708 Bluetooth controller, you’ll need the
receiver dongle. xboxdrv driver, as described earlier. You’ll also need to

126 | Ultimate Linux Projects

 Connect, configure and use gamepads TUTORIALS

USB game
controllers work
out of the box, but
if you’re not using
RetroPie, Recalbox,
disable ERTM (Enhanced Re-Transmission Mode). While or similar, you’ll
enabled, this Bluetooth feature blocks syncing between need to manually
install the xboxdrv.
the Xbox One controller and your Raspberry Pi.
echo 'options bluetooth disable_ertm=Y' | sudo tee -a I
etc/modprobe.d/bluetooth.conf r QUICKTIP
Follow this by rebooting the Pi
sudo reboot Don’t lumber an
old Raspberry
Pi Model B/
Start Bluetooth tools B+ board with
sudo bluetoothctl a Bluetooth
At the [Bluetooth]# prompt, enable the agent and set dongle-it will
it as default: slow things
agent on Make a note of the MAC code, then disconnect the down. Instead,
default-agent PS3 controller. You’re now ready to start a Bluetooth connect
Next, power up the Xbox One controller and hold the connection as explained earlier in the instructions for Bluetooth
sync button. Quickly enter: the Xbox One. controllers to

scan on Note that you aren’t limited to console controllers - a Raspberry

Pi 3 or later. For
to search for the controller. The MAC address should almost any controller you can think of with a USB
the very best
appear, comprising six pairs of letters and numbers connector can be hooked up to a Raspberry Pi. From a
results, use a
followed by “Xbox Wireless Controller.” Use the MAC cheap £5 controller to the top-end USB pads for PC, if
Raspberry Pi 4.
address to connect the Xbox controller: there’s a suitable USB driver available then the
connect [YOUR MAC ADDRESS] controller will work. The advantage of this is that if
When you see “Connection successful” you’re ready you're building a retro gaming system, pretty much any
to play. To save time connecting the controller manually controller you connect over USB will work.
in future, use the trust command: For other Bluetooth controllers, meanwhile, generic
trust [YOUR MAC ADDRESS] connections should work. This means that anything -
But what if you prefer to use a PS4 controller with smartphone game controllers, for example - can
your Raspberry Pi? The steps described earlier for the conceivably be connected using bluetoothctl, but
Xbox One controller also apply, and you can connect some calibration may be required.
with USB or Bluetooth. Whatever device you’re using, you may need to test
it. To do this, simply use the testing tool in the Linux
Using older or different controllers joystick utility:
If you don’t have more recent controllers (or the budget sudo apt install joystick
to buy them because they can be quite pricey these Then run jstest
days), it might be easier for you to grab a controller sudo jstest /dev/input/jsO
from an older generation of consoles, such as the This will help you to spot unresponsive buttons and
Xbox 360, or PlayStation 3. thumb sticks - useful for troubleshooting. E9
Connecting an Xbox 360 controller again requires
the xboxdrv driver. While the USB model should
work out of the box, the wireless model will require » CONTROLLERS AND RETRO GAMING
a dedicated wireless receiver (the type that is developed
for PC use). While you’ll need to manually install drivers on the Raspberry Pi for
The Xbox 360 controller is simple to sync with a native gaming with game controllers, using controllers with RetroPie,
Raspberry Pi, but connecting a PS3 controller is more Recalbox and so on, is easier. Whether you’re using a full disk image
involved. Although the USB option is straightforward, or have manually installed the retro gaming suite on your operating
Bluetooth access requires some compiling. system, the drivers are included.
After updating and upgrading the Raspberry Pi, However, this doesn’t mean you can simply plug and play. Rather,
install the libusb-dev software. This ensures the PS3 can you’ll need to take the time to detect and calibrate the controller. To
communicate with the Raspberry Pi over Bluetooth: illustrate, let's look at configuring a game controller in Recalbox.
sudo apt install libusb-dev Start by connecting the USB game controller. If you’re using
Next, create a folder for the sixpair software, switch Bluetooth, put the device into pairing mode, then with a USB
to that folder, and download it: controller, open Start>Controller Settings and choose Pair a
mkdir -/sixpair Bluetooth Controller. Select the controller from the list, then confirm.
cd -/sixpair Once detected, Recalbox will prompt the button mapping process.
wget http://www.pabr.org/sixlinux/sixpair.c This involves pressing buttons for each displayed option. For instance,
Compile the code with gcc: consider the ABXY buttons, triggers, D-pad and so on. It’s worth
gcc -o sixpair sixpair.c -lusb noting that if you make a mistake, you’ll need to restart the process
Now you need to connect the PS3 controller to the Pi for the controller in question.
using its USB cable and run sixpair to configure the Usually this doesn’t take too long - once the buttons and direction
Bluetooth connection: controls are mapped you’ll be ready to start playing retro games.
sudo -/sixpair/sixpair

Ultimate Linux Projects 1127

 NEW Essential tips for perfecting your composition

iMPTZ/W ^afZ-tXZAWiW<rT^< THE BEST DIGITAL ART FOR ELM ANO GAMES
ji a a ■ taiMakHi m

Paint Draw
Crochet u WATERCOLOUR

WITIONA L Everything you need to know aseasy as 1, Z 3

A LANDSCAPES

Master Ml the stitches to start on your very first project

HOb) TO C^TUXi-C
u^rtfr With ^il.^

a
NEW!

INSIDEAPJIST’S
FftWlC'

Pro tips and HWfflUUflR89l

Ml I K« UHJIAI HOWS'

DINOSAURS
L INCLUDED j

step-by-step
tutorials from
artists and
Discover how to
illustrators bring your artistic
creations to life
TOWUI KW • HHMIHl • IB8Y 80&MK • MOMIDHIUW • i IKRf

NEW! NEW Uncover th* ikdk you need to nuitrf painting w*th ecry Scs

Beginner's Guide to Paint&Draw FAMiLY

WATERCOLOURS k ACRYLICS.z>. CROCHET
TOYS. GIFTS. CLOTHING ANO MUCH MOPE!

PROJECTS
«tep-by-step
tutorials
INCLUDED
Learn and
AvtxvV*»to

Key painting
techniques
urtfeeeli |«jr rrw
in-depth
expert
workshops with drawing
Advice for

and colouring
Cotour theory Essential kit Core skills Unique effects -fhert's activities BOOK FOR KIDS!

the skiili you need to master dr;

NEW
NEW

MASTER CROCHET TECHNIQUES

URiOUS FROM THE MAKERS OF

WbmaniHteeWy
Gel Io grips with key skills, stitches end techniques
and loom how crochet patterns work

ANATOMY

CReaTURes
AMAZING AMIGURUMI PATTERNS
TO MAKE WONDUTVUV
WFIRD ANIMALS
130
Tf&V
ADVKX

EVERYTHING YOU NEED TO

NOW TO CREATE BEAUTIFUL
STtP'SY SHP INSTRUCTIONS SIMflf TECHNIQUES
ITEMS FOR YOUR HOME MMTftnttV>XYTItt>«HOI WDTIHMM AMK'I IU Mt
COSY CRAFTS
FOR THE WHOLE
FAMILY TO
ENJOY

NEW! FREE RESOURCES? WWMMDPttfCT Ki5. WO (UW.INW INCM!

Paint&Draw
Beginner's Guide to LNiMAML
DRAWING
FEATURES ♦ WORKSHOPS ♦ INTERVI

WHAT YOU
TO KNOW

step try step nmsof

tutorials MUMAnON

COMU

SKETi

Master new EROESt

wurez

skills and create

Learn how to capture an iconic character’s |
ersoqality with DC cover artist Bilquis Evely
(OWPKMWGtti
KM

Portraits • Wildlife • Budding* • Nature • Objects & more!

beautiful items
for your home

Get great savings when 1000s of great titles, many World-wide delivery and
you buy direct from us not available anywhere else super-safe ordering
 NEW! 132 pages of expert advice and mdcpth tutorials
0 W.77MA7T GUII>E TO
Paint Draw
PORTRAITS

MASTER THE ICONIC

JAPANESE ART STYLE

TO TRY Artist
secrets
• wua> acdon- START TODAY! on illustrating
PACCft> AWW
HOMEWARE realistic beads

HOOPS TOYS
VWMMT nuts IN
CUP srv&o PAtNT GIFT IDEAS
FASHION CROSS STITCH
PATTERNS

NEW DRAWING WORKSHOPS Laam to uatCft and Mwn*.' form NEW

> Ul/iicl? Law 4 HOMEWARE

ANATQMY SKETCHING
KNITTING
PROJECTS TO BRIGHTEN UP YOUR HOME ANO WARDROBE
PROJECTS
FOR YOUR OWN HOME
OR AS GREAT GIFTS
essentials > A i
DRAWING
ALL

INCLUDED!

CUSHION
DESIGNS

A STEP-BY-STEP GUIDE TO MODERN EMBROIDERY laixUcatxa. txMUmix wudiSc und otacuts

GET CREATIVE WITH

OUR BOOKAZINES
From crochet and quilting to painting and Photoshop,
pick up a book that will take your hobby to the next level
awt-'we rt?/’ v»ve» -traimimct-
NEW
Imagine < < < ?F Create 100 PAGES OF CREATIVE EXERCISES TO CALM YOUR MIND

TSCHOOLi BLANKETS
EVERYTHING YOU NEED TO CREATE
CRAFTS
_ COSY THROWS FOR YOUR HOME

BtAUTMUl BLAMUH
*O« TM WMOll
k FAMILY TO -
IHK>r

IMPROV!YOUR
PAINTING TODAY (RIGHT & (OLD SWHT DRE AMS

CHOCKTI • KMTTEMG • SAWING • UWVT • PAPfftCRAFT

ml thc stttcks you n«d to cmatt stunning «*okcts

big book of
NEW!
Paint&Draw
Beginner's Guide to
educ.
CROCHET PAINTING .
«JOS of
arf nps STITCHES step-by-step
tutorials
Ln'
FIND INN£R PtMt
THROUGH THe
Take up a <\POh^ OF ART

Learn new art

wwa
BrtbR Froud PAGES
ft or TUTORIAL* t
relaxing
techniques kA" K< xrwy

hobby with
G£? h>MD AMJ CUt AM
arrwR exA«<CTrPi and

gnaw

6h StvtU 6< F«hW

expert advice futurebookazmes

and top tips WHatewcr your pawxwx wt?\*

hwxry «nd science k> b'ettyle
ring* o< excellent bookennes et
rhe confert cohered F urn
Vevf. check out our

Imktf.ee/futuretooUxIne*

Guitar‘
farlvgw.vYa

www.magazinesdirect.com/creative
Magazines, back issues bookazines
 Delivered direct to your door
or straight to your device

TRANSFORM YOUR PHOTOGRA

200 unmissable pro tips in your FREE e-book YD f SEBASTIAN BACH f NAZABETH
KDION TULY0V7H GONE WO GROWS t# P€T£ AC/«£W THL5ML

for enthusiasts and pi

★CLASSIC*
ii turning (i(X
urHingand
-I- Find your ultimate i 'll it* brill a I
Ilf IlIINHt IOOIBAU ■ + PLUS Skincare that valih of TV
WWW. FAMILY SEC RETS
Two women, two tZlZOFFAT
* < sli(M'k resell lions
Zoff at
JEANS FOR k HOUSE Z
EVERY BODY
GUARANTEED

ALONSO
TTie Anfield hero's
I everkusen title bid
&WHIT
O Perfect mono conversion
HEALTH
RETREATS
wu//enjoy!
HOWTO
GOOD Nj
LOVE THE
YOU'RE

VICARIO O Shoot for the edit

EXCLUSIVE
On Ange s Spurs,
©Enhance detail WMI GARDENING EXTRA
Buffon and refugees
Fill your outdoor space without spending a penny
Expert Sarah Raven's must-read tips and tricks
CHAMPIONS FREE 116-page magazine worth £10.99
LEAGUE SHUTTER
The knockout
stoge previewed SPEED
Rethink your exposui^^
for
\T<ZS«NCE+ANIMALS+PUZZLES s-PEOPLE+APPS -? PHOTOS-r BOOKS 4-SP0RT+INCHGNOME
r..~! ,
/THE WORLD’S BEST ™ listen out - Scottish
NEWS & FACTS DOCStyour for oxkoo j leader
resigns
FOR YOUNG PEOPLE
4MXQ4 bsuMJS

£11
I a Cotswold restoration
How tooth ers: our animal heroes
ever star
over Ai Middle-earth

« IAJiqq|G-G3Ujj
|IGL?I OHL 3Uinj5J| JJGLOG2
jq 9 cou/AO|q lgzlol’jxjou

Distant spacecraft sends new signals to scientists on Earth pi

Choose from over 8o magazines and make great savings off the store price!
Binders, books and back issues also available
Simply visit www.magazinesdirect.com

No hidden costs Shipping included in all prices @ We deliver to over 100 countries Q Secure online payment

FUTURE
magazinesdirect •com
Official Magazine Subscription Store
 FROM THE MAKERS OF THE NUMBER ONE LINUX MAGAZINE

ULTIMATE

PROJECTS
Expert guides For
open-source enthusiasts

r-------------------------------------------------------

Ultimate Linux Projects Ultimate I nux Prefect t Escape Goodie Photos

CUSTOMISE The joy of tinkering Free your photos

MINT 20!
Lnux Mint is fantastic, but it s also
Sort out rollbacks so you con customise Lou
mcMjnty and immunity (to problems)
* ».<W with

GOOGLE
Whether at home orn the doud. your photos deserve a new host

flexible, malleable and tweakable

PHOTOS
Jonni Bid well .hows you hov
to tr uly make »t your’ owi i

'hrfaafvm’wwmccMtoMfld
f • eB MMMm < IMlu
'Me
l*
«
eM
e ee>t' l«Mit Brew
Se»W««aeM mw m<m< .Me mA *« — W
Ml urtona wmv ’rwT -rt* MM mM
• OMMNB Mb
W«M
*
—> — •• OIM— • • »— *«■ Me
eMS, »«|H eeyeneM
m— M 4 —mb
OW MM* *
M MRf14 MB Mt «4l
CM M OmmMm «Mk> Mrt «
*
» —•
WaMrWMWBMU
*
MM M MM —••• MM r
11 * * f
* —•
re—e ——■ r» 4«yNe—mum
MtXM»Ml MRW • UM Mm W ms - •
M—fc R * « *
i ;iw<4Mw re M rBe

KEEPING IT SIMPLE

» GET THE MOST FROM YOUR » FREEWARE ALTERNATIVES

LINUX DISTRO TO POPULAR SERVICES

[Budd A Smart Home Office Ultimate Unux Projects Raspberry P» projects

Ultimate Linux Projects

BUILD A SMART A smart home office? PLUG & PLAY Get your kit ready
HOME OFFICE Take a look at some great tools that can make a smart home
smart, and a home off <e. er. office Pi PROJECTS Pt*( ww your USB cjfol
*s
* ftnubetry hprqvct Ime
IV
SO rarrts and » cup nt twi

l Wiseguy Jonni Bidwell has some tips on making Jormi Bidwcl . ,th the hefc ot Torn?. Hardware
\ our Ixxnes and home offices smarter. Dr ma you the best m Raspberry
W^k with the latest FOSS offerings.
B O O K A Z IN E

wwmc $0 CAWS WITH nod r

9021

Flash Fhwless.

0«—MHflrfcB

•M , I Mm
O
w II I
IftalMlMMi W0C4MWWVB t *
>

AM MB Ml mhm m
VMWrt oM V» VMlto B wMrt >
■< mwwo—
ram
—are
* wrt tn association with I—a * ** •» — 4—• ••
M
rB
«MeAM,tr
* V»
•e tafKV M vm tom'sHAPDWARE

» SUPERCHARGE YOUR » HARNESS THE POWER OF

WORKING ENVIRONMENT RASPBERRY PI
9000