Gocator API
 All Classes Files Functions Variables Typedefs Macros Groups Pages
GoSystem.h
Go to the documentation of this file.
1 /**
2  * @file GoSystem.h
3  * @brief Declares the GoSystem class.
4  *
5  * @internal
6  * Copyright (C) 2011-2012 by LMI Technologies Inc.
7  * Licensed under the MIT License.
8  * Redistributed files must retain the above copyright notice.
9  */
10 #ifndef GO_API_SYSTEM_H
11 #define GO_API_SYSTEM_H
12 
13 #include <GoSdk/GoSdkDef.h>
14 #include <GoSdk/GoSensor.h>
15 #include <GoSdk/GoMultiplexBank.h>
16 
17 kBeginHeader()
18 
19 /**
20  * @class GoSystem
21  * @extends kObject
22  * @ingroup GoSdk
23  * @brief Represents a system of Gocator devices.
24  *
25  * During construction, a GoSystem object uses Gocator Discovery Protocol to locate devices.
26  * Subsequently, the list of detected devices can be accessed using GoSystem_SensorCount and
27  * GoSystem_SensorAt.
28  *
29  * Immediately after construction, all sensor objects are in the <em>online</em> state. This state
30  * indicates that a sensor has been detected, but that the client has not yet established a control
31  * connection to the sensor. The only sensor functions than can be used in this state are GoSensor_State,
32  * GoSensor_Address, and GoSensor_SetAddress.
33  *
34  * Because Gocator Discovery Protocol works <em>across</em> subnets, but Gocator Control Protocol
35  * does not, it is possible for a sensor to be successfully detected but for subequent connection
36  * attempts to fail. In this case, the GoSensor_SetAddress function can be used to reconfigure the
37  * sensor to operate on the same subnet as the client.
38  *
39  * If the client and device are configured to operate on the same subnet, the GoSystem_Connect or
40  * GoSensor_Connect functions can be used to establish control connections.
41  *
42  * @see GoSystem_Construct, GoSystem_Connect, GoSensor_State, GoSensor_Address, GoSensor_SetAddress.
43  */
44 typedef kObject GoSystem;
45 
46 /** Defines the signature for a GoSystem data/health handler. */
47 typedef kStatus (kCall* GoDataFx)(kPointer context, GoSensor system, GoDataSet data);
48 
49 /**
50  * Constructs a GoSystem object.
51  *
52  * During construction, a GoSystem object uses Gocator Discovery Protocol to locate sensors.
53  * The list of detected sensors can be accessed using the GoSystem_SensorCount and GoSystem_SensorAt
54  * functions.
55  *
56  * @public @memberof GoSystem
57  * @param system Receives constructed system object.
58  * @param allocator Memory allocator (or kNULL for default)
59  * @return Operation status.
60  */
61 GoFx(kStatus) GoSystem_Construct(GoSystem* system, kAlloc allocator);
62 
63 /**
64  * Establishes control connections to all sensors.
65  *
66  * A control connection is required before calling any sensor function except GoSensor_State,
67  * GoSensor_Address, or GoSensor_SetAddress.
68  *
69  * @public @memberof GoSystem
70  * @param system GoSystem object.
71  * @return Operation status.
72  */
73 GoFx(kStatus) GoSystem_Connect(GoSystem system);
74 
75 /**
76  * Terminates control connections to all sensors.
77  *
78  * @public @memberof GoSystem
79  * @param system GoSystem object.
80  * @return Operation status.
81  */
82 GoFx(kStatus) GoSystem_Disconnect(GoSystem system);
83 
84 /**
85  * Reports whether the system has changes that require a refresh.
86  *
87  * Sensors can undergo autonomous state changes that require client state to be refreshed
88  * (e.g. sensor goes offline). The GoSystem_HasChanges function can be used to determine
89  * if such changes have occurred.
90  *
91  * The GoSystem_HasChanges function does not perform communcation, and consequently, will not
92  * require the caller to block for a long duration. If changes are detected, the GoSystem_Refresh
93  * function can be called to resolve the changes.
94  *
95  * This method is thread-safe.
96  *
97  * @public @memberof GoSystem
98  * @param system GoSystem object.
99  * @return kTRUE if the system has changes.
100  */
101 GoFx(kBool) GoSystem_HasChanges(GoSystem system);
102 
103 /**
104  * Updates client state to reflect any changes that have occurred in the sensor network.
105  *
106  * Sensors can undergo autonomous state changes that require client state to be refreshed
107  * (e.g. sensor goes offline). The GoSystem_Refresh function resynchronizes client state
108  * with the current state of the sensor network.
109  *
110  * Calling this function may destroy or modify local sensor objects. The GoSystem_HasChanges
111  * function can be used prior to calling GoSystem_Refresh, to determine whether a refresh is
112  * needed.
113  *
114  * @public @memberof GoSystem
115  * @param system GoSystem object.
116  * @return Operation status.
117  */
118 GoFx(kStatus) GoSystem_Refresh(GoSystem system);
119 
120 /**
121  * Reports the Gocator Protocol version implemented by this library.
122  *
123  * A Gocator Protocol version number has a major component and a minor component.
124  * If the major version implemented by this library is the same as the major
125  * version implemented by a sensor device, then communcation can proceed. Otherwise,
126  * the sensor should be upgraded or a newer version of this library should be obtained.
127  * Sensors with incompatible major versions will be reported as being in the
128  * <em>incompatible</em> state upon connection.
129  *
130  * If major versions match, but the minor version implemented by this library
131  * is lower than the minor version implemented by the sensor, then some sensor features
132  * will not be accessible through this library.
133  *
134  * If major versions match, but the minor version implemented by this library
135  * is higher than the minor version implemented by the sensor, then some features
136  * exposed by this library may be unimplemented by the sensor.
137  *
138  * This method is thread-safe.
139  *
140  * @public @memberof GoSystem
141  * @return Protocol version implemented by this library.
142  * @see GoSensor_ProtocolVersion, GoSensor_State
143  */
144 GoFx(kVersion) GoSystem_ProtocolVersion();
145 
146 /**
147  * Sets a callback function that can be used to receive sensor data messages asychronously.
148  *
149  * Sensor data messages can be received synchronously using the GoSystem_ReceiveData function
150  * or asynchronously by registering a callback function. If a callback function is registered,
151  * a background thread will be created to perform notifications.
152  *
153  * To unregister a previously-registered data handler, call this function using kNULL in place
154  * of the callback function argument.
155  *
156  * @public @memberof GoSystem
157  * @param system GoSystem object.
158  * @param function Data callback function (or kNULL to unregister).
159  * @param receiver Receiver argument for callback.
160  * @return Operation status.
161  * @see GoDataFx, GoSystem_ReceiveData, GoSystem_SetDataCapacity, GoSystem_EnableData
162  */
163 GoFx(kStatus) GoSystem_SetDataHandler(GoSystem system, GoDataFx function, kPointer receiver);
164 
165 /**
166  * Sets the maximum amount of memory that can be used to buffer received data messages.
167  *
168  * Received data messages are enqueued until they are accepted by the caller. This function
169  * determines the maximum size, in bytes, of enqueued messages. The default maximum size is 50 MB.
170  *
171  * @public @memberof GoSystem
172  * @param system GoSystem object.
173  * @param capacity Data queue capacity, in bytes.
174  * @return Operation status.
175  * @see GoSystem_DataCapacity
176  */
177 GoFx(kStatus) GoSystem_SetDataCapacity(GoSystem system, kSize capacity);
178 
179 /**
180  * Reports that maximum amount of memory that can be used to buffer received data messages.
181  *
182  * @public @memberof GoSystem
183  * @param system GoSystem object.
184  * @return Data queue capacity, in bytes.
185  * @see GoSystem_SetDataCapacity
186  */
187 GoFx(kSize) GoSystem_DataCapacity(GoSystem system);
188 
189 /**
190  * Establishes data connections to all sensors currently in the <em>ready</em> or <em>running</em> states.
191  *
192  * Data connections are not automatically established when sensor control connection are established.
193  * Use this function (or GoSensor_EnableData) to enable/disable data connections.
194  *
195  * @public @memberof GoSystem
196  * @param system GoSystem object.
197  * @param enable kTRUE to enable data connections; kFALSE to disable.
198  * @return Operation status.
199  * @see GoSensor_EnableData
200  */
201 GoFx(kStatus) GoSystem_EnableData(GoSystem system, kBool enable);
202 
203 /**
204  * Clears any buffered data messages.
205  *
206  * When stopping and then restarting a system, it may be desirable to ensure that no messages from
207  * the previous session remain in any buffers. The GoSystem_ClearData function closes any open data
208  * channels, destroys any received messages, and then reopens data channels.
209  *
210  * @public @memberof GoSystem
211  * @param system GoSystem object.
212  * @return Operation status.
213  */
214 GoFx(kStatus) GoSystem_ClearData(GoSystem system);
215 
216 /**
217  * Receives a set of sensor data messages.
218  *
219  * Sensor data messages can be received synchronously using this function or asynchronously by
220  * registering a callback with the GoSystem_SetDataHandler function.
221  *
222  * @public @memberof GoSystem
223  * @param system GoSystem object.
224  * @param data Set of sensor data messages.
225  * @param timeout Duration to wait for messages, in microseconds.
226  * @return Operation status.
227  * @see GoSystem_SetDataHandler, GoSystem_SetDataCapacity, GoSystem_EnableData
228  */
229 GoFx(kStatus) GoSystem_ReceiveData(GoSystem system, GoDataSet* data, k64u timeout);
230 
231 /**
232  * Sets a callback function that can be used to receive sensor health messages asychronously.
233  *
234  * Sensor health messages can be received synchronously using the GoSystem_ReceiveHealth function
235  * or asynchronously by registering a callback function. If a callback function is registered,
236  * a background thread will be created to perform notifications.
237  *
238  * To unregister a previously-registered health handler, call this function using kNULL in place
239  * of the callback function argument.
240  *
241  * @public @memberof GoSystem
242  * @param system GoSystem object.
243  * @param function Health callback function (or kNULL to unregister).
244  * @param receiver Receiver argument, passed to callback.
245  * @return Operation status.
246  * @see GoDataFx, GoSystem_ReceiveHealth, GoSystem_SetDataCapacity, GoSystem_EnableData
247  */
248 GoFx(kStatus) GoSystem_SetHealthHandler(GoSystem system, GoDataFx function, kPointer receiver);
249 
250 /**
251  * Receives a set of sensor health messages.
252  *
253  * Sensor health messages can be received synchronously using this function or asynchronously by
254  * registering a callback with the GoSystem_SetHealthHandler function.
255  *
256  * @public @memberof GoSystem
257  * @param system GoSystem object.
258  * @param data Set of sensor health messages.
259  * @param timeout Duration to wait for messages, in microseconds.
260  * @return Operation status.
261  * @see GoSystem_SetHealthHandler
262  */
263 GoFx(kStatus) GoSystem_ReceiveHealth(GoSystem system, GoDataSet* data, k64u timeout);
264 
265 /**
266  * Clears any buffered health messages.
267  *
268  * @public @memberof GoSystem
269  * @param system GoSystem object.
270  * @return Operation status.
271  */
272 GoFx(kStatus) GoSystem_ClearHealth(GoSystem system);
273 
274 /**
275  * Starts all sensors that are currently in the <em>ready</em> state.
276  *
277  * @public @memberof GoSystem
278  * @param system GoSystem object.
279  * @return Operation status.
280  * @see GoSystem_Stop, GoSensor_Start, GoSensor_Stop
281  */
282 GoFx(kStatus) GoSystem_Start(GoSystem system);
283 
284 /**
285  * Starts alignment for sensor in the <em>ready</em> state.
286  *
287  * @public @memberof GoSystem
288  * @param system GoSystem object.
289  * @return Operation status.
290  * @see GoSystem_Stop, GoSensor_Start, GoSensor_Stop
291  */
292 GoFx(kStatus) GoSystem_StartAlignment(GoSystem system);
293 
294 /**
295  * Starts exposure auto set for sensor(s) in the <em>ready</em> state.
296  *
297  * @public @memberof GoSystem
298  * @param system GoSystem object.
299  * @return Operation status.
300  * @see GoSystem_Stop, GoSensor_Align, GoSensor_Stop
301  */
302 GoFx(kStatus) GoSystem_StartExposureAutoSet(GoSystem system);
303 
304 /**
305  * Stops all connected sensors.
306  *
307  * @public @memberof GoSystem
308  * @param system GoSystem object.
309  * @return Operation status.
310  * @see GoSystem_Start, GoSensor_Start, GoSensor_Stop
311  */
312 GoFx(kStatus) GoSystem_Stop(GoSystem system);
313 
314 
315 /**
316  * Reboots all connected sensors.
317  *
318  * @public @memberof GoSystem
319  * @param system GoSystem object.
320  * @param wait kTRUE to wait for reboot complete; kFALSE to return immediately.
321  * @return Operation status.
322  */
323 GoFx(kStatus) GoSystem_Reset(GoSystem system, kBool wait);
324 
325 /**
326  * Aborts ongoing sensor communication.
327  *
328  * This method asynchronously aborts ongoing communication; the next time that any
329  * I/O operation blocks for an extended period of time, it will be terminated. This method
330  * is thread-safe.
331  *
332  * In order to resume communication, call GoSystem_Refresh or GoSystem_Connect.
333  *
334  * @public @memberof GoSystem
335  * @param system GoSystem object.
336  * @return Operation status.
337  */
338 GoFx(kStatus) GoSystem_Cancel(GoSystem system);
339 
340 /**
341  * Gets the number of sensors in the system.
342  *
343  * @public @memberof GoSystem
344  * @param system GoSystem object.
345  * @return Count of sensors in the system.
346  * @see GoSystem_SensorAt
347  */
348 GoFx(kSize) GoSystem_SensorCount(GoSystem system);
349 
350 /**
351  * Gets the sensor object at the specified index.
352  *
353  * @public @memberof GoSystem
354  * @param system GoSystem object.
355  * @param index Sensor index.
356  * @return Sensor object.
357  * @see GoSystem_SensorCount
358  */
359 GoFx(GoSensor) GoSystem_SensorAt(GoSystem system, kSize index);
360 
361 /**
362  * Gets the sensor object with the specified device id (serial number).
363  *
364  * @public @memberof GoSystem
365  * @param system GoSystem object.
366  * @param id Device identifier.
367  * @param sensor Recieves sensor object.
368  * @return Operation status (kERROR_NOT_FOUND if sensor not found).
369  * @see GoSystem_SensorCount, GoSystem_SensorAt
370  */
371 GoFx(kStatus) GoSystem_FindSensor(GoSystem system, k32u id, GoSensor* sensor);
372 
373 /**
374  * Gets the current time stamp from the sensor network.
375  *
376  * @public @memberof GoSystem
377  * @param system GoSystem object.
378  * @param time Receives current time stamp(microseconds).
379  * @return Operation status (kERROR_NOT_FOUND if no sensors available).
380  * @see GoSystem_GetEncoder
381  */
382 GoFx(kStatus) GoSystem_GetTimeStamp(GoSystem system, k64u* time);
383 
384 /**
385  * Gets the current encoder value from the sensor network.
386  *
387  * @public @memberof GoSystem
388  * @param system GoSystem object.
389  * @param encoder Receives current encoder value (ticks).
390  * @return Operation status (kERROR_NOT_FOUND if no sensors available).
391  * @see GoSystem_GetTime
392  */
393 GoFx(kStatus) GoSystem_GetEncoder(GoSystem system, k64s* encoder);
394 
395 typedef struct GoSensorBankClass
396 {
397  kArrayList sensorList;
398  k32u id;
399 } GoSensorBankClass;
400 
401 GoFx(kSize) GoSystem_MultiplexBankCount(GoSystem system);
402 GoFx(GoMultiplexBank) GoSystem_MultiplexBankAt(GoSystem system, kSize index);
403 GoFx(GoMultiplexBank) GoSystem_AddMultiplexBank(GoSystem system);
404 GoFx(kStatus) GoSystem_RemoveMultiplexBank(GoSystem system, kSize index);
405 
406 GoFx(k64f) GoSystem_MaxBankExposureDuration(GoSystem system, GoMultiplexBank bank);
407 GoFx(kStatus) GoSystem_UpdateMultiplexingParameters(GoSystem system, k64f period);
408 
409 
410 kEndHeader()
411 #include <GoSdk/GoSystem.x.h>
412 
413 #endif
Represents a system of Gocator devices.
Definition: GoSystem.h:17
kStatus GoSystem_ReceiveHealth(GoSystem system, GoDataSet *data, k64u timeout)
Receives a set of sensor health messages.
kStatus GoSystem_FindSensor(GoSystem system, k32u id, GoSensor *sensor)
Gets the sensor object with the specified device id (serial number).
kSize GoSystem_SensorCount(GoSystem system)
Gets the number of sensors in the system.
kStatus GoSystem_ReceiveData(GoSystem system, GoDataSet *data, k64u timeout)
Receives a set of sensor data messages.
kStatus GoSystem_Cancel(GoSystem system)
Aborts ongoing sensor communication.
kStatus GoSystem_Stop(GoSystem system)
Stops all connected sensors.
kStatus GoSystem_SetHealthHandler(GoSystem system, GoDataFx function, kPointer receiver)
Sets a callback function that can be used to receive sensor health messages asychronously.
Declares the GoSensor class.
kStatus GoSystem_StartExposureAutoSet(GoSystem system)
Starts exposure auto set for sensor(s) in the ready state.
Represents a ...
Definition: GoMultiplexBank.h:16
GoSensor GoSystem_SensorAt(GoSystem system, kSize index)
Gets the sensor object at the specified index.
kStatus GoSystem_ClearData(GoSystem system)
Clears any buffered data messages.
kVersion GoSystem_ProtocolVersion()
Reports the Gocator Protocol version implemented by this library.
Essential API declarations.
kStatus GoSystem_Refresh(GoSystem system)
Updates client state to reflect any changes that have occurred in the sensor network.
kStatus GoSystem_GetEncoder(GoSystem system, k64s *encoder)
Gets the current encoder value from the sensor network.
Represents a collection of data or health messages transmitted together.
Definition: GoDataSet.h:14
kSize GoSystem_DataCapacity(GoSystem system)
Reports that maximum amount of memory that can be used to buffer received data messages.
kStatus GoSystem_SetDataCapacity(GoSystem system, kSize capacity)
Sets the maximum amount of memory that can be used to buffer received data messages.
kStatus GoSystem_SetDataHandler(GoSystem system, GoDataFx function, kPointer receiver)
Sets a callback function that can be used to receive sensor data messages asychronously.
kStatus GoSystem_GetTimeStamp(GoSystem system, k64u *time)
Gets the current time stamp from the sensor network.
kStatus(kCall * GoDataFx)(kPointer context, GoSensor system, GoDataSet data)
Defines the signature for a GoSystem data/health handler.
Definition: GoSystem.h:47
kStatus GoSystem_Disconnect(GoSystem system)
Terminates control connections to all sensors.
Declares the GoMultiplexBank class.
kBool GoSystem_HasChanges(GoSystem system)
Reports whether the system has changes that require a refresh.
kStatus GoSystem_EnableData(GoSystem system, kBool enable)
Establishes data connections to all sensors currently in the ready or running states.
kStatus GoSystem_Connect(GoSystem system)
Establishes control connections to all sensors.
kStatus GoSystem_StartAlignment(GoSystem system)
Starts alignment for sensor in the ready state.
kStatus GoSystem_Construct(GoSystem *system, kAlloc allocator)
Constructs a GoSystem object.
kStatus GoSystem_Reset(GoSystem system, kBool wait)
Reboots all connected sensors.
kStatus GoSystem_Start(GoSystem system)
Starts all sensors that are currently in the ready state.
Represents a Gocator sensor.
Definition: GoSensor.h:20
kStatus GoSystem_ClearHealth(GoSystem system)
Clears any buffered health messages.