PiUtil ( Frame4J -- the Java framework de.frame4j... )

All Superinterfaces:

ComVar, PiVals

All Known Implementing Classes:

BlinkOnPi, JustNotFLock, Pi1WireThDemo, PiWDogDemo, RdGnPiGpioDBlink, TestOnPi
```
public interface PiUtil
extends PiVals
```
Constants and methods for the Raspberry Pi and its I/O.

All methods define here are implemented. Insofar this interface isn't abstract (featuring a kind of multiple inheritance).
An application wanting to use ThePi, ClientPigpiod etc. must implement (inherit from) this interface PiUtil.

Copyright © 2019, 2021 Albrecht Weinert

Version:

56 (28.06.2021)

Author:

Albrecht Weinert

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class PiUtil.Impl
Internal implementation class.

static class PiUtil.LeTick
A tick as mutable object.

Nested Classes
Modifier and Type	Interface and Description
`static class`	`PiUtil.Impl` Internal implementation class.
`static class`	`PiUtil.LeTick` A tick as mutable object.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`ERR_ASSIGN_PIN` Pin assignment error.
`static int`	`ERR_CLOSE_WDOG` Can't close the watchdog.
`static int`	`ERR_NoGPIOLOCK` Program has no GPIO lock.
`static int`	`ERR_NoLOCKFILE` Lock file does not exist.
`static int`	`ERR_NoLOCKPROC` Lock process can not be started.
`static int`	`ERR_NOT_LOCKED` Lock file could not be locked.
`static int`	`ERR_OPEN_W_DOG` Can't open watchdog.
`static int`	`ERR_PIGPIOD_CON` Socket connecting error.
`static String`	`lckPiGpioPth` Common path to a lock file for Gpio use.
`static String`	`lckWinGpioPth` Common path to a lock file for use on Windows.

Fields inherited from interface de.weAut.PiVals
GPIO_INP, GPIO_OUT, GPIOmax, GPIOmin, GPIOutM, H1, HI, L0, LO, PI_PUD_DOWN, PI_PUD_DT, PI_PUD_KP, PI_PUD_OFF, PI_PUD_UP, PIN0, PIN00, PIN01, PIN02, PIN04, PIN06, PIN09, PIN0V, PIN1, PIN14, PIN17, PIN2, PIN20, PIN25, PIN3V, PIN4, PIN5V, PIN6, PIN9, PINig, PINix, PIO_ALT0, PIO_ALT1, PIO_ALT2, PIO_ALT3, PIO_ALT4, PIO_ALT5

Fields inherited from interface de.frame4j.util.ComVar
AUTHOR, BLANK_STRING, cons, CONSOL_ENCODING, COPYRIGHT, D, D_NaN, D_NegInf, D_PosInf, EMPTY_INT_A, EMPTY_STRING, FILE_ENCODING, FRW_CLLD, FS, FSS, H, hasCons, HOST_IP, HOST_IPv4, HOST_NAME, INIT_ERROR, JAR_ENCODING, JH, JOB_DONE_OK, JRL, LOG_OUT_ERROR, M, MAIN_THREAD_EXC, NO_BYTES, NO_CLASSES, NO_DOUBLES, NO_OBJECTS, NO_PARS_ERROR, NO_STRINGS, NOT_WINDOWS, ON_PI, ONE_DAY, ONE_HOUR, ONE_LEAP_YEAR, ONE_MINUTE, ONE_SECOND, ONE_WEEK, ONE_YEAR, OS, PROG_NAME, PROG_SHORT, PS, RUNTIME, S, SHY, UD, UL, UL_UR_da, UR

Method Summary

All Methods Static Methods Instance Methods Default Methods
Modifier and Type	Method and Description
`default String`	`argHost()` Start argument getter.
`default int`	`argPiType()` Start argument getter.
`default int`	`argPort()` Start argument getter.
`default int`	`argTimeout()` Start argument getter.
`default void`	`closeLock()` Unlock the lock file.
`default int`	`closeWatchdog()` Close the watchdog.
`static Appendable`	`eightDigitHex(Appendable dest, int value)` Format as eight digit hexadecimal number.
`static String`	`errorText(int errNum)` Get error text.
`default int`	`getDelCnt()` Get the number of thread delays.
`default Throwable`	`getLastExcept()` Get the last (recorded) exception.
`default String`	`getLastExcMess()` Get the last expection's message.
`default String`	`getLastLockFN()` Get the last lock file.
`default PrintWriter`	`getOut()` The standard output.
`default int`	`getOvrCnt()` Get the number of spoiled delays.
`default boolean`	`getUseLock()` Do use lock.
`default int`	`openLock(String lckPiGpioFil, boolean verbose)` Open and lock lock file.
`default int`	`openLockPi(String lckPiGpioFil, boolean verbose)` Open and lock lock file on Pi, only.
`default int`	`openWatchdog()` Initialise respectively start the watchdog.
`default String`	`regAsStdMBean()` Register this application as standard MBean.
`default void`	`repExc(Appendable out, Throwable exc, boolean trace)` Report an exception.
`default void`	`setArgHost(String argHost)` Start argument setter.
`default void`	`setArgPiType(int argPiType)` Start argument setter.
`default void`	`setArgPort(int argPort)` Start argument setter.
`default void`	`setArgTimeout(int argTimeout)` Start argument setter.
`default void`	`setUseLock(boolean use)` Do use lock.
`default void`	`systemExit(int ret)` System exit.
`default void`	`thrDelay(int millies)` Periodic delay.
`default void`	`triggerWatchdog()` Trigger the watchdog.
`static Appendable`	`twoDigitDec(Appendable dest, int value)` Format as two digit decimal number with leading zero.

- Field Detail
  - ERR_NoLOCKPROC
```
static final int ERR_NoLOCKPROC
```
    Lock process can not be started.
    
    This usually means no lock process existing on the Raspberry platform. More info in PiUtil.Impl.lastExept.
    
    See Also:
    
    Constant Field Values
  - ERR_NoLOCKFILE
```
static final int ERR_NoLOCKFILE
```
    Lock file does not exist.
    
    This usually means locking respectively using GPIO is forbidden for now.
    
    See Also:
    
    Constant Field Values
  - ERR_NOT_LOCKED
```
static final int ERR_NOT_LOCKED
```
    Lock file could not be locked.
    
    This usually means locking respectively using GPIO is momentarily forbidden.
    
    See Also:
    
    Constant Field Values
  - ERR_NoGPIOLOCK
```
static final int ERR_NoGPIOLOCK
```
    Program has no GPIO lock.
    
    Some operations (like e.g. openWatchdog()) will be rejected when the program is not owning the GPIO lock.
    
    See Also:
    
    Constant Field Values
  - ERR_OPEN_W_DOG
```
static final int ERR_OPEN_W_DOG
```
    Can't open watchdog.
    
    See Also:
    
    Constant Field Values
  - ERR_CLOSE_WDOG
```
static final int ERR_CLOSE_WDOG
```
    Can't close the watchdog.
    
    Not being able to close the watchdog usually leads to a reset.
    
    See Also:
    
    Constant Field Values
  - ERR_ASSIGN_PIN
```
static final int ERR_ASSIGN_PIN
```
    Pin assignment error.
    
    Trying to use a pin for IO that is not existing or no IO port.
    
    See Also:
    
    Constant Field Values
  - ERR_PIGPIOD_CON
```
static final int ERR_PIGPIOD_CON
```
    Socket connecting error.
    
    Trying to connect to the pigpiod daemon failed.
    
    See Also:
    
    Constant Field Values
  - lckPiGpioPth
```
static final String lckPiGpioPth
```
    Common path to a lock file for Gpio use.
    
    See Also:
    
    Constant Field Values
  - lckWinGpioPth
```
static final String lckWinGpioPth
```
    Common path to a lock file for use on Windows.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getOut
```
default PrintWriter getOut()
```
    The standard output.
    
    Hint: A PrintWriter is an Appendable.
  - systemExit
```
default void systemExit(int ret)
```
    System exit.
    
    This method flushes out, waits a few ms to let that happen and then lets end all with System.exit(ret).
    This methods end the programme (the JVM) and, hence, never returns.
    
    Parameters:
    
    ret - the return code
  - regAsStdMBean
```
default String regAsStdMBean()
                      throws JMException
```
    Register this application as standard MBean.
    
    Returns:
    
    the registered object name
    
    Throws:
    
    JMException - if the registering fails
  - repExc
```
default void repExc(Appendable out,
                    Throwable exc,
                    boolean trace)
```
    Report an exception.
    
    Parameters:
    
    out - the output for the report
    
    exc - the exception to report on
    
    trace - true: print also a stack trace (and only if out is a PrintWriter or a PrrintStream)
  - twoDigitDec
```
static Appendable twoDigitDec(Appendable dest,
                              int value)
```
    Format as two digit decimal number with leading zero.
    
    Appended to dest is the two digit decimal representation of value if in the range 0..99's. Otherwise two blanks are appended bits.
    
    Hint: This implementation delegates to TextHelper.twoDigitDec(Appendable, int). It is here to facilitate using PiUtil, ClientPigpiod sources etc. without the de.frame4j packages. But why should one want to do this?
    
    Parameters:
    
    dest - destination to append to; if null dest is made as StringBuilder with initial capacity of 6
    
    value - the number
    
    Returns:
    
    dest (appended is "00".."99")
  - eightDigitHex
```
static Appendable eightDigitHex(Appendable dest,
                                int value)
```
    Format as eight digit hexadecimal number.
    
    Appended to dest (generated StringBuilder if supplied as null) is the six digit hexadecimal representation of value's lower 24 bits. This representation is quite usual for 24 bit RGB colours.
    
    Hint: This implementation delegates to TextHelper.eightDigitHex(Appendable, int). It is here to facilitate using PiUtil, ClientPigpiod etc. (sources) without the de.frame4j packages. But why should one want to do this?
    
    Parameters:
    
    dest - destination to append to; if null dest is made as StringBuilder with initial capacity of 14
    
    Returns:
    
    dest (appended is "000000".."FFFFFF"
    
    See Also:
    
    Color, twoDigitDec(Appendable, int), getOut()
  - errorText
```
static String errorText(int errNum)
```
    Get error text.
    
    This function returns an error text for this type's error numbers ERR_NoLOCKPROC, ERR_NoLOCKFILE, ERR_NOT_LOCKED, ERR_NoGPIOLOCK, ERR_OPEN_W_DOG, ERR_CLOSE_WDOG. Other Errors return "error -123"
    
    Parameters:
    
    errNum - the error number; 0: OK gets an empty String
    
    Returns:
    
    the error text (never null)
  - getUseLock
```
default boolean getUseLock()
```
    Do use lock.
    
    default: false
    
    See Also:
    
    setUseLock(boolean)
  - setUseLock
```
default void setUseLock(boolean use)
```
    Do use lock.
    
    The lock file or process usage is by default false. It will be set true by this method. This setting is, thence on, final and valid for all (Pi IO) programs in this JVM.
    
    Parameters:
    
    use - true: usage will be set; false: will be ignored
    
    See Also:
    
    getUseLock()
  - openLock
```
default int openLock(String lckPiGpioFil,
                     boolean verbose)
```
    Open and lock lock file.
    
    This method uses a C process to lock the file lckPiGpioFil in a manner compatible with historical standard C file lock: {code flock(lockFd, LOCK_EX | LOCK_NB);}
    For the background see this blog post.
    
    If useLock is false this method does nothing and returns 0.
    
    Parameters:
    
    lckPiGpioFil - if not null or empty use this path instead of the platform default one (/home/pi/bin/.lockPiGpio)
    
    verbose - true: make the lock process verbose (by option -v) on standard output
    
    Returns:
    
    err 0: OK; else: error, see ERR_NoLOCKFILE, ERR_NOT_LOCKED
  - openLockPi
```
default int openLockPi(String lckPiGpioFil,
                       boolean verbose)
```
    Open and lock lock file on Pi, only.
    
    If running on a Pi this method does the same as openLock(String, boolean).
    If not running on a Pi this method does nothing and returns 0 (OK).
    
    See Also:
    
    openLock(String, boolean), #ERR_NOT_LOCKED
  - closeLock
```
default void closeLock()
```
    Unlock the lock file.
    
    If no lock file was locked by openLock(String, boolean) or openLockPi(String, boolean) this method just does nothing.
    Hence, it shall be called in program at places where a lock could be released, no matter if the program did get the lock. The place would be after ending the use of IO and releasing the outputs used.
  - openWatchdog
```
default int openWatchdog()
```
    Initialise respectively start the watchdog.
    
    If not on a PI this method does nothing and returns 0 (OK).
    
    Starting the watchdog will only be allowed when having got the GPIO lock by #openLock(). Additionally the watchdog will work only when allowed for non root. To use the watchdog in Java programs with this library the watchdog's access rights have to be changed; see the publication Raspberry for remote services.
    
    Starting the watchdog will only be allowed when having got the GPIO lock by openLock(String, boolean). Additionally the watchdog will work only when allowed (on the Pi) for non root.
    
    As soon as initialised the watchdog will have to be triggered (by triggerWatchdog()) at least every 16 s or closed (by closeWatchdog()). Otherwise the Raspberry Pi will be reset and reboot.
    
    Note: Obviously, for a Java program owning the (GPIO lock and) the watchdog is an opportunity to (mis-) use it for a total re-Start.
    
    Returns:
    
    err 0: OK; else: error
  - triggerWatchdog
```
default void triggerWatchdog()
```
    Trigger the watchdog.
  - closeWatchdog
```
default int closeWatchdog()
```
    Close the watchdog.
    
    Returns:
    
    err 0: OK; else: error
  - thrDelay
```
default void thrDelay(int millies)
```
    Periodic delay.
    
    This method delays the calling thread for the given number of ms (milliseconds) relative to its last call. Hence, it is able to implement strong long term periodicity. Called 86400 times with 1000 ms will end one day *) later, e.g.. The number of such successful delays can be obtained by getDelCnt().
    Hint: On a day with leap seconds either this fails or the underlying system clock has been spoiled.
    
    If this call's (corrected) relative end time would be in the past the current delay will be relative to now. In that case an existing long term periodicity will be destroyed. This would happen if other threads or processes hinder the wake up of this thread for more than millies ms. The number of delays having been spoiled so can be obtained by getOvrCnt().
    
    Parameters:
    
    millies - the number of ms to delay relativ to the last call
  - getDelCnt
```
default int getDelCnt()
```
    Get the number of thread delays.
    
    Returns:
    
    the number of successful thread delays
    
    See Also:
    
    #getOvrCnt()
  - getOvrCnt
```
default int getOvrCnt()
```
    Get the number of spoiled delays.
    
    Returns:
    
    the number of spoiled thread delays
    
    See Also:
    
    #getCycCnt()
  - getLastLockFN
```
default String getLastLockFN()
```
    Get the last lock file.
    
    Returns:
    
    the name of the last lock file locked and eventually released (in case of success) or the last file having been tried to lock.
  - getLastExcept
```
default Throwable getLastExcept()
```
    Get the last (recorded) exception.
    
    The information provided by this method and getLastExcMess() is not threadsafe. Use onla in single threaded program phases like first initialisation and final clean up.
  - getLastExcMess
```
default String getLastExcMess()
```
    Get the last expection's message.
    
    See Also:
    
    getLastExcept()
  - setArgPiType
```
default void setArgPiType(int argPiType)
```
    Start argument setter.
  - argPiType
```
default int argPiType()
```
    Start argument getter.
  - setArgPort
```
default void setArgPort(int argPort)
```
    Start argument setter.
  - argPort
```
default int argPort()
```
    Start argument getter.
  - setArgTimeout
```
default void setArgTimeout(int argTimeout)
```
    Start argument setter.
  - argTimeout
```
default int argTimeout()
```
    Start argument getter.
  - setArgHost
```
default void setArgHost(String argHost)
```
    Start argument setter.
  - argHost
```
default String argHost()
```
    Start argument getter.

Interface PiUtil

Nested Class Summary

Field Summary

Fields inherited from interface de.weAut.PiVals

Fields inherited from interface de.frame4j.util.ComVar

Method Summary

Field Detail

ERR_NoLOCKPROC

ERR_NoLOCKFILE

ERR_NOT_LOCKED

ERR_NoGPIOLOCK

ERR_OPEN_W_DOG

ERR_CLOSE_WDOG

ERR_ASSIGN_PIN

ERR_PIGPIOD_CON

lckPiGpioPth

lckWinGpioPth

Method Detail

getOut

systemExit

regAsStdMBean

repExc

twoDigitDec

eightDigitHex

errorText

getUseLock

setUseLock

openLock

openLockPi

closeLock

openWatchdog

triggerWatchdog

closeWatchdog

thrDelay

getDelCnt

getOvrCnt

getLastLockFN

getLastExcept

getLastExcMess

setArgPiType

argPiType

setArgPort

argPort

setArgTimeout

argTimeout

setArgHost

argHost