One of the useful tools I've written is a startup script called "blink.sh". Basically, this script blinks CHIP's on-board LED, and also monitors a button to initiate a graceful shutdown. (It does a bit more too.) I realized that this script demonstrates several techniques that CHIP beginners might like to see.
The "blink.sh" script can be found here: https://github.com/fordsfords/blink/blob/gh-pages/blink.sh. For instructions on how to install and use blink, see https://github.com/fordsfords/blink/tree/gh-pages.
The code fragments included below are largely extracted from the blink.sh script, with some simplifications.
NOTE: many of the commands shown below require root privilege to work. It is assumed that the "blink.sh" script is run as root.
1. Systemd service, which automatically starts at boot, and can be manually started and stopped via simple commands.
I'm not an expert in all things Linux, but I've been told that in Debian-derived Linuxes, "systemd" is how all the cool kids implement services and startup scripts. No more "rc.local", no run levels, etc.
Fortunately, systemd services are easy to implement. The program itself doesn't need to do anything special, although you might want to implement a kill signal handler to cleanup when the service is stopped.
You do need a definition file which specifies the command line and dependencies. It is stored in the /etc/systemd/system directory, named "<sevrice_name>.service". For example, here's blink's definition file:
$ cat /etc/systemd/system/blink.service
# blink.service -- version 24-Jul-2016
# See https://github.com/fordsfords/blink/tree/gh-pages
[Unit]
Description=start blink after boot
After=default.target
[Service]
Type=simple
ExecStart=/usr/local/bin/blink.sh
[Install]
WantedBy=default.target
When that file is created, you can tell the system to read it with:
sudo systemctl enable /etc/systemd/system/blink.service
Now you can start the service manually with:
sudo service blink start
You can manually stop it with:
sudo service blink stop
Given the way it is defined, it will automatically start at system boot.
2. Shell script which catches kill signals to clean itself up, including the signal that is generated when the service is stopped manually.
The blink script wants to do some cleanup when it is stopped (unexport GPIOs).
trap "blink_stop" 1 2 3 15
where "blink_stop" is a Bash function:
blink_stop()
{
blink_cleanup
echo "blink: stopped" `date` >>/var/log/blink.log
exit
}
This code snippet works if the script is used interactively and stopped with control-C, and also works if the "kill" command is used (but not "kill -9"), and also works when the "service blink stop" command is used.
3. Shell script with simple configuration mechanism.
This technique uses the following code in the main script:
export MON_RESET=
export MON_GPIO=
export MON_GPIO_VALUE=0 # if MON_GPIO supplied, default to active-0.
export MON_BATTERY=
export BLINK_STATUS=
export BLINK_GPIO=
export DEBUG=
if [ -f /usr/local/etc/blink.cfg ]; then :
source /usr/local/etc/blink.cfg
else :
MON_RESET=1
BLINK_STATUS=1
fi
The initial export commands define environment variables with default values. The use of the "source" command causes the /usr/local/etc/blink.cfg to be read by the shell, allowing that file to define shell variables. In other words, the config file is just another shell script that gets included by blink. What does that file contain? Here are its installed defaults:
MON_RESET=1 # Monitor reset button for short press.
#MON_GPIO=XIO_P7 # Which GPIO to monitor.
#MON_GPIO_VALUE=0 # Indicates which value read from MON_GPIO initiates shutdown.
MON_BATTERY=10 # When battery percentage is below this, shut down.
BLINK_STATUS=1 # Blink CHIP's status LED.
#BLINK_GPIO=XIO_P6 # Blink a GPIO.
4. Shell script that controls CHIP's status LED.
Here's how to turn off CHIP's status LED:
i2cset -f -y 0 0x34 0x93 0
Turn it back on:
i2cset -f -y 0 0x34 0x93 1
sudo apt-get install i2c-tools
5. Shell script that controls an external LED connected to a GPIO.
The blink program makes use of the "gpio_sh" package. Without that package, most programmers refer to gpio port numbers explicitly. For example, on CHIP the "CSID0" port is assigned the port number 132. However, this is dangerous because GPIO port numbers can change with new versions of CHIP OS. In fact, the XIO port numbers DID change between version 4.3 and 4.4, and they may well change again with the next version.
The "gpio_sh" package allows a script to reference GPIO ports symbolically. So instead of using "132", your script can use "CSID0". Or, if using an XIO port, use "XIO_P0", which should work for any version of CHIP OS.
Here's how to set up "XIO_P6" as an output and control whatever is connected to it (perhaps an LED):
BLINK_GPIO="XIO_P6"
gpio_export $BLINK_GPIO; ST=$?
if [ $ST -ne 0 ]; then :
echo "blink: cannot export $BLINK_GPIO"
fi
gpio_direction $BLINK_GPIO out
gpio_output $BLINK_GPIO 1 # turn LED on
gpio_output $BLINK_GPIO 0 # turn LED off
gpio_unexport $MON_GPIO # done with GPIO, clean it up
6. Shell script that monitors CHIP's reset button for a "short press" and reacts to it.
The small reset button on CHIP is monitored by the AXP209 power controller. It uses internal hardware timers to determine how long the button is pressed, and can perform different tasks. When CHIP is turned on, the AXP differentiates between a "short" press (typically a second or less) v.s. a long press (typically more than 8 seconds). A "long" press triggers a "force off" function, which abruptly cuts power to the rest of CHIP. A "short" press simply turns on a bit in a status register, which can be monitored from software.
REG4AH=`i2cget -f -y 0 0x34 0x4a` # Read AXP209 register 4AH
BUTTON=$((REG4AH & 0x02)) # mask off the short press bit
if [ $BUTTON -eq 2 ]; then :
echo "Button pressed!"
fi
Note that I have not figured out how to turn off that bit. The "blink.sh" program does not need to turn it off since it responds to it by shutting CHIP down gracefully. But if you want to use it for some other function, you'll have to figure out how to clear it.
7. Shell script that monitors a GPIO line, presumably a button but could be something else, and reacts to it.
MON_GPIO="XIO_P7"
gpio_export $MON_GPIO; ST=$?
if [ $ST -ne 0 ]; then :
echo "blink: cannot export $MON_GPIO"
fi
gpio_direction $MON_GPIO in
gpio_input $MON_GPIO; VAL=$?
if [ $VAL -eq 0 ]; then :
echo "GPIO input is grounded (0)"
fi
gpio_unexport $MON_GPIO # done with GPIO, clean it up
8. Shell script that monitors the battery charge level, and if it drops below a configured threshold, reacts to it.
This is a bit more subtle that it may seem at first. Checking the percent charge of the battery is easy:
REGB9H=`i2cget -f -y 0 0x34 0xb9` # Read AXP209 register B9H
PERC_CHG=$(($REGB9H)) # convert to decimal
But what if no battery is connected? It reads 0. How do you differentiate that from having a battery which is discharged? I don't know of a way to tell the difference. Another issue is what if a battery is connected and has low charge, but it doesn't matter because CHIP is connected to a power supply and is therefore not at risk of losing power? Basically, "blink.sh" only wants to shut down on low battery charge if the battery is actively being used to power CHIP. So in addition to reading the charge percentage (above), it also checks the battery discharge current:
BAT_IDISCHG_MSB=$(i2cget -y -f 0 0x34 0x7C)
BAT_IDISCHG_LSB=$(i2cget -y -f 0 0x34 0x7D)
BAT_DISCHG_MA=$(( ( ($BAT_IDISCHG_MSB << 5) | ($BAT_IDISCHG_LSB & 0x1F) ) / 2 ))
CHIP draws over 100 mA from the battery, so I check it against 50 mA. If it is lower than that, then either there is no battery or the battery is not running CHIP:
BAT_IDISCHG_MSB=$(i2cget -y -f 0 0x34 0x7C)
BAT_IDISCHG_LSB=$(i2cget -y -f 0 0x34 0x7D)
BAT_DISCHG_MA=$(( ( ($BAT_IDISCHG_MSB << 5) | ($BAT_IDISCHG_LSB & 0x1F) ) / 2 ))
if [ $BAT_DISCHG_MA -gt 50 ]; then :
REGB9H=`i2cget -f -y 0 0x34 0xb9` # Read AXP209 register B9H
PERC_CHG=$(($REGB9H)) # convert to decimal
if [ $PERC_CHG -lt 10 ]; then :
echo "Battery charge level is below 10%"
fi
fi
