Grove - Libraries

From openPicus Wiki
Jump to: navigation, search


Introduction to the Grove library

The Basic Grove Library is included inside each Grove or IoT Kit template on the IDE/IDEpro. It gives full functionalities for the following kind of Grove devices:

  • Digital IOs;
  • Analog inputs

The architecture of the Grove libraries allows to configure and use each Grove device with simply 6 functions:

new() To initialize the device object with some basic parameters
delete() To remove the device object from memory
attachToBoard() To specify the Grove port where the Grove device is connected
configure() To configure advanced parameters (available only for some devices)
set() To write a value to the device
get() To read a value from the device

These six functions gives to the user the ability to control each Grove device, even the most complex.
More details about each compatible Grove device are on Grove Devices and libraries page.

NOTE: some of the Grove devices made by Seeedstudio are not supported by our libraries.

Connect a new Grove device

Follow the steps below to connect a Grove device. The parameters of each function is described into the specific page of the devices.

  • Board Initialization: the first important part of the process is to initialize the board (mandatory). To initialize the board simply use the code:
    void *myNest = new (Board);  // Initialized the new board called "myNest"
    Now the board is ready and initialized and it'spossible to attach device to its ports.

  • Grove device initialization: the function new() initializes the desired Grove device. Its parameters depends on the Grove device you want to use. For example, to initialize a basic digital output the sintax is the following:
    void *myOutput = new (Dig_io, OUT);    // standard output

  • Specify the port for the Grove device: Just choose the right port on the board (DIG1. AN2....) where the Grove device is plugged. On the previous step we initialized a digital output device, the element must be connected to a digital port. The port must be specified in the firmware using the function attachToBoard(). On this example we use the digital port number 1:
    attachToBoard(myNest, myOutput, DIG1);
    Basically we have "attached" the device named myOutput to the digital port 1 of the board named myNest.

  • Configuring the Grove device: It's required only by some advanced Grove device. A standard output doesn't require any configuration, so you don't need to use the function Configure(). Details about device configuration can be found in the Grove Device page.

  • Using the Grove devices: now initialization and configuration of the Grove device is completed. So it is possible to read/write the element using the functions get() or set(). For example a digital output needs only the set() function, to change its state:
set(myOutput, ON);      // Turning on the output
set(myOutput, OFF);     // Turning off the output

Basic Grove Devices

Digital IO devices

The function new(type, subtype, [PWM_num]) initializes a digital IO device (such as a pushbutton)

  • type: specifies the type of devices, in this case is Dig_io;
  • subtype: specifies if the IO is input (standard or with pull-up or pull-down) or output (on/off or PWM);
  • PWM_num: Flyport provide up to 9 independent PWM channels (PWM frequency and duty cycle is settable). PWM_num is the number of PWM channel. Different devices must use different PWM channels.

In table are reported the right parameters for each type/subtype of device. (The type of device can be found in the related page of this wiki)

I/O type Function
INPUT standard new (Dig_io, IN)
INPUT with pull-up resistor new (Dig_io, INUp)
INPUT with pull-down resistor new (Dig_io, INDown)
OUTPUT standard (on/off) new (Dig_io, OUT)
OUTPUT with PWM new (Dig_io, PWM, 1)

Some examples of initialization of Digital IO devices:

  • Input initialization:
void *stdInput = new (Dig_io, IN);    // standard input
void *puInput = new (Dig_io, INUp);   // pullup input
void *pdInput = new (Dig_io, INDown); // pulldown input
  • Output initialization:
void *stdOut= new (Dig_io, OUT);          // New standard output element created and named stdOut
void *PWMOut= new (Dig_io, PWM, 1);       // New PWM output element created and named PWMOut

Read a Digital input

Once initialized, the value of a digital input can be read using the function get(device_name).
The device_name is the name during initialization.

For example, for the standard input, the name used in the initialization is stdInput, so to read the value from the device just get(stdInput);.
The reading process is the same for any subtype of digital input device.

Write a Digital output

To write values on digital output devices, it's used the function set(device_name, param2, param3). Device_name is the name used to initialize the device. While param2 and param3 changes according to the subtype of device:

  • standard output - the standard output devices can be turned on or off, so only the param2 is required, and can be ON or OFF.
set(stdOut, ON);      // Turn on the device
set(stdOut, OFF);      // Turn off the device

  • PWM output - the devices using the PWM have more parameters that can be changed, so the set() instruction can be used in different ways:
    • Change the frequency: set(device_name, FREQUENCY, float frequency_val);
    • Change the duty cycle: set(device_name, DUTY, float ducty_cycle value);
    • Turn on/off the PWM: set(device_name, ON[ or OFF]);

Analog Inputs

The second type of basic sensors are devices returning an analog value. The range is between 0 and 1023.

  • Initialization: void *device_name = new(An_i);
  • Connetion to board: attachToBoard(board_name, device_name, analog_port); analog port can be any ANx.
  • Reading value: get(device_name);

Other Grove devices

Visit the Grove Devices list to download libraries and technical information for each Grove Devices supported.


Manage an led

You have 2 options:
- Turn an led on using a simple On/Off function
- Dim an led using PWM modulation

How to turn on an Led on

void *myNest = new (GroveNest);                            // New board created and named myNest
void *myLed = new (Dig_io, OUT);                       // New LED created and named myLed
attachToBoard(myNest, myLed, DIG1);                    // Led attached to the board on the DIG1 port
set(myLed, ON);                                        // Led turned ON

How to dim an led

void *myNest = new (GroveNest);                            // New board created and named myNest
void *myDimLed = new (Dig_io, PWM, 1);                 // New LED created and named myDimLed
attachToBoard(myNest, myDimLed, DIG1);        	       // Led attached to the board on the DIG1 port
set(myDimLed, FREQUENCY, 500.0);                       // Frequency of the led set to 500.0Hz (remember the decimal!)
set(myDimLed, DUTY, 50.0);                             // Duty cycle set to 50.0% (remember the decimal!)
set(myDimLed, ON);                                     // Led turned on

Read an analog input device

void *myNest = new (GroveNest);                             // New board created and named myNest
void *myAnalog = new(An_i);				// New analog device initialized
attachToBoard(myNest, myAnalog, AN1);			// Device connected on analog port 1
int value;
value = get(myAnalog);					// Reading of the analog value (range:0-1023)

A potentiometer to dim a led

Here is a very simple example to integrate the usage of digital output and analog input. An led is connected on the digital port DIG1 and it is dimmed using a potentiometer connected on analog port AN1.

#include "taskFlyport.h"
#include "grovelib.h"
void FlyportTask()
	UARTWrite(1,"Welcome to DIM A LED example!\r\n");
	// Board initialization
	void *myBoard = new(Board);
	// GROVE devices
	void *led = new(Dig_io, PWM, 1);		// New led, using the PWM module number 1
	void *pot = new(An_i);					// New potentiometer
	attachToBoard(myBoard, led, DIG1);		// Led connected on digital port 1
	attachToBoard(myBoard, pot, AN1);		// potentiometer connected on analog port 1
	//	Setting the starting values for PWM on led
	set(led, FREQUENCY, 500.0);				// Frequency = 500 Hz
	set(led, DUTY, 50.0);					// Duty cycle = 50.0 
	set(led, ON);							// led control activated
	//	In the main loop, the value of duty cycle is tied to the value of potentiometer
	float val;
		val = (get(pot)/1023)*100;			// pot can vary between 0-1023, but duty cycle vary between 0-100
		set(led, DUTY, val);

Debug on serial port

Flyport UART 1 can be used for debug. It's the standard programming serial port and can be accessed using the embedded serial monitor in the IDE.
The default baudrate of the UART is 19200, but can be changed using the standard Flyport commands for UART.

Personal tools