Main Page | Data Structures | File List | Data Fields | Globals

src/emul.h File Reference

Header file for the emul library. More...

Go to the source code of this file.

Data Structures

struct  serconfig
 Structure used with em_serconfig_set and em_serconfig_get. More...


Defines

#define NORMAL   0x0
 For use with em_devtype function.

#define EMATE   0x1
 For use with em_devtype function.

#define CONTROL_DTR   0x20 /* data terminal ready - flow control - host to device */
 For use with em_linecontrol function.

#define CONTROL_RTS   0x10 /* request to send - flow control - host to device */
 For use with em_linecontrol function.

#define CONTROL_RESET   0x08 /* sent with output report (unknown affect) - host to device */
 For use with em_linecontrol function.

#define CONTROL_DROP   0x00 /* drop all lines */
 For use with em_linecontrol function.

#define PAR_ODD   0x30
 For use with parameter parity of structure serconfig.

#define PAR_EVEN   0x10
 For use with parameter parity of structure serconfig.

#define PAR_NONE   0x00
 For use with parameter parity of structure serconfig.

#define EM_MAX_READ   4096
 For use with em_read function.

#define EM_MAX_WRITE   4096
 For use with em_write function.

#define EMT_ACTIVE   1
 For use with em_change_state function.

#define EMT_IDLING   0
 For use with em_change_state function.

#define VENDOR_ID_DELORME   0x1163
 The USB Vendor ID used to find the Earthmate device with libusb.

#define PRODUCT_ID_EARTHMATEUSB   0x0100
 The USB Product ID used to find the Earthmate device with libusb.

#define MAX_READ_WRITE   30
 For use with em_raw_read and em_raw_write.


Functions

void em_devtype (int type)
 Sets the device type, either a normal tty or earthmate device.

int em_isemate (void)
 Indicates whether or not device type is set to normal tty or earthmate device.

int em_isactive (void)
 Indicates whether or not the device has been opened and thread is active.

int em_open (void)
 Opens the earthmate device and starts thread.

void em_close (void)
 Closes the earthmate device and stops thread.

int em_replug (void)
 Causes reenumeration after device and thread have been stopped.

void em_linecontrol (u_int8_t lines)
 Sets the line state for the earthmate device.

int em_serconfig_set (struct serconfig *sconfig)
 Function for setting serial parameters using serconfig object.

int em_serconfig_get (struct serconfig *sconfig)
 Function for retrieving serial parameters using serconfig object.

int em_read (u_int8_t buffer[], int count)
 Function for retrieving read data from Earthmate device from read buffer.

int em_write (const u_int8_t *buffer, int count)
 Function for sending write data from the program to the write buffer.

int em_flush (int queue_selector)
 Function for clearing either the read, write, or both buffers.

int em_read_data_avail (void)
 Function that indicates how much data is available in the read buffer.

int em_write_data_avail (void)
 Function that indicates how much data is available in the write buffer.

int em_datawait (struct timeval *tv, int jumpout)
 Function that stops execution by sleeping either until data becomes available in the read buffer, or the timeout value expires. Behaves almost like select.

int em_select (int n, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout)
 Function that waits on select activity and/or read buffer data becoming available.

void em_writewait (void)
 Counterpart to tcdrain. Sleeps until all data in write buffer has been written.

void em_debuglevel (int mode)
 Function that sets the debugging level of the emul library.

ssize_t READ (int fd, void *buf, size_t count)
 Function that can be placed wherever read() is used safely.

ssize_t WRITE (int fd, const void *buf, size_t count)
 Function that can be placed wherever write() is used safely.

unsigned int em_getbaudmask (unsigned int rate)
 Function for retrieving integer baud rate from masked rate.

long em_getbaudrate (void)
 Function for retriving current baudrate of connection with the Earthmate device.

int em_raw_read (u_int8_t buffer[])
 Function that reads directly from the Earthmate device. If the thread is active, this function should never be called as libusb will have you pulling your hair out.

int em_raw_write (u_int8_t *buffer, int size)
 Function that writes directly to the Earthmate device. If the thread is active, this function should never be called as libusb will have you pulling your hair out.


Detailed Description

Header file for the emul library.

Contains facilities for accessing the earthmate.


Define Documentation

#define CONTROL_DROP   0x00 /* drop all lines */
 

For use with em_linecontrol function.

When used in conjunction with em_linecontrol, this will drop both dtr and rts lines on the Earthmate device. This should be issued without bitmask.

#define CONTROL_DTR   0x20 /* data terminal ready - flow control - host to device */
 

For use with em_linecontrol function.

When used in conjunction with em_linecontrol, this will raise the dtr line on the Earthmate device. This can be bitmasked with CONTROL_RTS and CONTROL_RESET.

FYI, DTR is an acronym for data terminal ready.

#define CONTROL_RESET   0x08 /* sent with output report (unknown affect) - host to device */
 

For use with em_linecontrol function.

When used in conjunction with em_linecontrol, this will cause a device reset which has and as yet unknown affect on the Earthmate device. This can be bitmasked with CONTROL_DTR and CONTROL_RTS.

#define CONTROL_RTS   0x10 /* request to send - flow control - host to device */
 

For use with em_linecontrol function.

When used in conjunction with em_linecontrol, this will raise the rts line on the Earthmate device. This can be bitmasked with CONTROL_DTR and CONTROL_RESET.

FYI, RTS is an acronym for request to send.

#define EM_MAX_READ   4096
 

For use with em_read function.

This is the max amount of data the read buffer can store.

#define EM_MAX_WRITE   4096
 

For use with em_write function.

This is the max amount of data the write buffer can store.

#define EMATE   0x1
 

For use with em_devtype function.

When used in conjunction with em_devtype, this will set the active device to an Earthmate device.

#define EMT_ACTIVE   1
 

For use with em_change_state function.

When used in conjunction with the em_change_state function, this will change the thread state to active.

#define EMT_IDLING   0
 

For use with em_change_state function.

When used in conjunction with the em_change_state function, the thread state will change to idle.

#define MAX_READ_WRITE   30
 

For use with em_raw_read and em_raw_write.

This is the max amount of data that can be transmitted with em_raw_read and em_raw_write.

The device can handle 32 bytes for the input/output reports, but 2 bytes are used for length, control line, uart status, etc.

#define NORMAL   0x0
 

For use with em_devtype function.

When used in conjunction with em_devtype, this will set the active device to a normal tty device.

#define PAR_EVEN   0x10
 

For use with parameter parity of structure serconfig.

Indicates even parity.

#define PAR_NONE   0x00
 

For use with parameter parity of structure serconfig.

Indicates no parity.

#define PAR_ODD   0x30
 

For use with parameter parity of structure serconfig.

Indicates odd parity.


Function Documentation

void em_close void   ) 
 

Closes the earthmate device and stops thread.

em_close should be called when the program has finished communicating with the device.

int em_datawait struct timeval *  tv,
int  jumpout
 

Function that stops execution by sleeping either until data becomes available in the read buffer, or the timeout value expires. Behaves almost like select.

Parameters:
tv The timeout value in seconds and microseconds. Can be NULL for infinite block.
jumpout Can be used to skip over entirely the block on certain previous events like a select call. Not all that useful, see em_select below for a better way.
Returns:
Returns 1 if data becomes available in read buffer, or 0 if either timeout value has expired or jumpout has value of 1.

void em_debuglevel int  mode  ) 
 

Function that sets the debugging level of the emul library.

Note:
Debugging is by default 0, which means completely disabled. When enabled, data is printed to stdout or stderr depending on the situation.

void em_devtype int  type  ) 
 

Sets the device type, either a normal tty or earthmate device.

Parameters:
type The type of device (NORMAL or EMATE).

int em_flush int  queue_selector  ) 
 

Function for clearing either the read, write, or both buffers.

Parameters:
queue_selector The type of flush to perform. Valid value for now is TCIOFLUSH.
Returns:
Returns 0 on success, <0 on error.

unsigned int em_getbaudmask unsigned int  rate  ) 
 

Function for retrieving integer baud rate from masked rate.

Parameters:
rate The masked rate to lookup for the integer value.
Returns:
Returns the integer value of the given masked rate.

long em_getbaudrate void   ) 
 

Function for retriving current baudrate of connection with the Earthmate device.

Returns:
Returns the current baud rate in integer form, or <0 on error.

int em_isactive void   ) 
 

Indicates whether or not the device has been opened and thread is active.

Returns:
Returns 1 if device is open and thread is active, 0 otherwise.

int em_isemate void   ) 
 

Indicates whether or not device type is set to normal tty or earthmate device.

Returns:
Returns 1 if device type is EMATE or 0 if device type is NORMAL.

void em_linecontrol u_int8_t  lines  ) 
 

Sets the line state for the earthmate device.

Parameters:
lines This parameter can be bit masked with CONTROL_DTR, CONTROL_RTS, and CONTROL_RESET. CONTROL_DROP should be issued by itself and never masked. CONTROL_RESET has an unknown affect.

int em_open void   ) 
 

Opens the earthmate device and starts thread.

This must be the first function called before device can be accessed. Only a few functions can be called without opening the device first.

Returns:
Returns 0 on success, -1 on error.

int em_raw_read u_int8_t  buffer[]  ) 
 

Function that reads directly from the Earthmate device. If the thread is active, this function should never be called as libusb will have you pulling your hair out.

Note:
Always use the MAX_READ_WRITE define if you dare to use this function.

int em_raw_write u_int8_t *  buffer,
int  size
 

Function that writes directly to the Earthmate device. If the thread is active, this function should never be called as libusb will have you pulling your hair out.

Note:
Always use the MAX_READ_WRITE define if you dare to use this function.

int em_read u_int8_t  buffer[],
int  count
 

Function for retrieving read data from Earthmate device from read buffer.

Parameters:
buffer An array of unsigned 8 bit elements pre-allocated before being passed.
count The amount of data that the function should try to fill buffer with.
Note:
This function is non-blocking.
Returns:
Returns amount of data read. >=0 on success, <0 on error.

int em_read_data_avail void   ) 
 

Function that indicates how much data is available in the read buffer.

Note:
This function is non-blocking.
Returns:
On success the amount of data in read buffer is returned, <0 on error.

int em_replug void   ) 
 

Causes reenumeration after device and thread have been stopped.

After a successful call, a new usb device handle will have been obtained and the thread will start again. The usual functions may be called once more.

Returns:
Returns 0 on success, -1 on error.

int em_select int  n,
fd_set *  readfds,
fd_set *  writefds,
fd_set *  exceptfds,
struct timeval *  timeout
 

Function that waits on select activity and/or read buffer data becoming available.

Parameters:
n The number of fds to watch (always +1). Typically, FD_SETSIZE is passed.
readfds The fd_set to watch for read activity. Can be NULL.
writefds The fd_set to watch for write activity. Can be NULL.
exceptfds The fd_set to watch for exceptional activity, like errors. Can be NULL.
timeout The time in seconds and microseconds to wait. Can be NULL.
Note:
The function does not return on data becoming available in the write buffer.
Returns:
Returns the number of fds with activity. This can include read buffer activity as well.

int em_serconfig_get struct serconfig sconfig  ) 
 

Function for retrieving serial parameters using serconfig object.

Returns:
Returns 0 on success, <0 on error.

int em_serconfig_set struct serconfig sconfig  ) 
 

Function for setting serial parameters using serconfig object.

Parameters:
sconfig Object of serconfig which holds serial parameters to be set.
Note:
The serconfig object being passed must have all fields set.
Returns:
Returns 0 on success, <0 on error.

int em_write const u_int8_t *  buffer,
int  count
 

Function for sending write data from the program to the write buffer.

Parameters:
buffer Pointer to the data that is to be transfered into the write buffer.
count The amount of data to try and write to the write buffer.
Note:
This function is non-blocking.
Returns:
Returns amount of data written. >=0 on success, <0 on error.

int em_write_data_avail void   ) 
 

Function that indicates how much data is available in the write buffer.

Note:
This function is non-blocking.
Returns:
On success the amount of data in write buffer is returned, <0 on error.

ssize_t READ int  fd,
void *  buf,
size_t  count
 

Function that can be placed wherever read() is used safely.

Parameters:
fd File descriptor to read from.
buf Buffer to read into.
count Amount of data to try and read.
Note:
Also have a look at em_read().
Returns:
Returns amount of data read, or <0 on error.

ssize_t WRITE int  fd,
const void *  buf,
size_t  count
 

Function that can be placed wherever write() is used safely.

Parameters:
fd File descriptor to write to.
buf Buffer data to write.
count Amount of data to try and write.
Returns:
Returns amount of data written, or <0 on error.


Generated on Sat Apr 2 14:58:13 2005 for EarthMate Userland Library by doxygen 1.3.7