lgpio(3)

📦
version 0.2.0.0 · 3 versions
, in ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 lgpio — the C library that talks to your SBC's GPIO 💖

okay bestie, welcome to lgpio(3), straight outta the lg archive ✨ this is the whole vibe: a C library that lets you control the General Purpose Input Output pins on a Linux Single Board Computer. she's long, she's iconic, and she's about to be your whole personality. let's go 💅

🌸 NAME 🌸

lgpio — a C library to manipulate a local SBC's GPIO. yes. that's the whole job. and she ate. 🫶

✨ SYNOPSIS ✨

#include <lgpio.h>

gcc -Wall -o prog prog.c -llgpio

./prog

like, that's it. that's the ritual. 🎀

🦋 DESCRIPTION 🦋

lgpio is a C library for Linux Single Board Computers which allows control of the General Purpose Input Output pins. that's the mission statement, and she is so committed to it. 🌈

👑 Features

  • reading and writing GPIO singly and in groups
  • software timed PWM and waves
  • GPIO callbacks
  • pipe notification of GPIO alerts
  • I2C wrapper
  • SPI wrapper
  • serial link wrapper
  • a simple interface to start and stop new threads

look at that list. every single one. no skips, no cuts, we love a full feature set fr fr 💖

🧚 Usage

Include <lgpio.h> in your source files.

Assuming your source is in a single file called prog.c use the following command to build and run the executable.

gcc -Wall -o prog prog.c -llgpio

For examples of usage see the C programs within the lg archive file. 🍓

💀 Notes

All the functions which return an int return < 0 on error.

ok so this is THE rule to internalise: if an int comes back negative, something went wrong. that's your vibe check, always. 😭

🌈 OVERVIEW 🌈

⭐ GPIO

  • lgGpiochipOpen — Opens a gpiochip device
  • lgGpiochipClose — Closes a gpiochip device
  • lgGpioGetChipInfo — Gets gpiochip information
  • lgGpioGetLineInfo — Gets gpiochip line information
  • lgGpioGetMode — Gets the mode of a GPIO
  • lgGpioSetUser — Notifies Linux of the GPIO user
  • lgGpioClaimInput — Claims a GPIO for input
  • lgGpioClaimOutput — Claims a GPIO for output
  • lgGpioClaimAlert — Claims a GPIO for alerts
  • lgGpioFree — Frees a GPIO
  • lgGroupClaimInput — Claims a group of GPIO for inputs
  • lgGroupClaimOutput — Claims a group of GPIO for outputs
  • lgGroupFree — Frees a group of GPIO
  • lgGpioRead — Reads a GPIO
  • lgGpioWrite — Writes a GPIO
  • lgGroupRead — Reads a group of GPIO
  • lgGroupWrite — Writes a group of GPIO
  • lgTxPulse — Starts pulses on a GPIO
  • lgTxPwm — Starts PWM pulses on a GPIO
  • lgTxServo — Starts Servo pulses on a GPIO
  • lgTxWave — Starts a wave on a group of GPIO
  • lgTxBusy — See if tx is active on a GPIO or group
  • lgTxRoom — See if more room for tx on a GPIO or group
  • lgGpioSetDebounce — Sets the debounce time for a GPIO
  • lgGpioSetWatchdog — Sets the watchdog time for a GPIO
  • lgGpioSetAlertsFunc — Starts a GPIO callback
  • lgGpioSetSamplesFunc — Starts a GPIO callback for all GPIO

🔥 I2C

  • lgI2cOpen — Opens an I2C device
  • lgI2cClose — Closes an I2C device
  • lgI2cWriteQuick — SMBus write quick
  • lgI2cReadByte — SMBus read byte
  • lgI2cWriteByte — SMBus write byte
  • lgI2cReadByteData — SMBus read byte data
  • lgI2cWriteByteData — SMBus write byte data
  • lgI2cReadWordData — SMBus read word data
  • lgI2cWriteWordData — SMBus write word data
  • lgI2cReadBlockData — SMBus read block data
  • lgI2cWriteBlockData — SMBus write block data
  • lgI2cReadI2CBlockData — SMBus read I2C block data
  • lgI2cWriteI2CBlockData — SMBus write I2C block data
  • lgI2cReadDevice — Reads the raw I2C device
  • lgI2cWriteDevice — Writes the raw I2C device
  • lgI2cProcessCall — SMBus process call
  • lgI2cBlockProcessCall — SMBus block process call
  • lgI2cSegments — Performs multiple I2C transactions
  • lgI2cZip — Performs multiple I2C transactions

💌 NOTIFICATIONS

  • lgNotifyOpen — Request a notification
  • lgNotifyClose — Close a notification
  • lgNotifyPause — Pause notifications
  • lgNotifyResume — Start notifications

🎀 SERIAL

  • lgSerialOpen — Opens a serial device
  • lgSerialClose — Closes a serial device
  • lgSerialReadByte — Reads a byte from a serial device
  • lgSerialWriteByte — Writes a byte to a serial device
  • lgSerialRead — Reads bytes from a serial device
  • lgSerialWrite — Writes bytes to a serial device
  • lgSerialDataAvailable — Returns number of bytes ready to be read

🫶 SPI

  • lgSpiOpen — Opens a SPI device
  • lgSpiClose — Closes a SPI device
  • lgSpiRead — Reads bytes from a SPI device
  • lgSpiWrite — Writes bytes to a SPI device
  • lgSpiXfer — Transfers bytes with a SPI device

💜 THREADS

  • lgThreadStart — Start a new thread
  • lgThreadStop — Stop a previously started thread

🌸 UTILITIES

  • lguVersion — Gets the library version
  • lguSbcName — Gets the host name of the SBC
  • lguGetInternal — Get an internal configuration value
  • lguSetInternal — Set an internal configuration value
  • lguSleep — Sleeps for a given time
  • lguTimestamp — Gets the current timestamp
  • lguTime — Gets the current time
  • lguErrorText — Gets a text description of an error code
  • lguSetWorkDir — Set the working directory
  • lguGetWorkDir — Get the working directory

👑 FUNCTIONS 👑

int lgGpiochipOpen(int gpioDev)

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
}

int lgGpiochipClose(int handle)

This closes an opened gpiochip device. bye bestie 👋

  • 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
}

int lgGpioGetChipInfo(int handle, lgChipInfo_p chipInfo)

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))
}

int lgGpioGetLineInfo(int handle, int gpio, lgLineInfo_p lineInfo)

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))
}

int lgGpioGetMode(int handle, int gpio)

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 0, value 1 — Kernel: In use by the kernel
  • bit 1, value 2 — Kernel: Output
  • bit 2, value 4 — Kernel: Active low
  • bit 3, value 8 — Kernel: Open drain
  • bit 4, value 16 — Kernel: Open source
  • bit 5, value 32 — Kernel: Pull up set
  • bit 6, value 64 — Kernel: Pull down set
  • bit 7, value 128 — Kernel: Pulls off set
  • bit 8, value 256 — LG: Input
  • bit 9, value 512 — LG: Output
  • bit 10, value 1024 — LG: Alert
  • bit 11, value 2048 — LG: Group
  • bit 12, value 4096 — LG: ---
  • bit 13, value 8192 — LG: ---
  • bit 14, value 16384 — LG: ---
  • bit 15, value 32768 — LG: ---
  • bit 16, value 65536 — Kernel: Input
  • bit 17, value 1<<17 — Kernel: Rising edge alert
  • bit 18, value 1<<18 — Kernel: Falling edge alert
  • bit 19, value 1<<19 — Kernel: Realtime clock alert
heads up bestie: the LG bits are only set if the query was made by the process that owns the GPIO. 🔥

int lgGpioSetUser(int handle, const char *gpiouser)

This sets the user string to be associated with each claimed GPIO. like a little name tag 🏷️

  • 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");

int lgGpioClaimInput(int handle, int lFlags, int gpio)

This claims a GPIO for input. she's listening 👂

  • 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);

int lgGpioClaimOutput(int handle, int lFlags, int gpio, int level)

This claims a GPIO for output. now she's talking 🗣️

  • 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);

int lgGpioClaimAlert(int handle, int lFlags, int eFlags, int gpio, int nfyHandle)

This claims a GPIO for alerts on level changes. 🚨 she's noticing things

  • 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.

and that's part 1 bestie — more coming, don't go anywhere 💖

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);

int lgGpioFree(int handle, int gpio)

This frees a GPIO. bye bestie 👋💖

  • 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. it's free real estate now 🦋

Example

status = lgGpioFree(h, 16);

int lgGroupClaimInput(int handle, int lFlags, int count, const int *gpios)

This claims a group of GPIO for inputs. group project but make it GPIO 🎀

  • 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
}

int lgGroupClaimOutput(int handle, int lFlags, int count, const int *gpios, const int *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. no cap, zero = low, anything else = 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
}

int lgGroupFree(int handle, int gpio)

This frees all the GPIO associated with a group. the whole squad, gone 🫶

  • 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

int lgGpioRead(int handle, int gpio)

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

int lgGpioWrite(int handle, int gpio, int level)

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

int lgGroupRead(int handle, int gpio, 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
}

int lgGroupWrite(int handle, int gpio, uint64_t groupBits, uint64_t groupMask)

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. so like, mask bit off = hands off, don't touch 🙈

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);

int lgTxPulse(int handle, int gpio, int pulseOn, int pulseOff, int pulseOffset, int pulseCycles)

This starts software timed pulses on an output GPIO. blink blink blink 🔥

  • 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. 💀 (yes, "compete" — that's what the page says, we don't make the rules)

Multiple pulse settings may be queued in this way. it's giving queue energy 👑

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

int lgTxPwm(int handle, int gpio, float pwmFrequency, float pwmDutyCycle, int pwmOffset, int pwmCycles)

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. 🎀

int lgTxServo(int handle, int gpio, int pulseWidth, int servoFrequency, int servoOffset, int servoCycles)

okay bestie, this one kicks off software timed servo pulses on an output GPIO. ✨

🚨 real talk: only use software timed servo pulses for testing purposes. The timing jitter is gonna make your servo fidget, and that can make it overheat and wear out prematurely. It's giving sad servo energy, we don't want that.
  • 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 it's giving success, it returns the number of entries left in the PWM queue for the GPIO.

On failure it returns a negative error code.

Every single successful call to this function consumes one PWM queue entry. One in, one out, no cap.

Another servo command may be issued to the GPIO before the last one has finished. Iconic behaviour honestly.

If the last pulse had infinite cycles, it gets replaced by the new settings at the end of the current cycle. Otherwise it gets replaced by the new settings when all its cycles are complete.

Multiple servo settings may be queued up this way. It's a whole line of vibes waiting their turn. 💅

int lgTxWave(int handle, int gpio, int count, lgPulse_p pulses)

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 it goes well, it returns the number of entries left in the wave queue for the group.

On failure it returns a negative error code.

Every successful call to this function consumes one queue entry.

This command starts a wave of pulses, periodt.

pulses is an array of pulses to be transmitted on the group.

Each pulse is defined by this lil 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 one has finished transmission. The new wave will start when the previous wave has completed. So you can stack them. 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);
}

int lgTxBusy(int handle, int gpio, int kind)

Returns true if transmissions of the specified kind are active on the GPIO or group. Basically the "are we still going bestie" check. 💫

  • handle — >= 0 (as returned by lgGpiochipOpen)
  • gpio — the gpio or group to be checked
  • kind — LG_TX_PWM or LG_TX_WAVE

If OK it returns 1 for busy and 0 for not busy.

On failure it returns a negative error code.

Example

while (lgTxBusy(h, 15, LG_TX_PWM)) // wait for PWM to finish on GPIO 15
   lguSleep(0.1);

int lgTxRoom(int handle, int gpio, int kind)

This one tells you how many entries are available for queueing transmissions of the specified kind on the GPIO or group. Like checking how much room's left in the group chat. 🎀

  • handle — >= 0 (as returned by lgGpiochipOpen)
  • gpio — the gpio or group to be checked
  • kind — LG_TX_PWM or LG_TX_WAVE

If OK it returns the number of free entries (0 if none).

On failure it returns a negative error code.

Example

while (lgTxRoom(h, 17, LG_TX_WAVE) > 0))
{
   // queue another wave
}

int lgGpioSetDebounce(int handle, int gpio, int debounce_us)

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 it returns 0.

On failure it returns a negative error code.

This only affects alerts, bestie. 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). We love a stable queen. ✨

Suppose 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

int lgGpioSetWatchdog(int handle, int gpio, int watchdog_us)

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 it returns 0.

On failure it 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. It's the "hello?? are you still there??" of GPIO. 😭

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

int lgGpioSetAlertsFunc(int handle, int gpio, lgGpioAlertsFunc_t cbf, void *userdata)

Sets up a callback to be called when an alert GPIO changes state. This is where the main character energy lives. 🦋

  • 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 it returns 0.

On failure it 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)

void lgGpioSetSamplesFunc(lgGpioAlertsFunc_t cbf, void *userdata)

Sets up a callback to be called when any alert GPIO changes state. All of them. Every single one. The whole squad. 🌈

  • cbf — the callback function
  • userdata — a pointer to arbitrary user data

If OK it returns 0.

On failure it 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)

int lgNotifyOpen(void)

This function requests a free notification. 🧚

If OK it returns a handle (>= 0).

On failure it 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.
}

🫶 int lgNotifyResume(int handle)

This one un-pauses a notification that was paused. Like hitting play again bestie, the tea starts flowing once more. ✨

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

Future-proofing moment 💅 — for future proofing it is probably best to ignore any notification with non-zero flags.

Example

// Start notifications for associated GPIO.
lgNotifyResume(h);

🌸 int lgNotifyPause(int handle)

This function pauses notifications. It's giving "brb" energy. 😭

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);

🎀 int lgNotifyClose(int handle)

This function stops notifications and frees the handle for reuse. She's done, she's clocking out, no cap. 👑

handle: >= 0 (as returned by lgNotifyOpen)

If OK returns 0.

On failure returns a negative error code.

Example

lgNotifyClose(h);

🦋 int lgI2cOpen(int i2cDev, int i2cAddr, int i2cFlags)

This returns a handle for the device at the address on the I2C bus. Bestie, you're about to talk to a whole chip over two little wires. Iconic. ✨

  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

💜 int lgI2cClose(int handle)

This closes the I2C device. Say bye, she's leaving the group chat. 🫶

handle: >= 0 (as returned by lgI2cOpen)

If OK returns 0.

On failure returns a negative error code.

🌈 int lgI2cWriteQuick(int handle, int bitVal)

This sends a single bit (in the Rd/Wr bit) to the device. Literally one single bit, the smallest possible gossip. 🍓

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

⭐ int lgI2cWriteByte(int handle, int byteVal)

This sends a single byte to the device. One byte, one vibe. 💫

 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

🌸 int lgI2cReadByte(int handle)

This reads a single byte from the device. She's listening. 👂

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

🎀 int lgI2cWriteByteData(int handle, int i2cReg, int byteVal)

This writes a single byte to the specified register of the device. Register-pilled. 💅

 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

🔥 int lgI2cWriteWordData(int handle, int i2cReg, int wordVal)

This writes a single 16 bit word to the specified register of the device. Double the bytes, double the slay. ✨

 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

🦋 int lgI2cReadByteData(int handle, int i2cReg)

This reads a single byte from the specified register of the device. Peeking at one little register, respectfully. 🙈

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

💖 int lgI2cReadWordData(int handle, int i2cReg)

This reads a single 16 bit word from the specified register of the device. Two bytes walk in, one word walks out. 😌

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

🌈 int lgI2cProcessCall(int handle, int i2cReg, int wordVal)

This writes 16 bits of data to the specified register of the device and reads 16 bits of data in return. It's giving conversation — you say something, they say something back. No cap. 💬

 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

🎀 int lgI2cWriteBlockData(int handle, int i2cReg, const char *txBuf, int count)

This writes up to 32 bytes to the specified register of the device. A whole little block of tea, sent in one go. 📦

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

🌸 int lgI2cReadBlockData(int handle, int i2cReg, char *rxBuf)

This reads a block of up to 32 bytes from the specified register of the device. She's receiving, and honestly? She's thriving. 💅

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

⭐ int lgI2cBlockProcessCall(int handle, int i2cReg, char *ioBuf, int count)

This writes data bytes to the specified register of the device and reads a device specified number of bytes of data in return. One buffer, doing double duty, main character energy. 👑

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

🫶 int lgI2cReadI2CBlockData(int handle, int i2cReg, char *rxBuf, int count)

This reads count bytes from the specified register of the device. The count may be 1-32. You decide how much you want, bestie, you set the boundaries. ✨

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

🦋 int lgI2cWriteI2CBlockData(int handle, int i2cReg, const char *txBuf, int count)

This writes 1 to 32 bytes to the specified register of the device. Sending the whole block, no crumbs left. 🍓

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

💜 int lgI2cReadDevice(int handle, char *rxBuf, int count)

This reads count bytes from the raw device into rxBuf. No register, no middleman, just raw device talk. 😤

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

🌈 int lgI2cWriteDevice(int handle, const char *txBuf, int count)

This writes count bytes from txBuf to the raw device. Straight to the source, no filter, periodt. 💅

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

🎀 int lgI2cSegments(int handle, lgI2cMsg_t *segs, int count)

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.

int lgI2cZip(int handle, const char *txBuf, int txCount, char *rxBuf, int rxCount)

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:

  • 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

int lgSerialOpen(const char *serDev, int serBaud, int serFlags)

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.

int lgSerialClose(int handle)

This function closes the serial device.

  • handle: >= 0 (as returned by lgSerialOpen)

If OK returns 0.

On failure returns a negative error code.

int lgSerialWriteByte(int handle, int byteVal)

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.

int lgSerialReadByte(int handle)

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.

int lgSerialWrite(int handle, const char *txBuf, int count)

This function writes count bytes from txBuf to 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.

int lgSerialRead(int handle, char *rxBuf, int count)

This function reads up count bytes from 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.

int lgSerialDataAvailable(int handle)

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.

int lgSpiOpen(int spiDev, int spiChan, int spiBaud, int spiFlags)

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 0: POL 0, PHA 0
  • Mode 1: POL 0, PHA 1
  • Mode 2: POL 1, PHA 0
  • Mode 3: POL 1, PHA 1

The other bits in flags should be set to zero.

int lgSpiClose(int handle)

This function closes the SPI device.

  • handle: >= 0 (as returned by lgSpiOpen)

If OK returns 0.

On failure returns a negative error code.

int lgSpiRead(int handle, char *rxBuf, int count)

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.

int lgSpiWrite(int handle, const char *txBuf, int count)

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.

int lgSpiXfer(int handle, const char *txBuf, char *rxBuf, int count)

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_t f, 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);
}

void lgThreadStop(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_t lguTimestamp(void)

Returns the current timestamp.

The timestamp is the number of nanoseconds since the epoch (start of 1970).

double lguTime(void)

Returns the current time.

The time is the number of seconds since the epoch (start of 1970).

void lguSleep(double sleepSecs)

Sleeps for the specified number of seconds.

  • sleepSecs: how long to sleep in seconds

int lguSbcName(char *rxBuf, int count)

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.

int lguVersion(void)

Returns the lgpio library version number.

int lguGetInternal(int cfgId, 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.

int lguSetInternal(int cfgId, uint64_t cfgVal)

Set an internal configuration value.

  • cfgId: the item
  • cfgVal: the value to set

If OK returns 0.

On failure returns a negative error code.

const char *lguErrorText(int error)

Returns the error text for an error code.

  • error: the error code

void lguSetWorkDir(const char *dirPath)

Sets the library working directory.

This function has no effect 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.

const char *lguGetWorkDir(void)

Returns the library working directory.

💅 PARAMETERS 💅

Every single parameter type in this API, bestie. No skips, no cap. 💖

  • bitVal — a value of 0 or 1. ✨
  • byteVal: 0-255 — an 8-bit byte value. 💅
  • cbf — an alerts callback function. 🦋
  • cfgId — a number identifying a configuration item. 👑
LG_CFG_ID_DEBUG_LEVEL 0
LG_CFG_ID_MIN_DELAY   1
  • cfgVal — the value of a configuration item. 🌸
  • *cfgVal — the value of a configuration item. (Yes, same vibe, different pointer star. 💀)
  • char — a single character, an 8 bit quantity able to store 0-255. 🎀
  • chipInfo — a pointer to a lgChipInfo_t object. 🧚
  • count — the number of items. 🔥
  • debounce_us — the debounce time in microseconds. ⭐
  • *dirPath — a directory path which. (fr fr, that's literally where it ends. iconic 😭)
  • double — a floating point number. ✨
  • eFlags — the type of GPIO edge to generate an alert. See lgGpioClaimAlert. 🦋
    • LG_RISING_EDGE
    • LG_FALLING_EDGE
    • LG_BOTH_EDGES
  • error — an error code. All error codes are negative. 💀
  • f — a function. 👑
  • float — a floating point number ✨
  • gpio — a GPIO number, the offset of the GPIO from the base of the gpiochip. Offsets start at 0. 💅
  • gpioDev: >= 0 — the device number of a gpiochip. 🌈
  • *gpios — an array of GPIO numbers. 🎀
  • *gpiouser — a string of up to 32 characters denoting the user of a GPIO. 💖
  • groupBits — a 64-bit value used to set the levels of a group. 👑
    • Set bit x to set GPIO x of the group high.
    • Clear bit x to set GPIO x of the group low.
  • *groupBits — a 64-bit value denoting the levels of a group. ✨
    • If bit x is set then GPIO x of the group is high.
  • groupMask — a 64-bit value used to determine which members of a group should be updated. 🦋
    • Set bit x to update GPIO x of the group.
    • Clear bit x to leave GPIO x of the group unaltered.
  • handle: >= 0 — a number referencing an object opened by one of: 💅
    • lgGpiochipOpen
    • lgI2cOpen
    • lgNotifyOpen
    • lgSerialOpen
    • lgSpiOpen
  • i2cAddr: 0-0x7F — the address of a device on the I2C bus. 🎀
  • i2cDev: >= 0 — an I2C device number. 🌸
  • i2cFlags: 0 — flags which modify an I2C open command. None are currently defined. 💀
  • i2cReg: 0-255 — a register of an I2C device. 🧚
  • int — a whole number, negative or positive. 👑
  • *ioBuf — a pointer to a buffer used to hold data to send and the data received. 🔥
  • kind: LG_TX_PWM or LG_TX_WAVE — a type of transmission: PWM or wave. ⭐
  • level — a GPIO level (0 or 1). 💅
  • *levels — an array of GPIO levels. 🌈
  • lFlags — line flags for the GPIO. 🦋

The following values may be or'd to form the value.

  • LG_SET_ACTIVE_LOW
  • LG_SET_OPEN_DRAIN
  • LG_SET_OPEN_SOURCE
  • LG_SET_PULL_UP
  • LG_SET_PULL_DOWN
  • LG_SET_PULL_NONE
  • lgChipInfo_p — a pointer to a lgChipInfo_t object. 🎀
typedef struct lgChipInfo_s
{
   uint32_t lines;                // number of GPIO
   char name[LG_GPIO_NAME_LEN];   // Linux name
   char label[LG_GPIO_LABEL_LEN]; // functional name
} lgChipInfo_t, *lgChipInfo_p;
  • lgGpioAlert_t — 🫶
typedef struct lgGpioAlert_s
{
   lgGpioReport_t report;
   int nfyHandle;
} lgGpioAlert_t, *lgGpioAlert_p;

See lgGpioReport_t.

  • lgGpioAlertsFunc_t — 💖
typedef void (*lgGpioAlertsFunc_t)
   (int num_alerts, lgGpioAlert_p alerts, void *userdata);

See lgGpioAlert_t.

  • lgGpioReport_t — 👑
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=watchdog
   uint8_t flags;      // none defined, ignore report if non-zero
} lgGpioReport_t;
  • lgI2cMsg_t — 🦋
typedef struct
{
   uint16_t addr;  // slave address
   uint16_t flags;
   uint16_t len;   // msg length
   uint8_t  *buf;  // pointer to msg data
} lgI2cMsg_t;
  • lgLineInfo_p — a pointer to a lgLineInfo_t object. 🌸
typedef struct lgLine_s
{
   uint32_t offset;               // GPIO number
   uint32_t lFlags;
   char name[LG_GPIO_NAME_LEN];   // GPIO name
   char user[LG_GPIO_USER_LEN];   // user
} lgLineInfo_t, *lgLineInfo_p;
  • lgPulse_p — a pointer to a lgPulse_t object. ✨
typedef struct lgPulse_s
{
   uint64_t bits;
   uint64_t mask;
   int64_t delay;
} lgPulse_t, *lgPulse_p;
  • lgThreadFunc_t — 🧚
typedef void *(lgThreadFunc_t) (void *);
  • lineInfo — a pointer to a lgLineInfo_t object. 💅
  • nfyHandle: >= 0 — this associates a notification with a GPIO alert. 🔥
  • *pth — a thread identifier, returned by lgGpioStartThread. ⭐
  • pthread_t — a thread identifier. 🌈
  • pulseCycles: >= 0 — the number of PWM pulses to generate. A value of 0 means infinite. 👑
  • pulseOff: >= 0 — the off period for a PWM pulse in microseconds. 🎀
  • pulseOffset: >= 0 — the offset in microseconds from the nominal PWM pulse start. 💖
  • pulseOn: >= 0 — the on period for a PWM pulse in microseconds. 🦋
  • pulses — An pointer to an array of lgPulse_t objects. 🌸
  • pulseWidth: 0, 500-2500 microseconds — Servo pulse width 🌸
  • pwmCycles: >= 0 — the number of PWM pulses to generate. A value of 0 means infinite. 💀
  • pwmDutyCycle: 0-100 % — PWM duty cycle % ✨
  • pwmFrequency: 0.1-10000 Hz — PWM frequency 🎀
  • pwmOffset: >= 0 — the offset in microseconds from the nominal PWM pulse start. 💅
  • *rxBuf — a pointer to a buffer used to receive data. 🔥
  • rxCount — the size of an input buffer. ⭐
  • *segs — an array of segments which make up a combined I2C transaction. 🌈
  • serBaud — the speed of serial communication in bits per second. 👑
  • *serDev — the name of a serial tty device, e.g. /dev/ttyAMA0, /dev/ttyUSB0, /dev/tty1. 🦋
  • serFlags — flags which modify a serial open command. None are currently defined. 💀
  • servoCycles: >= 0 — the number of servo pulses to generate. A value of 0 means infinite. 💖
  • servoFrequency: 40-500 Hz — Servo pulse frequency 🎀
  • servoOffset: >= 0 — the offset in microseconds from the nominal servo pulse start. 🌸
  • sleepSecs: >= 0.0 — the number of seconds to sleep (may be fractional). ✨
  • spiBaud — the speed of serial communication in bits per second. 🧚
  • spiChan — a SPI channel, >= 0. 💅
  • spiDev — a SPI device, >= 0. 🔥
  • spiFlags — See lgSpiOpen. ⭐
  • *txBuf — An pointer to a buffer of data to transmit. 🌈
  • txCount — the size of an output buffer. 🌈
  • uint64_t — a 64-bit unsigned value. 👑
  • *userdata — a pointer to arbitrary user data. This may be used to identify the instance. 💖

You must ensure that the pointer is in scope at the time it is processed. If it is a pointer to a global this is automatic. Do not pass the address of a local variable. If you want to pass a transient object then use the following technique. 🫶

In the calling function:

user_type *userdata;
user_type my_userdata;

userdata = malloc(sizeof(user_type));
*userdata = my_userdata;

In the receiving function:

user_type my_userdata = *(user_type*)userdata;

free(userdata);
  • void — denoting no parameter is required. 🎀
  • watchdog_us — the watchdog time in microseconds. 💀
  • wordVal: 0-65535 — a 16-bit value. ✨

💖 ERROR CODES 💖

okay bestie, deep breath, this is the big one 🌈. Every single thing lgpio can come back at you with lives here. Zero means we ate. Anything negative means something went sideways and the number tells you exactly which way. Clock that each one is a #define-style constant with a lil integer value next to it, and the trailing comment is the official translation. Slay 💅

  • LG_OKAY — 0 — no error, everything's giving flawless ✨
  • LG_INIT_FAILED — -1 — initialisation failed 😭
  • LG_BAD_MICROS — -2 — micros not in the 0-999999 range 🙈
  • LG_BAD_PATHNAME — -3 — can not open the pathname 🚫
  • LG_NO_HANDLE — -4 — no handle available, they're all taken 💀
  • LG_BAD_HANDLE — -5 — unknown handle, who even is she 🎀
  • LG_BAD_SOCKET_PORT — -6 — socket port not in the 1024-32000 range 🧚
  • LG_NOT_PERMITTED — -7 — GPIO operation not permitted, the vibes are blocked 🔒
  • LG_SOME_PERMITTED — -8 — one or more GPIO not permitted 👀
  • LG_BAD_SCRIPT — -9 — invalid script, the plot isn't plotting 📜
  • LG_BAD_TX_TYPE — -10 — bad tx type for GPIO and group 🌸
  • LG_GPIO_IN_USE — -11 — GPIO already in use, she's taken 💖
  • LG_BAD_PARAM_NUM — -12 — script parameter id not 0-9 🔢
  • LG_DUP_TAG — -13 — script has a duplicate tag 👯
  • LG_TOO_MANY_TAGS — -14 — script has too many tags, tag hoarder 🏷️
  • LG_BAD_SCRIPT_CMD — -15 — illegal script command ⛔
  • LG_BAD_VAR_NUM — -16 — script variable id not 0-149 🔢
  • LG_NO_SCRIPT_ROOM — -17 — no more room for scripts, the club is full 🪩
  • LG_NO_MEMORY — -18 — can not allocate temporary memory 😵
  • LG_SOCK_READ_FAILED — -19 — socket read failed 📭
  • LG_SOCK_WRIT_FAILED — -20 — socket write failed 📮
  • LG_TOO_MANY_PARAM — -21 — too many script parameters (> 10) 🫠
  • LG_SCRIPT_NOT_READY — -22 — script still initialising, give her a sec ⏳
  • LG_BAD_TAG — -23 — script has an unresolved tag 🔍
  • LG_BAD_MICS_DELAY — -24 — bad MICS delay (too large) ⏱️
  • LG_BAD_MILS_DELAY — -25 — bad MILS delay (too large) ⏱️
  • LG_I2C_OPEN_FAILED — -26 — can not open I2C device 🔌
  • LG_SERIAL_OPEN_FAILED — -27 — can not open serial device 🔌
  • LG_SPI_OPEN_FAILED — -28 — can not open SPI device 🔌
  • LG_BAD_I2C_BUS — -29 — bad I2C bus 🚌
  • LG_BAD_I2C_ADDR — -30 — bad I2C address 📬
  • LG_BAD_SPI_CHANNEL — -31 — bad SPI channel 📺
  • LG_BAD_I2C_FLAGS — -32 — bad I2C open flags 🚩
  • LG_BAD_SPI_FLAGS — -33 — bad SPI open flags 🚩
  • LG_BAD_SERIAL_FLAGS — -34 — bad serial open flags 🚩
  • LG_BAD_SPI_SPEED — -35 — bad SPI speed 🏎️
  • LG_BAD_SERIAL_DEVICE — -36 — bad serial device name 🏷️
  • LG_BAD_SERIAL_SPEED — -37 — bad serial baud rate 🐢
  • LG_BAD_FILE_PARAM — -38 — bad file parameter 📄
  • LG_BAD_I2C_PARAM — -39 — bad I2C parameter 🔧
  • LG_BAD_SERIAL_PARAM — -40 — bad serial parameter 🔧
  • LG_I2C_WRITE_FAILED — -41 — i2c write failed ✍️
  • LG_I2C_READ_FAILED — -42 — i2c read failed 👓
  • LG_BAD_SPI_COUNT — -43 — bad SPI count 🔢
  • LG_SERIAL_WRITE_FAILED — -44 — ser write failed ✍️
  • LG_SERIAL_READ_FAILED — -45 — ser read failed 👓
  • LG_SERIAL_READ_NO_DATA — -46 — ser read no data available, she's ghosting 📵
  • LG_UNKNOWN_COMMAND — -47 — unknown command, never heard of her 💀
  • LG_SPI_XFER_FAILED — -48 — spi xfer/read/write failed 🛰️
  • LG_BAD_POINTER — -49 — bad (NULL) pointer 🎯
  • LG_MSG_TOOBIG — -50 — socket/pipe message too big 🐘
  • LG_BAD_MALLOC_MODE — -51 — bad memory allocation mode 🧠
  • LG_TOO_MANY_SEGS — -52 — too many I2C transaction segments ✂️
  • LG_BAD_I2C_SEG — -53 — an I2C transaction segment failed 💔
  • LG_BAD_SMBUS_CMD — -54 — SMBus command not supported by driver 🙅
  • LG_BAD_I2C_WLEN — -55 — bad I2C write length 📏
  • LG_BAD_I2C_RLEN — -56 — bad I2C read length 📏
  • LG_BAD_I2C_CMD — -57 — bad I2C command ⛔
  • LG_FILE_OPEN_FAILED — -58 — file open failed 📂
  • LG_BAD_FILE_MODE — -59 — bad file mode 🎛️
  • LG_BAD_FILE_FLAG — -60 — bad file flag 🚩
  • LG_BAD_FILE_READ — -61 — bad file read 👓
  • LG_BAD_FILE_WRITE — -62 — bad file write ✍️
  • LG_FILE_NOT_ROPEN — -63 — file not open for read 🙅
  • LG_FILE_NOT_WOPEN — -64 — file not open for write 🙅
  • LG_BAD_FILE_SEEK — -65 — bad file seek 🔎
  • LG_NO_FILE_MATCH — -66 — no files match the pattern 🫥
  • LG_NO_FILE_ACCESS — -67 — no permission to access the file 🔒
  • LG_FILE_IS_A_DIR — -68 — file is a directory 📁 (not what you thought bestie)
  • LG_BAD_SHELL_STATUS — -69 — bad shell return status 🐚
  • LG_BAD_SCRIPT_NAME — -70 — bad script name 🏷️
  • LG_CMD_INTERRUPTED — -71 — Python socket command interrupted ✋
  • LG_BAD_EVENT_REQUEST — -72 — bad event request 📅
  • LG_BAD_GPIO_NUMBER — -73 — bad GPIO number 🔢
  • LG_BAD_GROUP_SIZE — -74 — bad group size 👥
  • LG_BAD_LINEINFO_IOCTL — -75 — bad lineinfo IOCTL 🎚️
  • LG_BAD_READ — -76 — bad GPIO read 👓
  • LG_BAD_WRITE — -77 — bad GPIO write ✍️
  • LG_CANNOT_OPEN_CHIP — -78 — can not open gpiochip 🚪
  • LG_GPIO_BUSY — -79 — GPIO busy, she's booked and blessed 💅
  • LG_GPIO_NOT_ALLOCATED — -80 — GPIO not allocated 🫥
  • LG_NOT_A_GPIOCHIP — -81 — not a gpiochip 🚫
  • LG_NOT_ENOUGH_MEMORY — -82 — not enough memory 😵
  • LG_POLL_FAILED — -83 — GPIO poll failed 📊
  • LG_TOO_MANY_GPIOS — -84 — too many GPIO 🫠
  • LG_UNEGPECTED_ERROR — -85 — unexpected error 😱 (yes that's the actual spelling in the source, iykyk, no notes 💀)
  • LG_BAD_PWM_MICROS — -86 — bad PWM micros 🌊
  • LG_NOT_GROUP_LEADER — -87 — GPIO not the group leader 👑 (main character only)
  • LG_SPI_IOCTL_FAILED — -88 — SPI iOCTL failed 🎚️
  • LG_BAD_GPIOCHIP — -89 — bad gpiochip 🔧
  • LG_BAD_CHIPINFO_IOCTL — -90 — bad chipinfo IOCTL 🎚️
  • LG_BAD_CONFIG_FILE — -91 — bad configuration file ⚙️
  • LG_BAD_CONFIG_VALUE — -92 — bad configuration value ⚙️
  • LG_NO_PERMISSIONS — -93 — no permission to perform action 🔒
  • LG_BAD_USERNAME — -94 — bad user name 🏷️
  • LG_BAD_SECRET — -95 — bad secret for user 🤫
  • LG_TX_QUEUE_FULL — -96 — TX queue full, she's overflowing 📬
  • LG_BAD_CONFIG_ID — -97 — bad configuration id 🔢
  • LG_BAD_DEBOUNCE_MICS — -98 — bad debounce microseconds 🏓
  • LG_BAD_WATCHDOG_MICS — -99 — bad watchdog microseconds 🐕
  • LG_BAD_SERVO_FREQ — -100 — bad servo frequency 📻
  • LG_BAD_SERVO_WIDTH — -101 — bad servo pulsewidth 📏
  • LG_BAD_PWM_FREQ — -102 — bad PWM frequency 📻
  • LG_BAD_PWM_DUTY — -103 — bad PWM dutycycle ⚖️
  • LG_GPIO_NOT_AN_OUTPUT — -104 — GPIO not set as an output 📤
  • LG_INVALID_GROUP_ALERT — -105 — can not set a group to alert 🚨
💡 pro tip bestie: when something returns one of these, it's negative, so < 0 means "check which one it is". The named constant is the whole point — don't just stare at the raw number like it's a cryptic text from your ex 🫶

🌈 SEE ALSO 🌈

go read these next, they're the friend group:

aaaand that's the whole page bestie, you made it to the end 🎉💖 slay, go write some GPIO. this one's from the lgpio(3) man page on Linux, dated 2020-2021, and it's giving ✨ documentation era ✨. mwah, go forth and blink an LED for me 🦋🌸

📦 where this page comes from