start work on commandline documentation

4 files changed, 175 insertions, 1 deletions

diff --git a/commandline/Makefile b/commandline/Makefile
index 3a1c918..2e2ea32 100644
--- a/commandline/Makefile
+++ b/commandline/Makefile
@@ -8,6 +8,7 @@ LIBS      = $(USBLIBS)
 
 PREFIX ?= /usr/local
 bin_dir = ${DESTDIR}${PREFIX}/bin
+man_dir = ${DESTDIR}${PREFIX}/man/man1
 
 PROGRAMS = vusb-i2c vusb-i2cdetect vusb-i2cset vusb-i2cget
 
@@ -39,8 +40,12 @@ clean:
 
 install:
 	install -m 4755 $(PROGRAMS) $(bin_dir)
+	install -m 0644 man/vusb-i2cdetect.1 man/vusb-i2cget.1 man/vusb-i2cset.1 \
+	  $(man_dir)
 
 uninstall:
-	rm -rf $(bin_dir)/vusb-i2c $(bin_dir)/vusb-i2cdetect
+	rm -f $(bin_dir)/vusb-i2c $(bin_dir)/vusb-i2cdetect
+	rm -f $(bin_dir)/vusb-i2cget $(bin_dir)/vusb-i2cset
+	rm -f $(man_dir)/vusb-i2cdetect.1 $(man_dir)/vusb-i2cget.1 $(man_dir)vusb-i2cset.1
 
 .PHONY: all strip clean install uninstall
diff --git a/commandline/man/vusb-i2cdetect.1 b/commandline/man/vusb-i2cdetect.1
new file mode 100644
index 0000000..e43b268
--- /dev/null
+++ b/commandline/man/vusb-i2cdetect.1
@@ -0,0 +1,64 @@
+.Dd Jule 28, 2013
+.Dt VUSB-I2CDETECT 1
+.Os
+.
+.
+.Sh NAME
+.
+.Nm vusb-i2cdetect
+.Nd detect I2C devices
+.
+.
+.Sh SYNOPSIS
+.
+.Nm
+.
+.
+.Sh VERSION
+.
+This manual documents
+.Nm
+UNRELEASED
+.
+.
+.Sh DESCRIPTION
+.
+.Nm
+scans a vusb-i2c bus for connected devices and prints a result table to its
+standard output. A
+.Qq --
+entry means no device responded, while a hexadecimal address means there is
+a device acknowledging that address.
+.
+.Pp
+.
+In detail, for each I2C address between 0x00 and 0x7f (even the special ones),
+the following is done:
+
+.Bl -bullet
+.
+.It
+the bus is reset (START condition)
+.
+.It
+an address (with the read byte set) is transmitted
+.
+.It
+the transmission is terminated without reading any data (STOP condition)
+.
+.El
+
+If SDA is pulled low in the ACK cycle of the address transmission, it is
+considered to be a device listening for that address. If
+.Nm
+reports devices on all checked addresses, this may indicate a stuck SDA line,
+either caused by a hardware bug or a malfunctioning I2C device.
+.
+.Sh AUTHOR
+.
+Copyright (C) 2013 by Daniel Friesel
+.Aq derf@finalrewind.org
+.
+.Sh LICENSE
+.
+to be determined (BSD-ish)
diff --git a/commandline/man/vusb-i2cget.1 b/commandline/man/vusb-i2cget.1
new file mode 100644
index 0000000..0210f18
--- /dev/null
+++ b/commandline/man/vusb-i2cget.1
@@ -0,0 +1,44 @@
+.Dd Jule 28, 2013
+.Dt VUSB-I2CGET 1
+.Os
+.
+.
+.Sh NAME
+.
+.Nm vusb-i2cget
+.Nd read byte from an I2C device
+.
+.
+.Sh SYNOPSIS
+.
+.Nm
+.Ar address
+.Ar register
+.
+.
+.Sh VERSION
+.
+This manual documents
+.Nm
+UNRELEASED
+.
+.
+.Sh DESCRIPTION
+.
+.Nm
+reads one byte from an I2C device.
+It first writes
+.Ar register
+to the device, then starts a new read connection and reads one byte.
+This byte is printed to stdout as an unsigned char.
+.
+.
+.Sh AUTHOR
+.
+Copyright (C) 2013 by Daniel Friesel
+.Aq derf@finalrewind.org
+.
+.
+.Sh LICENSE
+.
+to be determined (BSD-ish)
diff --git a/commandline/man/vusb-i2cset.1 b/commandline/man/vusb-i2cset.1
new file mode 100644
index 0000000..7f24941
--- /dev/null
+++ b/commandline/man/vusb-i2cset.1
@@ -0,0 +1,61 @@
+.Dd Jule 28, 2013
+.Dt VUSB-I2CSET 1
+.Os
+.
+.
+.Sh NAME
+.
+.Nm vusb-i2cset
+.Nd send data to an I2C device
+.
+.
+.Sh SYNOPSIS
+.
+.Nm
+.Ar address
+.Ar data ...
+.
+.
+.Sh VERSION
+.
+This manual documents
+.Nm
+UNRELEASED
+.
+.
+.Sh DESCRIPTION
+.
+.Nm
+sends bytes to an I2C device. It transmits a START condition, then the
+.Ar address
+with the R/W bit set to write, and then all specified bytes.
+.
+.
+.Sh EXIT STATUS
+.
+.Bl -tag -width indnet
+.
+.It 0
+.
+after transmitting the
+.Ar address ,
+an ACK was received
+.
+.It 1
+.
+after transmitting the
+.Ar address ,
+a NAK was received
+.
+.El
+.
+.
+.Sh AUTHOR
+.
+Copyright (C) 2013 by Daniel Friesel
+.Aq derf@finalrewind.org
+.
+.
+.Sh LICENSE
+.
+to be determined (BSD-ish)