gsat Plugin API
---------------

How to write plugins for gsat.
------------------------------

This document tries to explain how to write your own plugins for gsat.

There are 2 types of plugins in gsat: the radio plugins and the rotor plugins.

- Radio plugins are used to control a rig with CAT capabilities and do automatic
  doppler correction of frequency. Their file name must begin by radio_.

- Rotor plugins are used to control a rotor in order to have the antennas
  pointed at the satellite being tracked. Their file name must begin by rotor_.

You can write your own plugins by implementing the functions described below.
Because gsat uses dynamic loading, plugins must be compiled with:

        gcc -fPIC -shared -o {plugin_name} {plugin_name}.c

There are some examples in the plugins directory.

Plugins must be installed in the /usr/local/lib/gsat/plugins directory. If you
need the plugins in another directory, you must set the GSATPLUGINSDIR environment
variable to point to your plugins directory.

To use a plugin, select it in the preferences window and set the config string if
 needed.

The config string is passed to the plugin_open function and can be used to 
configure a plugin. There is an example in the plugins directory (radio_PCR100.c).



RADIO PLUGINS
-------------

Functions required to implement a radio control plugin for gsat.


int plugin_open_rig( char * config )

Function:
Open and initialize the device

Parameters:
char * config: string with config parameters for the plugin

Returns:
int : TRUE=open ok
      FALSE=failed


void plugin_close_rig( void )

Function:
close and free resources used by the device

Parameters:
none

Returns:
none


void plugin_set_uplink_frequency( double frequency )

Function:
Set frequency on the device

Parameters:
double frequency: frequency in kilohertz

Returns:
none


void plugin_set_downlink_frequency( double frequency )

Function:
Set frequency on the device

Parameters:
double frequency: frequency in kilohertz

Returns:
none


char * plugin_info( void )

Function:
Get info string

Parameters:
none

Returns:
char *: pointer to a string containing the name of the device and plugin version



ROTOR PLUGINS
-------------

Functions required to implement a rotor control plugin for gsat.


int plugin_open_rotor( char * config );

Function:
Open and initialize the device

Parameters:
char * config: string with config parameters for the plugin

Returns:
int : TRUE=open ok
      FALSE=failed


void plugin_close_rotor( void );

Function:
close and free resources used by the device

Parameters:
none

Returns:
none


void plugin_set_rotor( double azimuth, double elevation );

Function:
Set rotor azimuth and elevation

Parameters:
double azimuth: azimuth in degrees
double elevation: elevation in degrees

Returns:
none


char * plugin_info( void )

Function:
Get info string

Parameters:
none

Returns:
char *: pointer to a string containing the name of the device and plugin version



That's all for now.

If you write a new plugin, please send me a copy so I can add it to gsat.


73 de Xavi, EB3CZS