bsSerial.doxy

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////////////
//
// Package:   BotSense
//
// File:      bsSerial.doxy
//
// Description:
//  This file contains the doxygen directives to document the BotSense Standard
//  R2-232 Serial Module. This module comes standard with the BotSense package.
//
////////////////////////////////////////////////////////////////////////////////

/*! \file */

/* ---------------------------------------------------------------------------
 * Serial
 * --------------------------------------------------------------------------*/

/*!
 * \ingroup bsmod
 * \defgroup bsmod_serial Serial
 *
 * BotSense standanrd raw RS-232 serial module.
 *
 * \section bsmod_intro Introduction
 * The client side C/C++ interfaces are provided by the header file
 * \ref include/botsense/bsSerial.h "botsense/bsSerial.h" in conjunction with
 * the libraries libbsclient_serial.a or libbsclient_serial.so.
 * For python clients, the python module
 * \ref bsPython/modules/BotSense/bsSerial.py "BotSense.bsSerial"
 * provides wrapper functions for the C libraries.
 *
 * The server side \ref man_bsproxy "bsProxy" plug-in is the Dynamic Link
 * Library (DLL) libbsserver_serial.so.
 *
 * \par Source Subdirectory: 
 * bsModules/bsSerial
 * \{
 */

/*! \} */ /* end bsmod_serial */


/* ---------------------------------------------------------------------------
 * Serial Client
 * --------------------------------------------------------------------------*/

/*!
 * \ingroup bsmod_serial
 * \defgroup bsmod_serial_cli Client Interfaces
 *
 * The BotSense standard serial client side interfaces provide APIs for C/C++
 * and python applications.
 *
 * \{
 */

/*! \} */ /* end bsmod_serial_cli */

/*!
 * \ingroup bsmod_serial_cli
 * \defgroup man_libbsclient_serial libbsclient_serial Man Pages
 *
 * The libbsclient_serial library provides the functional API between 
 * client applications on one side and request-response messages to/from
 * the \ref man_bsproxy "bsProxy" server on the other side.
 * The \ref man_libbotsense "libbotsense" client library mediates the 
 * client-server session.
 *
 * \{
 */

/*!
\ingroup man_libbsclient_serial
\defgroup man_bsSerialGetMsgName bsSerialGetMsgName
\par Synopsis:
<tt>
\#include "rnr/rnrconfig.h"\n
\#include "botsense/BotSense.h"\n
\#include "botsense/libBotSense.h"\n
\#include "botsense/bsSerial.h"\n\n
const char * \ref bsSerialGetMsgName(\ref BsClient_P   pClient,
                               \ref BsVConnHnd_T hndVConn,
                               uint_t       uMsgId);
</tt>

<b>Description:</b>\n
\copydoc bsSerialGetMsgName
 */

/*!
\ingroup man_libbsclient_serial
\defgroup man_bsSerialReqClose bsSerialReqClose
\par Synopsis:
<tt>
\#include "rnr/rnrconfig.h"\n
\#include "botsense/BotSense.h"\n
\#include "botsense/libBotSense.h"\n
\#include "botsense/bsSerial.h"\n\n
int \ref bsSerialReqClose(\ref BsClient_P pClient,
                          \ref BsVConnHnd_T hndVConn);
</tt>

<b>Description:</b>\n
\copydoc bsSerialReqClose
 */

/*!
\ingroup man_libbsclient_serial
\defgroup man_bsSerialReqOpen bsSerialReqOpen
\par Synopsis:
<tt>
\#include "rnr/rnrconfig.h"\n
\#include "botsense/BotSense.h"\n
\#include "botsense/libBotSense.h"\n
\#include "botsense/bsSerial.h"\n\n
int \ref bsSerialReqOpen(\ref BsClient_P  pClient,
                    const char *sDevName,
                    int         nBaudRate,
                    int         nByteSize,
                    int         cParity,
                    int         nStopBits,
                    bool_t      bRtsCts,
                    bool_t      bXonXoff,
                    bool_t      bInitTrace);
</tt>

<b>Description:</b>\n
\copydoc bsSerialReqOpen
 */

/*!
\ingroup man_libbsclient_serial
\defgroup man_bsSerialReqRead bsSerialReqRead
\par Synopsis:
<tt>
\#include "rnr/rnrconfig.h"\n
\#include "botsense/BotSense.h"\n
\#include "botsense/libBotSense.h"\n
\#include "botsense/bsSerial.h"\n\n
int \ref bsSerialReqRead(\ref BsClient_P   pClient,
                    \ref BsVConnHnd_T hndVConn,
                    size_t       uReadLen,
                    byte_t       rbuf[]);
</tt>

<b>Description:</b>\n
\copydoc bsSerialReqRead
 */

/*!
\ingroup man_libbsclient_serial
\defgroup man_bsSerialReqTrans bsSerialReqTrans
\par Synopsis:
<tt>
\#include "rnr/rnrconfig.h"\n
\#include "botsense/BotSense.h"\n
\#include "botsense/libBotSense.h"\n
\#include "botsense/bsSerial.h"\n\n
int \ref bsSerialReqTrans(\ref BsClient_P  pClient,
                     \ref BsVConnHnd_T hndVConn,
                     byte_t      wbuf[],
                     size_t      uWriteLen,
                     size_t      uReadLen,
                     byte_t      rbuf[]);
</tt>

<b>Description:</b>\n
\copydoc bsSerialReqTrans
 */

/*!
\ingroup man_libbsclient_serial
\defgroup man_bsSerialReqWrite bsSerialReqWrite
\par Synopsis:
<tt>
\#include "rnr/rnrconfig.h"\n
\#include "botsense/BotSense.h"\n
\#include "botsense/libBotSense.h"\n
\#include "botsense/bsSerial.h"\n\n
int \ref bsSerialReqWrite(\ref BsClient_P    pClient,
                     \ref BsVConnHnd_T  hndVConn,
                     byte_t        wbuf[],
                     size_t        uWriteLen);
</tt>

<b>Description:</b>\n
\copydoc bsSerialReqWrite
 */

/*! \} */ /* end bsmod_libbsclient_serial */


/*!
 * \ingroup bsmod_serial_cli
 * \defgroup bsSerial_py BotSense.bsSerial Python Module
 *
 * \{
The bsSerial module under the BotSense python package provides python
applications an interface to communicate with proxied serial devices.
The underlining compiled extension module _bsSerial.so library provides the  
provides the shim between python calling conventions and the C
libbsclient_serial.[a,so] library.

\sa \ref BotSense.bsSerial

\par Example:
\code
#
# Example use of BotSense.bsSerial Module
#

import sys

import BotSense.BotSenseTypes as bsTypes
import BotSense.BotSenseError as bsError
import BotSense.BotSenseServer as bsServer
import BotSense.bsSerial as bsSerial

# create a BotSense client 
cli = bsTypes.BsClient('myserial')

# connect to the bsProxy server at the given IP address and default port
try:
  bsServer.ServerConnect(cli, serverHostName="192.168.0.34")
except bsError.BotSenseError, inst:
  print inst
  sys.exit(8)

# open a virtual connection to a proxied serial device
try:
  hndVConn = bsSerial.SerialReqOpen(cli, "/dev/ttyUSB0", baudRate=115200)
except bsError.BotSenseError, inst:
  print inst
  sys.exit(8)
print "Example: established virtual connection %d" % (hndVConn)

# write some data
try:
  n = bsSerial.SerialReqWrite(cli, hndVConn, "hello dude\n")
except bsError.BotSenseError, inst:
  print inst
  sys.exit(8)
print "Example: %d bytes written" % (n)

# close the virtual connection
try:
  bsSerial.SerialReqClose(cli, hndVConn)
except bsError.BotSenseError, inst:
  print inst
  sys.exit(8)

# close the connection to the bsProxy server
try:
  bsServer.ServerDisconnect(cli)
except bsError.BotSenseError, inst:
  print inst
  sys.exit(8)

# delete the client
del cli

\endcode
 */

/*! \} */ /* end bsSerial_py */


/* ---------------------------------------------------------------------------
 * Serial Server
 * --------------------------------------------------------------------------*/

/*!
 * \ingroup bsmod_serial
 * \defgroup bsmod_serial_srv Server Plug-In
 *
 * BotSense \ref man_bsproxy "bsProxy" server plug-in DLL for proxied raw
 * RS-232 serial devices.
 *
 * See \ref bsModules/bsSerial/bsSerialServer.c
 *
 * \{
 */

/*! \} */ /* end bsmod_serial_srv */

/*!
 * \ingroup bsmod_serial_srv
 * \defgroup bsmod_serial_srv_cfg Serial Configuration
 *
 * The serial plug-in XML configuration will be supported in BotSense v3.1.0.
 * \{
 */

/*! \} */ /* end bsmod_serial_srv_cfg */


/* ---------------------------------------------------------------------------
 * Serial XML
 * --------------------------------------------------------------------------*/

/*!
 * \ingroup bsmod_serial
 * \defgroup bsmod_serial_xml XML Message Set

The bsSerialMsgs.xml specification defines the set of messages
for BotSense virtual connections exstablished
between BotSense
clients and raw RS-232 serial devices proxied by
the \ref bsserver "bsProxy" server.

The serial messages are terminated between the BotSense client
libbsclient_serial.so shared library or libbsclient_serial.a static library
and the bsProxy plug-in libbsserver_serial.so interface module DLL.

The message encoding is 8-bit Id-Type-Value (itv). All message fields are 
packed in big-endian order.

\include bsModules/bsSerial/bsSerialMsgs.xml

 */