From: Ben Harris <bjh21@bjh21.me.uk>
Date: Thu, 29 Nov 2018 23:30:54 +0000 (+0000)
Subject: Some documentation, in the form of a man page.
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~bjharris/git?a=commitdiff_plain;h=d4975e9b6ccfcb17933c2026f9eaac918c7a41a1;p=clunk.git

Some documentation, in the form of a man page.
---

diff --git a/clunk.8 b/clunk.8
new file mode 100644
index 0000000..b2db377
--- /dev/null
+++ b/clunk.8
@@ -0,0 +1,90 @@
+.Dd November 29, 2018
+.Os clunk
+.Dt clunk 8
+.Sh NAME
+.Nm clunk
+.Nd driver for half-minute pulse clocks
+.Sh SYNOPSIS
+.Nm
+.Op Fl f Ar statefile
+.Op Fl s Ar hh : Ns Ar mm : Ns Ar ss
+.Op Fl C Ar gpiochip
+.Op Fl L Ar gpioline
+.Op Fl G Ar gpioname
+.Op Fl Y Ar sysfspath
+.Sh DESCRIPTION
+.Nm
+produces pulses on a GPIO line to drive a clock dial that expects a
+pulse every 30 seconds.
+Normally, it simply emits a pulse every 30 seconds, but it can emit
+them faster to wind the dial forward, or omit them to allow real time
+to catch up.
+While
+.Nm
+is not running, it can write the state of the dial to a file so that
+it can adjust the dial appropriately when it next starts.
+.Ss Options
+.Bl -tag -width Fl
+.It Fl f Ar statefile
+Initialise
+.Nm Ns 's
+idea of the displayed time from
+.Ar statefile
+and write it back to that file every time the clock advances.
+.It Fl s Ar hh : Ns Ar mm : Ns Ar ss
+Inform
+.Nm
+that the dial currently shows a time of
+.Bk -words
+.Ar hh : Ns Ar mm : Ns Ar ss .
+.Ek
+The time can be expressed in the 12- or 24-hour clock.
+.It Fl C Ar gpiochip
+Set which GPIO chip
+.Nm
+should use.
+The
+.Nm gpiodetect
+command can be used to find the names of GPIO chips.
+.It Fl L Ar gpioline
+Select the number of the line on
+.Ar gpiochip
+that
+.Nm
+will use.
+This option requires the use of
+.Fl C .
+.It Fl G Ar gpioname
+Select a GPIO line by name.
+This option can be specified with or without
+.Fl C .
+.It Fl Y Ar sysfspath
+Selects the use of the
+.Xr sysfs 5
+GPIO interface.
+The argument
+.Ar sysfspath
+is the path to the
+.Pa value
+file of the required GPIO line.
+.Nm
+does not attempt to initialise the GPIO line, so this must be done
+separately.
+.El
+.Pp
+.Fl Y
+cannot be used with
+.Fl C
+.Fl L ,
+or
+.Fl G .
+.Sh EXAMPLES
+Use GPIO line 17 on a Raspberry Pi, saving state to
+.Pa /var/lib/clunk.state .
+The clock shows ten to two:
+.Pp
+.Dl clunk -C pinctrl-bcm2835 -L 17 -f /var/lib/clunk.state -s 1:50:00
+.Sh AUTHORS
+.Nm
+was written by
+.An Ben Harris Aq bjh21@bjh21.me.uk .