intlgGpiochipOpen(intgpioDev)
This returns a handle to a gpiochip device.
gpioDev: >= 0
If OK returns a handle (>= 0).
On failure returns a negative error code.
Example
h = lgGpiochipOpen(0); // open /dev/gpiochip0
if (h >= 0)
{
// open ok
}
else
{
// open error
}
intlgGpiochipClose(inthandle)
This closes an opened gpiochip device.
handle: >= 0 (as returned by lgGpiochipOpen)
If OK returns 0.
On failure returns a negative error code.
Example
status = lgGpiochipClose(h); // close gpiochip
if (status < 0)
{
// close failed
}
intlgGpioGetChipInfo(inthandle,lgChipInfo_pchipInfo)
This returns information about a gpiochip.
handle: >= 0 (as returned by lgGpiochipOpen)
chipInfo: A pointer to space for a lgChipInfo_t object
If OK returns 0 and updates chipInfo.
On failure returns a negative error code.
This command gets the number of GPIO on the gpiochip, its name, and its usage.
Example
lgChipInfo_t cInfo;
status = lgGpioGetChipInfo(h, &cInfo);
if (status == LG_OKAY)
{
printf("lines=%d name=%s label=%s0,
cInfo.lines, cInfo.name, cInfo.label))
}
intlgGpioGetLineInfo(inthandle,intgpio,lgLineInfo_plineInfo)
Returns information about a GPIO.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: >= 0, as legal for the gpiochip
lineInfo: A pointer to space for a lgLineInfo_t object
If OK returns 0 and updates lineInfo.
On failure returns a negative error code.
This command gets information for a GPIO of a gpiochip. In particular it gets the GPIO number,
flags, its user, and its purpose.
The meaning of the flags bits are as given for the mode by lgGpioGetMode.
The user and purpose fields are filled in by the software which has claimed the GPIO and may be
blank.
Example
lgLineInfo_t lInfo;
status = lgGpioGetLineInfo(h, gpio, &lInfo);
if (status == LG_OKAY)
{
printf("lFlags=%d name=%s user=%s0,
lInfo.lFlags, lInfo.name, lInfo.user))
}
intlgGpioGetMode(inthandle,intgpio)
Returns the GPIO mode.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: >= 0, as legal for the gpiochip
If OK returns the GPIO mode.
On failure returns a negative error code.
Bit Value Meaning
0 1 Kernel: In use by the kernel
1 2 Kernel: Output
2 4 Kernel: Active low
3 8 Kernel: Open drain
4 16 Kernel: Open source
5 32 Kernel: Pull up set
6 64 Kernel: Pull down set
7 128 Kernel: Pulls off set
8 256 LG: Input
9 512 LG: Output
10 1024 LG: Alert
11 2048 LG: Group
12 4096 LG: ---
13 8192 LG: ---
14 16384 LG: ---
15 32768 LG: ---
16 65536 Kernel: Input
17 1<<17 Kernel: Rising edge alert
18 1<<18 Kernel: Falling edge alert
19 1<<19 Kernel: Realtime clock alert
The LG bits are only set if the query was made by the process that owns the GPIO.
intlgGpioSetUser(inthandle,constchar*gpiouser)
This sets the user string to be associated with each claimed GPIO.
handle: >= 0 (as returned by lgGpiochipOpen)
gpiouser: a string up to 32 characters long
If OK returns 0.
On failure returns a negative error code.
Example
status = lgGpioSetUser(h, "my_title");
intlgGpioClaimInput(inthandle,intlFlags,intgpio)
This claims a GPIO for input.
handle: >= 0 (as returned by lgGpiochipOpen)
lFlags: line flags for the GPIO
gpio: the GPIO to be claimed
If OK returns 0.
On failure returns a negative error code.
The line flags may be used to set the GPIO as active low, open drain, or open source.
Example
// open GPIO 23 for input
status = lgGpioClaimInput(h, 0, 23);
intlgGpioClaimOutput(inthandle,intlFlags,intgpio,intlevel)
This claims a GPIO for output.
handle: >= 0 (as returned by lgGpiochipOpen)
lFlags: line flags for the GPIO
gpio: the GPIO to be claimed
level: the initial level to set for the GPIO
If OK returns 0.
On failure returns a negative error code.
The line flags may be used to set the GPIO as active low, open drain, or open source.
If level is zero the GPIO will be initialised low. If any other value is used the GPIO will be
initialised high.
Example
// open GPIO 31 for high output
status = lgGpioClaimOutput(h, 0, 31, 1);
intlgGpioClaimAlert(inthandle,intlFlags,inteFlags,intgpio,intnfyHandle)
This claims a GPIO for alerts on level changes.
handle: >= 0 (as returned by lgGpiochipOpen)
lFlags: line flags for the GPIO
eFlags: event flags for the GPIO
gpio: >= 0, as legal for the gpiochip
nfyHandle: >= 0 (as returned by lgNotifyOpen)
If OK returns 0.
On failure returns a negative error code.
The line flags may be used to set the GPIO as active low, open drain, or open source.
The event flags are used to specify alerts for a rising edge, falling edge, or both edges.
The alerts will be sent to a previously opened notification. If you don't want them sent to a
notification set nfyHandle to -1.
The alerts will also be sent to any callback registered for the GPIO by lgGpioSetAlertsFunc.
All GPIO alerts are also sent to a callback registered by lgGpioSetSamplesFunc.
Example
status = lgGpioClaimAlert(h, 0, LG_BOTH_EDGES, 16, -1);
intlgGpioFree(inthandle,intgpio)
This frees a GPIO.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: the GPIO to be freed
If OK returns 0.
On failure returns a negative error code.
The GPIO may now be claimed by another user or for a different purpose.
Example
status = lgGpioFree(h, 16);
intlgGroupClaimInput(inthandle,intlFlags,intcount,constint*gpios)
This claims a group of GPIO for inputs.
handle: >= 0 (as returned by lgGpiochipOpen)
lFlags: line flags for the GPIO group
count: the number of GPIO to claim
gpios: the group GPIO
If OK returns 0.
On failure returns a negative error code.
The line flags may be used to set the group as active low, open drain, or open source.
gpios is an array of one or more GPIO. The first GPIO is called the group leader and is used to
reference the group as a whole.
Example
int buttons[4] = {9, 7, 2, 6};
status = lgGroupClaimInput(h, 0, 4, buttons);
if (status == LG_OKAY)
{
// OK
}
else
{
// Error
}
intlgGroupClaimOutput(inthandle,intlFlags,intcount,constint*gpios,constint*levels)
This claims a group of GPIO for outputs.
handle: >= 0 (as returned by lgGpiochipOpen)
lFlags: line flags for the GPIO group
count: the number of GPIO to claim
gpios: the group GPIO
levels: the initial level for each GPIO
If OK returns 0.
On failure returns a negative error code.
The line flags may be used to set the group as active low, open drain, or open source.
gpios is an array of one or more GPIO. The first GPIO is called the group leader and is used to
reference the group as a whole.
levels is an array of initialisation values for the GPIO. If a value is zero the corresponding GPIO
will be initialised low. If any other value is used the corresponding GPIO will be initialised high.
Example
int leds[7] = {15, 16, 17, 8, 12, 13, 14};
int levels[7] = { 1, 0, 1, 1, 1, 0, 0};
status = lgGroupClaimInput(h, 0, 7, leds, levels);
if (status == LG_OKAY)
{
// OK
}
else
{
// Error
}
intlgGroupFree(inthandle,intgpio)
This frees all the GPIO associated with a group.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: the group to be freed
If OK returns 0.
On failure returns a negative error code.
The GPIO may now be claimed by another user or for a different purpose.
Example
status = lgGroupFree(9); // free buttons
intlgGpioRead(inthandle,intgpio)
This returns the level of a GPIO.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: the GPIO to be read
If OK returns 0 (low) or 1 (high).
On failure returns a negative error code.
This command will work for any claimed GPIO (even if a member of a group). For an output GPIO the
value returned will be that last written to the GPIO.
Example
level = lgGpioRead(h, 15); // get level of GPIO 15
intlgGpioWrite(inthandle,intgpio,intlevel)
This sets the level of an output GPIO.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: the GPIO to be written
level: the level to set
If OK returns 0.
On failure returns a negative error code.
This command will work for any GPIO claimed as an output (even if a member of a group).
If level is zero the GPIO will be set low (0). If any other value is used the GPIO will be set high
(1).
Example
status = lgGpioWrite(h, 23, 1); // set GPIO 23 high
intlgGroupRead(inthandle,intgpio,uint64_t*groupBits)
This returns the levels read from a group.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: the group to be read
groupBits: a pointer to a 64-bit memory area for the returned levels
If OK returns the group size and updates groupBits.
On failure returns a negative error code.
This command will work for an output group as well as an input group. For an output group the value
returned will be that last written to the group GPIO.
Note that this command will also work on an individual GPIO claimed as an input or output as that is
treated as a group with one member.
After a successful read groupBits is set as follows.
Bit 0 is the level of the group leader.
Bit 1 is the level of the second GPIO in the group.
Bit x is the level of GPIO x+1 of the group.
Example
// assuming a read group of 4 buttons: 9, 7, 2, 6.
uint64_t bits;
size = lgGroupRead(h, 9, &bits); // 9 is buttons group leader
if (size >= 0) // size of group is returned so size will be 4
{
level_9 = (bits >> 0) & 1;
level_7 = (bits >> 1) & 1;
level_2 = (bits >> 2) & 1;
level_6 = (bits >> 3) & 1;
}
else
{
// error
}
intlgGroupWrite(inthandle,intgpio,uint64_tgroupBits,uint64_tgroupMask)
This sets the levels of an output group.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: the group to be written
groupBits: the level to set if the corresponding bit in groupMask is set
groupMask: a mask indicating the group GPIO to be updated
If OK returns 0.
On failure returns a negative error code.
The values of each GPIO of the group are set according to the bits
of groupBits.
Bit 0 sets the level of the group leader.
Bit 1 sets the level of the second GPIO in the group.
Bit x sets the level of GPIO x+1 in the group.
However this may be modified by the groupMask. A GPIO is only updated if the corresponding bit in
the mask is 1.
Example
// assuming an output group of 7 LEDs: 15, 16, 17, 8, 12, 13, 14.
// switch on all LEDs
status = lgGroupWrite(h, 15, 0x7f, 0x7f);
// switch off all LEDs
status = lgGroupWrite(h, 15, 0x00, 0x7f);
// switch on first 4 LEDs, leave others unaltered
status = lgGroupWrite(h, 15, 0x0f, 0x0f);
// switch on LED attached to GPIO 13, leave others unaltered
status = lgGroupWrite(h, 15, 32, 32);
intlgTxPulse(inthandle,intgpio,intpulseOn,intpulseOff,intpulseOffset,intpulseCycles)
This starts software timed pulses on an output GPIO.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: the GPIO to be written
pulseOn: pulse high time in microseconds
pulseOff: pulse low time in microseconds
pulseOffset: offset from nominal pulse start position
pulseCycles: the number of pulses to be sent, 0 for infinite
If OK returns the number of entries left in the PWM queue for the GPIO.
On failure returns a negative error code.
If both pulseOn and pulseOff are zero pulses will be switched off for that GPIO. The active pulse,
if any, will be stopped and any queued pulses will be deleted.
Each successful call to this function consumes one PWM queue entry.
pulseCycles cycles are transmitted (0 means infinite). Each cycle consists of pulseOn microseconds
of GPIO high followed by pulseOff microseconds of GPIO low.
PWM is characterised by two values, its frequency (number of cycles per second) and its duty cycle
(percentage of high time per cycle).
The set frequency will be 1000000 / (pulseOn + pulseOff) Hz.
The set duty cycle will be pulseOn / (pulseOn + pulseOff) * 100 %.
E.g. if pulseOn is 50 and pulseOff is 100 the frequency will be 6666.67 Hz and the duty cycle will be
33.33 %.
pulseOffset is a microsecond offset from the natural start of the PWM cycle.
For instance if the PWM frequency is 10 Hz the natural start of each cycle is at seconds 0, then 0.1,
0.2, 0.3 etc. In this case if the offset is 20000 microseconds the cycle will start at seconds 0.02,
0.12, 0.22, 0.32 etc.
Another pulse command may be issued to the GPIO before the last has finished.
If the last pulse had infinite cycles then it will be replaced by the new settings at the end of the
current cycle. Otherwise it will be replaced by the new settings when all its cycles are compete.
Multiple pulse settings may be queued in this way.
Example
slots_left = lgTxPulse(h, 8, 100000, 100000, 0, 0); // flash LED at 5 Hz
slots_left = lgTxPulse(h, 30, 1500, 18500, 0, 0); // move servo to centre
slots_left = lgTxPulse(h, 30, 2000, 18000, 0, 0); // move servo clockwise
intlgTxPwm(inthandle,intgpio,floatpwmFrequency,floatpwmDutyCycle,intpwmOffset,intpwmCycles)
This starts software timed PWM on an output GPIO.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: the GPIO to be pulsed
pwmFrequency: PWM frequency in Hz (0=off, 0.1-10000)
pwmDutyCycle: PWM duty cycle in % (0-100)
pwmOffset: offset from nominal pulse start position
pwmCycles: the number of pulses to be sent, 0 for infinite
If OK returns the number of entries left in the PWM queue for the GPIO.
On failure returns a negative error code.
Each successful call to this function consumes one PWM queue entry.
PWM is characterised by two values, its frequency (number of cycles per second) and its duty cycle
(percentage of high time per cycle).
Another PWM command may be issued to the GPIO before the last has finished.
If the last pulse had infinite cycles then it will be replaced by the new settings at the end of the
current cycle. Otherwise it will be replaced by the new settings when all its cycles are complete.
Multiple PWM settings may be queued in this way.
intlgTxServo(inthandle,intgpio,intpulseWidth,intservoFrequency,intservoOffset,intservoCycles)
This starts software timed servo pulses on an output GPIO.
I would only use software timed servo pulses for testing purposes. The timing jitter will cause the
servo to fidget. This may cause it to overheat and wear out prematurely.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: the GPIO to be pulsed
pulseWidth: pulse high time in microseconds (0=off, 500-2500)
servoFrequency: the number of pulses per second (40-500).
servoOffset: offset from nominal pulse start position
servoCycles: the number of pulses to be sent, 0 for infinite
If OK returns the number of entries left in the PWM queue for the GPIO.
On failure returns a negative error code.
Each successful call to this function consumes one PWM queue entry.
Another servo command may be issued to the GPIO before the last has finished.
If the last pulse had infinite cycles then it will be replaced by the new settings at the end of the
current cycle. Otherwise it will be replaced by the new settings when all its cycles are compete.
Multiple servo settings may be queued in this way.
intlgTxWave(inthandle,intgpio,intcount,lgPulse_ppulses)
This starts a wave on an output group of GPIO.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: the group leader
count: the number of pulses in the wave
pulses: the pulses
If OK returns the number of entries left in the wave queue for the group.
On failure returns a negative error code.
Each successful call to this function consumes one queue entry.
This command starts a wave of pulses.
pulses is an array of pulses to be transmitted on the group.
Each pulse is defined by the following triplet:
bits: the levels to set for the selected GPIO
mask: the GPIO to select
delay: the delay in microseconds before the next pulse
Another wave command may be issued to the group before the last has finished transmission. The new
wave will start when the previous wave has competed.
Multiple waves may be queued in this way.
Example
#include <stdio.h>
#include <lgpio.h>
#define PULSES 2000
int main(int argc, char *argv[])
{
int GPIO[] = {16, 17, 18, 19, 20, 21};
int levels[] = { 1, 1, 1, 1, 1, 1};
int h;
int e;
int mask;
int delay;
int p;
lgPulse_t pulses[PULSES];
h = lgGpiochipOpen(0); // open /dev/gpiochip0
if (h < 0) { printf("ERROR: %s (%d)0, lguErrorText(h), h); return 1; }
e = lgGroupClaimOutput(h, 0, 6, GPIO, levels);
if (e < 0) { printf("ERROR: %s (%d)0, lguErrorText(e), e); return 1; }
mask = 0;
p = 0;
for (p=0; p<PULSES; p++)
{
pulses[p].bits = (p+1)>>2; // see what sort of pattern we get
pulses[p].mask = mask; // with bits and mask changing
pulses[p].delay = (PULSES + 500) - p;
if (++mask > 0x3f) mask = 0;
}
lgTxWave(h, GPIO[0], p, pulses);
while (lgTxBusy(h, GPIO[0], LG_TX_WAVE)) lguSleep(0.1);
lgGpiochipClose(h);
}
intlgTxBusy(inthandle,intgpio,intkind)
This returns true if transmissions of the specified kind are active on the GPIO or group.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: the gpio or group to be checked
kind: LG_TX_PWM or LG_TX_WAVE
If OK returns 1 for busy and 0 for not busy.
On failure returns a negative error code.
Example
while (lgTxBusy(h, 15, LG_TX_PWM)) // wait for PWM to finish on GPIO 15
lguSleep(0.1);
intlgTxRoom(inthandle,intgpio,intkind)
This returns the number of entries available for queueing transmissions of the specified kind on the
GPIO or group.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: the gpio or group to be checked
kind: LG_TX_PWM or LG_TX_WAVE
If OK returns the number of free entries (0 if none).
On failure returns a negative error code.
Example
while (lgTxRoom(h, 17, LG_TX_WAVE) > 0))
{
// queue another wave
}
intlgGpioSetDebounce(inthandle,intgpio,intdebounce_us)
This sets the debounce time for a GPIO.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: the GPIO to be configured
debounce_us: the debounce time in microseconds
If OK returns 0.
On failure returns a negative error code.
This only affects alerts.
An alert will only be issued if the edge has been stable for at least debounce microseconds.
Generally this is used to debounce mechanical switches (e.g. contact bounce).
Suppose that a square wave at 5 Hz is being generated on a GPIO. Each edge will last 100000
microseconds. If a debounce time of 100001 is set no alerts will be generated, If a debounce time
of 99999 is set 10 alerts will be generated per second.
Note that level changes will be timestamped debounce microseconds after the actual level change.
Example
lgSetDebounceTime(h, 16, 1000); // set a millisecond of debounce
intlgGpioSetWatchdog(inthandle,intgpio,intwatchdog_us)
This sets the watchdog time for a GPIO.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: the GPIO to be configured
watchdog_us: the watchdog time in microseconds
If OK returns 0.
On failure returns a negative error code.
This only affects alerts.
A watchdog alert will be sent if no edge alert has been issued for that GPIO in the previous watchdog
microseconds.
Note that only one watchdog alert will be sent per stream of edge alerts. The watchdog is reset by
the sending of a new edge alert.
The level is set to LG_TIMEOUT (2) for a watchdog alert.
Example
lgSetWatchdogTime(h, 17, 200000); // alert if nothing for 0.2 seconds
intlgGpioSetAlertsFunc(inthandle,intgpio,lgGpioAlertsFunc_tcbf,void*userdata)
This sets up a callback to be called when an alert GPIO changes state.
handle: >= 0 (as returned by lgGpiochipOpen)
gpio: the GPIO to be monitored
cbf: the callback function
userdata: a pointer to arbitrary user data
If OK returns 0.
On failure returns a negative error code.
Example
#include <stdio.h>
#include <inttypes.h>
#include <lgpio.h>
void afunc(int e, lgGpioAlert_p evt, void *data)
{
int i;
int userdata = *(int*)data;
for (i=0; i<e; i++)
{
printf("u=%d t=%"PRIu64" c=%d g=%d l=%d f=%d (%d of %d)0,
userdata, evt[i].report.timestamp, evt[i].report.chip,
evt[i].report.gpio, evt[i].report.level,
evt[i].report.flags, i+1, e);
}
}
int main(int argc, char *argv[])
{
int h;
int e;
static int userdata=123;
h = lgGpiochipOpen(0);
if (h < 0) { printf("ERROR: %s (%d)0, lguErrorText(h), h); return 1; }
lgGpioSetAlertsFunc(h, GPIO, afunc, &userdata);
e = lgGpioClaimAlert(h, 0, LG_BOTH_EDGES, 23, -1);
if (e < 0) { printf("ERROR: %s (%d)0, lguErrorText(e), e); return 1; }
lguSleep(10);
lgGpiochipClose(h);
}
Assuming square wave at 800 Hz is being received at GPIO 23.
u=123 ts=1602089980691229623 c=0 g=23 l=1 f=0 (1 of 1)
u=123 ts=1602089980691854934 c=0 g=23 l=0 f=0 (1 of 1)
u=123 ts=1602089980692479308 c=0 g=23 l=1 f=0 (1 of 1)
u=123 ts=1602089980693114566 c=0 g=23 l=0 f=0 (1 of 1)
u=123 ts=1602089980693728784 c=0 g=23 l=1 f=0 (1 of 1)
u=123 ts=1602089980694354355 c=0 g=23 l=0 f=0 (1 of 1)
u=123 ts=1602089980694978468 c=0 g=23 l=1 f=0 (1 of 1)
voidlgGpioSetSamplesFunc(lgGpioAlertsFunc_tcbf,void*userdata)
This sets up a callback to be called when any alert GPIO changes state.
cbf: the callback function
userdata: a pointer to arbitrary user data
If OK returns 0.
On failure returns a negative error code.
Note that no handle or gpio is specified. The callback function will receive alerts for all
gpiochips and gpio.
Example
#include <stdio.h>
#include <inttypes.h>
#include <lgpio.h>
void afunc(int e, lgGpioAlert_p evt, void *data)
{
int i;
int userdata = *(int*)data;
for (i=0; i<e; i++)
{
printf("u=%d t=%"PRIu64" c=%d g=%d l=%d f=%d (%d of %d)0,
userdata, evt[i].report.timestamp, evt[i].report.chip,
evt[i].report.gpio, evt[i].report.level,
evt[i].report.flags, i+1, e);
}
}
int main(int argc, char *argv[])
{
int h;
static int userdata=456;
h = lgGpiochipOpen(0);
if (h < 0) { printf("ERROR: %s (%d)0, lguErrorText(h), h); return 1; }
lgGpioSetSamplesFunc(afunc, &userdata);
lgGpioClaimAlert(h, 0, LG_BOTH_EDGES, 23, -1);
lgGpioClaimAlert(h, 0, LG_BOTH_EDGES, 24, -1);
lgGpioClaimAlert(h, 0, LG_BOTH_EDGES, 25, -1);
lguSleep(10);
lgGpiochipClose(h);
}
Assuming square wave at 800 Hz is being received at GPIO 23, 24, 25.
u=456 ts=1602090898869011679 c=0 g=24 l=1 f=0 (1 of 3)
u=456 ts=1602090898869016627 c=0 g=25 l=1 f=0 (2 of 3)
u=456 ts=1602090898869627667 c=0 g=23 l=0 f=0 (3 of 3)
u=456 ts=1602090898869636522 c=0 g=24 l=0 f=0 (1 of 3)
u=456 ts=1602090898869641157 c=0 g=25 l=0 f=0 (2 of 3)
u=456 ts=1602090898870252614 c=0 g=23 l=1 f=0 (3 of 3)
u=456 ts=1602090898870261155 c=0 g=24 l=1 f=0 (1 of 3)
u=456 ts=1602090898870266208 c=0 g=25 l=1 f=0 (2 of 3)
u=456 ts=1602090898870879800 c=0 g=23 l=0 f=0 (3 of 3)
u=456 ts=1602090898870890477 c=0 g=24 l=0 f=0 (1 of 3)
u=456 ts=1602090898870895529 c=0 g=25 l=0 f=0 (2 of 3)
u=456 ts=1602090898871503652 c=0 g=23 l=1 f=0 (3 of 3)
intlgNotifyOpen(void)
This function requests a free notification.
If OK returns a handle (>= 0).
On failure returns a negative error code.
A notification is a method for being notified of GPIO state changes via a pipe or socket.
The notification pipes are created in the library working directory (see lguGetWorkDir).
Pipe notifications for handle x will be available at the pipe named .lgd-nfy* (where * is the handle
number). E.g. if the function returns 15 then the notifications must be read from .lgd-nfy15.
Socket notifications are returned to the socket which requested the handle.
Example
h = lgNotifyOpen();
if (h >= 0)
{
sprintf(str, ".lgd-nfy%d", h);
fd = open(str, O_RDONLY);
if (fd >= 0)
{
// Okay.
}
else
{
// Error.
}
}
else
{
// Error.
}
intlgNotifyResume(inthandle)
This function restarts notifications on a paused notification.
handle: >= 0 (as returned by lgNotifyOpen)
If OK returns 0.
On failure returns a negative error code.
The notification gets state changes for each associated GPIO.
Each notification occupies 16 bytes in the fifo and has the following structure.
typedef struct
{
uint64_t timestamp; // alert time in nanoseconds
uint8_t chip; // gpiochip device number
uint8_t gpio; // offset into gpio device
uint8_t level; // 0=low, 1=high, 2=timeout
uint8_t flags; // none currently defined
} lgGpioReport_t;
timestamp: the number of nanoseconds since the epoch (start of 1970) level: indicates the level of
the GPIO
flags: no flags are currently defined
For future proofing it is probably best to ignore any notification with non-zero flags.
Example
// Start notifications for associated GPIO.
lgNotifyResume(h);
intlgNotifyPause(inthandle)
This function pauses notifications.
handle: >= 0 (as returned by lgNotifyOpen)
If OK returns 0.
On failure returns a negative error code.
Notifications are suspended until lgNotifyResume is called.
Example
lgNotifyPause(h);
intlgNotifyClose(inthandle)
This function stops notifications and frees the handle for reuse.
handle: >= 0 (as returned by lgNotifyOpen)
If OK returns 0.
On failure returns a negative error code.
Example
lgNotifyClose(h);
intlgI2cOpen(inti2cDev,inti2cAddr,inti2cFlags)
This returns a handle for the device at the address on the I2C bus.
i2cDev: >= 0
i2cAddr: 0-0x7F
i2cFlags: 0
If OK returns a handle (>= 0).
On failure returns a negative error code.
No flags are currently defined. This parameter should be set to zero.
For the SMBus commands the low level transactions are shown at the end of the function description.
The following abbreviations are used.
S (1 bit) : Start bit
P (1 bit) : Stop bit
Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0
A, NA (1 bit) : Accept and not accept bit
Addr (7 bits): I2C 7 bit address
i2cReg (8 bits): Command byte, a byte which often selects a register
Data (8 bits): A data byte
Count (8 bits): A byte defining the length of a block operation
[..]: Data sent by the device
intlgI2cClose(inthandle)
This closes the I2C device.
handle: >= 0 (as returned by lgI2cOpen)
If OK returns 0.
On failure returns a negative error code.
intlgI2cWriteQuick(inthandle,intbitVal)
This sends a single bit (in the Rd/Wr bit) to the device.
handle: >= 0 (as returned by lgI2cOpen)
bitVal: 0-1, the value to write
If OK returns 0.
On failure returns a negative error code.
Quick command. SMBus 2.0 5.5.1
S Addr bit [A] P
intlgI2cWriteByte(inthandle,intbyteVal)
This sends a single byte to the device.
handle: >= 0 (as returned by lgI2cOpen)
byteVal: 0-0xFF, the value to write
If OK returns 0.
On failure returns a negative error code.
Send byte. SMBus 2.0 5.5.2
S Addr Wr [A] bVal [A] P
intlgI2cReadByte(inthandle)
This reads a single byte from the device.
handle: >= 0 (as returned by lgI2cOpen)
If OK returns the byte read (0-255).
On failure returns a negative error code.
Receive byte. SMBus 2.0 5.5.3
S Addr Rd [A] [Data] NA P
intlgI2cWriteByteData(inthandle,inti2cReg,intbyteVal)
This writes a single byte to the specified register of the device.
handle: >= 0 (as returned by lgI2cOpen)
i2cReg: 0-255, the register to write
byteVal: 0-0xFF, the value to write
If OK returns 0.
On failure returns a negative error code.
Write byte. SMBus 2.0 5.5.4
S Addr Wr [A] i2cReg [A] bVal [A] P
intlgI2cWriteWordData(inthandle,inti2cReg,intwordVal)
This writes a single 16 bit word to the specified register of the device.
handle: >= 0 (as returned by lgI2cOpen)
i2cReg: 0-255, the register to write
wordVal: 0-0xFFFF, the value to write
If OK returns 0.
On failure returns a negative error code.
Write word. SMBus 2.0 5.5.4
S Addr Wr [A] i2cReg [A] wValLow [A] wValHigh [A] P
intlgI2cReadByteData(inthandle,inti2cReg)
This reads a single byte from the specified register of the device.
handle: >= 0 (as returned by lgI2cOpen)
i2cReg: 0-255, the register to read
If OK returns the byte read (0-255).
On failure returns a negative error code.
Read byte. SMBus 2.0 5.5.5
S Addr Wr [A] i2cReg [A] S Addr Rd [A] [Data] NA P
intlgI2cReadWordData(inthandle,inti2cReg)
This reads a single 16 bit word from the specified register of the device.
handle: >= 0 (as returned by lgI2cOpen)
i2cReg: 0-255, the register to read
If OK returns the word read (0-65535).
On failure returns a negative error code.
Read word. SMBus 2.0 5.5.5
S Addr Wr [A] i2cReg [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
intlgI2cProcessCall(inthandle,inti2cReg,intwordVal)
This writes 16 bits of data to the specified register of the device and reads 16 bits of data in
return.
handle: >= 0 (as returned by lgI2cOpen)
i2cReg: 0-255, the register to write/read
wordVal: 0-0xFFFF, the value to write
If OK returns the word read (0-65535).
On failure returns a negative error code.
Process call. SMBus 2.0 5.5.6
S Addr Wr [A] i2cReg [A] wValLow [A] wValHigh [A]
S Addr Rd [A] [DataLow] A [DataHigh] NA P
intlgI2cWriteBlockData(inthandle,inti2cReg,constchar*txBuf,intcount)
This writes up to 32 bytes to the specified register of the device.
handle: >= 0 (as returned by lgI2cOpen)
i2cReg: 0-255, the register to write
txBuf: an array with the data to send
count: 1-32, the number of bytes to write
If OK returns 0.
On failure returns a negative error code.
Block write. SMBus 2.0 5.5.7
S Addr Wr [A] i2cReg [A] count [A]
txBuf0 [A] txBuf1 [A] ... [A] txBufn [A] P
intlgI2cReadBlockData(inthandle,inti2cReg,char*rxBuf)
This reads a block of up to 32 bytes from the specified register of the device.
handle: >= 0 (as returned by lgI2cOpen)
i2cReg: 0-255, the register to read
rxBuf: an array to receive the read data
The amount of returned data is set by the device.
If OK returns the count of bytes read (0-32) and updates rxBuf.
On failure returns a negative error code.
Block read. SMBus 2.0 5.5.7
S Addr Wr [A] i2cReg [A]
S Addr Rd [A] [Count] A [rxBuf0] A [rxBuf1] A ... A [rxBufn] NA P
intlgI2cBlockProcessCall(inthandle,inti2cReg,char*ioBuf,intcount)
This writes data bytes to the specified register of the device and reads a device specified number of
bytes of data in return.
handle: >= 0 (as returned by lgI2cOpen)
i2cReg: 0-255, the register to write/read
ioBuf: an array with the data to send and to receive the read data
count: 1-32, the number of bytes to write
If OK returns the count of bytes read (0-32) and updates ioBuf.
On failure returns a negative error code.
The SMBus 2.0 documentation states that a minimum of 1 byte may be sent and a minimum of 1 byte may
be received. The total number of bytes sent/received must be 32 or less.
Block write-block read. SMBus 2.0 5.5.8
S Addr Wr [A] i2cReg [A] count [A] ioBuf0 [A] ... ioBufn [A]
S Addr Rd [A] [Count] A [ioBuf0] A ... [ioBufn] A P
intlgI2cReadI2CBlockData(inthandle,inti2cReg,char*rxBuf,intcount)
This reads count bytes from the specified register of the device. The count may be 1-32.
handle: >= 0 (as returned by lgI2cOpen)
i2cReg: 0-255, the register to read
rxBuf: an array to receive the read data
count: 1-32, the number of bytes to read
If OK returns the count of bytes read (0-32) and updates rxBuf.
On failure returns a negative error code.
S Addr Wr [A] i2cReg [A]
S Addr Rd [A] [rxBuf0] A [rxBuf1] A ... A [rxBufn] NA P
intlgI2cWriteI2CBlockData(inthandle,inti2cReg,constchar*txBuf,intcount)
This writes 1 to 32 bytes to the specified register of the device.
handle: >= 0 (as returned by lgI2cOpen)
i2cReg: 0-255, the register to write
txBuf: the data to write
count: 1-32, the number of bytes to write
If OK returns 0.
On failure returns a negative error code.
S Addr Wr [A] i2cReg [A] txBuf0 [A] txBuf1 [A] ... [A] txBufn [A] P
intlgI2cReadDevice(inthandle,char*rxBuf,intcount)
This reads count bytes from the raw device into rxBuf.
handle: >= 0 (as returned by lgI2cOpen)
rxBuf: an array to receive the read data bytes
count: >0, the number of bytes to read
If OK returns count (>0) and updates rxBuf.
On failure returns a negative error code.
S Addr Rd [A] [rxBuf0] A [rxBuf1] A ... A [rxBufn] NA P
intlgI2cWriteDevice(inthandle,constchar*txBuf,intcount)
This writes count bytes from txBuf to the raw device.
handle: >= 0 (as returned by lgI2cOpen)
txBuf: an array containing the data bytes to write
count: >0, the number of bytes to write
If OK returns 0.
On failure returns a negative error code.
S Addr Wr [A] txBuf0 [A] txBuf1 [A] ... [A] txBufn [A] P
intlgI2cSegments(inthandle,lgI2cMsg_t*segs,intcount)
This function executes multiple I2C segments in one transaction by calling the I2C_RDWR ioctl.
handle: >= 0 (as returned by lgI2cOpen)
segs: an array of I2C segments
count: >0, the number of I2C segments
If OK returns the number of segments executed.
On failure returns a negative error code.
intlgI2cZip(inthandle,constchar*txBuf,inttxCount,char*rxBuf,intrxCount)
This function executes a sequence of I2C operations. The operations to be performed are specified by
the contents of txBuf which contains the concatenated command codes and associated data.
handle: >= 0 (as returned by lgI2cOpen)
txBuf: pointer to the concatenated I2C commands, see below
txCount: size of command buffer
rxBuf: pointer to buffer to hold returned data
rxCount: size of receive buffer
If OK returns the count of bytes read (which may be 0) and updates rxBuf.
On failure returns a negative error code.
The following command codes are supported:
Name Cmd & Data Meaning
End 0 No more commands
Escape 1 Next P is two bytes
Address 2 P Set I2C address to P
Flags 3 lsb msb Set I2C flags to lsb + (msb << 8)
Read 4 P Read P bytes of data
Write 5 P ... Write P bytes of data
The address, read, and write commands take a parameter P. Normally P is one byte (0-255). If the
command is preceded by the Escape command then P is two bytes (0-65535, least significant byte
first).
The address defaults to that associated with the handle. The flags default to 0. The address and
flags maintain their previous value until updated.
The returned I2C data is stored in consecutive locations of rxBuf.
Example
Set address 0x53, write 0x32, read 6 bytes
Set address 0x1E, write 0x03, read 6 bytes
Set address 0x68, write 0x1B, read 8 bytes
End
2 0x53 5 1 0x32 4 6
2 0x1E 5 1 0x03 4 6
2 0x68 5 1 0x1B 4 8
0
intlgSerialOpen(constchar*serDev,intserBaud,intserFlags)
This function opens a serial device at a specified baud rate and with specified flags.
serDev: the serial device to open
serBaud: the baud rate in bits per second, see below
serFlags: 0
If OK returns a handle (>= 0).
On failure returns a negative error code.
The baud rate must be one of 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600,
19200, 38400, 57600, 115200, or 230400.
No flags are currently defined. This parameter should be set to zero.
intlgSerialClose(inthandle)
This function closes the serial device.
handle: >= 0 (as returned by lgSerialOpen)
If OK returns 0.
On failure returns a negative error code.
intlgSerialWriteByte(inthandle,intbyteVal)
This function writes the byte to the serial device.
handle: >= 0 (as returned by lgSerialOpen)
byteVal: the byte to write.
If OK returns 0.
On failure returns a negative error code.
intlgSerialReadByte(inthandle)
This function reads a byte from the serial device.
handle: >= 0 (as returned by lgSerialOpen)
If OK returns the byte read (0-255).
On failure returns a negative error code.
intlgSerialWrite(inthandle,constchar*txBuf,intcount)
This function writes count bytes from txBuf to the the serial device.
handle: >= 0 (as returned by lgSerialOpen)
txBuf: the array of bytes to write
count: the number of bytes to write
If OK returns 0.
On failure returns a negative error code.
intlgSerialRead(inthandle,char*rxBuf,intcount)
This function reads up count bytes from the the serial device and writes them to rxBuf.
handle: >= 0 (as returned by lgSerialOpen)
rxBuf: an array to receive the read data
count: the maximum number of bytes to read
If OK returns the count of bytes read (>= 0) and updates rxBuf.
On failure returns a negative error code.
intlgSerialDataAvailable(inthandle)
This function returns the count of bytes available to be read from the device.
handle: >= 0 (as returned by lgSerialOpen)
If OK returns the count of bytes available(>= 0).
On failure returns a negative error code.
intlgSpiOpen(intspiDev,intspiChan,intspiBaud,intspiFlags)
This function returns a handle for the SPI device on the channel.
spiDev: >= 0
spiChan: >= 0
spiBaud: the SPI speed to set in bits per second
spiFlags: see below
If OK returns a handle (>= 0).
On failure returns a negative error code.
The flags may be used to modify the default behaviour.
spiFlags consists of the least significant 2 bits.
1 0
m m
mm defines the SPI mode.
Mode POL PHA
0 0 0
1 0 1
2 1 0
3 1 1
The other bits in flags should be set to zero.
intlgSpiClose(inthandle)
This functions closes the SPI device.
handle: >= 0 (as returned by lgSpiOpen)
If OK returns 0.
On failure returns a negative error code.
intlgSpiRead(inthandle,char*rxBuf,intcount)
This function reads count bytes of data from the SPI device.
handle: >= 0 (as returned by lgSpiOpen)
rxBuf: an array to receive the read data bytes
count: the number of bytes to read
If OK returns the count of bytes read and updates rxBuf.
On failure returns a negative error code.
intlgSpiWrite(inthandle,constchar*txBuf,intcount)
This function writes count bytes of data from txBuf to the SPI device.
handle: >= 0 (as returned by lgSpiOpen)
txBuf: the data bytes to write
count: the number of bytes to write
If OK returns the count of bytes written.
On failure returns a negative error code.
intlgSpiXfer(inthandle,constchar*txBuf,char*rxBuf,intcount)
This function transfers count bytes of data from txBuf to the SPI device. Simultaneously count bytes
of data are read from the device and placed in rxBuf.
handle: >= 0 (as returned by lgSpiOpen)
txBuf: the data bytes to write
rxBuf: the received data bytes
count: the number of bytes to transfer
If OK returns the count of bytes transferred and updates rxBuf.
On failure returns a negative error code.
pthread_t*lgThreadStart(lgThreadFunc_tf,void*userdata)
Starts a new thread of execution with f as the main routine.
f: the main function for the new thread
userdata: a pointer to arbitrary user data
If OK returns a pointer to a pthread_t.
On failure returns NULL.
The function is passed the single argument arg.
The thread can be cancelled by passing the pointer to pthread_t to lgThreadStop.
Example
#include <stdio.h>
#include <unistd.h>
#include <lgpio.h>
void *myfunc(void *arg)
{
while (1)
{
printf("%s0, (char *)arg);
sleep(1);
}
}
int main(int argc, char *argv[])
{
pthread_t *p1, *p2, *p3;
p1 = lgThreadStart(myfunc, "thread 1"); sleep(3);
p2 = lgThreadStart(myfunc, "thread 2"); sleep(3);
p3 = lgThreadStart(myfunc, "thread 3"); sleep(3);
lgThreadStop(p3); sleep(3);
lgThreadStop(p2); sleep(3);
lgThreadStop(p1); sleep(3);
}
voidlgThreadStop(pthread_t*pth)
Cancels the thread pointed at by pth.
pth: a thread pointer (as returned by lgThreadStart)
No value is returned.
The thread to be stopped should have been started with lgThreadStart.
uint64_tlguTimestamp(void)
Returns the current timestamp.
The timestamp is the number of nanoseconds since the epoch (start of 1970).
doublelguTime(void)
Returns the current time.
The time is the number of seconds since the epoch (start of 1970).
voidlguSleep(doublesleepSecs)
Sleeps for the specified number of seconds.
sleepSecs: how long to sleep in seconds
intlguSbcName(char*rxBuf,intcount)
Copies the host name of the machine running the lgpio library to the supplied buffer. Up to count
characters are copied.
rxBuf: a buffer to receive the host name
count: the size of the rxBuf
If OK returns the count of bytes copied and updates rxBuf.
On failure returns a negative error code.
intlguVersion(void)
Returns the lgpiolibrary version number.
intlguGetInternal(intcfgId,uint64_t*cfgVal)
Get an internal configuration value.
cfgId: the item.
cfgVal: a variable to receive the returned value
If OK returns 0 and updates cfgVal.
On failure returns a negative error code.
intlguSetInternal(intcfgId,uint64_tcfgVal)
Set an internal configuration value.
cfgId: the item
cfgVal: the value to set
If OK returns 0.
On failure returns a negative error code.
constchar*lguErrorText(interror)
Returns the error text for an error code.
error: the error code
voidlguSetWorkDir(constchar*dirPath)
Sets the library working directory.
This function has no affect if the working directory has already been set.
dirPath: the directory to set as the working directory
If dirPath does not start with a / the directory is relative to the library launch directory.
constchar*lguGetWorkDir(void)
Returns the library working directory.
Install Now
PNG Icons
Emojis