.\"                                      Hey, EMACS: -*- nroff -*-
.\" (C) Copyright 2016-2018 Kunbus GmbH
.\"
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH piTest 1 "May 7 2018"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
piTest \- interact with in-kernel piControl process
.SH SYNOPSIS
.B piTest
.RI [ options ]
.SH DESCRIPTION
.B piTest
allows listing the I/O and gateway modules attached to a RevPi Core or
Connect, reading and writing values in the process image and resetting the
in-kernel piControl process.  Revolution Pi is a set of IoT products
based on the Raspberry Pi and geared towards industrial usage.
.SH OPTIONS
.TP
Multiple of these options may be given to execute a sequence of actions:
.TP
.B \-d
Get device list.
.TP
.B \-v \fIvariablename\fP
Shows infos for a variable.
.TP
.B \-1
Executes the following read command only once.
.TP
.B \-q
Executes the following read command quietly, print the value only.
.TP
.B \-r \fIvariablename[,f]\fP
Reads the value of a variable. It respects the length of variable as defined in PiCtory.
.br
The optional parameter <f> defines the format: h for hex, d for decimal (default) and b for binary.
.br
The value is displayed cyclically every second until Ctrl-C is pressed.
.br
E.g. \fI-r Input_001,h\fP reads the value of variable \fIInput_001\fP and displays it in hex format.
.TP
.B \-r \fIo,l[,f]\fP
Reads \fIl\fP bytes at offset \fIo\fP. The optional parameter \fIf\fP defines the format: 
h for hex, d for decimal (default) and b for binary.
.br
The value is displayed cyclically every second until Ctrl-C is pressed.
.br
E.g. \fI-r 1188,16\fP reads 16 bytes at offset 1188.
.TP
.B \-w \fIvariablename,v\fP
Writes value \fIv\fP to the variable. It respects the length of variable as defined in PiCtory.
.br
E.g. \fI-w Output_001,23\fP writes value 23 dec (= 17 hex) to variable \fIOutput_001\fP.
.TP
.B \-w \fIo,l,v\f
Writes \fIl\fP bytes with value \fIv\fP (as dec) to offset \fIo\fP.  Length should
be one of 1|2|4.  E.g. \fI-w 0,4,31224205\fP writes value 31224205 to the byte with offset 0 to 3.
.TP
.B \-g \fIo,b\fP
Gets bit \fIb\fP (0-7) from byte at offset \fIo\fP.  E.g. \fI-b 0,5\fP
gets bit 5 from the byte at offset 0.
.br
The value is displayed cyclically every second until Ctrl-C is pressed.
.TP
.B \-s \fIo,b,0/1\fP
Sets bit \fIb\fP (0-7) of byte at offset \fIo\fP to 0/1.  E.g. \fI-b 0,5,1\fP
sets bit 5 of the byte at offset 0 to 1.
.TP
.B \-R \fIa,b\fP
Sets counter and encoder values to 0. \fIa\fP is the address of a DIO or DI 
module as displayed in  the device list (option -d). \fIb\fP is a bitfield 
defining the counters/endcoders to reset.
.br
E.g. \fI-R 32,0x14\fP resets the counters on the inputs I2 and I5 because the bits 2 and 5 are set to 1.
The DIO must be the first module on the right of the RevPi.
.TP
.B \-f
Starts the firmware update process.
.TP
.B \-l
Listen for events such as a piControl reset initiated by another process.
.TP
.B \-S
Stop cyclic synchronization of the process image with attached I/O and
gateway modules. It is then possible to manually set values in the process
image using the \fI-w\fP option and thereby simulate that these values were
received from the attached modules. To restart synchronization with attached
modules, invoke the program with \fI-S\fP once more.
.TP
.B \-x
Reset control process.
.TP
.B \-h
Show summary of options.
.SH SEE ALSO
The source code of this program is available at
.IR https://github.com/RevolutionPi/piControl
.br
For more information on Revolution Pi visit
.IR https://revolutionpi.kunbus.com