Linux expansion, more pictures!

docs/beginners-guide.md

@@ -44,7 +44,7 @@ Instead of AM, FM, etc, we break to them down to 3 categories:
 
 Both stations must use the same protocol, speed and modulation to communicate on a shared frequency.
 
-You can see a good table of Protocols, Speeds and Modulations at [NinoTNC](../modems/ninotnc/#mode-switch) once you've digested the below and feel brave!
+You can see a good table of Protocols, Speeds and Modulations at [NinoTNC](modems/ninotnc.md#mode-switch) once you've digested the below and feel brave!
 
 #### Protocol
 
@@ -96,6 +96,14 @@ Frequency Shift Keying - Multiple tones, not necessarily audible. Commonly found
 
 Phase Shift Keying - Data encoded into changes of phase. Often found on HF links.
 
+### Linux
+
+A key component of the systems I'll be discussing in this guide is Linux. If you don't have a great understanding of Linux or it's a bit scary, I've got an overview of things you might want to know [here](linux.md).
+
+There's a lot to take in, and it can seem overwhelming at first, but feel free to read, ask for help and keep in mind that it's easy to be feel like that when you approach anything new.
+
+A simple starting point is a [Raspberry Pi](https://raspberrypi.org) - it will be a dedicated computer for just packet exploration, and if everything is broken you can easily start again without losing any importnt data.
+
 ## Radio Set Up
 
 Find out your local packet radio frequency first, and tune your radio to see if you can hear any activity. This will be a good indicator as to whether you need to think about HF instead of VHF/UHF.
@@ -156,8 +164,8 @@ Don't worry - there is always something you've forgotten to do, or think you've
 
 Learn more about debugging:
 
-  * [Your Radio](../modems/qtsm/#check-the-radio)
-  * [QtSoundModem](../modems/qtsm/#check-the-audio-coming-in-is-at-the-right-volume)
+  * [Your Radio](modems/qtsm.md#check-the-radio)
+  * [QtSoundModem](modems/qtsm.md#check-the-audio-coming-in-is-at-the-right-volume)
 
 ### Ask for Help!
 
@@ -171,4 +179,3 @@ There are a few great sources of assistance, some will be faster than others to
   * XROUTER help: [XROUTER mailing list](https://groups.io/g/xrouter)
   * NinoTNC: [NinoTNC mailing list](https://groups.io/g/ninotnc/)
   * My Inbox - see the [about page](about.md). I'll be thrilled if you get stuck and sent me an email saying you'd tried this and nothing worked!
-

docs/config/xrouter.md

@@ -0,0 +1,5 @@
+# Configure XROUTER
+
+!!! warning
+
+    More to follow

docs/detail/ax25.md

@@ -0,0 +1,5 @@
+# AX.25
+
+!!! warning
+
+    Details to follow

docs/detail/il2p.md

@@ -0,0 +1,5 @@
+# IL2P
+
+!!! warning
+
+    More to follow

docs/glossary.md

@@ -3,7 +3,22 @@
 | Term | Translation |
 |------|-------------|
 | AX.25 | The underlying packet radio protocol, sometimes used as a generic term |
+| AFSK | Audio Frequency Shift Keying. See [Modulation](beginners-guide.md#modulation) |
 | BBS | Bulletin Board System - an email and message service hosted on a nearby mailbox |
+| BSD | Berkely System Distribution - Linux's inspiration and predecessor, a commercial (now largely open source) family of Unix distributions | 
+| bd | Baud - a unit of data - 1 character, used to explain the speed of a link as bauds per second |
+| CLI | Command Line Interface - a text-first mode of interacting with the computer |
+| FSK | Frequency Shift Keying. See [Modulation](beginners-guide.md#modulation) |
+| IP | Internet Protocol |
+| IL2P | Improved Layer 2 Protocol - a new protocol to replace AX.25 over the air |
+| Kernel | The Linux Kernel is the core component of Linux, common to all distributions and the only atually part technically called Linux. It's the software at the very bottom of the pile, interacting with hardware and making stuff work |
+| KISS | Keep it Simple Stupid - a serial protocol to communicate with modems |
+| Linux | A family of computer operating systems, alternative to Windows |
 | NET/ROM | A routing and discovery layer that makes connecting to nearby and distant stations easier |
 | Node | A computer in the network. It can be a full featured system with applications hosted at home or at a nearby site, or it can be a simplified system that only passes messages on behalf others |
+| Repo | Repository of applications for a Linux Distribution - see [Applications and Repositories](linux.md##applications-and-repositories) |
 | PMS | Personal Message System - a reduced functionality BBS hosted on your home node |
+| PSK | Phase Shift Keying. See [Modulation](beginners-guide.md#modulation) |
+| QPSK | Quadrature Phase Shift Keying. PSK based on 4 different phase states. See [Modulation](beginners-guide.md#modulation) |
+| TCP | Transmission Control Porotocol. A protocol for transmitting data over an IP Link |
+| TNC | Terminal Node Controller - A modem with enhanced functionality. See [TNC](modems/index.md#what-is-a-tnc)

docs/install/xrouter.md

@@ -0,0 +1,5 @@
+# Install XROUTER
+
+!!! warning
+
+    More to follow

docs/linux.md

@@ -51,6 +51,32 @@ Instead of using `apt install x`, it is possible to run a graphical piece of sof
 
 Have a little look through your application launcher to see if there is an app catalogue, application store, package list or similar.
 
+## Filesystem Layout
+
+In a Windows system, the very top of your computer's filesystem is most often the C Drive, represented as C: commonly. Windows also neatly shows other drives as similar folder structures - CD Drives often start at D:, Floppy drives at A:.
+
+In Linux we follow a documented filesystem hierarchy, starting at the root of the drive, commonly labelled as `/`. Everything else on the system is presented as a file or a folder under `/`. This includes CD Roms, Hard drives which present as folders, serial & USB devices which present as files and more.
+
+Paths always start with a `/`, and if it's a folder it will end with a `/` to indicate there is more depth below.
+
+Devices, as they present, are often named by the class of device and a number starting at 0 to indicate which number it is. You'll commonly see references to `eth0`, showing the first ethernet device or `wlan0` showing the first wireless internet adaptor. A second would be `wlan1` etc. 
+
+If I look at my root filesystem, I see the following folders:
+
+```
+❯ ls /
+bin@   dev/  home/  lost+found/  mnt/  proc/  run/   srv/  tmp/  var/
+boot/  etc/  lib@   media/       opt/  root/  sbin@  sys/  usr/
+```
+
+Many folders won't be of interest to you day to day, but some helpful ones to know are:
+
+  * `/dev/` - A folder containing devices, it's likely your modem appears here as `/dev/ttyACM0`
+  * `/etc/` - This folder contains every system configuration file, and you could think of it as similar to the Windows Registry.
+  * `/home/` - The home folder is the equivalent to `C:\Users\` on Windows. `/home/hibby/` is where my files live, just like `C:\Users\Hibby`
+  * `/mnt/` - Often where hard drives appear as a folder. A CD Drive called `D:\` on Windows might appear as `/mnt/cdrom/` here.
+  * `/tmp/` - A handy scratchpad to test and download things to. It gets emptied on every reboot
+
 ## Users, Permissions and 'sudo'
 
 Much like other systems, Linux has the concept of a regular 'user' which you log in as, day to day and an 'administrator' user who is empowered to make configuration changes to the system, install software and so on. In the Linux world, the administrator is known as 'root'. As root has a lot of power - changing users passwords, deleting every file, overriding safe norms to damage hardware potentially - it is generally recommended that you do not log in day to day as root. If a bad actor or malicious piece of software runs while you are root, it can cause all of the aforementioned damage and more!
@@ -61,6 +87,7 @@ In graphical environments this may take the form of a pop up window - more often
 
 Looking at the repo as an example and considering our earlier learning from Applications and Repositories above - it's no wonder that you need to carry out the commands mostly as the root user! 
 To add my repository, you are making a major system configuration change in two manners: 
+
   * Telling it to trust absolutely the software that I distribute
   * Telling the package manager where to download that software from 
 
@@ -80,3 +107,65 @@ hibby cdrom floppy sudo audio dip video plugdev users netdev lpadmin scanner sbu
 You can see in my group list that I can access the cd rom drive, the floppy drive and run things as sudo, amongst other less important groups!
 
 If you do *not* have sudo in this list, you'll need a bit more help than I can give here - time to [ask for help!](beginners-guide.md#ask-for-help). If you're running a Raspberry Pi or Ubuntu, chances are that you'll be able to. Debian is a little more paranoid so we don't grant it by default. 
+
+You'll need to run a command called `usermod` as the root user to grant your regular user a new group - `usermod -aG <groupname> <username>` effectively translates to 'add <username> to <groupname>. Get rid of the brackets and add the user and group you're trying for! See [Permissions and Groups](#Permissions-and-Groups) for an example. 
+
+### Editing text as root
+
+The path of least resistance for many is to use the command line - if you know what file you need to edit, you can do that using a command line text editor. 
+
+##### GUI
+
+The Raspberry Pi ships with Featherpad - this is a lightweight text editor. You can open Featherpad from the application launcher and use the file->open menu to get access to files all round the system:
+
+![Featherpad Open File](static/img/featherpad-open.png)
+
+Take yourself back to `/` with the Path breadcrumb at the top, and to edit the bpq32.conf config file, for example, find `/etc/bpq32.cfg`. 
+
+On saving the file, the system will ask you to enter your password as it's a protected file that only the root user can write to:
+
+![Featherpad Save as Root Dialogue](static/img/featherpad-rootsave.png)
+
+Alternatively you can open your file manager, navigate to `/etc/`, open `bpq32.cfg` and the system will present a similar popup when you try to save:
+
+![PCManFM Select File](static/img/pcmanfm.png)
+
+In all these programs, you can find `/etc/` by pressing the `/` button on the navigation breadcrumb that is relatively top-central, or by Pressing 'Computer' on the left hand side.
+
+#### Command Line
+
+Every Debian system ships with one called `nano` which is relatively approachable. 
+
+You open your file directly, so to edit the BPQ config file, run `sudo nano /etc/bpq32.cfg`. This translates to: `As root user, open nano to edit /etc/bpq32.cfg`
+
+Navigation is with arrow keys (no mouse, sorry!). There are a list of commands at the bottom of the screen - they use ^ as a shortcut to indicate you must press control at the same time as those letters. Similarly, M is an idication of 'meta' key, which will likely be the alt key. This is quite similar to keyboard shortcuts in Microsoft Word (ctrl&s for save, alt-f4 for exit).
+
+Some helpful commands to know:
+
+| Command | Action |
+| ------- | ------ |
+| ctrl & o | Save |
+| ctrl & x | Exit |
+| ctrl & w | Find (helpful for quick navigation) |
+| alt & u | Undo |
+| alt & e | Redo |
+| ctrl & k | Cut Line |
+| ctrl & u | Paste Line |
+
+
+### Permissions and Groups
+
+Files, devices and folders can have read and write permissions tied to both a user and a group, just as in Windows. You can check this in your file manager by right clicking and selecting properties.
+
+In the command line, this can be checked also - to understand who can do what with a NinoTNC, plug it in and run
+
+```
+❯ ls -l /dev/ttyACM0
+crw-rw---- 1 root dialout 204, 64 Apr 11 08:32 /dev/ttyACM0
+```
+
+This can be read as the device is owned by root and accessible by the group `dialout`. This is a common group you'll see regularly for serial devices, and worth being a member of. If a device has dialout as its group, this is telling us unless your user is root or in the dialout group, you cannot use the device. 
+
+To add your user to the dialout group, you may need to run the usermod command as mentioned above. To add my user hibby, it would be `usermod -aG dialout hibby`. As this command needs to be run as the root user, we probably need to run `sudo usermod -aG dialout hibby`. 
+
+For this change to take effect, you will need to log out and log back in again.

docs/modems/ninotnc.md

@@ -98,11 +98,11 @@ Not seeing anything in the monitor? We need to think about two things here: Is t
 
 #### Radio -> Modem Fault
 
-First off, [check the radio](../qtsm/#check-the-radio) and [check the cable](../qtsm/#check-the-cable). Check if the radio is set up for outputting audio through the accessory socket you're using, and it's in the correct mode (1200bd vs 9600bd - check your manual). A good test here is can you *hear* the signal you want to decode? If you can hear it, we need to find out why your modem can't. As the faster modes sound quite close to white noise, this doesn't always hold true, but it's a least a starter. Perhaps combine eyes and ears and watch the S-meter too!
+First off, [check the radio](qtsm.md#check-the-radio) and [check the cable](qtsm.md#check-the-cable). Check if the radio is set up for outputting audio through the accessory socket you're using, and it's in the correct mode (1200bd vs 9600bd - check your manual). A good test here is can you *hear* the signal you want to decode? If you can hear it, we need to find out why your modem can't. As the faster modes sound quite close to white noise, this doesn't always hold true, but it's a least a starter. Perhaps combine eyes and ears and watch the S-meter too!
 
 I often confuse the 9600bd and 1200bd lines on my interface cable - have a look to see if you've done the same. More often than not, this has melted my head during cable construction, or I'm using the cable for my [UHF Radio](../equipment/ft-7900.md) on my [HF Radio](../equipment/ft-891.md).
 
-Next up: is your modem in the right mode? Look online at either the node's website or [UKPRN Website](https://ukpacketradio.network) for hints and clues or [ask questions](../../beginners-guide/#ask-for-help) of your peers - we're here to help.
+Next up: is your modem in the right mode? Look online at either the node's website or [UKPRN Website](https://ukpacketradio.network) for hints and clues or [ask questions](../beginners-guide.md#ask-for-help) of your peers - we're here to help.
 
 Finally - is your radio outputting enough audio? Is it too much audio? Look at the LEDs on your NinoTNC. Here is a guideline of how to read them:
 
@@ -122,6 +122,6 @@ hibby@GB7HIB:~ $ ls /dev | grep ttyACM
 ttyACM0
 ```
 
-We've now identified your modem's device and we know it is appearing on your computer. If it isn't, then start by trying a new USB cable. 
+We've now identified your modem's device and we know it is appearing on your computer. If it isn't, check you are in the 'dialout' group by opening a terminal and running `groups` on the command line. If it doesn't say `dialout` in the output, follow [this advice](linux.md#permissions-and-groups) and log out/in. If the above doesn't work, try a new USB cable. 
 
-An alternative command to look at running before and after disconnect is `sudo dmesg` - this should tell you if the kernel has detected your device disappearing and reappearing.
+An alternative command to look at running before and after disconnect is `sudo dmesg` - this should tell you if Linux has detected your device disappearing and reappearing.

docs/modems/qtsm.md

@@ -9,7 +9,7 @@ It has some compelling features - not only does it natively understand IL2P at a
 
 ### Installation
 
-If you're using Debian, Ubuntu or a Raspberry Pi it will be easiest if you install [hibby's repo](repo.md).
+If you're using Debian, Ubuntu or a Raspberry Pi it will be easiest if you install [hibby's repo](../repo.md).
 
 Once you have done that you can install the prerequisites:
 

mkdocs.yml

@@ -20,9 +20,11 @@ nav:
     - software.md
     - install/bpq.md
     - install/linux.md
+    - install/xrouter.md
   - Node Configuration:
     - config/bpq.md
     - config/linux.md
+    - config/xrouter.md
   - Misc:
     - linux.md
     - repo.md