JSIntro(3)

NAME

JSIntro - Introduction to the Joystick Wrapper library (libjsw)

OVERVIEW

The Joystick Wrapper library (libjsw) is a multi platform joystick IO library with an embedded calibration level to ensure client side functions can recieve the most accurate and useful joystick values.

To determine if your machine supports libjsw, check for the existance of libjsw.* in the expected library locations on your machine. Typical locations are /usr/lib/libjsw.* or /usr/local/lib/libjsw.*.

EXAMPLES

Below is an example that demostrates the use of the libjsw API to open the first joystick (/dev/js0) and fetch values from it as they become available.

#include <stdio.h>
#include <unistd.h>
#include <jsw.h>

int main(int argc, char *argv[])
{
        int i, status;
        char *device = "/dev/js0";
        char *calib = ".joystick";
        js_data_struct jsd;

        if(argc < 3)
        {
            printf(
"Usage: basic <joystick_device> <calibation_file>\n"
            );
            return(0);
        }

        device = argv[1];
        calib = argv[2];

        /* Initialize joystick. */
        status = JSInit(
            &jsd,
            device,
            calib,
            JSFlagNonBlocking
        );

        if(status != JSSuccess)
        {
            fprintf(
                stderr,
"Unable to open joystick, error code %i.\n",
                status
            );
            JSClose(&jsd);
            return(1);
        }

        while(1)
        {
            if(JSUpdate(&jsd) == JSGotEvent)
            {
                printf("\r");

                /* Print each axis position. */
                for(i = 0; i < jsd.total_axises; i++)
                    printf(
                        "A%i:%.3f ",
                        i,
                        JSGetAxisCoeffNZ(&jsd, i)
                    );

                printf(" ");

                /* Print state of each button. */
                for(i = 0; i < jsd.total_buttons; i++)
                    printf(
                        "B%i:%i ",
                        i,
                        JSGetButtonState(&jsd, i)
                    );

                fflush(stdout);
            }

            usleep(16000); /* Don't hog the cpu. */
        }

        /* Main while() loop never breaks, but if it
         * did, besure to close the joystick before
         * exiting.
         */
        JSClose(&jsd);

        return(0);
}

COMPILING

To compile the example, you will need to link the program to libjsw. Typically a C compiler command to achieve this would be as follows:

cc myprog.c -o myprog -ljsw

If you have libjsw installed in a directory that is not searched through by your linker and not defined in the environment variable LD_LIBRARY_PATH, then you may need to specify the -L argument. For example:

cc myprog.c -o myprog -ljsw -L/usr/nonstandard/lib

NOTES

Most common problems for the joystick not being initialized properly in JSInit(3) are as follows:

1. Joystick driver/module not loaded or not defined properly in the system configuration. For example, under Linux you need to ensure that your joystick driver modules are defined properly in /etc/conf.modules (look for module joy-analog) and that /dev/js* device nodes exist.

2. Joystick not plugged in or not switched to diginal or analog. You may have your system's joystick drivers looking for a joystick on the wrong port or with the wrong analog/digital setting. If you have your joystick plugged into the game port on a sound card, you may need to initialize your sound card's driver modules first.

3. Joystick needs to be calibrated, run jscalibrator(1).

SEE ALSO

jscalibrator(1) JSInit(3) JSUpdate(3) JSClose(3)