bsI2C.doxy

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////////////
//
// Package:   BotSense
//
// File:      bsI2C.doxy
//
// Description:
//  This file contains the doxygen directives to document the BotSense Standard
//  I2C Module. This module comes standard with the BotSense package.
//
////////////////////////////////////////////////////////////////////////////////

/*! \file */

/* ---------------------------------------------------------------------------
 * I2C
 * --------------------------------------------------------------------------*/

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

/*! \} */ /* end bsmod_i2c */


/* ---------------------------------------------------------------------------
 * I2C Client
 * --------------------------------------------------------------------------*/

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

/*! \} */ /* end bsmod_i2c_cli */

/*!
 * \ingroup bsmod_i2c_cli
 * \defgroup man_libbsclient_i2c libbsclient_i2c Man Pages
 *
 * The libbsclient_i2c 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_i2c
\defgroup man_bsI2CGetMsgName bsI2CGetMsgName
\par Synopsis:
<tt>
\#include "rnr/rnrconfig.h"\n
\#include "botsense/BotSense.h"\n
\#include "botsense/libBotSense.h"\n
\#include "botsense/bsI2C.h"\n\n
const char * \ref bsI2CGetMsgName(\ref BsClient_P   pClient,
                                  \ref BsVConnHnd_T hndVConn,
                                  uint_t       uMsgId);
</tt>

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

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

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

/*!
\ingroup man_libbsclient_i2c
\defgroup man_bsI2CReqOpen bsI2CReqOpen
\par Synopsis:
<tt>
\#include "rnr/rnrconfig.h"\n
\#include "botsense/BotSense.h"\n
\#include "botsense/libBotSense.h"\n
\#include "botsense/bsI2C.h"\n\n
int \ref bsI2CReqOpen(\ref BsClient_P pClient,
                      const char *sDevName,
                      bool_t bInitTrace);
</tt>

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

/*!
\ingroup man_libbsclient_i2c
\defgroup man_bsI2CReqRead bsI2CReqRead
\par Synopsis:
<tt>
\#include "rnr/rnrconfig.h"\n
\#include "rnr/i2c.h"\n
\#include "botsense/BotSense.h"\n
\#include "botsense/libBotSense.h"\n
\#include "botsense/bsI2C.h"\n\n
int \ref bsI2CReqRead(\ref BsClient_P   pClient,
                 \ref BsVConnHnd_T hndVConn,
                 i2c_addr_t   i2cAddr,
                 size_t       uReadLen,
                 byte_t       rbuf[]);
</tt>

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

/*!
\ingroup man_libbsclient_i2c
\defgroup man_bsI2CReqTrans bsI2CReqTrans
\par Synopsis:
<tt>
\#include "rnr/rnrconfig.h"\n
\#include "rnr/i2c.h"\n
\#include "botsense/BotSense.h"\n
\#include "botsense/libBotSense.h"\n
\#include "botsense/bsI2C.h"\n\n
int \ref bsI2CReqTrans(\ref BsClient_P  pClient,
                 \ref BsVConnHnd_T hndVConn,
                  i2c_addr_t  i2cAddr,
                  byte_t      wbuf[],
                  size_t      uWriteLen,
                  size_t      uReadLen,
                  byte_t      rbuf[]);
</tt>

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

/*!
\ingroup man_libbsclient_i2c
\defgroup man_bsI2CReqWrite bsI2CReqWrite
\par Synopsis:
<tt>
\#include "rnr/rnrconfig.h"\n
\#include "rnr/i2c.h"\n
\#include "botsense/BotSense.h"\n
\#include "botsense/libBotSense.h"\n
\#include "botsense/bsI2C.h"\n\n
int \ref bsI2CReqWrite(\ref BsClient_P    pClient,
                  \ref BsVConnHnd_T  hndVConn,
                  i2c_addr_t    i2cAddr,
                  byte_t        wbuf[],
                  size_t        uWriteLen);
</tt>

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

/*! \} */ /* end bsmod_libbsclient_i2c */


/*!
 * \ingroup bsmod_i2c_cli
 * \defgroup bsI2C_py BotSense.bsI2C Python Module
 *
 * \{
The bsI2C module under the BotSense python package provides python
applications an interface to communicate with proxied i2c devices.
The underlining compiled extension module _bsI2C.so library provides the  
provides the shim between python calling conventions and the C
libbsclient_i2c.[a,so] library.

\sa \ref BotSense.bsI2C

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

import sys

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

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

# connect to the bsProxy server at the given host name and listening port
try:
  bsServer.ServerConnect(cli, serverHostName="robot1", serverPort=9196)
except bsError.BotSenseError, inst:
  print inst
  sys.exit(8)

# open a virtual connection to a proxied I2C device
try:
  hndVConn = bsI2C.I2CReqOpen(cli, "/dev/i2c-1")
except bsError.BotSenseError, inst:
  print inst
  sys.exit(8)
print "Example: established virtual connection %d" % (hndVConn)

# the I2C device attached to the I2C bus
i2cAddr = 0x20

# execute a write-read transaction to the device
try:
  rsp = bsI2C.I2CReqTrans(cli, hndVConn, i2cAddr, '\x01', 6)
except bsError.BotSenseError, inst:
  print inst
  sys.exit(8)
print "Read response %s" % (repr(rsp))

# close the virtual connection
try:
  bsI2C.I2CReqClose(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 bsI2C_py */


/* ---------------------------------------------------------------------------
 * I2C Server
 * --------------------------------------------------------------------------*/

/*!
 * \ingroup bsmod_i2c
 * \defgroup bsmod_i2c_srv Server Plug-In
 *
 * BotSense \ref man_bsproxy "bsProxy" server plug-in DLL for proxied raw
 * \h_i2c devices.
 *
 * See \ref bsModules/bsI2C/bsI2CServer.c
 *
 * \{
 */

/*! \} */ /* end bsmod_i2c_srv */

/*!
 * \ingroup bsmod_i2c_srv
 * \defgroup bsmod_i2c_srv_cfg I2C Configuration
 *
 * The \h_i2c plug-in XML configuration will be supported in BotSense v3.1.0.
 * \{
 */

/*! \} */ /* end bsmod_i2c_srv_cfg */


/* ---------------------------------------------------------------------------
 * I2C XML
 * --------------------------------------------------------------------------*/

/*!
 * \ingroup bsmod_i2c
 * \defgroup bsmod_i2c_xml XML Message Set

The bsI2CMsgs.xml specification defines the set of messages
for BotSense virtual connections exstablished
between BotSense clients and raw \h_i2c devices proxied by
the \ref bsserver "bsProxy" server.

The \h_i2c messages are terminated between the BotSense client
libbsclient_i2c.so shared library or libbsclient_i2c.a static library
and the bsProxy plug-in libbsserver_i2c.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/bsI2C/bsI2CMsgs.xml

 */