botsense  3.2.0
RoadNarrows Client-Server Proxied Services Framework
bsI2C.i
1 /******************************************************************************
2  *
3  * Package: BotSense
4  *
5  * File: bsI2C.i
6  *
7  * $LastChangedDate$
8  * $Rev$
9  */
10 
11 /*!
12  * \file
13  *
14  * \brief BotSense \h_i2c 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 bsI2C
52 %{
53 #include "botsense/BotSense.h"
54 #include "botsense/bsI2C.h"
55 %}
56 
57 %begin
58 %{
59 /*! \file
60  * \brief Swig generated I2C 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 typedef ushort_t i2c_addr_t;
73 
74 /*
75  * Required BotSense C Types
76  */
77 typedef struct _bsClientStruct *BsClient_P;
78 typedef int BsVConnHnd_T;
79 
80 %include "carrays.i"
81 
82 /* the swigged interface */
83 %include "botsense/bsI2C.h"
84 
85 %array_functions(i2c_addr_t, i2cAddrArray);
86 
87 /*
88  * Higher-level python interface to the BotSense I2C C library.
89  */
90 %pythoncode
91 %{
92 
93 #
94 # BotSense I2C Python Wrappers
95 #
96 
97 """
98 BotSense I2C Python Inline Extensions and Wrappers.
99 """
100 
101 ## \file
102 ## \package BotSense.bsI2C
103 ##
104 ## \brief BotSense Swigged I2C Python Interface Module.
105 ##
106 ## \author Robin Knight (robin.knight@roadnarrows.com)
107 ##
108 ## \par Copyright:
109 ## (C) 2010. RoadNarrows LLC.\n
110 ## (http://www.roadnarrows.com)\n
111 ## All Rights Reserved
112 ##
113 
114 import BotSenseCore as bsCore
115 import BotSenseError as bsError
116 import BotSenseTypes as bsTypes
117 
118 # maximum number of scanned I2C attached device addresses
119 I2CMaxNumOfScannedAddrs = 256
120 
121 def I2CGetMsgName(client, hndVConn, msgId):
122  """ Get the I2C message name.
123 
124  For each (virtual connection, message id) 2-tuple, there can be a known
125  name string (provided the id is valid and an application provides the
126  information).
127 
128  Parameters:
129  client - BotSenseTypes.BsClient instance.
130  hndVConn - Virtual connection handle (ignored).
131  msgId - I2C message id.
132 
133  Return:
134  Returns message name string if it can be determined.
135  Otherwise returns 'unknown'.
136  """
137  bsTypes.BsClient.ChkClient(client)
138  return bsI2CGetMsgName(client.pClient, hndVConn, msgId)
139 
140 def I2CReqOpen(client, devName, trace=False):
141  """ Proxy server request to establish a virtual connection to an
142  I2C bus device.
143 
144  Raises a BotSenseError exception on failure.
145 
146  Parameters:
147  client - BotSenseTypes.BsClient instance.
148  devName - Proxied I2C device name (e.g. /dev/i2c-0).
149  trace - Initial message tracing enable(true)/disable(false) state.
150 
151  Return
152  New virtual connection handle.
153  """
154  bsTypes.BsClient.ChkClient(client)
155  hndVConn = bsI2CReqOpen(client.pClient, devName, trace)
156  bsError.ChkReturnIsNonNeg(hndVConn,
157  "Client %s: I2C Open request failed." % (client.AttrGetName()))
158  return hndVConn
159 
160 def I2CReqClose(client, hndVConn):
161  """ Proxy server request to close client's proxied I2C bus device virtual
162  connection.
163 
164  Raises a BotSenseError exception on failure.
165 
166  Parameters:
167  client - BotSenseTypes.BsClient instance.
168  hndVConn - Virtual connection handle.
169  """
170  bsTypes.BsClient.ChkClient(client)
171  rc = bsI2CReqClose(client.pClient, hndVConn)
172  bsError.ChkReturnIsOk(rc,
173  "Client %s: I2C Close request failed." % (client.AttrGetName()))
174 
175 def I2CReqRead(client, hndVConn, i2cAddr, readLen):
176  """ I2C request to read from a device attached to a proxied I2C bus.
177 
178  Raises a BotSenseError exception on failure.
179 
180  Parameters:
181  client - BotSenseTypes.BsClient instance.
182  hndVConn - Virtual connection handle.
183  i2cAddr - Address of attached device on the I2C bus.
184  readLen - Number of bytes to read.
185 
186  Return:
187  Buffer list of read bytes.
188  """
189  bsTypes.BsClient.ChkClient(client)
190  rbytebuf = bsTypes.ByteBuf(readLen)
191  n = bsI2CReqRead(client.pClient, hndVConn, i2cAddr, readLen,
192  rbytebuf.getSwigObj())
193  bsError.ChkReturnIsNonNeg(n,
194  "Client %s: I2C Read request failed." % (client.AttrGetName()))
195  rbytebuf.copyFromSwigObj(n)
196  return rbytebuf.buf
197 
198 def I2CReqWrite(client, hndVConn, i2cAddr, wbuf):
199  """ I2C request to write to a device attached to a proxied I2C bus.
200 
201  Raises a BotSenseError exception on failure.
202 
203  Parameters:
204  client - BotSenseTypes.BsClient instance.
205  hndVConn - Virtual connection handle.
206  i2cAddr - Address of attached device on the I2C bus.
207  wbuf - Write buffer.
208 
209  Return:
210  Number of bytes written.
211  """
212  bsTypes.BsClient.ChkClient(client)
213  wbytebuf = bsTypes.ByteBuf.Clone(wbuf)
214  wbytebuf.copyToSwigObj(len(wbytebuf))
215  n = bsI2CReqWrite(client.pClient, hndVConn, i2cAddr, wbytebuf.getSwigObj(),
216  len(wbytebuf))
217  bsError.ChkReturnIsNonNeg(n,
218  "Client %s: I2C Write request failed." % (client.AttrGetName()))
219  return n
220 
221 def I2CReqTrans(client, hndVConn, i2cAddr, wbuf, readLen):
222  """ I2C request to execute a write-read transaction to a device
223  attached to a proxied I2C bus.
224 
225  Raises a BotSenseError exception on failure.
226 
227  Parameters:
228  client - BotSenseTypes.BsClient instance.
229  hndVConn - Virtual connection handle.
230  i2cAddr - Address of attached device on the I2C bus.
231  wbuf - Write buffer.
232  readLen - Number of bytes to read.
233 
234  Return:
235  Buffer list of read bytes.
236  """
237  bsTypes.BsClient.ChkClient(client)
238  wbytebuf = bsTypes.ByteBuf.Clone(wbuf)
239  wbytebuf.copyToSwigObj(len(wbytebuf))
240  rbytebuf = bsTypes.ByteBuf(readLen)
241  n = bsI2CReqTrans(client.pClient, hndVConn, i2cAddr,
242  wbytebuf.getSwigObj(), len(wbytebuf),
243  readLen, rbytebuf.getSwigObj())
244  bsError.ChkReturnIsNonNeg(n,
245  "Client %s: I2C Transaction request failed." % (client.AttrGetName()))
246  rbytebuf.copyFromSwigObj(n)
247  return rbytebuf.buf
248 
249 def I2CReqScan(client, hndVConn):
250  """ I2C request to scan a proxied I2C bus for attached devices.
251 
252  Raises a BotSenseError exception on failure.
253 
254  Parameters:
255  client - BotSenseTypes.BsClient instance.
256  hndVConn - Virtual connection handle.
257 
258  Return:
259  List of I2C address of discovered attached devices.
260  """
261  bsTypes.BsClient.ChkClient(client)
262  swigObj = new_i2cAddrArray(I2CMaxNumOfScannedAddrs)
263  n = bsI2CReqScan(client.pClient, hndVConn, swigObj, I2CMaxNumOfScannedAddrs)
264  bsError.ChkReturnIsNonNeg(n,
265  "Client %s: I2C Read request failed." % (client.AttrGetName()))
266  addrs = []
267  for i in xrange(n):
268  addrs += [ i2cAddrArray_getitem(swigObj, i) ]
269  return addrs
270 
271 %}