botsense  3.2.0
RoadNarrows Client-Server Proxied Services Framework
bsSerial.i
1 /******************************************************************************
2  *
3  * Package: BotSense
4  *
5  * File: bsSerial.i
6  *
7  * $LastChangedDate$
8  * $Rev$
9  */
10 
11 /*!
12  * \file
13  *
14  * \brief BotSense serial library python swig interface definitions file.
15  *
16  * \author Robin Knight (robin.knight@roadnarrows.com)
17  *
18  * \par Copyright:
19  * (C) 2010. RoadNarrows LLC.
20  * (http://www.roadnarrows.com)
21  * All Rights Reserved
22  */
23 
24 /*
25  * Permission is hereby granted, without written agreement and without
26  * license or royalty fees, to use, copy, modify, and distribute this
27  * software and its documentation for any purpose, provided that
28  * (1) The above copyright notice and the following two paragraphs
29  * appear in all copies of the source code and (2) redistributions
30  * including binaries reproduces these notices in the supporting
31  * documentation. Substantial modifications to this software may be
32  * copyrighted by their authors and need not follow the licensing terms
33  * described here, provided that the new terms are clearly indicated in
34  * all files where they apply.
35  *
36  * IN NO EVENT SHALL THE AUTHOR, ROADNARROWS LLC, OR ANY MEMBERS/EMPLOYEES
37  * OF ROADNARROW LLC OR DISTRIBUTORS OF THIS SOFTWARE BE LIABLE TO ANY
38  * PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
39  * DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION,
40  * EVEN IF THE AUTHORS OR ANY OF THE ABOVE PARTIES HAVE BEEN ADVISED OF
41  * THE POSSIBILITY OF SUCH DAMAGE.
42  *
43  * THE AUTHOR AND ROADNARROWS LLC SPECIFICALLY DISCLAIM ANY WARRANTIES,
44  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
45  * FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN
46  * "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO
47  * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
48  *
49  ******************************************************************************/
50 
51 %module bsSerial
52 %{
53 #include "botsense/BotSense.h"
54 #include "botsense/bsSerial.h"
55 %}
56 
57 %begin
58 %{
59 /*! \file
60  * \brief Swig generated serial wrapper c file.
61  */
62 %}
63 
64 /*
65  * Required RNR C Types
66  */
67 typedef unsigned char byte_t;
68 typedef unsigned short ushort_t;
69 typedef unsigned int uint_t;
70 typedef unsigned long ulong_t;
71 typedef int bool_t;
72 
73 /*
74  * Required BotSense C Types
75  */
76 typedef struct _bsClientStruct *BsClient_P;
77 typedef int BsVConnHnd_T;
78 
79 /* the swigged interface */
80 %include "botsense/bsSerial.h"
81 
82 /*
83  * Higher-level python interface to the BotSense serial C library.
84  */
85 %pythoncode
86 %{
87 
88 """
89 BotSense Serial Python Inline Extensions and Wrappers.
90 """
91 
92 ## \file
93 ## \package BotSense.bsSerial
94 ##
95 ## \brief BotSense Swigged Serial Python Interface Module.
96 ##
97 ## \author Robin Knight (robin.knight@roadnarrows.com)
98 ##
99 ## \par Copyright:
100 ## (C) 2010. RoadNarrows LLC.\n
101 ## (http://www.roadnarrows.com)\n
102 ## All Rights Reserved
103 ##
104 
105 import BotSenseCore as bsCore
106 import BotSenseError as bsError
107 import BotSenseTypes as bsTypes
108 
109 def SerialGetMsgName(client, hndVConn, msgId):
110  """ Get the serial message name.
111 
112  For each (virtual connection, message id) 2-tuple, there can be a known
113  name string (provided the id is valid and an application provides the
114  information).
115 
116  Parameters:
117  client - BotSenseTypes.BsClient instance.
118  hndVConn - Virtual connection handle (ignored).
119  msgId - Serial message id.
120 
121  Return:
122  Returns message name string if it can be determined.
123  Otherwise returns 'unknown'.
124  """
125  bsTypes.BsClient.ChkClient(client)
126  return bsSerialGetMsgName(client.pClient, hndVConn, msgId)
127 
128 def SerialReqOpen(client, devName, baudRate=9600, byteSize=8, parity='N',
129  stopBits=1, rtscts=False, xonxoff=False, trace=False):
130  """ Proxy server request to establish a virtual connection to an RS-232
131  serial device.
132 
133  Raises a BotSenseError exception on failure.
134 
135  Parameters:
136  client - BotSenseTypes.BsClient instance.
137  devName - Proxied serial device name (e.g. /dev/ttyS0).
138  baudRate - Baud rate.
139  byteSize - Bytes size in bits 5...8.
140  parity - Parity. One of: 'N', 'E', 'O'
141  stopBits - Number of stop bits 1, 2
142  rtscts - Do [not] use hardware flow control.
143  xonxoff - Do [not] use software flow control.
144  trace - Initial message tracing enable(true)/disable(false) state.
145 
146  Return
147  New virtual connection handle.
148  """
149  bsTypes.BsClient.ChkClient(client)
150  hndVConn = bsSerialReqOpen(client.pClient, devName, baudRate, byteSize,
151  ord(parity), stopBits, rtscts, xonxoff, trace)
152  bsError.ChkReturnIsNonNeg(hndVConn,
153  "Client %s: Serial Open request failed." % (client.AttrGetName()))
154  return hndVConn
155 
156 def SerialReqClose(client, hndVConn):
157  """ Proxy server request to close client's proxied serial device virtual
158  connection.
159 
160  Raises a BotSenseError exception on failure.
161 
162  Parameters:
163  client - BotSenseTypes.BsClient instance.
164  hndVConn - Virtual connection handle.
165  """
166  bsTypes.BsClient.ChkClient(client)
167  rc = bsSerialReqClose(client.pClient, hndVConn)
168  bsError.ChkReturnIsOk(rc,
169  "Client %s: Serial Close request failed." % (client.AttrGetName()))
170 
171 def SerialReqRead(client, hndVConn, readLen):
172  """ Serial request to read from a proxied RS-232 serial device.
173 
174  Raises a BotSenseError exception on failure.
175 
176  Parameters:
177  client - BotSenseTypes.BsClient instance.
178  hndVConn - Virtual connection handle.
179  readLen - Number of bytes to read.
180 
181  Return:
182  Buffer list of read bytes.
183  """
184  bsTypes.BsClient.ChkClient(client)
185  rbytebuf = bsTypes.ByteBuf(readLen)
186  n = bsSerialReqRead(client.pClient, hndVConn, readLen, rbytebuf.getSwigObj())
187  bsError.ChkReturnIsNonNeg(n,
188  "Client %s: Serial Read request failed." % (client.AttrGetName()))
189  rbytebuf.copyFromSwigObj(n)
190  return rbytebuf.buf
191 
192 def SerialReqWrite(client, hndVConn, wbuf):
193  """ Serial request to write to a proxied RS-232 serial device.
194 
195  Raises a BotSenseError exception on failure.
196 
197  Parameters:
198  client - BotSenseTypes.BsClient instance.
199  hndVConn - Virtual connection handle.
200  wbuf - Write buffer.
201 
202  Return:
203  Number of bytes written.
204  """
205  bsTypes.BsClient.ChkClient(client)
206  wbytebuf = bsTypes.ByteBuf.Clone(wbuf)
207  wbytebuf.copyToSwigObj(len(wbytebuf))
208  n = bsSerialReqWrite(client.pClient, hndVConn, wbytebuf.getSwigObj(),
209  len(wbytebuf))
210  bsError.ChkReturnIsNonNeg(n,
211  "Client %s: Serial Write request failed." % (client.AttrGetName()))
212  return n
213 
214 def SerialReqTrans(client, hndVConn, wbuf, readLen):
215  """ Serial request to execute a write-read transaction to a proxied
216  RS-232 serial device.
217 
218  Raises a BotSenseError exception on failure.
219 
220  Parameters:
221  client - BotSenseTypes.BsClient instance.
222  hndVConn - Virtual connection handle.
223  wbuf - Write buffer.
224  readLen - Number of bytes to read.
225 
226  Return:
227  Buffer list of read bytes.
228  """
229  bsTypes.BsClient.ChkClient(client)
230  wbytebuf = bsTypes.ByteBuf.Clone(wbuf)
231  wbytebuf.copyToSwigObj(len(wbytebuf))
232  rbytebuf = bsTypes.ByteBuf(readLen)
233  n = bsSerialReqTrans(client.pClient, hndVConn,
234  wbytebuf.getSwigObj(), len(wbytebuf),
235  readLen, rbytebuf.getSwigObj())
236  bsError.ChkReturnIsNonNeg(n,
237  "Client %s: Serial Transaction request failed." % (client.AttrGetName()))
238  rbytebuf.copyFromSwigObj(n)
239  return rbytebuf.buf
240 
241 %}