Raspberry Pi: Measure, Record, Explore

Saturday, 14 May 2016

Turning the activity light on or off on the Raspberry Pi

The following post is a section of the book 'Raspberry Pi: Measure, Record, Explore'.  The entire book can be downloaded in pdf format for free from Leanpub or you can read it online here.
Since this post is a snapshot in time. I recommend that you download a copy of the book which is updated frequently to improve and expand the content.

The main board on the Raspberry Pi has power and activity LEDs to indicate when power has been applied (red) and when the on-board SD card is being accessed (green). These are situated near one end of the GPIO pins as indicated below.
LED Positions
Embarrassingly, I have found that when running multiple Raspberry Pi’s I have forgotten which ones are running which software or operating system (This is what I get for writing books on Nagios, Ghost, ownCloud etc). This is exacerbated by mounting the Pis in an open stack configuration similar to the following (Imagine it as a slightly higher stack).
Stack o' Pi
What to do then when faced with a stack o’ Pi and difficulty in telling which is which?
The good news is that we can log into each and with the help of the excellent post by BrianW on the Raspberry Pi Forums we can force the activity LED to illuminate and hence identify each device.

Cut to the chase and just do it

We need to be root to execute the command (just using sudo in front of the command won’t be enough). Switch to the root user by typing the following
This will switch to the root user and the -i option will acquire the root user’s environment.
The command prompt will indicate that we are now the root user thusly;
Then we can turn the LED on by writing a ‘1’ to the ‘led0’ brightness file with the following command;
If we want to turn it off we write a ‘0’ like so;
And to return it to the state where it indicates activity on the SD card we use mmc0 which is shorthand for multi media card 0 (or the SD card);
Don’t forget to log out of root using exit or ‘Crtl-d’ when you’re finished.

The explanation of how it works

The /sys directory exists as an interface between the kernel-space and the user-space. As such it is an implementation of the system filesystem (sysfs). The /sys/class subdirectory is exported by thee kernel at runtime and presents devices on the system as a ‘class’ in the sense that it abstracts out the detailed implementation that might otherwise be exposed (the example used in the ‘makelinux’ description of classes is that a driver might see a SCSI or ATA disk, but as a class they are all just ‘disks’).
The following is a highly abridged hierarchy of the /sys/class directory where we can see the range of classes and their respective links.
pi@raspberrypi /sys/class $ tree
├── bcm2708_vcio
│   └── vcio -> ../../devices/virtual/bcm2708_vcio/vcio
├── gpio
│   ├── export
│   ├── gpiochip0 -> ../../devices/soc/3f200000.gpio/gpio/gpiochip0
│   └── unexport
├── graphics
│   ├── fb0 -> ../../devices/virtual/graphics/fb0
│   └── fbcon -> ../../devices/virtual/graphics/fbcon
├── i2c-adapter
├── input
│   └── mice -> ../../devices/virtual/input/mice
├── leds
│   ├── led0 -> ../../devices/soc/soc:leds/leds/led0
│   └── led1 -> ../../devices/soc/soc:leds/leds/led1
├── mem
│   ├── full -> ../../devices/virtual/mem/full
│   ├── mem -> ../../devices/virtual/mem/mem
│   ├── null -> ../../devices/virtual/mem/null
│   ├── random -> ../../devices/virtual/mem/random
│   ├── urandom -> ../../devices/virtual/mem/urandom
│   └── zero -> ../../devices/virtual/mem/zero
├── misc
│   ├── autofs -> ../../devices/virtual/misc/autofs
│   ├── cachefiles -> ../../devices/virtual/misc/cachefiles
│   ├── cpu_dma_latency -> ../../devices/virtual/misc/cpu_dma_latency
│   ├── memory_bandwidth -> ../../devices/virtual/misc/memory_bandwidth
│   ├── network_latency -> ../../devices/virtual/misc/network_latency
│   └── network_throughput -> ../../devices/virtual/misc/network_throughput
├── mmc_host
│   └── mmc0 -> ../../devices/platform/mmc-bcm2835.0/mmc_host/mmc0
├── net
│   ├── eth0 -> ../../devices/platform/bcm2708_usb/usb1/1-1/1-1.1:1.0/net/
│   └── lo -> ../../devices/virtual/net/lo
├── power_supply
├── scsi_device
├── scsi_disk
├── scsi_host
├── sound
│   ├── card0 -> ../../devices/virtual/sound/card0
│   └── timer -> ../../devices/virtual/sound/timer
└── vtconsole
    └── vtcon1 -> ../../devices/virtual/vtconsole/vtcon1
The leds class contains directories for ‘led0’ and ‘led1’.
Inside this directory are the trigger file which determines which kernel modules activity will flash the led and the brightness file that will determine the brightness (duh!) of the led.
If we cat the trigger file we can see that there is a range of different things that can be used as the trigger to illuminate the led.
pi@raspberrypi /sys/class/leds/led0 $ cat trigger
none [mmc0] timer oneshot heartbeat backlight gpio cpu0 default-on input
The multimedia card (mmc0) is set as the default.
The led can only have two levels of brightness; ‘on’ or ‘off’. This corresponds to a ‘0’ or a ‘1’ respectively. To illuminate our led all we have to do therefore is to signal the brightness file that it has the value ‘1’ (per the example above).
To revert to control of the brightness we echo the device responsible for controlling the led to the trigger file. In this case for the activity led it is the ‘mmc0’ device.

The post above (and heaps of other stuff) is in the book 'Raspberry Pi: Measure, Record, Explore' that can be downloaded for free (or donate if you really want to :-)).

Monday, 11 April 2016

Scripting in Linux

The following post is a section of the book 'Just Enough Linux'.  The entire book can be downloaded in pdf format for free from Leanpub or you can read it online here.
Since this post is a snapshot in time. I recommend that you download a copy of the book which is updated frequently to improve and expand the content.

A shell script is a file containing a series of commands. The process of scripting is the writing of those commands in the file. The shell can read this file and act on the commands as if they were typed at the keyboard.
Because there are many commands available to use we can realise the real power of computing and the reduction of repetitive tasks by automating processes.
Think of shell scripts as program commands which are chained together and which the system can execute as a scripted event. They make use of functions such as command substitution where we can invoke a command, like date, and use it’s output as part of a file-naming scheme. Scripts are programs in their own right which use programming functions such as loops, variables and if/then/else statements. The beauty of scripting is that we don’t have to learn another programming language to script effectively, we simply use the commands we use at the command line.
To successfully write a script to do something we have to do three things;
  1. Write a script (a file with a ‘.sh’ extension) that uses common commands.
  2. Set the permissions on the file so that it can be executed
  3. Place the file somewhere that the shell can locate it when it’s invoked

Writing our Script

The script itself is just a text file. The only thing fancy about it is that it contains commands and we’re going to make it executable.
We can start with a simple example that demonstrates echoing a simple message to the screen.
Starting in our home directory (/home/pi) we can use the nano editor to create our script by running the following command;
This will open the nano editor and we can type in something like the following;
# Hello World Script

echo "Hello World!"
The first line of the script is important because it provides information to the shell about what program should be used to interpret and run the script. The line starts with a ‘shebang’ (#!) and then the path to the program (in this case /bin/bash).
The second line is a comment that we would place in a script to tell ourselves or others that open the file what is going on. Anything that appears after a # mark (except for on the first line with the ‘shebang’) will be ignored by the script and is entered to make notes for the reader.
The last line is the command we will run. In this case it only one command, but it could also be any number. The command in this case is a very simple echo command to print the words ‘Hello World!’ to the screen.
Once finished we can close and save the file (CTRL-x to close and say ‘y’ to save);
That’s our script written.

Make the script executable

If we list the properties of our file sayhello.sh with ls as follows;
… we will see the details of the file something like this;
-rw-r--r-- 1 pi pi 54 Feb 17 17:18 sayhello.sh
Linux permissions specify what the owning user can do, what a member of the owning group can do and what other users can do with the file. For any given user, we need three bits to specify access permissions: the first to denote read (r) access, the second to denote (w) access and the third to denote execute (x) access.
We also have three levels of ownership: ‘user’, ‘group’ and ‘others’ so we need a triplet (three sets of three) for each, resulting in nine bits.
The following diagram shows how this grouping of permissions can be represented on a Linux system where the user, group and others had full read, write and execute permissions;
Linux permissions as rwx
The permissions of our sayhello.sh file tell us that the user can read and write the file, members of the group and anyone else can read the file. What we need to do is to make it executable using the chmod command
If we check again with ls -l sayhello.sh we should see something similar to this;
-rwxrwxr-x 1 pi pi 54 Feb 17 17:18 sayhello.sh
Here everyone has execute permissions and the ‘pi’ user and the ‘pi’ group have read and write permissions.

Place the script somewhere that the shell can find it

Currently we’re working in the ‘pi’ home directory where we’ve saved our file. This should be the easiest example of making the script accessible and as such we should be able to simply run the command directly from the command line as follows;
The output from the command should look something like this;
Hello World!
The ./ notation in front of the script designates the path to the file being our current directory. We could have also provided the full path as follows;
(Since /home/pi/ is the directory that the file is currently in.)
So that works, but in the perfect world we wouldn’t need to designate a path to the script in order to execute it. We can make that happen by placing the script in one of the directories in the users ‘PATH’.
PATH is an environmental variable that tells the shell which directories to search for executable files. It should not be confused with the term ‘path’ which refers to a file’s or directory’s address in a files system
A user’s PATH consists of a series of colon-separated absolute paths. When we type in a command at the command line that is not distributed with the operating system or which does not include its absolute path and then the shell searches through the directories in PATH, which constitute the our search path, until it finds an executable file with that name.
We can check what the paths available are by echo-ing the PATH variable to the screen like so;
This will then report PATH to the screen something like the following
We can therefore add our script to any of those directories and it will work like a normal command. However, this will make it available to all users on the system and if we want to only make it available to ourselves as the current user we will need to add a new path to PATH.
The good news is that this is simple to do and in Debian Jessie all we need to do is to create a directory in our home directory (if we are logged in as the ‘pi’ user, that would be /home/pi) called bin. We can place any script that we want to be available to the ‘pi’ user in there and they will have access to it. The reason they will have access is that while it doesn’t appear in PATH at the moment, when we add the bin directory to our home directory, there is a script called .profile which gets checked whenever we start our bash shell. If .profile sees that we have a bin directory in our home directory it adds it to our PATH.
So if we add the directory using mkdir as follows;
… we will be set up with a new path in PATH the next time we start our shell.
Let’s not forget that we should move our file into our new directory with mv as follows;
If we open a new terminal and log on as our user (it’s ‘pi’ in the example) we can how go anywhere (cd) in the directory structure and simply run the command;
… and get the response;
Hello World!
That’s the completion of our simple first example. More advanced work with loops, variables and if/then/else statements will have to be an exercise for the reader. Hopefully that’s ‘Just Enough’ to get you started.

The post above (and heaps of other stuff) is in the book 'Just Enough Linux' that can be downloaded for free (or donate if you really want to :-)).

Saturday, 9 April 2016

File Editing in Linux

The following post is a section of the book 'Just Enough Linux'.  The entire book can be downloaded in pdf format for free from Leanpub or you can read it online here.
Since this post is a snapshot in time. I recommend that you download a copy of the book which is updated frequently to improve and expand the content.

Working in Linux is an exercise in understanding the concepts that Linux uses as its foundations such as ‘Everything is a file’ and the use of wildcardspipes and the directory structure.
While working at the command line there will very quickly come the realisation that there is a need to know how to edit a file. Linux being what it is, there are many ways that files can be edited.
An outstanding illustration of this is via the excellent cartoon work of the xkcd comic strip (Buy his stuff, it’s awesome!).
Real Programmers (courtesy xkcd)
For a taste of the possible options available Wikipedia has got our back. Inevitably where there is choice there are preferences and where there are preferences there is bias. Everyone will have a preference towards a particular editor and don’t let a particular bias influence you to go down a particular direction without considering your options. Speaking from personal experience I was encouraged to use ‘vi’ as it represented the preference of the group I was in, but because I was a late starter to the command line I struggled for the longest time to try and become familiar with it. I know I should have tried harder, but I failed. For a while I wandered in the editor wilderness trying desperately to cling to the GUI where I could use ‘gedit’ or ‘geany’ and then one day I was introduced to ‘nano’.
This has become my preference and I am therefore biased towards it. Don’t take my word for it. Try alternatives. I’ll describe ‘nano’ below, but take that as a possible path and realise that whatever editor works for you will be the right one. The trick is simply to find one that works for you.

The nano Editor

The nano editor can be started from the command line using just the command and the /path/name of the file.
If the file requires administrator permissions it can be executed with ‘sudo`.
When it opens it presents us with a working space and part of the file and some common shortcuts for use at the bottom of the console;
nano Interface
It includes some simple syntax highlighting for common file formats;
nano Syntax Highlighting
This can be improved if desired (cue Google).
There is a swag of shortcuts to make editing easier, but the simple ones are as follows;
  • CTRL-x - Exit the editor. If we are in the middle of editing a file we will be asked if we want to save our work
  • CTRL-r - Read a file into our current working file. This enables us to add text from another file while working from within a new file.
  • CTRL-k - Cut text.
  • CTRL-u - Uncut (or Paste) text.
  • CTRL-o - Save file name and continue working.
  • CTRL-t - Check the spelling of our text.
  • CTRL-w - Search the text.
  • CTRL-a - Go to the beginning of the current working line.
  • CTRL-e - Go to the end of the current working line.
  • CTRL-g - Get help with nano.

The post above (and heaps of other stuff) is in the book 'Just Enough Linux' that can be downloaded for free (or donate if you really want to :-)).

Thursday, 7 April 2016

Links in Linux

The following post is a section of the book 'Just Enough Linux'.  The entire book can be downloaded in pdf format for free from Leanpub or you can read it online here.
Since this post is a snapshot in time. I recommend that you download a copy of the book which is updated frequently to improve and expand the content.

A link in a Linux file system provides a mechanism for making a connection between files. While comparisons can be made to shortcuts in Windows, this is not terribly accurate as linking in Linux has a lot more utility.
To get the full benefit from the description of links we should be passingly familiar with the previous discussion on files and inodes. We should recall that a Linux file consists of three parts;
  1. The filename and it’s associated inode number
  2. An inode that describes the attributes of the file
  3. The data associated with the file.
The file name and inode number point to an inode that has all the information about the file and in turn points to the data stored on the hard drive.
Links can be identified when listing files with ls -l by a l that appears as the first character in the listing for th file and by the arrow (->) at the end that illustrates the link. For example by executing the following list command we can see (as only one amongst many files) that the file /etc/vtrgb is a link to the file /etc/alternatives/vtrgb.
Note the leading l and link sign for vtrgb in the output.
drwxr-xr-x  2 root root     4096 Apr 17  2014 vim
lrwxrwxrwx  1 root root       23 Jul 10 07:45 vtrgb -> /etc/alternatives/vtrgb
-rw-r--r--  1 root root     4812 Feb  8  2014 wgetrc
drwxr-xr-x  2 root root     4096 Jul 10 08:04 wildmidi

A soft link can also be referred to as a symbolic link, but is probably more frequently called a ‘symlink’. A symlink has a file name and inode number that points to it’s own inode, but in the inode there is a path that redirects to another inode that in turn points to a data block.
Soft Link
Because inodes are restricted to the partition they are created on, a symbolic link allows redirecting to a path that can cross partitions.
If we edit the linked file, the original file will be edited. If we delete the linked file, the original file will not be deleted. But if we delete the original file without deleting the link, we will be left with an orphaned link.
Soft links can link to directories and files but if the file is moved the link will no longer work.

A hard link is one where more than one file name links to an inode.
Hard Link
This means that two file names are essentially sharing the same inode and data block, however they will behave as independent files. For example if we then delete one of the files the link is broken, but the inode and data block will remain until all the file names that link to the inode are deleted.
Hard links only link to a file (no directories), cannot span partitions and will still link to a file even if it is moved.

Hard links
  • Will only link to a file (no directories)
  • Will not link to a file on a different hard drive / partition
  • Will link to a file even when it is moved
  • Links to an inode and a physical location on the disk
Soft links (or symbolic links or symlinks)
  • Will link to directories or files
  • Will link to a file or directory on a different hard drive / partition
  • Links will remain if the original file is deleted
  • Links will not connect to the file if it is moved
  • Links connect via abstract (hence symbolic) conventions, not physical locations on the disk. They have their own inode

The post above (and heaps of other stuff) is in the book 'Just Enough Linux' that can be downloaded for free (or donate if you really want to :-)).