Rotator API


Files

file  rot_conf.c
 Rotator Configuration Interface.
file  rotator.c
 Rotator interface.
file  rotator.h
 Hamlib rotator data structures.
file  rotlist.h
 Hamlib rotator model definitions.

Data Structures

struct  rot_caps
 Rotator data structure. More...
struct  rot_state
 Live data and customized fields. More...
struct  rot
 This is the master data structure, acting as a handle for the controlled rotator. More...

Defines

#define ROT_RESET_ALL   1
 A macro that returns the flag for the reset operation.
#define ROT_FLAG_AZIMUTH   (1<<1)
 A macro that returns the azimuth flag.
#define ROT_FLAG_ELEVATION   (1<<2)
 A macro that returns the elevation flag.
#define ROT_MOVE_UP   (1<<1)
 A macro that returns the flag for the UP direction.
#define ROT_MOVE_DOWN   (1<<2)
 A macro that returns the flag for the DOWN direction.
#define ROT_MOVE_LEFT   (1<<3)
 A macro that returns the flag for the LEFT direction.
#define ROT_MOVE_CCW   ROT_MOVE_LEFT
 A macro that returns the flag for the counterclockwise direction.
#define ROT_MOVE_RIGHT   (1<<4)
 A macro that returns the flag for the RIGHT direction.
#define ROT_MOVE_CW   ROT_MOVE_RIGHT
 A macro that returns the flag for the clockwise direction.
#define rot_debug   rig_debug
 Convenience definition for debug level.
#define ROT_MODEL_DUMMY   ROT_MAKE_MODEL(ROT_DUMMY, 1)
 A macro that returns the model number for the dummy backend.
#define ROT_MODEL_RPC   ROT_MAKE_MODEL(ROT_RPC, 1)
 A macro that returns the model number of the RPC Network pseudo-backend.
#define ROT_MODEL_EASYCOMM1   ROT_MAKE_MODEL(ROT_EASYCOMM, 1)
 A macro that returns the model number of the EasyComm 1 backend.
#define ROT_MODEL_EASYCOMM2   ROT_MAKE_MODEL(ROT_EASYCOMM, 2)
 A macro that returns the model number of the EasyComm 2 backend.
#define ROT_MODEL_FODTRACK   ROT_MAKE_MODEL(ROT_FODTRACK, 1)
 A macro that returns the model number of the Fodtrack backend.
#define ROT_MODEL_ROTOREZ   ROT_MAKE_MODEL(ROT_ROTOREZ, 1)
 A macro that returns the model number of the Rotor-EZ backend.
#define ROT_MODEL_ROTORCARD   ROT_MAKE_MODEL(ROT_ROTOREZ, 2)
 A macro that returns the model number of the Rotor Card backend.
#define ROT_MODEL_DCU   ROT_MAKE_MODEL(ROT_ROTOREZ, 3)
 A macro that returns the model number of the DCU backend.
#define ROT_MODEL_SARTEK1   ROT_MAKE_MODEL(ROT_SARTEK, 1)
 A macro that returns the model number of the SARtek-1 backend.
#define ROT_BACKEND_LIST
 Static list of rotator models.

Typedefs

typedef struct rot ROT
 Rotator structure definition (see rot for details).
typedef float elevation_t
 Type definition for elevation.
typedef float azimuth_t
 Type definition for azimuth.
typedef int rot_reset_t
 Type definition for rotator reset.
typedef int rot_model_t
 Convenience type definition for rotator model.

Functions

int frontrot_set_conf (ROT *rot, token_t token, const char *val)
 Set rotator state info from alpha input.
int frontrot_get_conf (ROT *rot, token_t token, char *val)
 Get data from rotator state in alpha form.
int rot_token_foreach (ROT *rot, int(*cfunc)(const struct confparams *, char *), char *data)
 Executes cfunc on all the elements stored in the conf table.
struct confparamsrot_confparam_lookup (ROT *rot, const char *name)
 lookup conf token by its name, return pointer to confparams struct.
token_t rot_token_lookup (ROT *rot, const char *name)
 Simple lookup returning token id associated with name.
int foreach_opened_rot (int(*cfunc)(ROT *, char *), char *data)
 execs cfunc() on each opened rot
ROTrot_init (rot_model_t rot_model)
 allocate a new ROT handle
int rot_open (ROT *rot)
 open the communication to the rot
int rot_close (ROT *rot)
 close the communication to the rot
int rot_cleanup (ROT *rot)
 release a rot handle and free associated memory
int rot_set_conf (ROT *rot, token_t token, const char *val)
 set a rotator configuration parameter
int rot_get_conf (ROT *rot, token_t token, char *val)
 get the value of a configuration parameter
int rot_set_position (ROT *rot, azimuth_t azimuth, elevation_t elevation)
 set the azimuth and elevation of the rotator
int rot_get_position (ROT *rot, azimuth_t *azimuth, elevation_t *elevation)
 get the azimuth and elevation of the rotator
int rot_park (ROT *rot)
 park the antenna
int rot_stop (ROT *rot)
 stop the rotator
int rot_reset (ROT *rot, rot_reset_t reset)
 reset the rotator
int rot_move (ROT *rot, int direction, int speed)
 move the rotator in the specified direction
const char * rot_get_info (ROT *rot)
 get general information from the rotator

Rotator interface

Rotator can be any kind of azimuth or azimuth and elevation controlled antenna system.

Define Documentation

#define ROT_BACKEND_LIST

Value:

{               \
        { ROT_DUMMY, ROT_BACKEND_DUMMY }, \
        { ROT_RPC, ROT_BACKEND_RPC }, \
        { ROT_EASYCOMM, ROT_BACKEND_EASYCOMM }, \
        { ROT_FODTRACK, ROT_BACKEND_FODTRACK }, \
        { ROT_ROTOREZ, ROT_BACKEND_ROTOREZ }, \
        { ROT_SARTEK, ROT_BACKEND_SARTEK }, \
        { 0, NULL }, /* end */  \
}
Static list of rotator models.

This is a NULL terminated list of available rotator backends. Each entry in the list consists of two fields: The branch number, which is an integer, and the branch name, which is a character string.

#define rot_debug   rig_debug

Convenience definition for debug level.

This is just as convenience definition of the rotator debug level, and is the same as for the rig debug level.

See also:
rig_debug

#define ROT_MODEL_DCU   ROT_MAKE_MODEL(ROT_ROTOREZ, 3)

A macro that returns the model number of the DCU backend.

The Rotor-EZ backend can be used with rotators that support the DCU command set by Hy-Gain (currently the DCU-1).

#define ROT_MODEL_DUMMY   ROT_MAKE_MODEL(ROT_DUMMY, 1)

A macro that returns the model number for the dummy backend.

The dummy backend, as the name suggests, is a backend which performs no hardware operations and always behaves as one would expect. It can be thought of as a hardware simulator and is very usefull for testing client applications.

#define ROT_MODEL_EASYCOMM1   ROT_MAKE_MODEL(ROT_EASYCOMM, 1)

A macro that returns the model number of the EasyComm 1 backend.

The EasyComm 1 backend can be used with rotators that support the EASYCOMM I Standard.

#define ROT_MODEL_EASYCOMM2   ROT_MAKE_MODEL(ROT_EASYCOMM, 2)

A macro that returns the model number of the EasyComm 2 backend.

The EasyComm 2 backend can be used with rotators that support the EASYCOMM II Standard.

#define ROT_MODEL_FODTRACK   ROT_MAKE_MODEL(ROT_FODTRACK, 1)

A macro that returns the model number of the Fodtrack backend.

The Fodtrack backend can be used with rotators that support the FODTRACK Standard.

#define ROT_MODEL_ROTORCARD   ROT_MAKE_MODEL(ROT_ROTOREZ, 2)

A macro that returns the model number of the Rotor Card backend.

The Rotor-EZ backend can be used with Yaesu rotators that support the extended DCU command set by Idiom Press Rotor Card board.

#define ROT_MODEL_ROTOREZ   ROT_MAKE_MODEL(ROT_ROTOREZ, 1)

A macro that returns the model number of the Rotor-EZ backend.

The Rotor-EZ backend can be used with Hy-Gain rotators that support the extended DCU command set by Idiom Press Rotor-EZ board.

#define ROT_MODEL_RPC   ROT_MAKE_MODEL(ROT_RPC, 1)

A macro that returns the model number of the RPC Network pseudo-backend.

The RPC backend can be used to connect and send commands to a rotator server, rpc.rotd, running on a remote machine. Using this client/server scheme, several clients can control and monitor the same rotator hardware.

#define ROT_MODEL_SARTEK1   ROT_MAKE_MODEL(ROT_SARTEK, 1)

A macro that returns the model number of the SARtek-1 backend.

The sartek backend can be used with rotators that support the SARtek protocol.

#define ROT_MOVE_CCW   ROT_MOVE_LEFT

A macro that returns the flag for the counterclockwise direction.

This macro defines the value of the counterclockwise direction which can be used with the rot_move() function. This value is equivalent to ROT_MOVE_LEFT .

See also:
rot_move(), ROT_MOVE_UP, ROT_MOVE_DOWN, ROT_MOVE_LEFT, ROT_MOVE_RIGHT, ROT_MOVE_CW

#define ROT_MOVE_CW   ROT_MOVE_RIGHT

A macro that returns the flag for the clockwise direction.

This macro defines the value of the clockwise direction wich can be used with the rot_move() function. This value is equivalent to ROT_MOVE_RIGHT .

See also:
rot_move(), ROT_MOVE_UP, ROT_MOVE_DOWN, ROT_MOVE_LEFT, ROT_MOVE_CCW, ROT_MOVE_RIGHT

#define ROT_MOVE_DOWN   (1<<2)

A macro that returns the flag for the DOWN direction.

This macro defines the value of the DOWN direction which can be used with the rot_move() function.

See also:
rot_move(), ROT_MOVE_UP, ROT_MOVE_LEFT, ROT_MOVE_CCW, ROT_MOVE_RIGHT, ROT_MOVE_CW

#define ROT_MOVE_LEFT   (1<<3)

A macro that returns the flag for the LEFT direction.

This macro defines the value of the LEFT direction which can be used with the rot_move function.

See also:
rot_move(), ROT_MOVE_UP, ROT_MOVE_DOWN, ROT_MOVE_CCW, ROT_MOVE_RIGHT, ROT_MOVE_CW

#define ROT_MOVE_RIGHT   (1<<4)

A macro that returns the flag for the RIGHT direction.

This macro defines the value of the RIGHT direction which can be used with the rot_move() function.

See also:
rot_move(), ROT_MOVE_UP, ROT_MOVE_DOWN, ROT_MOVE_LEFT, ROT_MOVE_CCW, ROT_MOVE_CW

#define ROT_MOVE_UP   (1<<1)

A macro that returns the flag for the UP direction.

This macro defines the value of the UP direction which can be used with the rot_move() function.

See also:
rot_move(), ROT_MOVE_DOWN, ROT_MOVE_LEFT, ROT_MOVE_CCW, ROT_MOVE_RIGHT, ROT_MOVE_CW

#define ROT_RESET_ALL   1

A macro that returns the flag for the reset operation.

See also:
rot_reset(), rot_reset_t


Typedef Documentation

typedef float azimuth_t

Type definition for azimuth.

The azimuth_t type is used as parameter for the rot_set_position() and rot_get_position() functions.

Unless specified otherwise, the unit of azimuth_t is decimal degrees.

typedef float elevation_t

Type definition for elevation.

The elevation_t type is used as parameter for the rot_set_position() and rot_get_position() functions.

Unless specified otherwise, the unit of elevation_t is decimal degrees.

typedef int rot_reset_t

Type definition for rotator reset.

The rot_reset_t type is used as parameter for the rot_reset() API function.


Function Documentation

int foreach_opened_rot ( int(*)(ROT *, char *)  cfunc,
char *  data 
)

execs cfunc() on each opened rot

Parameters:
cfunc The function to be executed on each rot
data Data pointer to be passed to cfunc()
Calls cfunc() function for each opened rot. The contents of the opened rot table is processed in random order according to a function pointed to by cfunc, whic is called with two arguments, the first pointing to the ROT handle, the second to a data pointer data. If data is not needed, then it can be set to NULL. The processing of the opened rot table is stopped when cfunc() returns 0.

int frontrot_get_conf ( ROT rot,
token_t  token,
char *  val 
)

Get data from rotator state in alpha form.

Parameters:
rot non-null
token TOK_... specifying which data to get
val result non-null
Returns:
RIG_OK or < 0 if error

int frontrot_set_conf ( ROT rot,
token_t  token,
const char *  val 
)

Set rotator state info from alpha input.

Parameters:
rot 
token TOK_... specifying which info to set
val input
Returns:
RIG_OK or < 0 error
assumes rot!=NULL, val!=NULL TODO: check format of val before doing atoi().

int rot_cleanup ( ROT rot  ) 

release a rot handle and free associated memory

Parameters:
rot The ROT handle of the radio to be closed
Releases a rot struct which port has eventualy been closed already with rot_close().

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rot_init(), rot_close()

int rot_close ( ROT rot  ) 

close the communication to the rot

Parameters:
rot The ROT handle of the rotator to be closed
Closes communication to a radio which ROT handle has been passed by argument that was previously open with rot_open().

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rot_cleanup(), rot_open()

struct confparams* rot_confparam_lookup ( ROT rot,
const char *  name 
) [read]

lookup conf token by its name, return pointer to confparams struct.

Parameters:
rot 
name 
Returns:
confparams or NULL
lookup backend config table first, then fall back to frontend. TODO: should use Lex to speed it up, strcmp hurts!

int rot_get_conf ( ROT rot,
token_t  token,
char *  val 
)

get the value of a configuration parameter

Parameters:
rot The rot handle
token The parameter
val The location where to store the value of config token
Retrieves the value of a configuration paramter associated with token.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rot_set_conf()

const char* rot_get_info ( ROT rot  ) 

get general information from the rotator

Parameters:
rot The rot handle
Retrieves some general information from the rotator. This can include firmware revision, exact model name, or just nothing.

Returns:
a pointer to static memory containing the ASCIIZ string if the operation has been sucessful, otherwise NULL if an error occured or get_info not part of capabilities.

int rot_get_position ( ROT rot,
azimuth_t azimuth,
elevation_t elevation 
)

get the azimuth and elevation of the rotator

Parameters:
rot The rot handle
azimuth The location where to store the current azimuth
elevation The location where to store the current elevation
Retrieves the current azimuth and elevation of the rotator.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rot_set_position()

ROT* rot_init ( rot_model_t  rot_model  ) 

allocate a new ROT handle

Parameters:
rot_model The rot model for this new handle
Allocates a new ROT handle and initializes the associated data for rot_model.

Returns:
a pointer to the ROT handle otherwise NULL if memory allocation failed or rot_model is unknown (e.g. backend autoload failed).
See also:
rot_cleanup(), rot_open()

int rot_move ( ROT rot,
int  direction,
int  speed 
)

move the rotator in the specified direction

Parameters:
rot The rot handle
direction Direction of movement
speed Speed of movement
Move the rotator in the specified direction. The speed is a value between 1 and 100.

int rot_open ( ROT rot  ) 

open the communication to the rot

Parameters:
rot The ROT handle of the rotator to be opened
Opens communication to a rotator which ROT handle has been passed by argument.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
Return values:
RIG_EINVAL rot is NULL or unconsistent.
RIG_ENIMPL port type communication is not implemented yet.
See also:
rot_init(), rot_close()

int rot_park ( ROT rot  ) 

park the antenna

Parameters:
rot The rot handle
Park the antenna.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).

int rot_reset ( ROT rot,
rot_reset_t  reset 
)

reset the rotator

Parameters:
rot The rot handle
reset The reset operation to perform
Resets the rotator.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).

int rot_set_conf ( ROT rot,
token_t  token,
const char *  val 
)

set a rotator configuration parameter

Parameters:
rot The rot handle
token The parameter
val The value to set the parameter to
Sets a configuration parameter.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rot_get_conf()

int rot_set_position ( ROT rot,
azimuth_t  azimuth,
elevation_t  elevation 
)

set the azimuth and elevation of the rotator

Parameters:
rot The rot handle
azimuth The azimuth to set to
elevation The elevation to set to
Sets the azimuth and elevation of the rotator.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).
See also:
rot_get_position()

int rot_stop ( ROT rot  ) 

stop the rotator

Parameters:
rot The rot handle
Stop the rotator.

Returns:
RIG_OK if the operation has been sucessful, otherwise a negative value if an error occured (in which case, cause is set appropriately).

int rot_token_foreach ( ROT rot,
int(*)(const struct confparams *, char *)  cfunc,
char *  data 
)

Executes cfunc on all the elements stored in the conf table.

Parameters:
rot non-null
cfunc function(..)
data start first with backend conf table, then finish with frontend table

token_t rot_token_lookup ( ROT rot,
const char *  name 
)

Simple lookup returning token id associated with name.

Parameters:
rot 
name 
Returns:
token enum


Hamlib documentation for version 1.2.7 -- Tue Aug 26 21:43:29 2008
Project page: http://hamlib.org