I/O Pin Handling

Table of Contents

Initialize

Some Kvaser products feature I/O pins that can be used in real-time applications using our API dedicated to I/O Pin Handling. This API is initialized by confirming the I/O pin configuration, see kvIoConfirmConfig. Before the configuration is confirmed the user can only retrieve information about the pins, such as the total number of pins using kvIoGetNumberOfPins, and after the configuration has been confirmed the user may set or read any values of the I/O pins.

int channel_nbr;
int nbr_of_pins;
int hnd;
canStatus status;
.
.
.
canInitializeLibrary();
hnd = canOpenChannel(channel_nbr, 0);
if ( hnd < 0 ) {
printf("Failed to open channel\n");
return;
}
status = kvIoGetNumberOfPins(hnd, &nbr_of_pins);
if ( status != canOK ) {
printf("Failed to get the number of pins (%d)\n", status);
canClose(hnd);
return;
}
printf("Found %d pins.\n", nbr_of_pins);
status = kvIoConfirmConfig(hnd);
if ( status != canOK ) {
printf("Failed to confirm the configuration (%d)\n", status);
canClose(hnd);
return;
}
// Now we can read and set values of the I/O pins.

Pin information

Pins are identified by their pin number, which is a number from zero up to, but not including, the value returned by kvIoGetNumberOfPins(). Using the pin number the specific properties of any pin is retrieved using kvIoPinGetInfo and modified using kvIoPinSetInfo. See kvIO_INFO_GET_xxx and kvIO_INFO_SET_xxx to learn what properties can be read and modified.

unsigned int i;
unsigned int nbr_of_pins;
.
.
.
// Getting some information from the pins
for ( i = 0; i < nbr_of_pins; i++ ) {
printf("Pin %u:\n", i);
status = kvIoPinGetInfo(hnd, i, kvIO_INFO_GET_DIRECTION, &data, sizeof(data));
if ( status == canOK ) {
printf(" direction: %s\n", ( data == kvIO_PIN_DIRECTION_IN ? "In" : "Out" ));
} else {
printf(" direction: error\n");
}
status = kvIoPinGetInfo(hnd, i, kvIO_INFO_GET_PIN_TYPE, &data, sizeof(data));
if ( status == canOK ) {
printf(" Pin type: %s\n",
( data == kvIO_PIN_TYPE_DIGITAL ? "Digital" : \
( data == kvIO_PIN_TYPE_RELAY ? "Relay" : \
( data == kvIO_PIN_TYPE_ANALOG ? "Analog" : \
"Unknown")
)));
} else {
printf(" Pin type: error\n");
}
}

IO pin types

There are currently three types of pins that is supported by our API dedicated to I/O Pin Handling. These include analog, digital and relay pins. To learn what pin type a given pin is, the argument kvIO_INFO_GET_PIN_TYPE is used when calling kvIoPinGetInfo. See kvIO_PIN_TYPE_xxx to see what type each value represents.

Analog Pins

The analog pins are represented by multiple bits, the number of bits can be retrieved by using kvIoPinGetInfo with kvIO_INFO_GET_NUMBER_OF_BITS as an argument. The value of an analog pin is within in the interval given by kvIO_INFO_GET_RANGE_MIN and kvIO_INFO_GET_RANGE_MAX. The analog input pin has two configurable properties, namely the low pass filter order and the hysteresis. See kvIO_INFO_SET_AI_LP_FILTER_ORDER and kvIO_INFO_SET_AI_HYSTERESIS to learn about these properties. Pins are read and set using kvIoPinSetAnalog and kvIoPinGetAnalog respectively. To read the latest set output of an output pin the function kvIoPinGetOutputAnalog is used.

int pin_type;
int direction;
unsigned int pin;
.
.
.
if ( pin_type == kvIO_PIN_TYPE_ANALOG ) {
float data = (float) 0.2;
int lp_fo = 3
// Setting the hysteresis to 0.2
status = kvIoPinSetInfo(hnd, pin, kvIO_INFO_SET_AI_HYSTERESIS, &data, sizeof(data));
if ( status != canOK )
printf("Failed to set hysteresis of pin %u\n", pin);
// Setting the low pass filter to 3
status = kvIoPinSetInfo(hnd, pin, kvIO_INFO_SET_AI_LP_FILTER_ORDER, &lp_fo, sizeof(lp_fo));
if ( status != canOK )
printf("Failed to set low pass filter order of pin %u\n", pin);
.
.
.
if ( direction == kvIO_PIN_DIRECTION_OUT ) {
// Writing 4.0 Volts to the analog output
status = kvIoPinSetAnalog(hnd, pin, (float) 4.0);
} else if ( direction == kvIO_PIN_DIRECTION_IN ) {
// Reading the voltage level on the analog input
status = kvIoPinGetAnalog(hnd, pin, &data);
if ( status == canOK )
printf("The voltage level is at %f on pin %u\n", data, pin);
}
if ( status != canOK )
printf("Failed to set/get voltage level on pin %u\n", pin);
}

Digital Pins

The digital pins have two configurable properties, namely the low-to-high and the high-to-low filter time. See kvIO_INFO_SET_DI_HIGH_LOW_FILTER and kvIO_INFO_SET_DI_LOW_HIGH_FILTER to learn about these properties. Pins are read and set using kvIoPinSetDigital and kvIoPinGetDigital respectively. To read the latest set output of an output pin the function kvIoPinGetOutputDigital is used.

if ( pin_type == kvIO_PIN_TYPE_DIGITAL ) {
unsigned int data = 500;
// Setting the high-to-low filter time to 500 µs
status = kvIoPinSetInfo(hnd, pin, kvIO_INFO_SET_DI_HIGH_LOW_FILTER, &data, sizeof(data));
if ( status != canOK )
printf("Failed to set high-to-low filter time of pin %u\n", pin);
// Setting the low-to-high filter time to 500 µs
status = kvIoPinSetInfo(hnd, pin, kvIO_INFO_SET_DI_LOW_HIGH_FILTER, &data, sizeof(data));
if ( status != canOK )
printf("Failed to set low-to-high filter time of pin %u\n", pin);
.
.
.
if ( direction == kvIO_PIN_DIRECTION_OUT ) {
// Writing 1 to the digital output
status = kvIoPinSetDigital(hnd, pin, 1);
} else if ( direction == kvIO_PIN_DIRECTION_IN ) {
status = kvIoPinGetDigital(hnd, pin, &data);
if ( status == canOK )
printf("The digital input pin %u is %d\n", pin, data);
}
if ( status != canOK )
printf("Failed to set/get voltage level on digital pin %u\n", pin);
}

Relay Pins

The relay pins have no configurable properties. All of these pins are considered as outputs. Pins are set using kvIoPinSetRelay and the status of them, whether they are activated or not, is read using kvIoPinGetOutputRelay.

if ( pin_type == kvIO_PIN_TYPE_RELAY ) {
unsigned int data;
status = kvIoPinGetOutputRelay(hnd, pin, &data);
if ( status == canOK ) {
printf("Status of relay pin %u: %u\n", pin, data);
data = !data; // Toggle the relay pin
status = kvIoPinSetRelay(hnd, pin, data);
}
if ( status != canOK )
printf("Failed to set value of relay pin %u.\n", pin);
}