RPI Learning--wiringpi_api

reference:https://projects.drogon.net/raspberry-pi/wiringpi/functions/

Functions (API)

Some of the functions in the WIRINGPI Library is designed to mimic those in the Arduino Wiring system. There is relatively easy-to-use and should present no problems-anyone used to the Arduino system, or C programming in -general.

The main difference is this unlike the Arduino system, the main loop of the program was not provided for you–you need to Write it yourself. This is often desirable in a Linux system anyway as it can give you access to command-line arguments and so on. See the examples page for some simple examples and a Makefile to use.

Before using the WIRINGPI Library, you need to include its header file:

#include <wiringPi.h>

Also need to add

-i/usr/local/include-l/usr/local/lib-lwiringpi

The compile line of your program depending on the environment is using. The important one is -lwiringpi

Setup Functions

There is three ways to Initialise Wiringpi.

• int wiringpisetup (void);
  
• int Wiringpisetupgpio (void);
  
• int Wiringpisetupsys (void);
  

One of the setup functions must is called at the start of the Your program.  If it returns -1 then the initialisation of the GPIO have failed, and you should consult the global errno To see why.

The differences between the setup functions is as follows:

• Wiringpisetup (void);
  

This initialises the WIRINGPI system and assumes, the calling program are going to be using the WIRINGPI pin n Umbering scheme. This was a simplified numbering scheme which provides a mapping from virtual PIN numbers 0 through to the real Underlyin G Broadcom GPIO pin numbers. See the Pins page for a table which maps the WIRINGPI pin number to the Broadcom GPIO pin number to the physical Location on the edge connector.

This function needs to is called with root privileges.

• Wiringpisetupgpio (void);
  

This was identical to above, however it allows the calling programs to use the Broadcom GPIO pin numbers directly with no R E-mapping.

As above, this function need to is called with Root priveledges

• Wiringpisetupsys (void)

This initialises the WIRINGPI system but uses The/sys/class/gpio interface rather than accessing the hardware directly. This can is called as a non-root user provided the Gpio pins has been exported before-hand using the gpio progra M. Pin number in this mode is the native Broadcom GPIO numbers.

Note: In this mode, the pins which has been exported via The/sys/class/gpio interface. You must export these pins before your call to your program. Separate shell-script, or by using the system () function from inside your program.

Also Note that some functions (noted below) has no effect when using the this mode as they ' re not currently possible to actio n unless called with root privileges.

General wiring functions

• void Pinmode (int pin, int mode);
  

This sets the mode of a pin to either INPUT, OUTPUT, or pwm_output. Note that onlyWIRINGPI pin 1 (bcm_gpio) supports PWM output. The PIN number is the number obtained from the pins table.

This function has the no effect when in Sys mode.

• void digitalwrite (int pin, int value);
  

Writes the value High or low (1 or 0) to the given pin which must has been previously set as an output.

• void Digitalwritebyte (int value);

This writes the 8-bit byte supplied to the 8 GPIO pins. It's the fastest-to-set all 8 bits at once to a particular value, although it still takes TWI write operations to the GPIO hardware.

• void pwmwrite (int pin, int value);
  

Writes the value to the PWM register for the given pin. The value must be between 0 and 1024. (Again, note that only pin 1 (bcm_gpio) supports PWM)

This function had no effect when in Sys mode (see above)

• int digitalread (int pin);
  

This function returns the value of read at the given pin. It would be is high or low (1 or 0) depending on the logic level at the pin.

• void Pullupdncontrol (int pin, int pud);
  

This sets the pull-up or Pull-down resistor mode on the given pin, which should is set as an input. Unlike the Arduino, the BCM2835 has both pull-up a down internal resistors. The parameter pud should be; Pud_off, (no pull Up/down), Pud_down (pulling to ground) orpud_up (pulling to 3.3v)

This function has the no effect when in Sys mode. If you need to activate a pull-up/pull-down and then you can do it with the Gpio program in a script before you star T your program.

PWM Control

PWM can not is controlled when running in Sys mode.

• Pwmsetmode (int mode);

The PWM generator can run in 2 modes– "balanced" and "mark:space". The Mark:space mode is traditional and however the default mode in the Pi is "balanced". You can switch modes by supplying the parameter: pwm_mode_bal or Pwm_mode_ms.

• Pwmsetrange (unsigned int range);

This sets is the range register in the PWM generator. The default is 1024.

• Pwmsetclock (int divisor);

This sets the divisor for the PWM clock.

To understand more on the PWM system, you'll need to read the Broadcom ARM Peripherals Manual.

Timing functions

• unsigned int millis (void)

This returns a number representing the number if milliseconds since your program called one of the Wiringpisetup Functions. It returns an unsigned 32-bit number which wraps.

• void delay (unsigned int howlong)

This causes program execution to pause for at least howlong milliseconds. Due to the multi-tasking nature of Linux it could be longer. Note that the maximum delay was an unsigned 32-bit integer or approximately.

• void delaymicroseconds (unsigned int howlong)

This causes program execution to pause for at least howlong microseconds. Due to the multi-tasking nature of Linux it could be longer. Note that the maximum delay was an unsigned 32-bit integer microseconds or approximately minutes.

Program/thread Priority

• int Pihipri (int priority);
  

This attempts to shift your program (or thread in a multi-threaded program) to a higher priority and enables a real-time s Cheduling. The priority parameter should is from 0 (the default) to the (the maximum). This won ' t do your program go to any faster, but it'll give it a bigger slice of time when other programs is running. The priority parameter works relative to Others–so you can make one program Priority 1 and another priority 2 and it wil L has the same effect as setting one to ten and the other-to-MAX (as long as no other programs is running with elevated PR Iorities)

The return value is 0 for success And-1 for error. If An error is returned, the program should then consult the errno global variable, as per the usual conventions.

Note: Only programs running as root can change the their priority. If called from a non-root and nothing happens.

Interrupts

With a newer kernel patched and the GPIO interrupt handling code, (ie. any kernel after about June), you can now Wai T for a interrupt in your program. This frees up the processor to does other tasks while you ' re waiting for that interrupt. The GPIO can is set to interrupt on a rising, falling or both edges of the incoming signal.

Note: Jan 2013:the waitforinterrupt () function is deprecated–you should use of the newer and easier to use wiring PIISR () function below.

• int waitforinterrupt (int pin, int timeOut);
  

When called, it'll wait for a interrupt event to happen on that PIN and your program would be stalled. The timeOut parameter is given in milliseconds, or can be-1 which means to wait forever.

The return value IS-1 if an error occurred (and errno would is set appropriately), 0 if it timed out, or 1 on a s Uccessful Interrupt event.

Before Waitforinterrupt, you must first initialise the GPIO pin and at present the only-to-do-is-to-use The GPIO program, either in a script, or using the system () call from inside your program.

e.g. we want to wait for a falling-edge interrupt on GPIO pin 0, so-to-setup the hardware, we need to run:

Gpio Edge 0 Falling

Before running the program.

• int WIRINGPIISR (int pin, int edgetype, void (*function) (void));

This function registers a function to received interrupts on the specified pin. The Edgetype parameter is either int_edge_falling, int_edge_rising, int_edge_both orINT _edge_setup. If It is int_edge_setup then no initialisation of the pin would happen–it ' s assumed that you have already SETUP The pin elsewhere (e.g. with the gpio program), and if you specify one of the other types, then the pin would be E Xported and initialised as specified. This was accomplished via a suitable call to the Gpio utility program, so it need to be available.

The PIN number is supplied in the current mode–native Wiringpi, Bcm_gpio or Sys modes.

This function would work on any mode, and does not need root privileges to work.

The function would be called when the interrupt triggers. When it was triggered, it ' s cleared in the dispatcher before calling your function, so if a subsequent interrupt fires BEFO Re you finish your handler and then it won ' t be missed. (however it can only track one more interrupt, if more than one interrupt fires while one was being handled then they would Be ignored)

This function was run at a high priority (if the program was run using sudo, or as root) and executes concurrently with the Main program. It has full access to all of the global variables, open file handles and so on.

See the isr.c -Example program for more details about the use of this feature.

Concurrent Processing (multi-threading)

Wiringpi have a simplified interface to the Linux implementation for Posix threads, as well as a (simplified) mecha Nisms to access Mutex ' s (Mutual exclusions)

Using These functions you can create a new process (a function inside your main program) which runs concurrently with your Main program and using the mutex mechanisms, safely pass variables between them.

• int pithreadcreate (name);
  

This function creates a thread which are another function in your program previously declared using the pi_thread Declaration. This function was then the run concurrently with your main program. An example is to has this function, wait for a interrupt while your program carries on doing other tasks. The thread can indicate an event, or action by using global variables to communicate back to the main program, or other th Reads.

Thread functions is declared as follows:

Pi_thread (myThread) {  .. code here to run concurrently        with the main program, probably in an        infinite loop}

And would is started in the main program with:

x = Pithreadcreate (MyThread); if (x! = 0)  printf ("It didn ' t start\n")

This was really nothing more than a simplified interface to the Posix threads mechanism that Linux supports. See the manual pages in Posix threads (man pthread) If you need more control over them.

• Pilock (int keynum);
  

• Piunlock (int keynum);
  

These the synchronise variable updates from your main program to any threads running in your program. Keynum is a number from 0 to 3 and represents a "key". When another process tries to lock the same key, it'll be stalled until the first process has unlocked the same key.

Need to use these functions to ensure so get valid data when exchanging data between your main program and a Thread–otherwise it ' s possible that the thread could wake-up halfway during your data copy and change the Data–so the Data you end up copying is incomplete, or invalid. See the WFI.C program in the examples directory for a example.

Misc. Functions

• Piboardrev (void);

This returns the board revision of the Raspberry Pi. It'll be either 1 or 2. Some of the Bcm_gpio pins changed number and function when moving from board Revision 1 to 2, so if you are using Bcm_gpio Pin numbers, then you need to be aware of the differences.

• Wpipintogpio (int wpipin);

This returns the Bcm_gpio pin number of the supplied WIRINGPI pin. It takes the board revision into account.

• setpaddrive (int group, int value);

This sets the ' strength ' of the pad drivers for a particular group of pins. There was 3 groups of pins and the drive strength was from 0 to 7. Do not use the this unless you know what is doing.