IO functions for Raspberry Pis. More...

#include "arch/config.h"
#include "weUtil.h"
#include <pigpiod_if2.h>

Macros
#define	PI_PUD_DEFAULT
	Leave pull resistor setting as defaulted. More...

#define	PI_PUD_KEEP
	Leave pull resistor setting unchanged. More...

#define	PINig
	Defines a disabled GPIO. More...

Functions
uint8_t	gpio4pin (int const pin)
	Pin number to GPIO number lookup. More...

void	initAsDrive (int thePi, unsigned gpio, unsigned init)
	Initialise a GPIO pin as output. More...

void	initAsHiDrive (int thePi, unsigned gpio, unsigned init)
	Initialise a GPIO pin as high drive. More...

void	initAsHiInput (int thePi, unsigned gpio)
	Initialise a GPIO pin as input with pull down. More...

void	initAsInput (int thePi, unsigned gpio)
	Initialise a GPIO pin as input. More...

void	initAsInputs (unsigned const lesGPIOs[])
	Initialise one or more GPIO pin as input. More...

void	initAsLoInput (int thePi, unsigned gpio)
	Initialise a GPIO pin as input with pull up. More...

uint32_t	initAsOutput (int thePi, unsigned gpio)
	Initialise a GPIO pin as output. More...

uint32_t	initAsOutputs (unsigned const lesGPIOs[])
	Make one or more GPIO pins output. More...

uint8_t	pin4GPIO (int const gpio)
	GPIO number to pin number lookup. More...

uint32_t	releaseOutputs (int const thePi)
	Release all GPIO pins set as output. More...

uint32_t	releaseOutputsReport (int const thePi)
	Release all GPIO pins set as output with report. More...

void	reportPinOp (char const *op, unsigned const lesGpio[])
	Report an arbitrary operation on a list of GPIOs. More...

void	setOutput (unsigned const gpio, unsigned const level)
	Set a GPIO output pin. More...

void	setOutputs (uint32_t const lesOuts, unsigned const level)
	Set a list/mask of GPIO output pins. More...

void	setPadStrength (int thePi, unsigned mA)
	Set the output drive capacity of GPIO ports 0..27. More...

Variables
uint32_t const	gpio2bit [36]
	GPIO number to bank pin number lookup. More...

uint8_t const	gpio2pin []
	GPIO number to pin number lookup. More...

uint8_t const	pin2gpio [44]
	Pin number to GPIO number lookup. More...

char const	pudTxt [5][6]
	Names for input's pull resistor settings.

int	thePi
	The standard Pi for gpio(d) IO of the program. More...

Detailed Description

IO functions for Raspberry Pis.

Copyright  (c)   2020 2023    Albrecht Weinert
weinert-automation.de         a-weinert.de
 
    /         /      /\
   /         /___   /  \      |
   \        /____\ /____\ |  _|__
    \  /\  / \    /      \|   |
     \/  \/   \__/        \__/|_                                 

Revision history

Rev. 253 9.10.2023
Rev. 232 12.08.2020 : common functions collected and consolidated
Rev. 233 12.10.2020 : initAsHiInput() added
Rev. 237 01.03.2021 : documentation (Doxygen) corrected/improved
Rev. 251 15.08.2023 : documentation corrected/improved
Rev. 252 17.08.2023 : ECar loading ++

The IO functions will work with the gpio/gpiod library – daemon running – as defined in pigpiod_if2.h.

This is a supplementary basic library to be used in conjunction with the pigpio library (linked by: -lpigpiod_if2 -lrt).

Macro Definition Documentation

◆ PI_PUD_KEEP

#define PI_PUD_KEEP

Leave pull resistor setting unchanged.

This is an illegal value (4) just one above the legal ones (0..2). Its purpose is to state the current whatever pull setting shall be left untouched.

◆ PI_PUD_DEFAULT

#define PI_PUD_DEFAULT

Leave pull resistor setting as defaulted.

This is an illegal value (3) just one above the legal ones (0..2). Its purpose is to state that an otherwise defined default value shall be used. If no such default value is known, the current pull setting shall be left untouched.

◆ PINig

#define PINig

Defines a disabled GPIO.

This is an illegal GPIO value (33) which some IO functions recognise as "disabled". Hence they can be just called in the normal program flow doing no I/O on a disabled port.

Function Documentation

◆ pin4GPIO()

uint8_t pin4GPIO ( int const gpio )

GPIO number to pin number lookup.

Parameters

gpio	a GPIO number (>= 0) available on the Pi's 40 respectively 26 pins IO connector

Returns: the GPIO's pin number (1..40 resp. 26) on the IO connector;
0 means not available in the Pi IO connector or even undefined

◆ gpio4pin()

uint8_t gpio4pin ( int const pin )

Pin number to GPIO number lookup.

Parameters

pin	1..40 (26) is the legal IO connector pin number

Returns: 0..56 the GPIO number; 90: ground (0V);
93: 3.3V; 95: 5V; 99: undefined, i.e. illegal pin number

◆ initAsInputs()

void initAsInputs ( unsigned const 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 impedandance.

The Pi for the IO operation is thePi.

Parameters

lesGPIOs array of GPIO numbers (0..53); use 0x7F as end marker

◆ reportPinOp()

void reportPinOp	(	char const *	op,
		unsigned const	lesGpio[]
	)

Report an arbitrary operation on a list of GPIOs.

The report lines on outLog will be

progNam ___operation GPIO: 13 pin: 27

progNam

char const * progNam()

The program name.

Definition: sysBasic.c:94

Parameters

op	the operation displayed as 12 characters right justified.
lesGpio	a GPIO list (terminated by a value > 56)

◆ initAsOutputs()

uint32_t initAsOutputs ( unsigned const lesGPIOs[] )

Make one or more GPIO pins output.

This functions sets the pins listed as GPIOs to output mode.
Normally, at program end, the same list of outputs should be released to high impedance by initAsInputs().

The Pi for the IO operations is thePi.

Parameters

lesGPIOs array of GPIO numbers (0..53); use 0x7F as end marker

Returns: the bank mask of the outputs set so by this function; 0 means non set (complete failure)

◆ setOutputs()

void setOutputs	(	uint32_t const	lesOuts,
		unsigned const	level
	)

Set a list/mask of GPIO output pins.

This functions sets the (output) pins set in the bank mask ON or OFF.

The Pi for the IO operations is thePi.

Parameters

lesOuts	bank mask of outputs to be set
level	OFF or ON (0 or 1)

◆ setOutput()

void setOutput	(	unsigned const	gpio,
		unsigned const	level
	)

Set a GPIO output pin.

This functions sets an output pin gpio ON or OFF.
If gpio is > 31 nothing is done. That handles the meaning of gpio 33 (within a bank) as unused.

The Pi for the IO operations is thePi.

Parameters

gpio	an output pin (that should have been set as such!)
level	OFF or ON (0 or 1)

◆ initAsOutput()

uint32_t initAsOutput	(	int	thePi,
		unsigned	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).

All functions setting setting as output should use this function.

Parameters

thePi	the Raspberry's identifier as got from initialising gpio(d)
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()

uint32_t releaseOutputs ( int const thePi )

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.

Parameters

thePi the Raspberry's identifier as got from initialising gpio(d)

Returns: the bank mask of the previous resp. released outputs

◆ releaseOutputsReport()

uint32_t releaseOutputsReport ( int const thePi )

Release all GPIO pins set as output with report.

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

Parameters

thePi the Raspberry's identifier as got from initialising gpio(d)

Returns: the bank mask of the previous resp. released outputs

◆ initAsInput()

void initAsInput	(	int	thePi,
		unsigned	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

thePi	the Raspberry's identifier as got from initialising gpio(d)
gpio	the GPIO number (0..53)

◆ initAsLoInput()

void initAsLoInput	(	int	thePi,
		unsigned	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

thePi	the Raspberry's identifier as got from initialising gpio(d)
gpio	the GPIO number (0..53)

◆ initAsHiInput()

void initAsHiInput	(	int	thePi,
		unsigned	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

thePi	the Raspberry's identifier as got from initialising gpio(d)
gpio	the GPIO number (0..53)

◆ initAsHiDrive()

void initAsHiDrive	(	int	thePi,
		unsigned	gpio,
		unsigned	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

thePi	the Raspberry's identifier as got from initialising gpio(d)
gpio	the GPIO number (0..53)
init	0 or 1: the initial output value; else: leave unchanged

◆ initAsDrive()

void initAsDrive	(	int	thePi,
		unsigned	gpio,
		unsigned	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

thePi	the Raspberry's identifier as got from initialising gpio(d)
gpio	the GPIO number (0..53)
init	0 or 1: the initial output value; else: leave unchanged

◆ setPadStrength()

void setPadStrength	(	int	thePi,
		unsigned	mA
	)

Set the output drive capacity of GPIO ports 0..27.

For pins set as output (by initAsHiDrive() or initAsDrive() e.g.) this function sets the drive capacity in the range of 2..16 mA.
Note 1: All 27 pins 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

thePi	the Raspberry's identifier as got from initialising gpio(d)
mA	2..16: output drive capacity for providing legal low or high; else: leave drive capacity unchanged

Variable Documentation

◆ gpio2pin

uint8_t const gpio2pin[]

extern

GPIO number to pin number lookup.

Index [0..39] is a GPIO number available on the Pi's 40 (26) pins connector. Result 1..40: The GPIO's pin number on the IO connector;
0: not available in the Pi IO connector or even undefined
Outside [0..39] index out of bound.
See also gpio2bit, pin2gpio

◆ gpio2bit

uint32_t const gpio2bit[36]

extern

GPIO number to bank pin number lookup.

Index [0..31] is a GPIO number partly (2..27) available on the Pi's 40 (26) pins connector. Result 0x00000001..0x80000000: a 32 bit with exactly one bit set corresponding to place in a 32 bit bank mask.
Outside [0..31] index out of bound.
See also gpio2pin, pin2gpio

◆ pin2gpio

uint8_t const pin2gpio[44]

extern

Pin number to GPIO number lookup.

Index [1..40 (26)] is the legal pin number.
Result 0..56: GPIO number; 90: ground (0V); 93: 3.3V; 95: 5V;
99: undefined (for pin 0 and 41 (27)..44).
Outside [0..43] index out of bound.
See also gpio2bit, gpio2pin

◆ thePi

int thePi

extern

The standard Pi for gpio(d) IO of the program.

This global variable is provided to hold the main pi used by a program doing process IO via piGpIO[d]. In most local use cases

thePi = pigpio_start(NULL, NULL);

thePi

int thePi

The standard Pi for gpio(d) IO of the program.

Definition: weGPIOd.c:99

it will be 0 = this local Pi. After usage don't forget to terminate the connection to the pigpio daemon by

pigpio_stop(thePi);

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ PI_PUD_KEEP

◆ PI_PUD_DEFAULT

◆ PINig

Function Documentation

◆ pin4GPIO()

◆ gpio4pin()

◆ initAsInputs()

◆ reportPinOp()

◆ initAsOutputs()

◆ setOutputs()

◆ setOutput()

◆ initAsOutput()

◆ releaseOutputs()

◆ releaseOutputsReport()

◆ initAsInput()

◆ initAsLoInput()

◆ initAsHiInput()

◆ initAsHiDrive()

◆ initAsDrive()

◆ setPadStrength()

Variable Documentation

◆ gpio2pin

◆ gpio2bit

◆ pin2gpio

◆ thePi