Rig Internal API


Files

file  cal.c
 Calibration routines.
file  debug.c
 control hamlib debugging functions
file  misc.c
 Miscellaneous utility routines.
file  parallel.c
 Parallel Port IO.
file  serial.c
 Serial port IO.
file  token.h
 Token definitions.
file  usb_port.c
 USB IO.

Defines

#define TOKEN_BACKEND(t)   (t)
 Create a backend token, t.
#define TOKEN_FRONTEND(t)   ((t)|(1<<30))
 Create a frontend token, t.
#define IS_TOKEN_FRONTEND(t)   ((t)&(1<<30))
 Test for token - frontend?
#define TOK_FRONTEND_NONE   TOKEN_FRONTEND(0)
 Null frontend token.
#define TOK_BACKEND_NONE   TOKEN_BACKEND(0)
 Null backend token.
#define TOK_PATHNAME   TOKEN_FRONTEND(10)
 Pathname is device for rig control, e.g. /dev/ttyS0.
#define TOK_WRITE_DELAY   TOKEN_FRONTEND(12)
 Delay before serial output (units?).
#define TOK_POST_WRITE_DELAY   TOKEN_FRONTEND(13)
 Delay after serial output (units?).
#define TOK_TIMEOUT   TOKEN_FRONTEND(14)
 Timeout delay (units?).
#define TOK_RETRY   TOKEN_FRONTEND(15)
 Number of retries permitted.
#define TOK_SERIAL_SPEED   TOKEN_FRONTEND(20)
 Serial speed - "baud rate".
#define TOK_DATA_BITS   TOKEN_FRONTEND(21)
 No. data bits per serial character.
#define TOK_STOP_BITS   TOKEN_FRONTEND(22)
 No. stop bits per serial character.
#define TOK_PARITY   TOKEN_FRONTEND(23)
 Serial parity (format?).
#define TOK_HANDSHAKE   TOKEN_FRONTEND(24)
 Serial Handshake (format?).
#define TOK_RTS_STATE   TOKEN_FRONTEND(25)
 Serial Req. To Send status.
#define TOK_DTR_STATE   TOKEN_FRONTEND(26)
 Serial Data Terminal Ready status.
#define TOK_VFO_COMP   TOKEN_FRONTEND(110)
 rig: ??
#define TOK_POLL_INTERVAL   TOKEN_FRONTEND(111)
 rig: polling interval (units?)
#define TOK_ITU_REGION   TOKEN_FRONTEND(120)
 rig: International Telecommunications Union region no.
#define TOK_MIN_AZ   TOKEN_FRONTEND(110)
 rot: Minimum Azimuth
#define TOK_MAX_AZ   TOKEN_FRONTEND(111)
 rot: Maximum Azimuth
#define TOK_MIN_EL   TOKEN_FRONTEND(112)
 rot: Minimum Elevation
#define TOK_MAX_EL   TOKEN_FRONTEND(113)
 rot: Maximum Elevation

Functions

float rig_raw2val (int rawval, const cal_table_t *cal)
 Convert raw S-meter data to calibated value, according to table.
void dump_hex (const unsigned char ptr[], size_t size)
 Do a hex dump of the unsigned char array.
void rig_set_debug (enum rig_debug_level_e debug_level)
 Change the current debug level.
int rig_need_debug (enum rig_debug_level_e debug_level)
 Useful for dump_hex, etc.
void rig_debug (enum rig_debug_level_e debug_level, const char *fmt,...)
 Default is debugging messages are done through stderr.
vprintf_cb_t rig_set_debug_callback (vprintf_cb_t cb, char *arg)
 set callback to handle debug messages
FILE * rig_set_debug_file (FILE *stream)
 change stderr to some different output
int write_block (hamlib_port_t *p, const char *txbuffer, size_t count)
 Write a block of characters to an fd.
int read_block (hamlib_port_t *p, char *rxbuffer, size_t count)
 Read bytes from an fd.
int read_string (hamlib_port_t *p, char *rxbuffer, size_t rxmax, const char *stopset, int stopset_len)
 Read a string from an fd.
unsigned char * to_bcd (unsigned char bcd_data[], unsigned long long freq, unsigned bcd_len)
 Convert from binary to 4-bit BCD digits, little-endian.
unsigned long long from_bcd (const unsigned char bcd_data[], unsigned bcd_len)
 Convert BCD digits, little-endian, to a long long (e.g. frequency in Hz).
unsigned char * to_bcd_be (unsigned char bcd_data[], unsigned long long freq, unsigned bcd_len)
 Convert from binary to 4-bit BCD digits, big-endian.
unsigned long long from_bcd_be (const unsigned char bcd_data[], unsigned bcd_len)
 Convert 4-bit BCD digits to binary, big-endian.
int sprintf_freq (char *str, freq_t freq)
 Pretty print a frequency.
const char * rig_strstatus (enum rig_status_e status)
 Convert enum RIG_STATUS_... to printable string.
rmode_t rig_parse_mode (const char *s)
 Convert alpha string to enum RIG_MODE.
const char * rig_strrmode (rmode_t mode)
 Convert enum RIG_MODE to alpha string.
vfo_t rig_parse_vfo (const char *s)
 Convert alpha string to enum RIG_VFO_...
const char * rig_strvfo (vfo_t vfo)
 Convert enum RIG_VFO_... to alpha string.
setting_t rig_parse_func (const char *s)
 Convert alpha string to enum RIG_FUNC_...
const char * rig_strfunc (setting_t func)
 Convert enum RIG_FUNC_... to alpha string.
setting_t rig_parse_level (const char *s)
 Convert alpha string to enum RIG_LEVEL_...
const char * rig_strlevel (setting_t level)
 Convert enum RIG_LEVEL_... to alpha string.
setting_t rig_parse_parm (const char *s)
 Convert alpha string to RIG_PARM_...
const char * rig_strparm (setting_t parm)
 Convert enum RIG_PARM_... to alpha string.
vfo_op_t rig_parse_vfo_op (const char *s)
 Convert alpha string to enum RIG_OP_...
const char * rig_strvfop (vfo_op_t op)
 Convert enum RIG_OP_... to alpha string.
scan_t rig_parse_scan (const char *s)
 Convert alpha string to enum RIG_SCAN_...
const char * rig_strscan (scan_t rscan)
 Convert enum RIG_SCAN_... to alpha string.
const char * rig_strptrshift (rptr_shift_t shift)
 convert enum RIG_RPT_SHIFT_... to printable character
rptr_shift_t rig_parse_rptr_shift (const char *s)
 Convert alpha char to enum RIG_RPT_SHIFT_...
int par_open (hamlib_port_t *port)
 Open Parallel Port.
int par_close (hamlib_port_t *port)
 Close Parallel Port.
int par_write_data (hamlib_port_t *port, unsigned char data)
 Send data on Parallel port.
int par_read_data (hamlib_port_t *port, unsigned char *data)
 Receive data on Parallel port.
int par_write_control (hamlib_port_t *port, unsigned char control)
 Set control data for Parallel Port.
int par_read_control (hamlib_port_t *port, unsigned char *control)
 Read control data for Parallel Port.
int par_read_status (hamlib_port_t *port, unsigned char *status)
 Get parallel port status.
int par_lock (hamlib_port_t *port)
 Get a lock on the Parallel Port.
int par_unlock (hamlib_port_t *port)
 Release lock on Parallel Port.
int par_ptt_set (hamlib_port_t *p, ptt_t pttx)
 Set or unset Push to talk bit on Parallel Port.
int par_ptt_get (hamlib_port_t *p, ptt_t *pttx)
 Get state of Push to Talk from Parallel Port.
int par_dcd_get (hamlib_port_t *p, dcd_t *dcdx)
 get Data Carrier Detect (squelch) from Parallel Port
int serial_open (hamlib_port_t *rp)
 Open serial port using rig.state data.
int serial_setup (hamlib_port_t *rp)
 Set up Serial port according to requests in port.
int serial_flush (hamlib_port_t *p)
 Flush all characters waiting in RX buffer.
int ser_open (hamlib_port_t *p)
 Open serial port.
int ser_close (hamlib_port_t *p)
 Close serial port.
int ser_set_rts (hamlib_port_t *p, int state)
 Set Request to Send (RTS) bit.
int ser_get_rts (hamlib_port_t *p, int *state)
 Get RTS bit.
int ser_set_dtr (hamlib_port_t *p, int state)
 Set Data Terminal Ready (DTR) bit.
int ser_get_dtr (hamlib_port_t *p, int *state)
 Get DTR bit.
int ser_set_brk (hamlib_port_t *p, int state)
 Set Break.
int ser_get_car (hamlib_port_t *p, int *state)
 Get Carrier (CI?) bit.
int ser_get_cts (hamlib_port_t *p, int *state)
 Get Clear to Send (CTS) bit.
int ser_get_dsr (hamlib_port_t *p, int *state)
 Get Data Set Ready (DSR) bit.

Function Documentation

void dump_hex ( const unsigned char  ptr[],
size_t  size 
)

Do a hex dump of the unsigned char array.

Parameters:
ptr Pointer to memory area
size Number of chars to words to dump

unsigned long long from_bcd ( const unsigned char  bcd_data[],
unsigned  bcd_len 
)

Convert BCD digits, little-endian, to a long long (e.g. frequency in Hz).

Parameters:
bcd_data 
bcd_len 
Returns:
binary result (e.g. frequency)
Convert BCD digits, little-endian, (byte order 90 78 56 34 12 for 1234567890 Hz) to a long long (e.g. frequency in Hz)

bcd_len is the number of BCD digits.

Hope the compiler will do a good job optimizing it (esp. w/ the 64bit freq)

Returns frequency in Hz an unsigned long long integer.

See also:
from_bcd_be

unsigned long long from_bcd_be ( const unsigned char  bcd_data[],
unsigned  bcd_len 
)

Convert 4-bit BCD digits to binary, big-endian.

Parameters:
bcd_data 
bcd_len 
Returns:
binary result
Same as from_bcd, but in big-endian order (e.g. byte order 12 34 56 78 90 for 1234567890 Hz)

See also:
from_bcd

int par_close ( hamlib_port_t port  ) 

Close Parallel Port.

Parameters:
port 

int par_dcd_get ( hamlib_port_t p,
dcd_t dcdx 
)

get Data Carrier Detect (squelch) from Parallel Port

Parameters:
p 
dcdx return value (Must be non NULL)
Returns:
RIG_OK or < 0 error

int par_lock ( hamlib_port_t port  ) 

Get a lock on the Parallel Port.

Parameters:
port 
Returns:
RIG_OK or < 0

int par_open ( hamlib_port_t port  ) 

Open Parallel Port.

Parameters:
port 
Returns:
file descriptor
TODO: to be called before exiting: atexit(parport_cleanup) void parport_cleanup() { ioctl(fd, PPRELEASE); }

int par_ptt_get ( hamlib_port_t p,
ptt_t pttx 
)

Get state of Push to Talk from Parallel Port.

Parameters:
p 
pttx return value (must be non NULL)
Returns:
RIG_OK or < 0 error

int par_ptt_set ( hamlib_port_t p,
ptt_t  pttx 
)

Set or unset Push to talk bit on Parallel Port.

Parameters:
p 
pttx RIG_PTT_ON --> Set PTT
Returns:
RIG_OK or < 0 error

int par_read_control ( hamlib_port_t port,
unsigned char *  control 
)

Read control data for Parallel Port.

Parameters:
port 
control 

int par_read_data ( hamlib_port_t port,
unsigned char *  data 
)

Receive data on Parallel port.

Parameters:
port 
data 

int par_read_status ( hamlib_port_t port,
unsigned char *  status 
)

Get parallel port status.

Parameters:
port 
status 
Returns:
RIG_OK or < 0 for error

int par_unlock ( hamlib_port_t port  ) 

Release lock on Parallel Port.

Parameters:
port 
Returns:
RIG_OK or < 0

int par_write_control ( hamlib_port_t port,
unsigned char  control 
)

Set control data for Parallel Port.

Parameters:
port 
control 

int par_write_data ( hamlib_port_t port,
unsigned char  data 
)

Send data on Parallel port.

Parameters:
port 
data 

int read_block ( hamlib_port_t p,
char *  rxbuffer,
size_t  count 
)

Read bytes from an fd.

Parameters:
p rig port descriptor
rxbuffer buffer to receive text
count number of bytes
Returns:
count of bytes received
Read "num" bytes from "fd" and put results into an array of unsigned char pointed to by "rxbuffer"

Blocks on read until timeout hits.

It then reads "num" bytes into rxbuffer.

Actually, this function has nothing specific to serial comm, it could work very well also with any file handle, like a socket.

int read_string ( hamlib_port_t p,
char *  rxbuffer,
size_t  rxmax,
const char *  stopset,
int  stopset_len 
)

Read a string from an fd.

Parameters:
p Hamlib port descriptor
rxbuffer buffer to receive string
rxmax maximum string size + 1
stopset string of recognized end of string characters
stopset_len length of stopset
Read a string from "fd" and put result into an array of unsigned char pointed to by "rxbuffer"

Blocks on read until timeout hits.

It then reads characters until one of the characters in "stopset" is found, or until "rxmax-1" characters was copied into rxbuffer. String termination character is added at the end.

Actually, this function has nothing specific to serial comm, it could work very well also with any file handle, like a socket.

Assumes rxbuffer!=NULL

void rig_debug ( enum rig_debug_level_e  debug_level,
const char *  fmt,
  ... 
)

Default is debugging messages are done through stderr.

Parameters:
debug_level 
fmt 

int rig_need_debug ( enum rig_debug_level_e  debug_level  ) 

Useful for dump_hex, etc.

Parameters:
debug_level 

setting_t rig_parse_func ( const char *  s  ) 

Convert alpha string to enum RIG_FUNC_...

Parameters:
s input alpha string
Returns:
RIG_FUNC_...
See also:
rig_func_e

setting_t rig_parse_level ( const char *  s  ) 

Convert alpha string to enum RIG_LEVEL_...

Parameters:
s input alpha string
Returns:
RIG_LEVEL_...
See also:
rig_level_e

rmode_t rig_parse_mode ( const char *  s  ) 

Convert alpha string to enum RIG_MODE.

Parameters:
s input alpha string
Returns:
enum RIG_MODE_??
See also:
rmode_t

setting_t rig_parse_parm ( const char *  s  ) 

Convert alpha string to RIG_PARM_...

Parameters:
s input alpha string
Returns:
RIG_PARM_...
See also:
rig_parm_e

rptr_shift_t rig_parse_rptr_shift ( const char *  s  ) 

Convert alpha char to enum RIG_RPT_SHIFT_...

Parameters:
s alpha char
Returns:
RIG_RPT_SHIFT_...

scan_t rig_parse_scan ( const char *  s  ) 

Convert alpha string to enum RIG_SCAN_...

Parameters:
s alpha string
Returns:
RIG_SCAN_...
See also:
scan_t

vfo_t rig_parse_vfo ( const char *  s  ) 

Convert alpha string to enum RIG_VFO_...

Parameters:
s input alpha string
Returns:
RIG_VFO_...
See also:
RIG_VFO_A RIG_VFO_B RIG_VFO_C RIG_VFO_MAIN RIG_VFO_SUB RIG_VFO_VFO RIG_VFO_CURR RIG_VFO_MEM RIG_VFO_TX RIG_VFO_RX RIG_VFO_NONE

vfo_op_t rig_parse_vfo_op ( const char *  s  ) 

Convert alpha string to enum RIG_OP_...

Parameters:
s alpha string
Returns:
RIG_OP_...
See also:
vfo_op_t

float rig_raw2val ( int  rawval,
const cal_table_t cal 
)

Convert raw S-meter data to calibated value, according to table.

Parameters:
rawval input value
cal calibration table
Returns:
calibrated value
cal_table_t is a data type suited to hold linear calibration cal_table_t.size tell the number of plot cal_table_t.table contains If a value is below or equal to cal_table_t.table[0].raw, rig_raw2val() will return cal_table_t.table[0].val If a value is greater or equal to cal_table_t.table[cal_table_t.size-1].raw, rig_raw2val() will return cal_table_t.table[cal_table_t.size-1].val

void rig_set_debug ( enum rig_debug_level_e  debug_level  ) 

Change the current debug level.

Parameters:
debug_level 

vprintf_cb_t rig_set_debug_callback ( vprintf_cb_t  cb,
char *  arg 
)

set callback to handle debug messages

Parameters:
cb The callback to install
arg A Pointer to some private data to pass later on to the callback
Install a callback for rig_debug messages.
int
rig_message_cb   (enum rig_debug_level_e debug_level,
                  rig_ptr_t user_data,
                  const char *fmt,
                  va_list ap)
{
        char buf[1024];

        sprintf (buf, "Message(%s) ", (char*)user_data);
        syslog (LOG_USER, buf);
        vsprintf (buf, fmt, ap);
        syslog (LOG_USER, buf);

        return RIG_OK;
}

        . . .

        char *cookie = "Foo";
        rig_set_debug_callback (rig_message_cb, (rig_ptr_t)cookie);

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:
rig_debug()

FILE* rig_set_debug_file ( FILE *  stream  ) 

change stderr to some different output

Parameters:
stream The stream to set output to

const char* rig_strfunc ( setting_t  func  ) 

Convert enum RIG_FUNC_... to alpha string.

Parameters:
func RIG_FUNC_...
Returns:
alpha string
See also:
rig_func_e

const char* rig_strlevel ( setting_t  level  ) 

Convert enum RIG_LEVEL_... to alpha string.

Parameters:
level RIG_LEVEL_...
Returns:
alpha string
See also:
rig_level_e

const char* rig_strparm ( setting_t  parm  ) 

Convert enum RIG_PARM_... to alpha string.

Parameters:
parm RIG_PARM_...
Returns:
alpha string
See also:
rig_parm_e

const char* rig_strptrshift ( rptr_shift_t  shift  ) 

convert enum RIG_RPT_SHIFT_... to printable character

Parameters:
shift RIG_RPT_SHIFT_??
Returns:
alpha character

const char* rig_strrmode ( rmode_t  mode  ) 

Convert enum RIG_MODE to alpha string.

Parameters:
mode RIG_MODE_...
Returns:
alpha string
See also:
rmode_t

const char* rig_strscan ( scan_t  rscan  ) 

Convert enum RIG_SCAN_... to alpha string.

Parameters:
rscan RIG_SCAN_...
Returns:
alpha string
See also:
scan_t

const char* rig_strstatus ( enum rig_status_e  status  ) 

Convert enum RIG_STATUS_... to printable string.

Parameters:
status RIG_STATUS_??
Returns:
string

const char* rig_strvfo ( vfo_t  vfo  ) 

Convert enum RIG_VFO_... to alpha string.

Parameters:
vfo RIG_VFO_...
Returns:
alpha string
See also:
RIG_VFO_A RIG_VFO_B RIG_VFO_C RIG_VFO_MAIN RIG_VFO_SUB RIG_VFO_VFO RIG_VFO_CURR RIG_VFO_MEM RIG_VFO_TX RIG_VFO_RX RIG_VFO_NONE

const char* rig_strvfop ( vfo_op_t  op  ) 

Convert enum RIG_OP_... to alpha string.

Parameters:
op RIG_OP_...
Returns:
alpha string
See also:
vfo_op_t

int ser_close ( hamlib_port_t p  ) 

Close serial port.

Parameters:
p fd
Returns:
RIG_OK or < 0

int ser_get_car ( hamlib_port_t p,
int *  state 
)

Get Carrier (CI?) bit.

Parameters:
p supposed to be &rig->state.rigport
state non-NULL

int ser_get_cts ( hamlib_port_t p,
int *  state 
)

Get Clear to Send (CTS) bit.

Parameters:
p supposed to be &rig->state.rigport
state non-NULL

int ser_get_dsr ( hamlib_port_t p,
int *  state 
)

Get Data Set Ready (DSR) bit.

Parameters:
p supposed to be &rig->state.rigport
state non-NULL

int ser_get_dtr ( hamlib_port_t p,
int *  state 
)

Get DTR bit.

Parameters:
p supposed to be &rig->state.rigport
state non-NULL

int ser_get_rts ( hamlib_port_t p,
int *  state 
)

Get RTS bit.

Parameters:
p supposed to be &rig->state.rigport
state non-NULL

int ser_open ( hamlib_port_t p  ) 

Open serial port.

Parameters:
p 
Returns:
fd

int ser_set_brk ( hamlib_port_t p,
int  state 
)

Set Break.

Parameters:
p 
state (ignored?)
Returns:
RIG_OK or < 0

int ser_set_dtr ( hamlib_port_t p,
int  state 
)

Set Data Terminal Ready (DTR) bit.

Parameters:
p 
state true/false
Returns:
RIG_OK or < 0

int ser_set_rts ( hamlib_port_t p,
int  state 
)

Set Request to Send (RTS) bit.

Parameters:
p 
state true/false
Returns:
RIG_OK or < 0

int serial_flush ( hamlib_port_t p  ) 

Flush all characters waiting in RX buffer.

Parameters:
p 
Returns:
RIG_OK

int serial_open ( hamlib_port_t rp  ) 

Open serial port using rig.state data.

Parameters:
rp port data structure (must spec port id eg /dev/ttyS1)
Returns:
RIG_OK or < 0 if error

int serial_setup ( hamlib_port_t rp  ) 

Set up Serial port according to requests in port.

Parameters:
rp 
Returns:
RIG_OK or < 0

int sprintf_freq ( char *  str,
freq_t  freq 
)

Pretty print a frequency.

Parameters:
str for result (may need up to 17 char)
freq input in Hz
rig_freq_snprintf? pretty print frequencies str must be long enough. max can be as long as 17 chars

unsigned char* to_bcd ( unsigned char  bcd_data[],
unsigned long long  freq,
unsigned  bcd_len 
)

Convert from binary to 4-bit BCD digits, little-endian.

Parameters:
bcd_data 
freq 
bcd_len 
Returns:
bcd_data
Convert a long long (e.g. frequency in Hz) to 4-bit BCD digits, packed two digits per octet, in little-endian order (e.g. byte order 90 78 56 34 12 for 1234567890 Hz).

bcd_len is the number of BCD digits, usually 10 or 8 in 1-Hz units, and 6 digits in 100-Hz units for Tx offset data.

Hope the compiler will do a good job optimizing it (esp. w/the 64bit freq)

Returns a pointer to (unsigned char *)bcd_data.

See also:
to_bcd_be

unsigned char* to_bcd_be ( unsigned char  bcd_data[],
unsigned long long  freq,
unsigned  bcd_len 
)

Convert from binary to 4-bit BCD digits, big-endian.

Parameters:
bcd_data 
freq 
bcd_len 
Returns:
bcd_data
Same as to_bcd, but in big-endian order (e.g. byte order 12 34 56 78 90 for 1234567890 Hz)

See also:
to_bcd

int write_block ( hamlib_port_t p,
const char *  txbuffer,
size_t  count 
)

Write a block of characters to an fd.

Parameters:
p rig port descriptor
txbuffer command sequence to be sent
count number of bytes to send
Returns:
0 = OK, <0 = NOK
Write a block of count characters to port file descriptor, with a pause between each character if write_delay is > 0

The write_delay is for Yaesu type rigs..require 5 character sequence to be sent with 50-200msec between each char.

Also, post_write_delay is for some Yaesu rigs (eg: FT747) that get confused with sequential fast writes between cmd sequences.

input:

fd - file descriptor to write to txbuffer - pointer to a command sequence array count - count of byte to send from the txbuffer write_delay - write delay in ms between 2 chars post_write_delay - minimum delay between two writes post_write_date - timeval of last write

Actually, this function has nothing specific to serial comm, it could work very well also with any file handle, like a socket.


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