Class Waves

Provides Waveform methods for the pigpio library. These are methods to send pulses on the pins with precise timing.

Inheritance
Object
Waves
Inherited Members
Namespace: Unosquare.PiGpio.NativeMethods
Syntax
public static class Waves

Methods

GpioWaveAddGeneric(UInt32, GpioPulse[])

This function adds a number of pulses to the current waveform.

The pulses are interleaved in time order within the existing waveform (if any).

Merging allows the waveform to be built in parts, that is the settings for GPIO#1 can be added, and then GPIO#2 etc.

If the added waveform is intended to start after or within the existing waveform then the first pulse should consist of a delay.

Declaration
public static int GpioWaveAddGeneric(uint numPulses, GpioPulse[] pulses)
Parameters
Type Name Description
UInt32 numPulses

the number of pulses.
GpioPulse[] pulses

an array of pulses.
Returns
Type Description
Int32

Returns the new total number of pulses in the current waveform if OK, otherwise PI_TOO_MANY_PULSES.
Examples
// Construct and send a 30 microsecond square wave.

gpioSetMode(gpio, PI_OUTPUT);

pulse[0].gpioOn = (1<<gpio);
pulse[0].gpioOff = 0;
pulse[0].usDelay = 15;

pulse[1].gpioOn = 0;
pulse[1].gpioOff = (1<<gpio);
pulse[1].usDelay = 15;

gpioWaveAddNew();

gpioWaveAddGeneric(2, pulse);

wave_id = gpioWaveCreate();

if (wave_id >= 0)
{
   gpioWaveTxSend(wave_id, PI_WAVE_MODE_REPEAT);

   // Transmit for 30 seconds.

   sleep(30);

   gpioWaveTxStop();
}
else
{
   // Wave create failed.
}

GpioWaveAddNew()

This function starts a new empty waveform.

You wouldn't normally need to call this function as it is automatically called after a waveform is created with the GpioWaveCreate() function.

Declaration
public static int GpioWaveAddNew()
Returns
Type Description
Int32

Returns 0 if OK.
Examples
gpioWaveAddNew();

GpioWaveAddSerial(UserGpio, UInt32, UInt32, UInt32, UInt32, UInt32, Byte[])

This function adds a waveform representing serial data to the existing waveform (if any). The serial data starts offset microseconds from the start of the waveform.

NOTES:

The serial data is formatted as one start bit, data_bits data bits, and stop_bits/2 stop bits.

It is legal to add serial data streams with different baud rates to the same waveform.

numBytes is the number of bytes of data in str.

The bytes required for each character depend upon data_bits.

For data_bits 1-8 there will be one byte per character. For data_bits 9-16 there will be two bytes per character. For data_bits 17-32 there will be four bytes per character.

Declaration
public static int GpioWaveAddSerial(UserGpio userGpio, uint baudRate, uint dataBits, uint stopBits, uint offset, uint numBytes, byte[] str)
Parameters
Type Name Description
UserGpio userGpio

0-31.
UInt32 baudRate

50-1000000.
UInt32 dataBits

1-32.
UInt32 stopBits

2-8.
UInt32 offset

=0.
UInt32 numBytes

=1.
Byte[] str

an array of chars (which may contain nulls).
Returns
Type Description
Int32

Returns the new total number of pulses in the current waveform if OK, otherwise PI_BAD_USER_GPIO, PI_BAD_WAVE_BAUD, PI_BAD_DATABITS, PI_BAD_STOPBITS, PI_TOO_MANY_CHARS, PI_BAD_SER_OFFSET, or PI_TOO_MANY_PULSES.
Examples
#define MSG_LEN 8

int i;
char *str;
char data[MSG_LEN];

str = "Hello world!";

gpioWaveAddSerial(4, 9600, 8, 2, 0, strlen(str), str);

for (i=0; i<MSG_LEN; i++) data[i] = i;

// Data added is offset 1 second from the waveform start.
gpioWaveAddSerial(4, 9600, 8, 2, 1000000, MSG_LEN, data);

GpioWaveChain(Byte[], UInt32)

This function transmits a chain of waveforms.

NOTE: Any hardware PWM started by GpioHardwarePwm(SystemGpio, UInt32, UInt32) will be cancelled.

The waves to be transmitted are specified by the contents of buf which contains an ordered list of wave Ids and optional command codes and related data.

Each wave is transmitted in the order specified. A wave may occur multiple times per chain.

A blocks of waves may be transmitted multiple times by using the loop commands. The block is bracketed by loop start and end commands. Loops may be nested.

Delays between waves may be added with the delay command.

The following command codes are supported:

Name @ Cmd & Data @ Meaning Loop Start @ 255 0 @ Identify start of a wave block Loop Repeat @ 255 1 x y @ loop x + y256 times Delay @ 255 2 x y @ delay x + y256 microseconds Loop Forever @ 255 3 @ loop forever

If present Loop Forever must be the last entry in the chain.

The code is currently dimensioned to support a chain with roughly 600 entries and 20 loop counters.

Declaration
public static ResultCode GpioWaveChain(byte[] buffer, uint bufferSize)
Parameters
Type Name Description
Byte[] buffer

pointer to the wave_ids and optional command codes.
UInt32 bufferSize

the number of bytes in buf.
Returns
Type Description
ResultCode

Returns 0 if OK, otherwise PI_CHAIN_NESTING, PI_CHAIN_LOOP_CNT, PI_BAD_CHAIN_LOOP, PI_BAD_CHAIN_CMD, PI_CHAIN_COUNTER, PI_BAD_CHAIN_DELAY, PI_CHAIN_TOO_BIG, or PI_BAD_WAVE_ID.
Examples
#include <stdio.h>
#include <pigpio.h>

#define WAVES 5
#define GPIO 4

int main(int argc, char *argv[])
{
   int i, wid[WAVES];

   if (gpioInitialise()<0) return -1;

   gpioSetMode(GPIO, PI_OUTPUT);

   printf("start piscope, press return"); getchar();

   for (i=0; i<WAVES; i++)
   {
      gpioWaveAddGeneric(2, (gpioPulse_t[])
         {{1<<GPIO, 0,        20},
          {0, 1<<GPIO, (i+1)*200}});

      wid[i] = gpioWaveCreate();
   }

   gpioWaveChain((char []) {
      wid[4], wid[3], wid[2],       // transmit waves 4+3+2
      255, 0,                       // loop start
         wid[0], wid[0], wid[0],    // transmit waves 0+0+0
         255, 0,                    // loop start
            wid[0], wid[1],         // transmit waves 0+1
            255, 2, 0x88, 0x13,     // delay 5000us
         255, 1, 30, 0,             // loop end (repeat 30 times)
         255, 0,                    // loop start
            wid[2], wid[3], wid[0], // transmit waves 2+3+0
            wid[3], wid[1], wid[2], // transmit waves 3+1+2
         255, 1, 10, 0,             // loop end (repeat 10 times)
      255, 1, 5, 0,                 // loop end (repeat 5 times)
      wid[4], wid[4], wid[4],       // transmit waves 4+4+4
      255, 2, 0x20, 0x4E,           // delay 20000us
      wid[0], wid[0], wid[0],       // transmit waves 0+0+0

      }, 46);

   while (gpioWaveTxBusy()) time_sleep(0.1);

   for (i=0; i<WAVES; i++) gpioWaveDelete(wid[i]);

   printf("stop piscope, press return"); getchar();

   gpioTerminate();
}

GpioWaveClear()

This function clears all waveforms and any data added by calls to the GpioWaveAdd functions.

Declaration
public static int GpioWaveClear()
Returns
Type Description
Int32

Returns 0 if OK.
Examples
gpioWaveClear();

GpioWaveCreate()

This function creates a waveform from the data provided by the prior calls to the GpioWaveAdd* functions. Upon success a wave id greater than or equal to 0 is returned, otherwise PI_EMPTY_WAVEFORM, PI_TOO_MANY_CBS, PI_TOO_MANY_OOL, or PI_NO_WAVEFORM_ID.

The data provided by the GpioWaveAdd* functions is consumed by this function.

As many waveforms may be created as there is space available. The wave id is passed to GpioWaveTxSend(UInt32, WaveMode) to specify the waveform to transmit.

Normal usage would be

Step 1. GpioWaveClear() to clear all waveforms and added data.

Step 2. GpioWaveAdd* calls to supply the waveform data.

Step 3. GpioWaveCreate() to create the waveform and get a unique id

Repeat steps 2 and 3 as needed.

Step 4. GpioWaveTxSend(UInt32, WaveMode) with the id of the waveform to transmit.

A waveform comprises one of more pulses. Each pulse consists of a GpioPulse structure.

The fields specify

1) the GPIO to be switched on at the start of the pulse. 2) the GPIO to be switched off at the start of the pulse. 3) the delay in microseconds before the next pulse.

Any or all the fields can be zero. It doesn't make any sense to set all the fields to zero (the pulse will be ignored).

When a waveform is started each pulse is executed in order with the specified delay between the pulse and the next.

PI_NO_WAVEFORM_ID, PI_TOO_MANY_CBS, or PI_TOO_MANY_OOL.

Declaration
public static int GpioWaveCreate()
Returns
Type Description
Int32

Returns the new waveform id if OK, otherwise PI_EMPTY_WAVEFORM, PI_NO_WAVEFORM_ID, PI_TOO_MANY_CBS, or PI_TOO_MANY_OOL.
Remarks

typedef struct { uint gpioOn; uint gpioOff; uint usDelay; } gpioPulse_t;.

GpioWaveDelete(UInt32)

This function deletes the waveform with id waveId.

The wave is flagged for deletion. The resources used by the wave will only be reused when either of the following apply.

  • all waves with higher numbered wave ids have been deleted or have been flagged for deletion.

  • a new wave is created which uses exactly the same resources as the current wave (see the C source for gpioWaveCreate for details).

Wave ids are allocated in order, 0, 1, 2, etc.

Declaration
public static ResultCode GpioWaveDelete(uint waveId)
Parameters
Type Name Description
UInt32 waveId

=0, as returned by GpioWaveCreate().
Returns
Type Description
ResultCode

Returns 0 if OK, otherwise PI_BAD_WAVE_ID.

GpioWaveGetCbs()

This function returns the length in DMA control blocks of the current waveform.

Declaration
public static int GpioWaveGetCbs()
Returns
Type Description
Int32

The result code. 0 for success. See the ResultCode enumeration.

GpioWaveGetHighCbs()

This function returns the length in DMA control blocks of the longest waveform created since GpioInitialise() was called.

Declaration
public static int GpioWaveGetHighCbs()
Returns
Type Description
Int32

The result code. 0 for success. See the ResultCode enumeration.

GpioWaveGetHighMicros()

This function returns the length in microseconds of the longest waveform created since GpioInitialise() was called.

Declaration
public static int GpioWaveGetHighMicros()
Returns
Type Description
Int32

The result code. 0 for success. See the ResultCode enumeration.

GpioWaveGetHighPulses()

This function returns the length in pulses of the longest waveform created since GpioInitialise() was called.

Declaration
public static int GpioWaveGetHighPulses()
Returns
Type Description
Int32

The result code. 0 for success. See the ResultCode enumeration.

GpioWaveGetMaxCbs()

This function returns the maximum possible size of a waveform in DMA control blocks.

Declaration
public static int GpioWaveGetMaxCbs()
Returns
Type Description
Int32

The result code. 0 for success. See the ResultCode enumeration.

GpioWaveGetMaxMicros()

This function returns the maximum possible size of a waveform in microseconds.

Declaration
public static int GpioWaveGetMaxMicros()
Returns
Type Description
Int32

The result code. 0 for success. See the ResultCode enumeration.

GpioWaveGetMaxPulses()

This function returns the maximum possible size of a waveform in pulses.

Declaration
public static int GpioWaveGetMaxPulses()
Returns
Type Description
Int32

The result code. 0 for success. See the ResultCode enumeration.

GpioWaveGetMicros()

This function returns the length in microseconds of the current waveform.

Declaration
public static int GpioWaveGetMicros()
Returns
Type Description
Int32

The result code. 0 for success. See the ResultCode enumeration.

GpioWaveGetPulses()

This function returns the length in pulses of the current waveform.

Declaration
public static int GpioWaveGetPulses()
Returns
Type Description
Int32

The result code. 0 for success. See the ResultCode enumeration.

GpioWaveTxAt()

This function returns the id of the waveform currently being transmitted.

PI_WAVE_NOT_FOUND (9998) - transmitted wave not found. PI_NO_TX_WAVE (9999) - no wave being transmitted.

Declaration
public static int GpioWaveTxAt()
Returns
Type Description
Int32

Returns the waveform id or one of the following special values:.

GpioWaveTxBusy()

This function checks to see if a waveform is currently being transmitted.

Declaration
public static int GpioWaveTxBusy()
Returns
Type Description
Int32

Returns 1 if a waveform is currently being transmitted, otherwise 0.

GpioWaveTxSend(UInt32, WaveMode)

This function transmits the waveform with id waveId. The mode determines whether the waveform is sent once or cycles endlessly. The SYNC variants wait for the current waveform to reach the end of a cycle or finish before starting the new waveform.

WARNING: bad things may happen if you delete the previous waveform before it has been synced to the new waveform.

NOTE: Any hardware PWM started by GpioHardwarePwm(SystemGpio, UInt32, UInt32) will be cancelled.

otherwise PI_BAD_WAVE_ID, or PI_BAD_WAVE_MODE.

Declaration
public static int GpioWaveTxSend(uint waveId, WaveMode waveMode)
Parameters
Type Name Description
UInt32 waveId

=0, as returned by GpioWaveCreate().
WaveMode waveMode

PI_WAVE_MODE_ONE_SHOT, PI_WAVE_MODE_REPEAT, or one of their SYNC variants.
Returns
Type Description
Int32

Returns the number of DMA control blocks in the waveform if OK, otherwise PI_BAD_WAVE_ID, or PI_BAD_WAVE_MODE.
Remarks

PI_WAVE_MODE_ONE_SHOT_SYNC, PI_WAVE_MODE_REPEAT_SYNC.

GpioWaveTxStop()

This function aborts the transmission of the current waveform.

This function is intended to stop a waveform started in repeat mode.

Declaration
public static int GpioWaveTxStop()
Returns
Type Description
Int32

Returns 0 if OK.

Comments