Linux: how to run commands by keypress on the local console

This is probably not the only way to do this, and just something I had to dig up to be able to control the piStorm from the console keyboard without being logged in.

After trying to find some built-in way of doing it, I ended up using ‘lirc’ (‘inputlircd’) to fetch the keystrokes and execute appropriate commands in the background. The guide is not intended to be complete, and it’s not even re-tested because of the trial-and-error attempt on getting this working the first time, and not taking any notes.

The most useful resource for the success was:
How to run script on keypress? (superuser.com)

Required steps to getting started with lirc

Become root

sudo su -

Install required packages:

apt -y install lirc inputlirc input-utils socat

Configuration
Find the input device you wish to capture keypresses from:

lsinput

The not really necessary step
Examine the inputlirc start/stop script “/etc/init.d/inputlirc” to see where it looks for configuration:

...
DAEMON="/usr/sbin/inputlircd"
NAME="inputlirc"
DESC="inputlirc"

test -x $DAEMON || exit 0

[ -r /etc/default/$NAME ] && . /etc/default/$NAME
...

The marked lines in the partial content of “/etc/init.d/inputlirc” reveals that a file “/etc/default/inputlirc” is sourced.

Change startup parameters for inputlircd
“/etc/default/inputlirc” contains parameters for running inputlircd, including the input device to capture events from and the parameters to the service looking for keystrokes.

Read the inputlircd manpage (man 8 inputlircd) to find out which parameters you need/want to use. The below is what I had to put in the file:

# Options to be passed to inputlirc.
EVENTS="/dev/input/event0"
OPTIONS=-m 0 -c

-m 0 = -m sets the lowest keycode to pass to the daemon
I also use -c to allow to capture the modifier keys (CTRL, SHIFT, ALT) so they will be part of a keystroke instead of generating their own events. This will make it possible to use combinations like SHIFT + F1 for command execution.

After editing and saving the file, enable and (re)start the inputlirc service:

systemctl enable inputlirc
systemctl restart inputlirc

Then check that it’s running:

systemctl status inputlirc

Snooping for keypress events
Unless you know all the keycodes you are going to use for running commands, now is a good time to check what lircd receives on specific keypresses. Run the command to snoop for keypresses in the shell, and press keys on the keyboard connected to the computer (this could be connected through USB, PS/2, Bluetooth, IR, whatever)

socat UNIX-CONNECT:/var/run/lirc/lircd STDOUT

Sample output (F12 and modifier keys)

root@raspberrypi:~# socat UNIX-CONNECT:/var/run/lirc/lircd STDOUT
58 0 SHIFT_KEY_F12 /dev/input/event0
58 0 CTRL_SHIFT_KEY_F12 /dev/input/event0

The irexec service
To make the irexec service restart when inputlirc is restarted (due to a key configuration change), the service startup file has to be slightly modified:

/lib/systemd/system/irexec.service:

[Unit]
Documentation=man:irexec(1)
Documentation=http://lirc.org/html/configure.html
Documentation=http://lirc.org/html/configure.html#lircrc_format
Description=Handle events from IR remotes decoded by lircd(8)
After=inputlirc.service
Requires=inputlirc.service
...

Add the lines marked above, then rebuild the systemd service configuration file and enable and start the irexec service:

systemctl daemon-reload
systemctl enable irexec
systemctl start irexec

Check that the irexec.service is running:

systemctl status irexec

Configuring what to run on keypresses
The file “/etc/lirc/irexec.lircrc” contains the configuration for what commands to run when selected key(combinations) are used. Wipe out all the defaults in there and add something useful. Below is the updated, more generic configuration I use on my PiOS for the piStorm now, just mapping some keys to a script with a similar name:

begin
    prog   = irexec
    button = SHIFT_KEY_F1
    config = /home/pi/irexec/shift_f1.sh
end

begin
    prog   = irexec
    button = SHIFT_KEY_F2
    config = /home/pi/irexec/shift_f2.sh
end

begin
    prog   = irexec
    button = SHIFT_KEY_F3
    config = /home/pi/irexec/shift_f3.sh
end

begin
    prog   = irexec
    button = SHIFT_KEY_F4
    config = /home/pi/irexec/shift_f4.sh
end

begin
    prog   = irexec
    button = SHIFT_KEY_F5
    config = /home/pi/irexec/shift_f5.sh
end

begin
    prog   = irexec
    button = SHIFT_KEY_F6
    config = /home/pi/irexec/shift_f6.sh
end

begin
    prog   = irexec
    button = SHIFT_KEY_F7
    config = /home/pi/irexec/shift_f7.sh
end

begin
    prog   = irexec
    button = SHIFT_KEY_F8
    config = /home/pi/irexec/shift_f8.sh
end

begin
    prog   = irexec
    button = SHIFT_KEY_F9
    config = /home/pi/irexec/shift_f9.sh
end

begin
    prog   = irexec
    button = SHIFT_KEY_F10
    config = /home/pi/irexec/shift_f10.sh
end

begin
    prog   = irexec
    button = SHIFT_KEY_F11
    config = /home/pi/irexec/shift_f11.sh
end

begin
    prog   = irexec
    button = SHIFT_KEY_F12
    config = /home/pi/irexec/shift_f12.sh
end

begin
    prog   = irexec
    button = CTRL_SHIFT_KEY_F12
    config = /home/pi/irexec/ctrl_shift_f12.sh
end

Whenever you have made a change to /etc/lirc/irexec.lircrc, you need to restart inputlirc (which automatically restarts liexec):

systemctl restart inputlirc

Action scripts in /home/pi/irexec
These scripts can be updated without having to restart inputlirc. Be sure to set the execute flag on them (chmod 755 /home/pi/irexec/*.sh)
For the piOS installation for the piStorm, the content of my configuration-switching scripts are as follows:

/home/pi/irexec/shift_f1.sh (the F-keys 1-10 with the SHIFT key held down):

#!/bin/sh
cp /home/pi/cfg/a1200_4068_os31.cfg /home/pi/default.cfg
sudo systemctl restart pistorm

In a similar way, I have set up the other shift-f-key combinations as shown in the video.

I have used SHIFT+F12 for a safe reboot, and CTRL+SHIFT+F12 for a shutdown of the pi. If running piStorm in RTG mode there can be a delay of about 1 minute before something happens.

/home/pi/irexec/shift_f12.sh:

#!/bin/sh
sudo systemctl stop pistorm
sudo reboot

/home/pi/irexec/ctrl_shift_f12.sh:

#!/bin/sh
sudo systemctl stop pistorm
sudo halt -p

You can check the status of the piStorm service to see that it received the shutdown command:

root@raspberrypi:~# systemctl status pistorm
● pistorm.service - Start piStorm 68k emulator
   Loaded: loaded (/lib/systemd/system/pistorm.service; disabled; vendor preset: enabled)
   Active: deactivating (final-sigterm) since Sat 2021-04-24 23:48:43 BST; 1min 6s ago
  Process: 1023 ExecStart=/home/pi/start-emulator.sh (code=killed, signal=TERM)
 Main PID: 1023 (code=killed, signal=TERM)
    Tasks: 10 (limit: 873)
   CGroup: /system.slice/pistorm.service
           ├─1024 sudo ./emulator --config /home/pi/default.cfg
           └─1025 ./emulator --config /home/pi/default.cfg

Apr 24 13:23:53 raspberrypi start-emulator.sh[1023]: [MUSASHI] Mapped read range 4: 40000000-48000000
Apr 24 13:23:53 raspberrypi start-emulator.sh[1023]: [MUSASHI] Mapped write range 3: 40000000-4800000
Apr 24 13:23:53 raspberrypi start-emulator.sh[1023]: Platform custom range: 00E90000-80010000
Apr 24 13:23:53 raspberrypi start-emulator.sh[1023]: Platform mapped range: 00200000-48000000
Apr 24 13:23:53 raspberrypi start-emulator.sh[1023]: RTG display disabled.
Apr 24 13:23:53 raspberrypi start-emulator.sh[1023]: Pitch: 800 (800 bytes)
Apr 24 13:23:53 raspberrypi start-emulator.sh[1023]: RTG thread running
Apr 24 13:23:53 raspberrypi start-emulator.sh[1023]: error: XDG_RUNTIME_DIR not set in the environmen
Apr 24 23:48:43 raspberrypi systemd[1]: Stopping Start piStorm 68k emulator...
Apr 24 23:48:43 raspberrypi systemd[1]: pistorm.service: Main process exited, code=killed, status=15/
root@raspberrypi:~# 

Revised start-emulator.sh script
Because I want to run the wip-crap version of the emulator at some points, I have added a check for the mentioning of “wip-crap” in the configuration file that is going to be used, then depending on its existance or not, launching the emulator from the correct directory:

#!/bin/sh
if grep -q wip-crap "/home/pi/default.cfg"; then
  echo "wip-crap"
  cd /home/pi/pistorm-bnu/
else
  echo "main"
  cd /home/pi/pistorm/
fi
sudo ./emulator --config /home/pi/default.cfg
exit 0

To enable the wip-crap version, just add a comment in the beginning of the configuration such as:

# using wip-crap functions

piStorm – basic configuration

After going through my Getting Started guide you have the piStorm starting up automatically (if followed the very last step) as a emulated 68020 CPU. If your onboard kickstart allows it, you might also have 128MB Z3 RAM. It will start up and display the “insert a disk” screen/animation depending on which Kickstart you have on the Amiga motherboard.

Configuration file

The default configuration file, named “default.cfg”, is located in the “pistorm” folder. It’s a good idea to keep this file untouched and make changes to a copy of it, then telling the emulator to use it by using the –config parameter.

In my installations, I have put the copy of “default.cfg” in /home/pi (“../” as a relative path from within the pistorm folder), and keep the rest of Amiga-related files (kickstart and hdf) in a folder named “amiga-files” in the ‘pi’ user’s home (/home/pi/amiga-files).

Here are the very initial steps to copy the default configuration to /home/pi, and to set up the amiga-files folder (after logging in as the ‘pi’ user):

cp -p pisotrm/default.cfg .
mkdir amiga-files

Stop the 68k-emulator if it is running (two methods, depending on how/if it is auto starting):
If started from rc.local:

sudo killall emulator

If set up as a service:

sudo systemctl stop pistorm

Now to autostart the 68k-emulator with a specified configuration file, edit rc.local (if it is started from there) and add –config ../default.cfg so the full command reads:

cd /home/pi/pistorm/ && sudo ./emulator --config ../default.cfg&

For the service method (using my instructions), change the file “start-emulator.sh” in /home/pi:

#!/bin/sh
cd /home/pi/pistorm/
sudo ./emulator --config ../default.cfg
exit 0

Start the 68k-emulator again by running the command from the rc.local file above (for non-service autostart), or by using systemctl if you have set it up as a service:

sudo systemctl start pistorm

For further restarts of the 68k-emulator, do as previously described with “killall” or “systemctl” depending on your choice of setup. With “systemctl” there is also the “restart” option:

sudo systemctl restart pistorm

A restart of the 68k-emulator will also reboot the Amiga.

Configuration options

The default.cfg contains some examples and descriptions of many of the options available. You can also read the current distributed configuration file on GitHub:
default.cfg

Documentation for some the piStorm features for the Amiga is located within some subfolders on GitHub:
piscsi (map hdf files as hard drives on the Amiga side)
rtg (RTG using the Picasso96/P96 package)
net (not fully implemented)
a314 (includes shared folder on sd-card, networking and shell-access to the pi)

CPU type

The easiest one, leave this at “68020”. This is the most complete and compatible CPU for the emulator.

Kickstart mapping

To get better performance and enable Z3 RAM and get P96 2.4+ working, a Kickstart version 3.1 (40.68) for Amiga 1200 is highly recommended. To obtain the kickstart file the correct way, purchase the Plus edition of Amiga Forever. If you own an Amiga 1200, you can also use any of the tools available for saving the kickstart to a file.

You can name the file whatever you want, but mine is named (renamed from the Amiga Forever set) “kick-31-a1200-40.68.rom”, and I have the file in “/home/pi/amiga-files”.

Early in the config, there is this line:

# Map 512KB kickstart ROM to default offset.
map type=rom address=0xF80000 size=0x80000 file=kick.rom ovl=0

It makes the emulator look for the file “kick.rom” in the current directory (as cd:ed to /home/pi/pistorm before starting the emulator).

Change this to:

# Map 512KB kickstart ROM to default offset.
map type=rom address=0xF80000 size=0x80000 file=../amiga-files/kick-31-a1200-40.68.rom ovl=0

Then restart the emulator to see that it uses the kickstart file (easy to spot if you have a 2.x or 1.x KS on the motherboard).

Have the installation floppy for AmigaOS 3.1 ready (also available from Amiga Forever). If you boot the installation floppy, you would end up at the Workbench and be able to see that the FastRAM (128MB Z3) has been mapped.

Memory mapping

The default memory section in the config looks like this:

# Map 128MB of Fast RAM at 0x8000000, also known as 32-bit Fast RAM or CPU local Fast RAM.
# Only supported properly on select Kickstarts, such as 3.1+ for Amiga 1200, 3000 and 4000.
#map type=ram address=0x08000000 size=128M id=cpu_slot_ram
# Map 128MB of Z3 Fast. Note that the address here is not actually used, as it gets auto-assigned by Kickstart itself.
# Enabling Z3 fast requires at least Kickstart 2.0.
map type=ram address=0x10000000 size=128M id=z3_autoconf_fast
# Max 8MB of Z2 Fast can be mapped due to addressing space limitations, but for instance 2+4MB can be chained to leave 2MB for something else.
#map type=ram address=0x200000 size=8M id=z2_autoconf_fast
#map type=ram address=0x200000 size=2M id=z2_autoconf_fast
#map type=ram address=0x400000 size=4M id=z2_autoconf_fast

Pretty self-explanatory, but some of the RAM types are not supported on all Kickstarts. There is no speed difference in using “32-bit FastRAM” compared to “Z3 Fast”. The “Z2 FastRAM” is the equivalent of a RAM expansion plugged into the expansion port of Amiga 500 and Amiga 1000, or in a Zorro slot on the Amiga 2000. These expansions could be standalone or a part of a hard drive controller for those systems.

piscsi – hard drive emulation

The next section in the configuration is about piscsi, which allows you to assign up to 7 auto-mounted and auto-bootable virtual hard drives on the Amiga.

# Uncomment this line to enable the PiSCSI interface
#setvar piscsi
# Use setvar piscsi0 through piscsi6 to add up to seven mapped drives to the interface.
#setvar piscsi0 PI0.hdf
#setvar piscsi1 PI1.hdf

My virtual disk is 1GB in size and consists of several partitions (three smaller ones for different versions of AmigaOS, and a larger one for common content) and is named “amiga-1gb.hdf”. The location for my .hdf is as the Kickstart ROM, “/home/pi/amiga-files”.
To enable the pi-scsi.device, just uncomment the line “setvar piscsi”, then put the name of the .hdf as a parameter the “setvar piscsi0” (or 1-6):

# Uncomment this line to enable the PiSCSI interface
setvar piscsi
# Use setvar piscsi0 through piscsi6 to add up to seven mapped drives to the interface.
setvar piscsi0 ../amiga-files/amiga-1gb.hdf

This will make the Amiga recognize the harddrive with the correct DEVICE tooltype of HDToolbox (“DEVICE=scsi.device” should be changed to “DEVICE=pi-scsi.device”). Once set up using HDToolbox (detect/change disk type and create the partitions), it can be used to install AmigaOS on and boot from.

Also take a look at the current documentation at GitHUb:
piscsi

RTG using Picasso96 or P96

See the documentation at GitHub:
rtg (RTG using the Picasso96/P96 package)

You need two files from the GitHub repository transferred over to the Amiga after having installed Picasso96 or the more maintaned release of P96. I use my registered 2.4.6 from Individual Computers
Google search for 'P96+2.4.6'

See my updated instructions in piStorm – AmigaOS 3.1 installation

Keyboard and mouse passthrough

It’s pretty well documented in the default.cfg:

# Forward keyboard events to host system, defaults to off unless toggle key is pressed, toggled off using F12.
# Syntax: keyboard [grab key] [grab|nograb] [autoconnect|noautoconnect]
#   "grab" steals the keyboard from the Pi so Amiga/etc. input is not sent to the Pi
#   (also helps prevent sending any ctrl-alt-del to the Amiga from resetting the Pi)
#
#   "autoconnect" connects the keyboard to the Amiga/etc. on startup
keyboard k nograb noautoconnect
# Select a specific filename for the keyboard event source.
# This is typically /dev/input/event1 or event0, but it may be event3 with for instance a wireless keyboard.
# Use ls /dev/input/event* to check which event files are available and try until you find the one that works.
#kbfile /dev/input/event1
# Forward mouse events to host system, defaults to off unless toggle key is pressed on the Pi.
# Syntax is mouse [device] [toggle key] [autoconnect|noautoconnect]
# (see "keyboard" above for autoconnect description)
mouse /dev/input/mice m noautoconnect

Just enable the kbfile line and set the correct device there if it doesn’t work with the defaults.

Real Time Clock (RTC)

The RTC is enabled in the default configuration and transfers over the time and date on the Pi to the Amiga.

# Map RTC as a register range.
map type=register address=0xDC0000 size=0x30000

To get the correct time on the Pi, it must be connected to the Internet (as set up in my Getting Started guide).
Also, you must ensure the timezone is set correct on the Pi, otherwise your time will be off an hour or two. To set the correct time zone, hse the ‘timedatectl’ command:

List the available time zones:

timedatectl list-timezones

Set the time zone:

sudo timedatectl set-timezone Europe/Stockholm

Switching between multiple configurations

When you have one configuration you’re happy with, you might want to set up alternative configurations for compatibility or experimental reasons.
I wrote this guide on how to capture keypresses on a keyboard connected to the pi on the piStorm. Before setting up the commands to execute (the very last step), make a copy of your /home/pi/default.cfg, as this file is to be overwritten when changing configuration using the defined keypress events (in my example SHIFT in combination with the F-keys, SHIFT+F12 to reboot the pi, CTRL+SHIFT+F12 to shut down the pi).

Getting files over to the Amiga

Not really a configuration thing, but I’ll explain the possible methods to transfer files (as for example archives for installing, or unpacked archives of programs ready to launch the installer from) over to the Amiga.

Since networking is not yet implemented, and a shared folder from the Linux side is not available, files have to be transferred the ‘classic’ way.

The options as I see are:
* (real) floppy disks
* (adf) through either an externally connected GoTek drive, or as a replacement for the internal drive
* (hdf) a pre-prepared hdf (full RDSK image, not a partition) file containing archives of programs to install
* (adf) from a hdf, mounting using any of the available options like GoADF
* physical disk connected to the pi, then exported as a piscsi device on the Amiga (complicated and a bit risky, described in detail in the piscsi documentation at GitHub)

piStorm – experimental stuff wip-crap

Some documentation (at least of changes) can be found in the repo: https://github.com/beeanyew/pistorm/tree/wip-crap/

Get and build piStorm software (wip-crap tree)

mkdir -p /home/pi/bnu
cd /home/pi/bnu
git clone https://github.com/beeanyew/pistorm.git
cd pistorm
git checkout wip-crap
make
cd ..
mv pistorm ../pistorm-bnu

Expected output:

Update CPLD bitstream

Build the program to test access to chip RAM

cd pistorm-bnu
chmod +x ./build_buptest.sh
./build_buptest.sh

For EPM240

chmod +x nprog_240.sh
sudo ./nprog_240.sh

For EPM570

chmod +x nprog.sh
sudo ./nprog.sh

wip-crap-only feature configuration

By the merge of July 11 2021, main is up to date with wip-crap.

piStorm – Getting started

In this guide, I explain how I set up the piStorm, beginning from a fresh board (with just the pins and pi header soldered onto it) until it starts up the Kickstart “insert disk” screen. This is not the only way to do things, and necessarily not the best way, it’s my way 🙂

Pi setup

Use the official Raspberry Pi Imager or a third party tool like BalenaEtcher to write the Lite version of Raspberry Pi OS to a SD-card and start up the pi
Using raspi-config, set wifi-credentials (System Options) and activate SSH (Interface Options).
(everything except the basic installation can be done without network connectivity, but it is easier to do it over SSH than at the terminal)

sudo su -
apt -y update
apt -y upgrade

Updating will take about 10 minutes. Usually a reboot is recommended here, but in this case not necessary, so continue with the section below and install some packages and test the GPIOs.

Install required packages

apt -y install git
apt -y install libsdl2-dev
apt -y install openocd
exit

Testing your Pi’s GPIO pins

Testing your Pi’s GPIO pins. This MUST be run disconnected from the PiStorm, just power up the Pi with USB and do it outside the Amiga entirely.
Info from https://www.raspberrypi.org/forums/viewtopic.php?t=180505

sudo apt -y install pigpio
wget http://abyz.me.uk/rpi/pigpio/code/gpiotest.zip
unzip gpiotest.zip
sudo pigpiod
./gpiotest

Expected output:

Get and build piStorm software

git clone https://github.com/captain-amygdala/pistorm.git
cd pistorm
make

Expected output:

Optional step, get and build wip-crap development version

Only build the emulator for use/test later on – skip the CPLD update for now and do that when the wip-crap build is going to be used.
piStorm – experimental stuff wip-crap

Shut down the pi

This is as far as you get without the piStorm connected, so it’s time to shut down the pi and then stuff it away until you get your piStorm (- shutdown and continue as below if you already have it).
‘pigpiod’ (for testing the GPIOs) above keeps the pi waiting for 90 sec if not killed before shutdown.

sudo killall -9 pigpiod
sudo halt -p

Update CPLD bitstream

Shut down the pi, take a look 20 pixels above :), disconnect power and connect the piStorm adapter to the GPIO

Connect power and let the pi start, check network connectivity or re-setup if necessary.

Build the program to test access to chip RAM

cd pistorm
chmod +x ./build_buptest.sh
./build_buptest.sh

For EPM240

chmod +x nprog_240.sh
./nprog_240.sh

For EPM570

chmod +x nprog.sh
./nprog.sh

Expected output (nprog.sh for EPM240):

Installing the piStorm in the Amiga

Shut down the pi, disconnect everything and separate the adapter from it.
Replace the CPU in the Amiga with the adapter board (the Pi connector should be on the left side). Align both rows of pins with the CPU socket, then, without any pressure on the board, move the adapter up and down (front and back) on the socket to feel the point in which the pins are centered in the socket.
Check that all pins go into the socket an press it down until it bottoms.

Mount the pi on the adapter with the USB port facing towards you, and the HDMI connector on the right side.

Connect the HDMI output and a keyboard.

Starting the emulator

Power on the Amiga, the pi will be powered and boot up (the output from the Amiga will be just a black screen (or any other single-colored screen, I usually get a red one before the emulator starts) until the CPU emulator is started).
Login as ‘pi’ and change directory to ‘pistorm’.

Initial check – can the piStorm read and write to the CHIP RAM ?

sudo ./buptest

Expected output:

In case of any error, check that the piStorm adapter is pressed down firmly in the CPU-socket. It should be pressed down so it bottoms (plastic on the pins touching the socket). Once fixed, re-run buptest. Repeat until zero errors are reported.

Start the emulator

sudo ./emulator

Expected output (untouched default.cfg in pistorm directory). If the kickstart file (kick.rom) for softkicking is not found it defaults to using the KS on the mainboard.

On my test computer (A500 r6) it falls back to the 3.1.4 ROM:

From here on, you can use the Amiga as any other floppy-only Amiga. I will document the features (kickstart switch, RAM, hard drive, RTG) in another post to keep these at readable length.

Autostart the emulator on system boot – the simple method

In /etc/rc.local, add before the “exit 0” line:

cd /home/pi/pistorm/ && sudo ./emulator&

Autostart the emulator on system boot – advanced method

The CPU-emulator will be started a lot earlier if adding it as a systemd service.
Become root (the ugly way):

sudo su -

Create the file “pistorm.service” in /lib/systemd/system:

[Unit]
Description=Start piStorm 68k emulator
After=local-fs.target

[Service]
ExecStart=/home/pi/start-emulator.sh

[Install]
WantedBy=local-fs.target

Create the file “start-emulator.sh” in /home/pi:

#!/bin/sh
cd /home/pi/pistorm/
sudo ./emulator
exit 0

Make “start-emulator.sh” executable:

chmod 755 /home/pi/start-emulator.sh

Reload/regenerate systemd configuration files:

systemctl daemon-reload

Enable the automatic start of the CPU-emulator:

systemctl enable pistorm.service

Now, in case you need to restart the emulator (and Amiga as well), this can be done without having to find the ’emulator’ process:

systemctl restart pistorm

Other similar guides for the piStorm

Lightning Amiga Performance With PiStorm (LinuxJedi)