Installing and Updating - opencardev/crankshaft GitHub Wiki

First installation

1. Download the zip file of the latest version available at the top of the Releases section, under the Code tab
2. Unpack the zip to a temporary location
3. Write the .img file to your MicroSD card, for example with Win32DiskImager (on Windows)
4. Insert the MicroSD card into your Pi

Thats it.

Known Update Issues

If updating between Stretch and Buster releases you may experience the pi hanging at the crankshaft screen try adding the following to the config.txt

[pi4]
# Enable DRM VC4 V3D driver on top of the dispmanx display stack
dtoverlay=vc4-fkms-v3d
max_framebuffers=2
[all]
dtoverlay=vc4-fkms-v3d

Updating your installation

Note: Don't remove the USB stick during the whole flash process until system is up in normal mode again!

Several methods are available:

1. Manually flash the full image, erasing your existing configuration. Not the best solution ...
2. Online update
3. Online update via ssh
4. Upgrade via USB stick, the recommended way to preserve your general system setup

Online update

1. Insert usb flash named CSSTORAGE
2. Click update system when presented it in the GUI, the process will now follow the USB upgrade process

Online update via ssh

1. Enable dev mode
2. SSH into PI
3. Run

crankshaft update check

4. It should say update available

Crankshaft Management Tool v2.4.0 is executing command...

Internet connection available

New csmt available!
New openauto available!
New system image available!

Done.
pi@CRANKSHAFT-NG:~ $

5. Run

crankshaft update csmt

6. Insert usb flash named CSSTORAGE
7. Run

crankshaft update system

8. You should see it downloading the update to the flash media.
9. Run

sudo reboot

10. The pi will reboot and detect the update on the flash media and apply it. This will take a while 20+mins depending on SD card

Upgrade via USB stick

1. Place the downloaded zip on a USB stick (must be FAT32, EXT(2|3|4) or EXFAT formatted and mininum 2GB)
2. Power off your system
3. Plug in your stick
4. Power on
5. During startup the USB stick which is containing your zip (or .img and the .md5) will be detected
6. If flash file is a zip it will be unpacked to the USB stick
7. Now the system is preparing the flash mode and backing up default config files. When finished, it will reboot into flash mode
8. The system starts now to flash the MicroSD card
9. After successfull flash the config.txt and crankshaft_env.sh will be restored to ensure your display is working again if custom settings are needed for your display
10. System is rebooting again in normal mode
11. During first boot some intial setup processes are run, including resizing your MicroSD card (2nd partition)
12. After initial setup your backup is restored from USB stick
13. Now all is done and your system will boot normally with the new software version
14. The USB stick is no longer needed and can be removed

Please note:

The system will flash every version different from the current installed - there is no lock for up or downgrading. But if you switch back to older versions there is no guarantee that all will work fine.

Files backed up during flash:

/boot/config.txt
/boot/crankshaft/crankshaft_env.sh
/boot/crankshaft/custom/
/boot/crankshaft/gpio2kbd.cfg
/boot/crankshaft/startup.py
/boot/crankshaft/startup.sh
/boot/crankshaft/triggerhappy.conf
/boot/crankshaft/brightness
/boot/crankshaft/brightness-night
/boot/crankshaft/volume
/boot/crankshaft/capvolume
/boot/crankshaft/wpa_supplicant.conf
/boot/crankshaft/openauto.ini
/boot/crankshaft/wallpaper.png
/boot/crankshaft/wallpaper-night.png
/boot/crankshaft/wallpaper-devmode.png
/boot/crankshaft/wallpaper-devmode-night.png
/etc/timezone
/etc/X11/xorg.conf.d/99-calibration.conf
/etc/pulse/client.conf
/etc/modules

Flash same version again

If you have any reason to flash the same version again (perhaps a damaged system) you can create a file called FORCE_FLASH on your USB stick alongside the update files. The flash mode will now ignore the version check and flash it.