de.weAut

Class ClientPigpiod

java.lang.Object

de.weAut.ClientPigpiod

public class ClientPigpiod
extends Object

Handling of pigpio library's socket interface.

An object of this class represents one Raspberry Pi's GPIO by being a socket connection to the Pi's pigpiod server. Who has such object may do almost all possible IO with Java — no matter if the JVM + frame4j is on this Pi or another machine including Windows or Linux PCs and servers. For one Pi and its IO only one ClientPigpiod object should be created and used (and the ClientPigpiod object will be associated with this Pi object). The IO methods and most others are threadsafe. Nevertheless, initialising and shutting down / cleaning up the control IO application is usually better done in one thread.
The IO functions of the piogpio daemon on the Raspberry Pi are also threadsafe, there.


© Copyright 2019, 2021 Albrecht Weinert

Version:

60 (15.07.2021)

Author:

Albrecht Weinert

See Also:

Pi1, Pi2, Pi3, ThePi, PiVals

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ClientPigpiod.CmdState Status of a command executed.

Field Summary

Fields

Modifier and Type	Field and Description
ThePi	thePi The Raspberry Pi used for IO.

Constructor Summary

Constructors

Constructor and Description
ClientPigpiod(ThePi thePi, Object app) Construct and connect to a given Pi.

Method Summary

Modifier and Type	Method and Description
int	areOut() Stores all output GPIO as bitmask.
Socket	connect() Connecting.
int	debugCommand(int ret) Debug info on last command execution.
void	disconnect() Disconnecting.
boolean	equals(Object other) Equal with other ClientPigPiod.
int	extCmd(int cmd, int p1, int p2, int p3, byte[] buffC, byte[] buffR) Implementation of the commands with extensions.
int	getInp(int gpio) Read the IO state.
int	getMode(int gpio) Get the mode of one GPIO pin.
int	getPadS(int pad) Get the output strength of a set of GPIO pins.
int	getPWMcycle(int gpio) Get the PWM duty cycle.
int	getPWMhertz(int gpio) Get the PWM frequency.
int	getServoPw(int gpio) Get the servo pulse width.
static int	gpio2bit(int gpio) GPIO number to bank pin number lookup.
void	gpioActionsByMsk(int mask, IntConsumer action) Perform a separate action on every GPIO (0..31) given by mask.
PrimitiveIterator.OfInt	gpiosByMsk(int mask) Iterate over GPIOs (0..31) given by mask.
int	hashCode() Hashcode.
int	initAsDrive(int gpio, int init) Initialise a GPIO pin as output.
int	initAsHiDrive(int gpio, int init) Initialise a GPIO pin as high drive.
int	initAsHiInput(int gpio) Initialise a GPIO pin as input with pull down.
int	initAsInput(int gpio) Initialise a GPIO pin as input.
void	initAsInputs(int[] lesGPIOs) Initialise one or more GPIO pin as input.
int	initAsLoInput(int gpio) Initialise a GPIO pin as input with pull up.
int	initAsOutput(int gpio) Initialise a GPIO pin as output.
int	initAsOutputs(int[] lesGPIOs) Put one or more GPIO pins to output mode.
int	logCommand(int ret) Log of last command execution.
int	logIfBad(int ret) Log of last bad command execution.
static void	main(String[] args) ClientPigpoid application.
static ClientPigpiod	make(PiUtil app) Make a new Pi and connect to it.
static ClientPigpiod	make(String host, int port, int timeout, int type, Object app) Make and connect to a new Pi.
static String	pudTxt(int pud) Names for input's pull resistor settings.
int	releaseOutputs() Release all GPIO pins set as output.
int	releaseOutputsReport(Appendable log) Release all GPIO pins set as output with report.
void	reportPinOp(Appendable out, String op, int[] lesGPIOs) Report an arbitrary operation on a list of GPIOs.
protected int	rErr(int error, int cmd) Recording helper for IO methods for errors.
protected int	rErr(int error, int cmd, int p1, int p2) Recording helper for IO methods.
protected int	rIgn(int cmd, int p2) Recording helper for IO methods.
int	setAsOutputs(boolean report, String grp, int mask) Set all GPIO pins named by mask as outputs with report.
int	setAsOutputs(int mask) Set all GPIO pins named by mask as outputs.
int	setMode(int gpio, int mode) Set the mode of one GPIO pin.
protected PrintWriter	setOut(Object app) Set own PrintWriter out.
int	setOutput(int gpio, boolean level) Set one GPIO as output.
int	setOutput(int gpio, String out) Output to one GPIO pin.
int	setOutSet(int lesOuts, boolean level) Set a list/mask/set of GPIOs as output pins.
int	setPadS(int pad, int mA) Set the output strength of a set of GPIO pins.
int	setPullR(int gpio, int pud) Set the pull resistor for one GPIO.
int	setPullR(ThePi.Port port, int pud) Set the pull resistor for one port and record the setting.
int	setPWMcycle(int gpio, int val) Set the PWM duty cycle.
int	setPWMhertz(int gpio, int hz) Set the PWM frequency.
int	setServoPos(int gpio, int val) Set the servo position.
int	stdCmd(int cmd, int p1, int p2) Implementation of two parameter (standard) commands.
int	stdCmd(int cmd, int p1, int p2, int pNum) Implementation of three parameter (numerical extension) commands.
String	toString() The connection's settings as String.
static boolean	uint32ret(int cmd) Command result type.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

thePi

public final ThePi thePi

The Raspberry Pi used for IO.

This object describes the used Pi type.

It is either Pi3 (default, describing Pi0, Pi3 and Pi4) or Pi1 (with the 26 pin connector only) or the practically unused Pi2 (with two IO connectors).

Constructor Detail

ClientPigpiod

public ClientPigpiod(ThePi thePi,
                     Object app)
              throws IOException

Construct and connect to a given Pi.

Parameters:

thePi - if null a default Pi3 is made and used

app - the application using the ClientPigpiod object to be made

Throws:

IOException - when connecting to the pigpiod server fails

See Also:

{@link #setOut(Object)}

Method Detail

setOut

protected PrintWriter setOut(Object app)

Set own PrintWriter out.

Helper method for constructors / factories.

This method sets this ClientPigpiod objects PrintWriter for reports. If the parameter app is a PrintWriter app will be be used.
Otherwise, if app is of type App, App or PiUtil that objects own (current) PrintWriter out will be taken.
All other cases default to (wrapped) System.out.

connect

public Socket connect()
               throws IOException

Connecting.

A socket connection to the server's socket port is made. The streams will be provided.

An exception occurring during the proceeding will be forwarded. A partly built up connection will be destroyed (by disconnect() in this case.

Hint: After successfully making an ClientPigpiod object it is connected. Hence, this method is normally not needed. The only exception would be re-connect after disconnect(). So far, no use case for this was reported. If this does not change connect() might be removed / made private in future.

Throws:

IOException - if the connecting to host.port fails

make

public static ClientPigpiod make(String host,
                                 int port,
                                 int timeout,
                                 int type,
                                 Object app)
                          throws IOException

Make and connect to a new Pi.

Depending on parameter type this method makes a new Pi object. Then it tries to make a a new ClientPigpiod connected to a real Raspberry Pi according to parameters host, port and timeout.
Finally (and on success, only) the new ClientPigpiod object will get a PrintWriter for reports according to setOut(app).

Returns:

a ClientPipiod with the given Pi = host connected via socket port within timeout

Throws:

IOException - when connecting to the pigpiod server fails

See Also:

Pi3.make(String, int, int, int), Pi1.make(String, int, int)

make

public static ClientPigpiod make(PiUtil app)
                          throws IOException

Make a new Pi and connect to it.

This method does the same as make(host, port, timeout, type, app). The values host, port, timeout and type are got from app's PiUtil genes as default values or by start parameter evaluation.

Parameters:

app - the application as PiUtil object

Returns:

a ClientPipiod with the given Pi = host connected via socket port within timeout

Throws:

IOException - when connecting to the pigpiod server fails

See Also:

Pi3.make(String, int, int, int), Pi1.make(String, int, int)

disconnect

public void disconnect()
                throws IOException

Disconnecting.

The socket connection made by connect() will be closed.

Hint: Another thread blocked on this connection's I/O will get a SocketException.
Hint 2: We do not recommend to disconnect and re-connect in an application.

Throws:

IOException - on closing problems

toString

public String toString()

The connection's settings as String.

Overrides:

toString in class Object

equals

public final boolean equals(Object other)

Equal with other ClientPigPiod.

From the sight of socket communication to a pigpiod daemon two Clients using the same host and socket port are considered equal.
This sight is implemented here and, consistently, in hashCode().

Overrides:

equals in class Object

Returns:

true when other is a ClientPigPiod object with same host and socket

hashCode

public final int hashCode()

Hashcode.

Overrides:

hashCode in class Object

See Also:

equals(Object)

debugCommand

public int debugCommand(int ret)

Debug info on last command execution.

When this method is called immediately after a command method it will log the command on out.
Compared to logCommand(int) debugCommand also logs the socket request and response buffers which is only very seldom of any interest.

Parameters:

ret - the return value of the command method;
e.g. by placing the call as parameter logCommand(commandMethod(...))

Returns:

ret (the return value of the command method)

See Also:

#logIfBad(int)

rErr

protected final int rErr(int error,
                         int cmd,
                         int p1,
                         int p2)

Recording helper for IO methods.

Some of the comfortable IO methods bypass the implementing command stdCmd(int, int, int) when recognising erroneous parameters (e.g.) hence bypassing the socket communication for the thrill of just getting an error value in return (for those cases where stdCmd(int, int, int) does not do pre-checks itself).
As by doing so the parameter recording is bypassed also the methods with such pre-checks must (should) set lastCmd, lastP1, lastP2 in this case in the thread local lastCmdState object.
This method is a helper therefore, as are rErr(int, int) and rIgn(int, int).

rErr

protected final int rErr(int error,
                         int cmd)

Recording helper for IO methods for errors.

See Also:

rErr(int, int, int, int)

rIgn

protected final int rIgn(int cmd,
                         int p2)

Recording helper for IO methods.

Correctly doing nothing (except returning 0 = OK) when operating on a pin/GPIO to be ignored would, of course, also bypass the recording of the last command. As not to spoil log outputs the "ignoring" must do this recording.
This method implements it.

See Also:

rErr(int, int, int, int)

logCommand

public int logCommand(int ret)

Log of last command execution.

When this method is called immediately after a command method with the command's return value it will log the command on out.
Scheme: [int r = ]logCommand(anyIOcommand(p1, p2));

Parameters:

ret - the return value of the command method;
e.g. by placing the call as parameter logCommand(commandMethod(...))

Returns:

ret the return value of the command method to be logged.) It must have been passed as parameter

See Also:

logIfBad(int)

logIfBad

public int logIfBad(int ret)

Log of last bad command execution.

When this method is called immediately after a command method it will log the command on out if and only if the execution failed (with a negative return code). (In that case it will delegate to logCommand(int).)

Parameters:

ret - the return value of the command method;
e.g. by placing the call as parameter logIfBad(commandMethod(...))

Returns:

ret the return value of the IO command method

See Also:

logCommand(int)

stdCmd

public int stdCmd(int cmd,
                  int p1,
                  int p2)

Implementation of two parameter (standard) commands.

This method handles (is the swiss army knife for) all (75) socket interface commands with up to two parameters and no extra extension data on neither command or response. These 75 commands are the majority and the others are very often not needed in control applications. This method is the base for the more comfortable convenient methods (see some mentioned below).

This method does the bookkeeping for logging the actions afterwards. It also checks a lot of command (cmd) and parameter combinations to save the pains of socket communication for just getting an error. stdCmd() does the communication with the pigpiod daemon as well as the bookkeeping threadsafe.

It is not complicated to use stdCmd(3*int) directly – nevertheless this is not recommended when a convenient implementation of the IO operations in question is provided here, as setMode(int, int), getMode(int), setPadS(int, int), getPadS(int), setPullR(int, int), setOutput(int, boolean) etc. pp..

Parameters:

cmd - the command number

p1 - first parameter, mostly GPIO number

p2 - optional second parameter

Returns:

commands return value >= 0; or error number (<0) except for commands returning an unsigned value (see uint32ret(int)

stdCmd

public int stdCmd(int cmd,
                  int p1,
                  int p2,
                  int pNum)

Implementation of three parameter (numerical extension) commands.

This method handles (is the swiss army knife for) all (11) socket interface commands with three parameters (the third sent as fixed 4 byte extension, technically) and a simple response.
All other commands are delegated to stdCmd(cmd, p1, p2) to be rejected or (if one of the 75 command without extensions) be executed there.

Parameters:

cmd - the command number

p1 - first parameter, mostly GPIO number

p2 - second parameter

pNum - the one numerical (extension) parameter

Returns:

commands return value >= 0; or error number (<0) except for commands returning an unsigned value (see uint32ret(int)

See Also:

stdCmd(int, int, int)

extCmd

public int extCmd(int cmd,
                  int p1,
                  int p2,
                  int p3,
                  byte[] buffC,
                  byte[] buffR)

Implementation of the commands with extensions.

This method handles (is the swiss army knife for) all (31) socket interface commands with a byte array as command extension or response or both but not none.
If cmd is one of the 11 with a numerical command extension (fixed length 4) and no extended response use better stdCmd(cmd, p1, p2, intBuffc) directly instead of letting this method delegate.

Some of these 31 extended commands are rarely used in most applications and are (as of 15.07.2021) not implemented yet.

If cmd is one of the 75 non extended command (and for the most trivial errors) this method delegated to stdCmd(int, int, int).

Parameters:

cmd - the command number

p1 - first parameter, mostly GPIO number

p2 - optional second parameter

p3 - the length of the command extension

buffC - the command extension buffer

buffR - the response buffer (might be the same as buffC)

Returns:

commands return value >= 0; is length of response in bytes or error number (<0)

gpiosByMsk

public PrimitiveIterator.OfInt gpiosByMsk(int mask)

Iterate over GPIOs (0..31) given by mask.

Besides being usable by forEachRemaining
IntConsumer action = gpio -> doWhatOn(gpio);
gpiosByMsk(mask).forEachRemaining(action);
one may create such Iterator and use its methods hasNext() and nextInt() directly in a while loop, e.g.
Note: for (type i : typeIiterator)won't work for PrimitiveIterators (at least in Java 8).

Parameters:

mask - a bank 0 bit mask of GPIOs in the range 0..31

Returns:

an Iterator for the primitive type int, its nextInt() method returning the GPIOs in Mask in ascending order

gpioActionsByMsk

public void gpioActionsByMsk(int mask,
                             IntConsumer action)

Perform a separate action on every GPIO (0..31) given by mask.

This method does a forEachRemaining(action) as described in gpiosByMsk(int) plus some checks and synchronising:
When mask is 0 nothing is done. When action is null nothing is done.
Otherwise, in one synchronized (this ClientPigdiod object) block all actions are done.

Parameters:

mask - a bank 0 bit mask of GPIOs in the range 0..31

action - what to do with each GPIO in mask

setMode

public int setMode(int gpio,
                   int mode)

Set the mode of one GPIO pin.

Parameters:

gpio - a legal IO number 0.. 31

mode - a mode like PiGpioDdefs.PI_INPUT, PiGpioDdefs.PI_OUTPUT, PiGpioDdefs.PI_ALT0 etc.

Returns:

0: OK; < 0: error

getMode

public int getMode(int gpio)

Get the mode of one GPIO pin.

Parameters:

gpio - a legal BCM IO number 0.. 56

Returns:

the mode like PiGpioDdefs.PI_INPUT, PiGpioDdefs.PI_OUTPUT, PiGpioDdefs.PI_ALT0 etc. or < 0: error

setPullR

public int setPullR(int gpio,
                    int pud)

Set the pull resistor for one GPIO.

Parameters:

gpio - a legal BCM IO number 0.. 31 or PiVals.PINig

pud - a mode: PiGpioDdefs.PI_PUD_OFF, PiGpioDdefs.PI_PUD_DOWN or PiGpioDdefs.PI_PUD_UP

Returns:

0: OK; < 0: error

setPullR

public int setPullR(ThePi.Port port,
                    int pud)

Set the pull resistor for one port and record the setting.

Parameters:

port - a Pi port; null means ignore

pud - a mode: PiGpioDdefs.PI_PUD_OFF, PiGpioDdefs.PI_PUD_DOWN or PiGpioDdefs.PI_PUD_UP PI_PUD_DT (default) will be replaced by the port's pull resistor flag.

Returns:

0: OK; < 0: error

See Also:

setPullR(int, int)

pudTxt

public static String pudTxt(int pud)

Names for input's pull resistor settings.

Parameters:

pud - a mode: PiGpioDdefs.PI_PUD_OFF, PiGpioDdefs.PI_PUD_DOWN, PiGpioDdefs.PI_PUD_UP, PiVals.PI_PUD_KP, PiVals.PI_PUD_DT

Returns:

"off ", "down", "up ", "keep", "dflt" (0..4) else "err ".

setPadS

public int setPadS(int pad,
                   int mA)

Set the output strength of a set of GPIO pins.

For pins set as output (by setMode(int, int) e.g.) this function sets the drive capacity in the range of 2..16 mA.
Note 1: All pins of the set/pad get the same common value. Hence, one has to set the maximum needed for any pin.
Note 2: This value is no current limit nor pin overload protection. It is the maximum load current, which a valid 0 or 1 output voltage can be guaranteed under.
Note 3: The BCM processor can set the strength in 2mA steps (2, 4.. 14, 16). Nevertheless, this function accepts all values 2..16 incrementing odd values.

Parameters:

pad - The pad or I/O port set number; 0 is GPIO numbers 0..27.
1 would be 28..45 and 2 46..53; To use 1 and 2 is not recommended as GPIO > 31 should not be touched in regard to output.

mA - 2..16, the strength in mA

Returns:

0: OK; < 0: error

See Also:

getPadS(int), PiGpioDdefs.PI_BAD_PAD, PiGpioDdefs.PI_BAD_STRENGTH

getPadS

public int getPadS(int pad)

Get the output strength of a set of GPIO pins.

For pins set as output (by setMode(int, int) e.g.) this function gets the drive capacity in the range of 2..16 mA.

Parameters:

pad - The pad or I/O port set number; 0 is GPIO numbers 0..27

Returns:

2..16 pad strength in mA

See Also:

setPadS(int, int), PiGpioDdefs.PI_BAD_PAD, PiGpioDdefs.PI_BAD_STRENGTH

initAsInputs

public void initAsInputs(int[] lesGPIOs)

Initialise one or more GPIO pin as input.

This functions sets the pins listed as GPIOs to input mode. This is also used to release them from any output modes as input means hi impedance.

Parameters:

lesGPIOs - array of GPIO numbers (0..53); use PiVals.PINix as end marker if the array is too long and PiVals.PINig as an entry to be ignored.

See Also:

initAsOutputs(int[])

initAsOutputs

public int initAsOutputs(int[] lesGPIOs)

Put one or more GPIO pins to output mode.

This functions sets the pins listed by GPIO number in the parameter array to output mode.

Parameters:

lesGPIOs - array of GPIO numbers (0..53); use PiVals.PINix as end marker if the array is too long and PiVals.PINig as an entry to be ignored.

Returns:

the bit mask for all GPIOs set (or left) as output by this call

See Also:

initAsInputs(int[])

reportPinOp

public void reportPinOp(Appendable out,
                        String op,
                        int[] lesGPIOs)

Report an arbitrary operation on a list of GPIOs.

The report lines on out will be progNam operation GPIO: 13 pin: 27.

Parameters:

out - the writer to output to

op - the operation displayed as 12 characters right justified

lesGPIOs - a GPIO list (terminated by a value >= PiVals.PINix)

areOut

public final int areOut()

Stores all output GPIO as bitmask.

For all GPIOs in the range 0..31 set by ClientPigpiod as output *) the corresponding bit is set. For all GPIOs in the range 0..31 set by ClientPigpiod as input the corresponding bit is cleared.
The rationale is an automatic bookkeeping to enable a comfortable "release as input" function (releaseOutputs()) mainly for the end / shutdown of the application.

Note *): To be precise, it is set as "not input" as we want also to release alternate GPIO functions as well as pigpiod's usage as PWM or servo.

initAsOutput

public int initAsOutput(int gpio)

Initialise a GPIO pin as output.

This sets a GPIO as output and puts it in the list of GPIOs used as outputs by the program if in the range of 0..31 (resp. 2..27). For other values nothing is done and 0 is returned.

All functions setting setting as output should use this function.

Parameters:

gpio - the GPIO number (0..31); PINig means no action

Returns:

the bank mask of this output if set (0 no action or error)

releaseOutputs

public int releaseOutputs()

Release all GPIO pins set as output.

This releases all GPIO in the range 0..27 that this program has set as outputs (by setting those as inputs).
The order of this operation is by increasing GPIO number. If another order or extra actions are required this must be done before or afterwards.

Returns:

the bank mask of the previous resp. released outputs

See Also:

releaseOutputsReport(Appendable)

releaseOutputsReport

public int releaseOutputsReport(Appendable log)

Release all GPIO pins set as output with report.

Same as releaseOutputs() plus a "releaseToIn" report line for every output released.

Parameters:

log - a destination to report to; for example a PrintWriter, PrintStream or StringBuilder
if null the standard PrintWriter is used

Returns:

the bank mask of the released (previous) outputs

setAsOutputs

public int setAsOutputs(boolean report,
                        String grp,
                        int mask)

Set all GPIO pins named by mask as outputs with report.

If report is false this method does the same as setAsOutputs(mask) (ignoring the parameter grp.
If report is true an extra "make output" report line for every output set so is printed to out.

Parameters:

report - true: report every every pin/GPIO set as output

grp - a short (best 7 char) description of the pin / signal or device group like "redLEDs", "relaysH" etc.

mask - GPIOs to be set as outputs as bit mask

Returns:

the bank mask of all outputs now set

setAsOutputs

public int setAsOutputs(int mask)

Set all GPIO pins named by mask as outputs.

This method sets all GPIOs (0..31) named by its bit in the mask as outputs.
Rationale: While output commands referring one single GPIO – be it binary, PWM or servo – do (automatically set this GPIO as output the bank / mask commands (PiGpioDdefs.PI_CMD_BS1, PiGpioDdefs.PI_CMD_BC1 respectively setOutSet(int, boolean)) don't. Hence, outputs to be used so, will have to be explicitly set as such. This method offers the comfort (and error avoidance) to use the very same mask parameters as the bulk output commands.

Parameters:

mask - GPIOs to be set as outputs as bit mask

Returns:

the bank mask of all outputs now set

initAsInput

public int initAsInput(int gpio)

Initialise a GPIO pin as input.

This sets a GPIO as input and removes it form the list of GPIOs set as output if in the range of 0..31 (resp. 2..27).

All functions setting as input should use this function.

Parameters:

gpio - the GPIO number (0..53)

initAsLoInput

public int initAsLoInput(int gpio)

Initialise a GPIO pin as input with pull up.

This initialisation is for an input sensing a switch (button) or transistor (optocoupler) connected to ground (gnd, 0V). This is the normal configuration instead of switching to Hi (3.3V).
In most of the cases the Pi's internal pull up resistor (about 50 kOhm) is sufficient for Lo-switches and should then be used.

Parameters:

gpio - the GPIO number (0..53)

Returns:

< 0 : error

initAsHiInput

public int initAsHiInput(int gpio)

Initialise a GPIO pin as input with pull down.

This initialisation is for an input sensing an electronic device delivering a voltage about 3 V when active respectively ON. Some of those devices require a pull down to deliver clean signals.
The Pi's internal pull down resistor (about 50 kOhm) may be sufficient for Hi-switches and should then be used.

Parameters:

gpio - the GPIO number (0..53)

Returns:

< 0 : error

initAsHiDrive

public int initAsHiDrive(int gpio,
                         int init)

Initialise a GPIO pin as high drive.

Of course, Raspberry's (BCM2837's) GPIO pins are high and low drivers as output. Hi-drive is provided by turning on pull-up as to allow broken wire diagnosis when shortly switching to input.

Parameters:

gpio - the GPIO number (0..53)

init - 0 or 1: the initial output value; else: leave unchanged

Returns:

< 0 : error

initAsDrive

public int initAsDrive(int gpio,
                       int init)

Initialise a GPIO pin as output.

This function sets the GPIO pi as output, optionally sets the drive capacity and leaves a pull resistor setting unchanged.

Parameters:

gpio - the GPIO number (0..53)

init - 0 or 1: the initial output value; else: leave unchanged

Returns:

< 0 : error

getInp

public int getInp(int gpio)

Read the IO state.

Parameters:

gpio - a legal BCM IO number (0..56)

Returns:

0 or 1: OK; < 0: error

setOutput

public int setOutput(int gpio,
                     String out)

Output to one GPIO pin.

This is the universal output method, choosing one of the more specialised ones by its String parameter.
Programmatically, one would call specialised ones directly, saving the toils of parsing and choosing. But for interactive purposes (MBean, JMX, JConsole) or command line arguments this method is the Swiss army knife.
Interpretation of the text out:
Binary output false, Off:
null, empty, 0, F, f as well as all interpreted as false by TextHelper.asBoolObj(out)
Binary output true, On:
255, T, t as well as all interpreted as true by TextHelper.asBoolObj(out)
Pulse width modulation PWM 0..255 (i.e. 0..100%):
when out is a decimal value in that range.
Note: 0=0% and 255=100% will be done as binary output.
Servo setting 500 (left) .. 2500 (right): when out is a numerical value in that range.
Note: right = clockwise (from above); 1500 = middle, neutral.

All other values/texts will return an error and do no output.

If gpio is PiVals.PINig nothing is done and 0 is returned. That implements the meaning of PINig as unused.

Parameters:

gpio - a GPIO (0..31) to output to

out - the output level or PWM 7 servo setting

Returns:

< 0: pigpiod error

setOutput

public int setOutput(int gpio,
                     boolean level)

Set one GPIO as output.

This functions sets an output pin gpio ON or OFF.
If gpio is PiVals.PINig nothing is done and 0 is returned. That handles the meaning of PINig as unused.

Parameters:

gpio - a GPIO (0..31) to output to

level - OFF or ON (0 or 1)

Returns:

< 0: pigpiod error

setOutSet

public int setOutSet(int lesOuts,
                     boolean level)

Set a list/mask/set of GPIOs as output pins.

This functions sets the (output) pins set in the bank mask ON or OFF. The method only works for bank 0 (GPIO 0..27) which pigpiod (falsely calls bank1),

Parameters:

lesOuts - bank mask of outputs to be set

level - OFF or ON (0 or 1)

Returns:

< 0: pigpiod error

setPWMcycle

public int setPWMcycle(int gpio,
                       int val)

Set the PWM duty cycle.

Parameters:

gpio - a legal BCM IO number 0..28

val - 0..255 as 0 .. 100% (in default pwm range)

Returns:

0: OK; < 0: error

getPWMcycle

public int getPWMcycle(int gpio)

Get the PWM duty cycle.

Parameters:

gpio - a legal BCM IO number 0.28

Returns:

0..255 as 0 .. 100% or < 0: error

setServoPos

public int setServoPos(int gpio,
                       int val)

Set the servo position.

This is a special PWM command for RC servos.

Parameters:

gpio - a legal BCM IO number 0..28

val - 0 (Off) or 500 (full left) .. 2500 (full right)

Returns:

0: OK; < 0: error

getServoPw

public int getServoPw(int gpio)

Get the servo pulse width.

Parameters:

gpio - a legal BCM IO number 0.28

Returns:

0 Off, or pulse width in µs (1500..2500)

setPWMhertz

public int setPWMhertz(int gpio,
                       int hz)

Set the PWM frequency.

Parameters:

gpio - a legal BCM IO number 0..28

hz - frequency in Hz 5... 40000 depending on duty cycle

Returns:

0: OK; < 0: error

getPWMhertz

public int getPWMhertz(int gpio)

Get the PWM frequency.

Parameters:

gpio - a legal BCM IO number 0..28

Returns:

frequency in Hz 5... 40000 depending on duty cycle or < 0: error

gpio2bit

public static int gpio2bit(int gpio)

GPIO number to bank pin number lookup.

The parameter gpio in the range 0..31 is a GPIO number partly available on the Pi's 40 (26) pins connector.
Returned result is then 0x00000001..0x80000000: a 32 bit number with exactly one bit set corresponding to place in a 32 bit bank mask.
Outside the range 0..31 this method returns 0 (no bit set).

See Also:

ThePi.gpio2pin(int), ThePi.gpio4pin(int)

uint32ret

public static final boolean uint32ret(int cmd)

Command result type.

Most commands return a (signed) int value as result. Then any not negative value means a good return value or without a return value 0 means the the command was executed OK. A negative value means an error; PiGpioDdefs.PI_INIT_FAILED..PiGpioDdefs.PI_BAD_EVENT_ID.

But few commands return an unsigned 32 bit value (uint32_t in C); here Java's (always signed) int negative value interpretation as error would be utterly wrong.
These five commands returning uint32_t are:
BR1 * 10, BR2 * 11, TICK * 16, HWVER * 17, PIGPV * 26.
In Joan N.N.'s documentation they are marked with *; and they can't fail.

Parameters:

cmd - command number (0..117)

Returns:

true: the commands return value is a 32 bit unsigned value

main

public static void main(String[] args)

ClientPigpoid application.

As of July 2021 this application just lists all commands with properties on standard output. This might come handy as a little pigpiod online documentation when having Frame4J installed.
The rationale to make this application was to to check this package's implementation and lookups in ClientPigpiod and PiGpioDdefs against the official socket interface documentation.

Parameters:

args - ignored