These instructions were used to build a demo platform for use with the Raspberry Pi3B or later. The same approach should work with any Debian based distribution on other hardware and is useful in the evaluation phase.
-
In my tests I used a PI Rev 3B (4x 1.2GHz ARM Cortex A53 with WiFi and Bluetooth) Starter Kit (though the 3B+ has now been released - slightly faster and with a PoE option) https://thepihut.com/products/raspberry-pi-3b-plus-starter-kit
-
I also used the Official Pi 7inch touch screen display kit with optional stand: https://thepihut.com/collections/raspberry-pi-screens/products/official-raspberry-pi-7-touchscreen-display
-
A 16GB micro SD card for the NOOBS starter image copied on
-
We can power and use the board entirely from the USB cable but a suitable 5V power brick (recommended min 2.4Amp@5V) saves effort, keeps the board powered if you switch laptops or it goes into standby and also ensures there is enough power supply for running the board
-
The assumption is that if using the PI with no display an external touch display monitor such as a Gechic or Lilliput is used for the display complete with a mini HDMI adapter/cable for the display output
-
Wired ethernet connection for the target board on the PI 3B or there is an optional step to connect to a WiFi router with internet access for the installs phase
-
The latest Storyboard release install for which I used 5.2 and ...some patience
Take a latest Raspbian 9.3 Stretch Lite (at time of writing) community base image for the Pi from the link below and burn to an SD Card (recommend 16GB min) as we will use the console image as we will not be needing the bloaty display manager and all the other desktop graphics infrastructure.
We have our own lightweight GUI technology!
Note: for NOOBS a display, USB mouse and keyboard is recommended for the initial install step:
https://www.raspberrypi.org/downloads/noobs/
Once the board has booted with the NOOBS image you will need to select Raspbian Stretch Lite from the menu of different OS install options displayed on the LCD or HDMI monitor and click Install which will take some time to complete….
Reboot and you should now be running Raspbian on the Pi.
I created a backup of the target image once built so you should be able to just clone it onto a 16GB or larger SD Card.
This is how the backup (gzipped) clone of the image initially:
sudo dd if=/dev/sdb bs=1M | gzip > pi_crank_raspbian_stretch_lite_4gb.img.gz
This is how to restore or clone to SD card from Linux to a new SD card in this case on /dev/sdb - NOTE: BE CAREFUL TO SPECIFY THE CORRECT DRIVE !!!
sudo cat pi_crank_raspbian_stretch_lite_4gb.img.gz | gunzip | dd of=/dev/sdb
Many evaluation and homer platforms execute everything as 'root' privilege which is great for demo and ease of use but the reality is that production deployments should *never* do this due to security and robustness. For the purposes of this evaluation, we will configure Storyboard so that it can be executed by a 'standard' user account.
https://wiki.debian.org/Permissions
For simplicity we will use the out of box ‘pi’ user account for all operations, making use of privilege escalation using 'sudo' where necessary for installs and setting permissions.
If you connect the USB cable the image should start-up and we can configure it in headless mode to expose a USB RNDIS (Virtual network device) which may need drivers installing for your OS…
You can now SSH (port 22) into the pi using mDNS using hostname: pi@raspberrypi.local
Note: this ZeroConf approach may not work on all host platforms as it requires an mDNS browsing client such as Bonjour or Avahi. If this is the case then you will need to find out from the router what IP address has been assigned and use that in place of raspberrypi.local.
Username: pi
Password: raspberry
Once you have console access and have logged in we can begin...
Linux raspberrypi 4.9.80+ #1098 Fri Mar 9 18:51:28 GMT 2018 armv6l The programs included with the Debian GNU/Linux system are free software; the exact distribution terms for each program are described in the individual files in /usr/share/doc/*/copyright. Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent permitted by applicable law. Last login: Mon Mar 19 14:48:58 2018 from fe80::6cb2:1234:3d1a:cb55%usb0 SSH is enabled and the default password for the 'pi' user has not been changed. This is a security risk - please login as the 'pi' user and type 'passwd' to set a new password. pi@raspberrypi:~ $
The first thing you are wanting to do is refresh the package lists and update the image (this assumes internet connectivity for your Pi via the wired ethernet connection:
sudo apt-get update sudo apt-get upgrade
If a full desktop distribution is used it will likely be necessary to disable the window manager. Assuming your distribution uses systemd, systemd's default target is graphical.target.
You can check the default with:
systemctl get-default
You can change the default to multi-user.target and console mode with (reboot to take effect):
systemctl set-default multi-user.target
You can change the default back to desktop mode with (reboot to take effect):
systemctl set-default graphical.target
By default, SSH is disabled in the newer Raspbian images as a security measure and we will be using this channel to deploy new files and Storyboard assets to the target board as well as a remote Linux console.
To enable ssh on the target by default on every boot (NB this is a security issue for production devices) create an empty dummy file ‘ssh’ on the boot partition of the SD Card. You can even do this from inside the pi console itself::
sudo nano /boot/ssh sudo reboot now
It is also possible to configure the Pi to connect automatically to a WiFi network on boot allowing a wireless operation between the Pi and the PC.
We will add the necessary WiFi configuration in the wpa_supplicant.conf file:
sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
Add the following entry to the file, assuming WPA/WPA2 authentication updated for your wireless network SSID and access key, save and close (you can add additional network AP entries if needed):
network={
ssid="YOUR NETWORK SSID"
psk="YOUR PASSWORD"
key_mgmt=WPA-PSK
}
Apply the changes to the configuration:
sudo wpa_cli reconfigure
Reboot the Pi and hopefully, your board should have connected to the WiFi AP and received an IP address:
ifconfig wlan0
The following sections detail how to build-up the SD card from a base Debian Stretch distribution and should be similar to what a customer would do from first principles to port onto a different target image.
Once the board is booting we can begin adding the Storyboard dependencies for storyboard.
Not everything required by Storyboard comes ready installed so we are going to have to go and fetch these via the appropriate Debian packages hence the internet access.
Step 1: Update and fetch (give 'pi' user root permissions via 'sudo' with password 'raspberry' on demand)
sudo apt-get install libavformat-dev libavfilter sudo apt-get install libts-dev libts-bin input-utils sudo apt-get install libmtdev-dev mtdev-tools
We also need to transfer our Storyboard runtimes across to the target filesystem in the right place using SCP. For ease of use, I suggest using WinSCP on Windows or FileZilla on Linux hosts.
First, we have to create the folders in the right place on the target filesystem to receive the runtime files and we will put them under /usr/share/crank/ thus requiring ‘root’ privilege to create:
sudo mkdir /usr/share/crank sudo mkdir /usr/share/crank/runtimes sudo mkdir /usr/share/crank/apps
We are going to access these with our SCP client but with our standard user as exposing root access over SSH is never a good idea. To do this we will need to grant (to Debian user) some write access and execute permissions.
sudo chmod -R 777 /usr/share/crank
We are going to need to give ownership of the crank folder and its’ sub-folders to user ‘pi’ so that SCP can be used to manage files more conveniently:
sudo chown -R pi /usr/share/crank/
Now using a SCP client (I used WinSCP) you can login to the target and prepare to transfer the runtime folders across from the Storyboard Runtime Install distribution folders to the target using scp:
linux-raspberry-armle-fbdev-GST01-obj/* -> /usr/share/crank/runtimes linux-raspberry-armle-opengles_2.0-GST01-obj/* -> /usr/share/crank/runtimes
Allow execute permissions which are applied recursively to the sub-folders) to the runtimes. Note: This should probably be done more selectively for a production release and here we are also using the mDNS zero config hostname for the pi rather than IP address for convenience….
sudo chmod -R 755 /usr/share/crank/runtimes
There are a number of standard Storyboard Engine runtimes for various common software and hardware platforms which are included in the Storyboard Suite installer and can be found under the install directory (i.e for Windows and Storyboard release 5.3.x as below):
C:\Program Files\Crank_Software\Storyboard_Engine\5.3.201807051156
Storyboard Engine has a number of shared library dependencies which underpin the plug-ins for Storyboard. Depending on the exact versions of the libraries and Debian packages some or all of the following symbolic links may be necessary to be made on the target.
To fine tune this next step we need to know which shared library links need to be fixed which can be determined firstly by running sbengine with the -i or -vvvv command line option and then checking the console output.
For this distribution, the shared libraries are located under /usr/lib/arm-linux-gnueabihf/
Configuring with Standard Touch screen support (typically resistive touch screens)
sudo apt-get install libts-dev libts-bin sudo ln -s /usr/lib/arm-linux-gnueabihf/libts.so.0.9.0 /usr/lib/arm-linux-gnueabihf/libts-1.0.so.0
Configuring with Multi-touch support (eg with Gechic and Lilliput USB touch screens):
sudo ln -s /usr/lib/arm-linux-gnueabihf/libmtdev.so.1.0.0 /usr/lib/arm-linux-gnueabihf/libmtdev.so
To check what devices are available type:
cat /proc/bus/input/devices
Or alternatively, use the lsinput utility to display touch devices (below from Pi 3B + official 7 inch capacitive touchscreen):pi@raspberrypi:~ $ lsinput
/dev/input/event0 bustype : (null) vendor : 0x0 product : 0x0 version : 0 name : "FT5406 memory based driver" bits ev : EV_SYN EV_KEY EV_ABS
Further details and testing of the capacitive touch device can be achieved using the mtdev-test utility to show press and release events and other data:
sudo mtdev-test /dev/input/event0
The target launcher script that gets invoked by Storyboard export after target SCP deployment needs a little fix-up to align the paths and devices on the target and also will need execute permissions set.
scp storyboard_scp.sh -> /usr/share/crank sudo chmod 755 /usr/share/crank/storyboard_scp.sh
Here is one that is used on the Raspberry Pi 3B image using fbdev based graphics support via the official 7 inch LCD capacitive touchscreen visible as /dev/input/event0:
#!/bin/bash killall sbengine echo "Starting Storyboard from SCP..." echo 0 >> /sys/class/graphics/fbcon/cursor_blink echo -e '\033[9;0]' >> /dev/tty1 echo 0 >> /sys/class/graphics/fb0/blank dmesg -D cat /dev/zero > /dev/fb0 export TSLIB_TSDEVICE=/dev/input/touchscreen0 export TSLIB_CALIBFILE=/run/media/mmcblk0p1/pointercal export ENGINE=/usr/share/crank/runtimes/linux-raspberry-armle-fbdev-GST01-obj export SB_PLUGINS=/usr/share/crank/runtimes/linux-raspberry-armle-fbdev-GST01-obj/plugins export LD_LIBRARY_PATH=/usr/share/crank/runtimes/linux-raspberry-armle-fbdev-GST01-obj/lib $ENGINE/bin/sbengine -v -omtdev,device=/dev/input/event0 -orender_mgr,scale,multisample=0 $1
If using a stand the screen will likely be displaying upside down!!!
The fix is as follows is to rotate the screen by 180 deg
sudo nano /boot/config.txt
Then add the line
lcd_rotate=2
The LCD screen will turn-off by default after a short while - consoleblank is a kernel parameter. In order to be permanently set, it needs to be defined on the kernel command line.
sudo nano /boot/cmdline.txt
Add consoleblank=0 to turn screen blanking off completely, or edit it to set the number of seconds of inactivity before the console # will blank. Note insert after rootwait on the kernel command line which must be a single line of text.
consoleblank=0
If you are using the desktop version of Raspbian Stretch then you will likely find that the screen still blanks after a period. This can be fixed by installing the X Windows screensaver application.
sudo apt-get install xscreensaver
This may take a few minutes.
Once this has been installed, you can find the screensaver application under the Preferences option on the main desktop menu. This provides many options for setting up the screensaver, or disabling it completely under:
Preferences->Screensaver-> Display Modes Tab->Mode: Disable Screen Saver Advanced Tab-> Uncheck Power Managment Enabled and Quick Power-off in Blank Only Mode
When planning to use the hardware accelerated graphics with the GPU on the Broadcom devices it is crucial that the GPU be given enough memory for our graphics operations otherwise OpenGL errors occur and general instability.
By default the Raspbian Stretch is configured for a memory split of 64MB which seems may not to be enough (tested on a 1080p display). This can be adjusted as per below.
Select the legacy non OpenGL drivers for the desktop to prevent conflict and select using the raspi-config manager:
sudo raspi-config
7 Advanced Options-> A3 Memory Split->256 (Note: Recommend 128 on a Pi ZeroW) A7 GL Driver->G3 Legacy
Add symbolic links to the legacy Broadcom hardware acceleration libraries and drivers:
cd /usr/lib/arm-linux-gnueabihf/ sudo ln -s /opt/vc/lib/libbrcmEGL.so libEGL.so sudo ln -s /opt/vc/lib/libbrcmGLESv2.so libGLESv2.so
The following is the OpenGL ES 2.0 version of the scp launcher (save as eg: /usr/share/crank/storyboard_opengles_scp.sh) adjusted for the appropriate runtime:
#!/bin/bash killall sbengine echo "Starting Storyboard from SCP..." echo 0 >> /sys/class/graphics/fbcon/cursor_blink echo -e '\033[9;0]' >> /dev/tty1 echo 0 >> /sys/class/graphics/fb0/blank dmesg -D cat /dev/zero > /dev/fb0 export TSLIB_TSDEVICE=/dev/input/touchscreen0 export TSLIB_CALIBFILE=/run/media/mmcblk0p1/pointercal export ENGINE=/usr/share/crank/runtimes/linux-raspberry-armle-opengles_2.0-GST01-obj export SB_PLUGINS=/usr/share/crank/runtimes/linux-raspberry-armle-opengles_2.0-GST01-obj/plugins export LD_LIBRARY_PATH=/usr/share/crank/runtimes/linux-raspberry-armle-opengles_2.0-GST01-obj/lib $ENGINE/bin/sbengine -vvvv -omtdev,device=/dev/input/event0 -orender_mgr,scale,multisample=0 $1
If creating as an additional file don’t forget to add execute permissions so that it can be run from the Storyboard SCP deploy dialog:
sudo chmod 755 /usr/share/crank/storyboard_opengles_scp.sh
Changing the hostname on your Pi might be useful if you have several Pi’s on your network and you need to be able to address them individually or just rename it for convenience to be the new gadget that you have turned it into e.g: ‘crankenpi’.
This name change will also appear on your console. To see what the current hostname is just type the following at a console prompt:
hostname
The first step is to either open up the terminal on the device or to SSH into the device and open up a remote terminal. Our device is headless and currently running, so we’ll take the remote terminal route and connect to it via SSH.
At the terminal, type the following command to open the hosts file and edit the default ‘127.0.1.1 raspberrypi’ entry to be renamed to what you want e.g: ‘crankenpi’:
sudo nano /etc/hosts
Next type the following command to open the hostname file and rename the hostname to the same what you just changed above e.g: ‘crankenpi’::
sudo nano /etc/hostname
This file only contains your current hostname.
Reboot the board for the change to be made on restart and now you should be able to address the board by its’ new hostname ie:
crankenpi.local