Introduction
This short tutorial will guide you through creating a Mender state script on a Raspberry Pi 3 platform.
When deploying over-the-air software updates, you will benefit from having the capability to customize software releases and installations on your devices with more flexibility and control over your deployments. There are many use cases and we have taken only one use case in this tutorial to demonstrate this capability.
Prerequisites
To follow this tutorial, you will need:
- A Raspberry Pi 3 kit with ideally a 7â display or any HDMI connected display running Raspbian with SSH enabled. You can use any of the methods suggested to install the OS image to your device.
- A deployment environment using a desktop PC with Ubuntu 18.04 and Google Chrome as a web browser and at least 10 GB free disk space and 2 GB RAM available for Mender.
- Mender quickstart guide completed using the latest version of Mender documentation
- Basic fundamentals of state scripts in the latest version of Mender documentation
- Basic knowledge of scripting in Python or any other similar scripting language.
Step 1: Define a use case
There are many use cases to choose from and we have taken the âuser confirmationâ use case to demonstrate state script capability in this tutorial.
For many devices with a display that interacts with an end user, it is desirable to ask the user before applying the update. Mender state scripts enable this use case with a script written to create the dialog box on the UI framework used. The script will simply wait for user input, and Mender will wait with the update process while waiting for the script to finish. Depending on what the user selects, the script can return 0 (proceed) or 21 (retry later). For example, this script can be run in the ArtifactInstall_Enter state as shown below, and the user will be asked before the download begins. Alternatively, the script can also be run in the ArtifactInstall_Leave state, if you want the download to finish first, and the user only to accept installing the update and rebooting.
Step 2: Create a script
For the use case in step one, we create a Python script to display a user confirmation dialog box on the screen:
#!/usr/bin/env python3
import os, pwd
import tkinter, tkinter.messagebox
# draw on default display regardless where run from
os.environ["DISPLAY"] = ":0"
pwstruct = pwd.getpwnam("pi")
os.setgid(pwstruct.pw_uid)
os.setuid(pwstruct.pw_gid)
window = tkinter.Tk()
window.eval('tk::PlaceWindow %s center' % window.winfo_toplevel())
window.withdraw()
if tkinter.messagebox.askyesno('User Confirmation', 'Do you want to update to the latest release
version?', icon='warning') == True:
tkinter.sys.exit(0)
else:
tkinter.sys.exit(21)
window.deiconify()
window.destroy()
window.quit()
Accessing the display is important and whatever language you decide to use, make sure you are able to correctly code it in order to get permission to display the box on the screen.
Step 3: Create a Mender Artifact with a state script
The Artifact can be generated using the mender-artifact tool. You can set the variables first just like any standard shell scripting:
ARTIFACT_NAME="my-state_script-update-1.0"
DEVICE_TYPE="raspberrypi3"
OUTPUT_PATH="~/OUTPUT_PATH"
SHELL_SCRIPTS="do_nothing.sh"
As you can see from the name of the script in SHELL_SCRIPTS for simplicity we have created an Artifact payload that does nothing with the following lines in the file:
#!/bin/sh
#
true
This payload could be any piece of software you need to update. You will include a state script as part of the Artifact when you generate it.
You can combine assigning variables (as shown above) and generating the Artifact as in the following command to generate the state script as part of Mender Artifact:
mender-artifact write module-image -T script -n my-state_script-1.0 -t raspberrypi3 -o ~/Downloads/my-state_script-1.0.mender -f ~/Downloads/do_nothing.sh -s ~/Downloads/ArtifactInstall_Enter_01_User_Confirmation-v2.py
After executing the above command, you should see an Artifact file in your chosen directory that contains the state script.
Step 4: Create a Deployment
Upload the Artifact you created in Step 3 in your Mender GUI, under RELEASES tab.
Create a deployment in the DEPLOYMENTS tab by selecting the Artifact and the device you want to deploy to. Press âNextâ and follow to deploy.
Once you have deployed your software release to your Raspberry Pi board you should see the user confirmation dialog box on your display connected to the board as such:
Once you click âyesâ, it will download the software and install it on your device.
If the deployment is successful, you will see it in the DEPLOYMENTS tab under the âFinishedâ tab.
Conclusion
In this tutorial we went through a step-by-step guide on how to utilize a Mender state script to do a simple software update with a user confirmation dialog box using a Raspberry Pi 3 kit.
For further reading please visit: