Gocator API

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) 2016-2020 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef GO_SDK_SYSTEM_H
11 #define GO_SDK_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 * (if the autodiscovery capability is selected).
27 * Subsequently, the list of detected devices can be accessed using GoSystem_SensorCount and
28 * GoSystem_SensorAt.
29 *
30 * Immediately after construction, all sensor objects are in the <em>online</em> state. This state
31 * indicates that a sensor has been detected, but that the client has not yet established a control
32 * connection to the sensor. The only sensor functions than can be used in this state are GoSensor_State,
33 * GoSensor_Address, and GoSensor_SetAddress.
34 *
35 * Because Gocator Discovery Protocol works <em>across</em> subnets, but Gocator Control Protocol
36 * does not, it is possible for a sensor to be successfully detected but for subsequent connection
37 * attempts to fail. In this case, the GoSensor_SetAddress function can be used to reconfigure the
38 * sensor to operate on the same subnet as the client.
39 *
40 * If the client and device are configured to operate on the same subnet, the GoSystem_Connect or
41 * GoSensor_Connect functions can be used to establish control connections.
42 *
43 * Note that GoSystem and other system API objects such as GoSensor and GoSetup are *not thread safe*. They
44 * should not be accessed concurrently by multiple threads, without the proper use of synchronization
45 * techninques such as mutexes and event loops. A typical example of this is when one thread polls
46 * GoSensor_State(), while another calls functions such as GoSensor_Connect() or GoSystem_Refresh(). Without
47 * proper locking, this code will result in undefined behavior such as invalid values being returned, or
48 * even program crash.
49 *
50 * Message objects such as GoUniformProfileMsg do not access shared system resources and can be accessed
51 * concurrently with system API objects.
52 *
53 * @see GoSystem_Construct, GoSystem_Connect, GoSensor_State, GoSensor_Address, GoSensor_SetAddress.
54 */
55 typedef kObject GoSystem;
56
57 /** Defines the signature for a GoSystem data/health handler.
58 *
59 * NOTE: The GoDataSet received by this function must be destroyed after use,
60 * otherwise a memory leak will result.
61 *
62 * @see GoDestroy
63 */
64 typedef kStatus (kCall* GoDataFx)(kPointer context, GoSensor system, GoDataSet data);
65
66 /**
67 * Constructs a GoSystem object.
68 *
69 * During construction, a GoSystem object uses Gocator Discovery Protocol to locate sensors.
70 * The list of detected sensors can be accessed using the GoSystem_SensorCount and GoSystem_SensorAt
71 * functions.
72 *
73 * @public @memberof GoSystem
74 * @version Introduced in firmware 4.0.10.27
75 * @param system Receives constructed system object.
76 * @param allocator Memory allocator (or kNULL for default)
77 * @return Operation status.
78 */
79 GoFx(kStatus) GoSystem_Construct(GoSystem* system, kAlloc allocator);
80
81 /**
82 * Constructs a GoSystem object.
83 *
84 * During construction, a GoSystem object does not automatically locate sensors
85 * using the Gocator Discovery Protocol. Sensor discovery must be explicitly
86 * enabled by the following steps:
87 * 1. Specify which interface(s) on which the protocol is allowed run by calling
88 * GoSystem_EnableDiscoveryInterface() API.
89 * By default, the discovery protocol cannot use any interface.
90 * To allow the protocol to run on all interfaces, call the API
91 * GoSystem_EnableDiscoveryInterfaceAll().
92 * 2. Start the discovery protocol with the API GoSystem_StartDiscovery().
93 *
94 * @public @memberof GoSystem
95 * @version Introduced in firmware 4.6.7.157
96 * @param system Receives constructed system object.
97 * @param allocator Memory allocator (or kNULL for default)
98 * @return Operation status.
99 */
100 GoFx(kStatus) GoSystem_ConstructEx(GoSystem* system, kAlloc allocator);
101
102 /**
103 * Establishes control connections to all sensors.
104 *
105 * A control connection is required before calling any sensor function except GoSensor_State,
106 * GoSensor_Address, or GoSensor_SetAddress.
107 *
108 * @public @memberof GoSystem
109 * @version Introduced in firmware 4.0.10.27
110 * @param system GoSystem object.
111 * @return Operation status.
112 */
113 GoFx(kStatus) GoSystem_Connect(GoSystem system);
114
115 /**
116 * Terminates control connections to all sensors.
117 *
118 * @public @memberof GoSystem
119 * @version Introduced in firmware 4.0.10.27
120 * @param system GoSystem object.
121 * @return Operation status.
122 */
123 GoFx(kStatus) GoSystem_Disconnect(GoSystem system);
124
125 /**
126 * Adds a sensor by passing a custom address and port info, this doesnt require discovery
127 *
128 * @public @memberof GoSystem
129 * @version Introduced in firmware 4.8.2.76
130 * @param system GoSystem object.
131 * @param addressInfo GoAddressInfo object containing IP to connnect on.
132 * @param portInfo GoPortInfo object containing custom port values.
133 * @param sensor point to a GoSensor object to return newly created sensor.
134 * @return A status.
135 */
136 GoFx(kStatus) GoSystem_AddSensor(GoSystem system, const GoAddressInfo* addressInfo, const GoPortInfo* portInfo, GoSensor* sensor);
137
138 /**
139 * Reports whether the system has changes that require a refresh.
140 *
141 * Sensors can undergo autonomous state changes that require client state to be refreshed
142 * (e.g. sensor goes offline). The GoSystem_HasChanges function can be used to determine
143 * if such changes have occurred.
144 *
145 * The GoSystem_HasChanges function does not perform communication, and consequently, will not
146 * require the caller to block for a long duration. If changes are detected, the GoSystem_Refresh
147 * function can be called to resolve the changes.
148 *
149 * This method is thread-safe.
150 *
151 * @public @memberof GoSystem
152 * @version Introduced in firmware 4.0.10.27
153 * @param system GoSystem object.
154 * @return kTRUE if the system has changes.
155 */
156 GoFx(kBool) GoSystem_HasChanges(GoSystem system);
157
158 /**
159 * Updates client state to reflect any changes that have occurred in the sensor network.
160 *
161 * Sensors can undergo autonomous state changes that require client state to be refreshed
162 * (e.g. sensor goes offline). The GoSystem_Refresh function resynchronizes client state
163 * with the current state of the sensor network.
164 *
165 * Calling this function may destroy or modify local sensor objects. The GoSystem_HasChanges
166 * function can be used prior to calling GoSystem_Refresh, to determine whether a refresh is
167 * needed.
168 *
169 * This call is thread-safe with regards to modifying this class's set of sensors.
170 *
171 * @public @memberof GoSystem
172 * @version Introduced in firmware 4.0.10.27
173 * @param system GoSystem object.
174 * @return Operation status.
175 */
176 GoFx(kStatus) GoSystem_Refresh(GoSystem system);
177
178 /**
179 * Reports the Gocator Protocol version implemented by this library.
180 *
181 * A Gocator Protocol version number has a major component and a minor component.
182 * If the major version implemented by this library is the same as the major
183 * version implemented by a sensor device, then communication can proceed. Otherwise,
184 * the sensor should be upgraded or a newer version of this library should be obtained.
185 * Sensors with incompatible major versions will be reported as being in the
186 * <em>incompatible</em> state upon connection.
187 *
188 * If major versions match, but the minor version implemented by this library
189 * is lower than the minor version implemented by the sensor, then some sensor features
190 * will not be accessible through this library.
191 *
192 * If major versions match, but the minor version implemented by this library
193 * is higher than the minor version implemented by the sensor, then some features
194 * exposed by this library may be unimplemented by the sensor.
195 *
196 * This method is thread-safe.
197 *
198 * @public @memberof GoSystem
199 * @version Introduced in firmware 4.0.10.27
200 * @return Protocol version implemented by this library.
201 * @see GoSensor_ProtocolVersion, GoSensor_State
202 */
203 GoFx(kVersion) GoSystem_ProtocolVersion();
204
205 /**
206 * Reports the Gocator firmware version that was built alongside this library.
207 *
208 * A Gocator SDK version number has a major component and a minor component.
209 * If the major version implemented by this library is the same as the major
210 * version implemented by a sensor device, then communication can proceed. Otherwise,
211 * the sensor should be upgraded or a version of this library matching the sensor
212 * should be obtained.
213 *
214 * When it comes to the matter of mismatched SDK and firmware versions, so long
215 * as the protocol versions match up, they should be compatible.
216 *
217 * @public @memberof GoSystem
218 * @version Introduced in firmware 4.0.10.27
219 * @return Firmware version that was built alongside this library.
220 * @see GoSensor_FirmwareVersion, GoSystem_ProtocolVersion
221 */
222 GoFx(kVersion) GoSystem_SdkVersion();
223
224 /**
225 * Sets a callback function that can be used to receive sensor data messages asynchronously.
226 *
227 * Sensor data messages can be received synchronously using the GoSystem_ReceiveData function
228 * or asynchronously by registering a callback function. If a callback function is registered,
229 * a background thread will be created to perform notifications.
230 *
231 * To unregister a previously-registered data handler, call this function using kNULL in place
232 * of the callback function argument.
233 *
234 * @public @memberof GoSystem
235 * @version Introduced in firmware 4.0.10.27
236 * @param system GoSystem object.
237 * @param function Data callback function (or kNULL to unregister).
238 * @param receiver Receiver argument for callback.
239 * @return Operation status.
240 * @see GoDataFx, GoSystem_ReceiveData, GoSystem_SetDataCapacity, GoSystem_EnableData
241 */
242 GoFx(kStatus) GoSystem_SetDataHandler(GoSystem system, GoDataFx function, kPointer receiver);
243
244 /**
245 * Sets the maximum amount of memory that can be used to buffer received data messages.
246 *
247 * Received data messages are enqueued until they are accepted by the caller. This function
248 * determines the maximum size, in bytes, of enqueued messages. The default maximum size is 50 MB.
249 *
250 * @public @memberof GoSystem
251 * @version Introduced in firmware 4.0.10.27
252 * @param system GoSystem object.
253 * @param capacity Data queue capacity, in bytes.
254 * @return Operation status.
255 * @see GoSystem_DataCapacity
256 */
257 GoFx(kStatus) GoSystem_SetDataCapacity(GoSystem system, kSize capacity);
258
259 /**
260 * Reports that maximum amount of memory that can be used to buffer received data messages.
261 *
262 * @public @memberof GoSystem
263 * @version Introduced in firmware 4.0.10.27
264 * @param system GoSystem object.
265 * @return Data queue capacity, in bytes.
266 * @see GoSystem_SetDataCapacity
267 */
268 GoFx(kSize) GoSystem_DataCapacity(GoSystem system);
269
270 /**
271 * Establishes data connections to all connected sensors currently in the <em>ready</em> or <em>running</em> states.
272 *
273 * Data connections are not automatically established when sensor control connection are established.
274 * Use this function (or GoSensor_EnableData) to enable/disable data connections.
275 *
276 * @public @memberof GoSystem
277 * @version Introduced in firmware 4.0.10.27
278 * @param system GoSystem object.
279 * @param enable kTRUE to enable data connections; kFALSE to disable.
280 * @return Operation status.
281 * @see GoSystem_ReceiveData, GoSensor_EnableData
282 */
283 GoFx(kStatus) GoSystem_EnableData(GoSystem system, kBool enable);
284
285 /**
286 * Clears any buffered data messages.
287 *
288 * When stopping and then restarting a system, it may be desirable to ensure that no messages from
289 * the previous session remain in any buffers. The GoSystem_ClearData function closes any open data
290 * channels, destroys any received messages, and then reopens data channels.
291 *
292 * @public @memberof GoSystem
293 * @version Introduced in firmware 4.0.10.27
294 * @param system GoSystem object.
295 * @return Operation status.
296 */
297 GoFx(kStatus) GoSystem_ClearData(GoSystem system);
298
299 /**
300 * Receives a set of sensor data messages.
301 *
302 * Sensor data messages can be received synchronously using this function or asynchronously by
303 * registering a callback with the GoSystem_SetDataHandler function.
304 *
305 * NOTE: Data received with this function must be destroyed after use,
306 * otherwise a memory leak will result.
307 *
308 * @public @memberof GoSystem
309 * @version Introduced in firmware 4.0.10.27
310 * @param system GoSystem object.
311 * @param data Set of sensor data messages.
312 * @param timeout Duration to wait for messages, in microseconds.
313 * @return Operation status.
314 * @see GoDestroy, GoSystem_SetDataHandler, GoSystem_SetDataCapacity, GoSystem_EnableData
315 */
316 GoFx(kStatus) GoSystem_ReceiveData(GoSystem system, GoDataSet* data, k64u timeout);
317
318 /**
319 * Sets a callback function that can be used to receive sensor health messages asynchronously.
320 *
321 * Sensor health messages can be received synchronously using the GoSystem_ReceiveHealth function
322 * or asynchronously by registering a callback function. If a callback function is registered,
323 * a background thread will be created to perform notifications.
324 *
325 * To unregister a previously-registered health handler, call this function using kNULL in place
326 * of the callback function argument.
327 *
328 * @public @memberof GoSystem
329 * @version Introduced in firmware 4.0.10.27
330 * @param system GoSystem object.
331 * @param function Health callback function (or kNULL to unregister).
332 * @param receiver Receiver argument, passed to callback.
333 * @return Operation status.
334 * @see GoDataFx, GoSystem_ReceiveHealth, GoSystem_SetDataCapacity, GoSystem_EnableData
335 */
336 GoFx(kStatus) GoSystem_SetHealthHandler(GoSystem system, GoDataFx function, kPointer receiver);
337
338 /**
339 * Receives a set of sensor health messages.
340 *
341 * Sensor health messages can be received synchronously using this function or asynchronously by
342 * registering a callback with the GoSystem_SetHealthHandler function.
343 *
344 * @public @memberof GoSystem
345 * @version Introduced in firmware 4.0.10.27
346 * @param system GoSystem object.
347 * @param data Set of sensor health messages.
348 * @param timeout Duration to wait for messages, in microseconds.
349 * @return Operation status.
350 * @see GoSystem_SetHealthHandler
351 */
352 GoFx(kStatus) GoSystem_ReceiveHealth(GoSystem system, GoDataSet* data, k64u timeout);
353
354 /**
355 * Clears any buffered health messages.
356 *
357 * @public @memberof GoSystem
358 * @version Introduced in firmware 4.0.10.27
359 * @param system GoSystem object.
360 * @return Operation status.
361 */
362 GoFx(kStatus) GoSystem_ClearHealth(GoSystem system);
363
364 /**
365 * Starts all sensors that are currently in the <em>ready</em> state.
366 *
367 * @public @memberof GoSystem
368 * @version Introduced in firmware 4.0.10.27
369 * @param system GoSystem object.
370 * @return Operation status.
371 * @see GoSystem_Stop, GoSensor_Start, GoSensor_Stop
372 */
373 GoFx(kStatus) GoSystem_Start(GoSystem system);
374
375 /**
376 * Starts all sensors that are currently in the <em>ready</em> state at a scheduled value.
377 *
378 * NOTE: The value specified is the target value to start at, not a relative
379 * offset from the current value. The typical usage is to obtain the current
380 * value first, add an offset to it, and start at that value.
381 *
382 * @public @memberof GoSystem
383 * @version Introduced in firmware 4.1.3.106
384 * @param system GoSystem object.
385 * @param value The value at which to start the sensor. It is in uS when time triggered and ticks when encoder triggered.
386 * @return Operation status.
387 * @see GoSystem_Stop, GoSensor_ScheduledStart, GoSensor_Stop, GoSetup_SetTriggerSource, GoSetup_TriggerSource
388 */
389 GoFx(kStatus) GoSystem_ScheduledStart(GoSystem system, k64s value);
390
391 /**
392 * Performs alignment for sensors in the <em>ready</em> state.
393 *
394 * WARNING! This operation writes to flash storage.
395 * Review the user manual for implications.
396 *
397 * NOTE: This operation will result in sensor starts for the duration of the
398 * alignment. It can be canceled via GoSystem_Stop. This function's operation
399 * status does not correspond to the actual alignment result. In order to
400 * retrieve the alignment result, you must enable the data channel before calling
401 * this function, receive an alignment data message and then check its status.
402 *
403 * @public @memberof GoSystem
404 * @version Introduced in firmware 4.0.10.27
405 * @param system GoSystem object.
406 * @return Operation status.
407 * @see GoSystem_EnableData, GoSystem_ReceiveData, GoSystem_Stop
408 * @remark Calling this function will result in writing operations to flash storage. Should the process be disrupted due to power loss or other factors, the sensor may enter Rescue mode.
409 */
410 GoFx(kStatus) GoSystem_StartAlignment(GoSystem system);
411
412 /**
413 * Performs exposure auto set for sensors in the <em>ready</em> state.
414 *
415 * NOTE: This operation will result in sensor starts for the duration of the
416 * exposure AutoSet. A successful operation status does NOT modify the configuration.
417 * You must retrieve the resulting exposure values and set it for the appropriate
418 * exposure setting. This involves enabling the data connection prior to running
419 * exposure auto set and then receiving an exposure auto set message, which
420 * you can then use to query the status and access the resulting value.
421 *
422 * @public @memberof GoSystem
423 * @version Introduced in firmware 4.0.10.27
424 * @param system GoSystem object.
425 * @return Operation status.
426 * @see GoSystem_EnableData, GoSystem_ReceiveData
427 */
428 GoFx(kStatus) GoSystem_StartExposureAutoSet(GoSystem system);
429
430 /**
431 * Stops all connected sensors.
432 *
433 * @public @memberof GoSystem
434 * @version Introduced in firmware 4.0.10.27
435 * @param system GoSystem object.
436 * @return Operation status.
437 * @see GoSystem_Start, GoSensor_Start, GoSensor_Stop
438 */
439 GoFx(kStatus) GoSystem_Stop(GoSystem system);
440
441
442 /**
443 * Reboots all connected sensors.
444 *
445 * @public @memberof GoSystem
446 * @version Introduced in firmware 4.0.10.27
447 * @param system GoSystem object.
448 * @param wait kTRUE to wait for reboot complete; kFALSE to return immediately.
449 * @return Operation status.
450 */
451 GoFx(kStatus) GoSystem_Reset(GoSystem system, kBool wait);
452
453 /**
454 * Aborts ongoing sensor communication.
455 *
456 * This method asynchronously aborts ongoing communication; the next time that any
457 * I/O operation blocks for an extended period of time, it will be terminated. This method
458 * is thread-safe.
459 *
460 * In order to resume communication, call GoSystem_Refresh or GoSystem_Connect.
461 *
462 * @public @memberof GoSystem
463 * @version Introduced in firmware 4.0.10.27
464 * @param system GoSystem object.
465 * @return Operation status.
466 */
467 GoFx(kStatus) GoSystem_Cancel(GoSystem system);
468
469 /**
470 * Gets the Discovery channel information for the given device ID (if the device is present and the command is supported)
471 *
472 * @public @memberof GoSensor
473 * @version Introduced in firmware 4.3.3.124
474 * @param system GoSystem object.
475 * @param deviceId The ID of the device with which to retrieve Discovery channel information.
476 * @param info A handled to the sensor's constructed discovery information.
477 * @param allocator Memory allocator (or kNULL for the default).
478 * @see GoDestroy
479 */
480 GoFx(kStatus) GoSystem_GetExtendedDiscoveryInfo(GoSystem system, k32u deviceId, GoDiscoveryExtInfo* info, kAlloc allocator);
481
482 /**
483 * Gets the number of sensors in the system.
484 *
485 * @public @memberof GoSystem
486 * @version Introduced in firmware 4.0.10.27
487 * @param system GoSystem object.
488 * @return Count of sensors in the system.
489 * @see GoSystem_SensorAt
490 */
491 GoFx(kSize) GoSystem_SensorCount(GoSystem system);
492
493 /**
494 * Gets the sensor object at the specified index.
495 *
496 * @public @memberof GoSystem
497 * @version Introduced in firmware 4.0.10.27
498 * @param system GoSystem object.
499 * @param index Sensor index.
500 * @return Sensor object.
501 * @see GoSystem_SensorCount
502 */
503 GoFx(GoSensor) GoSystem_SensorAt(GoSystem system, kSize index);
504
505 /**
506 * Gets the sensor object with the specified device id (serial number).
507 *
508 * @public @memberof GoSystem
509 * @version Introduced in firmware 4.0.10.27
510 * @param system GoSystem object.
511 * @param id Device identifier.
512 * @param sensor Receives sensor object.
513 * @return Operation status (kERROR_NOT_FOUND if sensor not found).
514 * @see GoSystem_SensorCount, GoSystem_SensorAt
515 */
516 GoFx(kStatus) GoSystem_FindSensorById(GoSystem system, k32u id, GoSensor* sensor);
517
518 /**
519 * Gets the sensor object with the specified IP address.
520 *
521 * @public @memberof GoSystem
522 * @version Introduced in firmware 4.0.10.27
523 * @param system GoSystem object.
524 * @param address Pointer to sensor IP address.
525 * @param sensor Receives sensor object.
526 * @return Operation status (kERROR_NOT_FOUND if sensor not found).
527 * @see GoSystem_SensorCount, GoSystem_SensorAt
528 */
529 GoFx(kStatus) GoSystem_FindSensorByIpAddress(GoSystem system, const kIpAddress* address, GoSensor* sensor);
530
531 /**
532 * Gets the current time stamp from the sensor network.
533 *
534 * @public @memberof GoSystem
535 * @version Introduced in firmware 4.0.10.27
536 * @param system GoSystem object.
537 * @param time Receives current time stamp(microseconds).
538 * @return Operation status (kERROR_NOT_FOUND if no sensors available).
539 * @see GoSystem_GetEncoder
540 */
541 GoFx(kStatus) GoSystem_Timestamp(GoSystem system, k64u* time);
542
543 /**
544 * Gets the current encoder value from the sensor network.
545 *
546 * @public @memberof GoSystem
547 * @version Introduced in firmware 4.0.10.27
548 * @param system GoSystem object.
549 * @param encoder Receives current encoder value (ticks).
550 * @return Operation status (kERROR_NOT_FOUND if no sensors available).
551 * @see GoSystem_GetTime
552 */
553 GoFx(kStatus) GoSystem_Encoder(GoSystem system, k64s* encoder);
554
555
556 /// @cond (Gocator_1x00 || Gocator_2x00)
557
558 /**
559 * Gets the current multiplex bank count.
560 *
561 * @public @memberof GoSystem
562 * @version Introduced in firmware 4.0.10.27
563 * @param system GoSystem object.
564 * @return The current number of defined multiplex banks.
565 */
566 GoFx(kSize) GoSystem_MultiplexBankCount(GoSystem system);
567
568 /**
569 * Gets a multiplex bank corresponding to the given index.
570 *
571 * @public @memberof GoSystem
572 * @version Introduced in firmware 4.0.10.27
573 * @param system GoSystem object.
574 * @param index The index of the multiplex bank to retrieve.
575 * @return The multiplex bank at the given index or kNULL if an invalid index is given.
576 */
577 GoFx(GoMultiplexBank) GoSystem_MultiplexBankAt(GoSystem system, kSize index);
578
579 /**
580 * Adds a multiplex bank with a unique ID to the system.
581 *
582 * @public @memberof GoSystem
583 * @version Introduced in firmware 4.0.10.27
584 * @param system GoSystem object.
585 * @param bank A pointer to the newly created GoMultiplexBank object.
586 * @return Operation status.
587 */
588 GoFx(kStatus) GoSystem_AddMultiplexBank(GoSystem system, GoMultiplexBank* bank);
589
590 /**
591 * Removes a multiplex bank at the given index.
592 *
593 * @public @memberof GoSystem
594 * @version Introduced in firmware 4.0.10.27
595 * @param system GoSystem object.
596 * @param index The index of the multiplex bank to remove.
597 * @return Operation status.
598 */
599 GoFx(kStatus) GoSystem_RemoveMultiplexBank(GoSystem system, kSize index);
600
601 /**
602 * Removes all multiplex banks.
603 *
604 * @public @memberof GoSystem
605 * @version Introduced in firmware 4.0.10.27
606 * @param system GoSystem object.
607 * @return Operation status.
608 */
609 GoFx(kStatus) GoSystem_ClearMultiplexBanks(GoSystem system);
610
611 /**
612 * Gets the maximum sensor exposure duration in the given multiplex bank.
613 *
614 * @public @memberof GoSystem
615 * @version Introduced in firmware 4.0.10.27
616 * @param system GoSystem object.
617 * @param bank The multiplex bank to check.
618 * @return The maximum sensor exposure duration contained in the multiplexing bank.
619 */
620 GoFx(k64f) GoSystem_MaxBankExposureDuration(GoSystem system, GoMultiplexBank bank);
621
622 /**
623 * Automatically update the single multiplexing delay and period configuration for all sensors contained in all defined multiplex banks.
624 *
625 * @public @memberof GoSystem
626 * @version Introduced in firmware 4.0.10.27
627 * @param system GoSystem object.
628 * @param period The exposure period to set among all multiplexed sensors. A value of 0.0 will result in automatic period determination.
629 * @return Operation status.
630 */
631 GoFx(kStatus) GoSystem_UpdateAllMultiplexParameters(GoSystem system, k64f period);
632
633 /**
634 * Automatically update the multiplexing single delay configuration for all sensors contained in all defined multiplex banks.
635 *
636 * @public @memberof GoSystem
637 * @version Introduced in firmware 4.0.10.27
638 * @param system GoSystem object.
639 * @return Operation status.
640 */
641 GoFx(kStatus) GoSystem_UpdateMultiplexDelay(GoSystem system);
642
643 /**
644 * Returns the maximum value of all multiplexed sensor's minimum multiplexing periods.
645 *
646 * @public @memberof GoSystem
647 * @version Introduced in firmware 4.0.10.27
648 * @param system GoSystem object.
649 * @return Operation status.
650 */
651 GoFx(k64f) GoSystem_MaxMinimumMultiplexPeriod(GoSystem system);
652
653 /**
654 * Automatically update the multiplexing single period configuration for all sensors contained in all defined multiplex banks.
655 *
656 * @public @memberof GoSystem
657 * @version Introduced in firmware 4.0.10.27
658 * @param system GoSystem object.
659 * @param period The exposure period to set among all multiplexed sensors. A value of 0.0 will result in automatic period determination.
660 * @return Operation status.
661 */
662 GoFx(kStatus) GoSystem_UpdateMultiplexPeriod(GoSystem system, k64f period);
663
664 /**
665 * Enable or disable running the Gocator Discovery Protocol over the specified
666 * host interface which the given address.
667 *
668 * @public @memberof GoSystem
669 * @version Introduced in firmware 4.6.7.157
670 * @param system GoSystem object.
671 * @param address IP address of interface over which the discovery protocol is or is not allowed to run.
672 * @param enable Select whether to enable or disable the interface.
673 * @return Operation status.
674 */
675 GoFx(kStatus) GoSystem_SetOneDiscoveryInterface(GoSystem system, kIpAddress* address, kBool enable);
676
677 /**
678 * Enable or disable running the Gocator Discovery Protocol over all the host interfaces.
679 *
680 * @public @memberof GoSystem
681 * @version Introduced in firmware 4.6.7.157
682 * @param system GoSystem object.
683 * @param enable Select whether to enable or disable the interface(s).
684 * @return Operation status.
685 */
686 GoFx(kStatus) GoSystem_SetAllDiscoveryInterface(GoSystem system, kBool enable);
687
688 /**
689 * Enable or disable compatibility mode for the discovery service.
690 *
691 * Compatibility mode can discover older firwmare (4.2 or earlier). However
692 * the discovery traffic over the network is doubled. Compatibility mode is
693 * on by default.
694 *
695 * @public @memberof GoSystem
696 * @version Introduced in firmware 5.2.18.3
697 * @param system GoSystem object.
698 * @param enable Enable or disable compatibility mode.
699 * @return Operation status.
700 */
701 GoFx(kStatus) GoSystem_EnableDiscoveryCompatibility(GoSystem system, kBool enable);
702
703 /**
704 * Returns whether or not compatibility mode is enabled.
705 *
706 * @public @memberof GoSystem
707 * @version Introduced in firmware 5.2.18.3
708 * @param system GoSystem object.
709 * @return Compatibility enable flag.
710 */
711 GoFx(kBool) GoSystem_DiscoveryCompatibilityEnabled(GoSystem system);
712
713 /**
714 * Start running the Gocator Discovery Protocol to discover sensors. The protocol
715 * will run over the interfaces which have enabled to run the protocol.
716 *
717 * @public @memberof GoSystem
718 * @version Introduced in firmware 4.6.7.157
719 * @param system GoSystem object.
720 * @return Operation status.
721 */
722 GoFx(kStatus) GoSystem_StartDiscovery(GoSystem system);
723
724 /**
725 * Lock the system state to ensure thread safety while reading/modifying the GoSystem
726 * class's list of sensors. Call this to lock the state before retrieving and using
727 * sensor object handles to ensure the sensor object is not deleted because another
728 * thread refreshed the system.
729 * Used in multi-threaded SDK applications.
730 *
731 * @public @memberof GoSystem
732 * @version Introduced in firmware 5.2.18.3
733 * @param system GoSystem object.
734 * @return Operation status.
735 */
736 GoFx(kStatus) GoSystem_LockState(GoSystem system);
737
738 /**
739 * Unlock the system state to allow other threads to read/modify the GoSystem
740 * class's list of sensors.
741 * Used in multi-threaded SDK applications.
742 *
743 * @public @memberof GoSystem
744 * @version Introduced in firmware 5.2.18.3
745 * @param system GoSystem object.
746 * @return Operation status.
747 */
748 GoFx(kStatus) GoSystem_UnlockState(GoSystem system);
749
750
751 /// @endcond
752
753 kEndHeader()
754 #include <GoSdk/GoSystem.x.h>
755
756 #endif
k32u
GoPortInfo
Ports used from a source device.
Definition: GoSdkDef.h:764
GoSystem::GoSystem_Disconnect
kStatus GoSystem_Disconnect(GoSystem system)
Terminates control connections to all sensors.
GoSystem
Represents a system of Gocator devices.
GoSystem::GoSystem_EnableData
kStatus GoSystem_EnableData(GoSystem system, kBool enable)
Establishes data connections to all connected sensors currently in the ready or running states.
GoSystem::GoSystem_Start
kStatus GoSystem_Start(GoSystem system)
Starts all sensors that are currently in the ready state.
GoSystem::GoSystem_AddSensor
kStatus GoSystem_AddSensor(GoSystem system, const GoAddressInfo *addressInfo, const GoPortInfo *portInfo, GoSensor *sensor)
Adds a sensor by passing a custom address and port info, this doesnt require discovery.
GoSystem::GoSystem_StartExposureAutoSet
kStatus GoSystem_StartExposureAutoSet(GoSystem system)
Performs exposure auto set for sensors in the ready state.
k64u
GoSystem::GoSystem_Stop
kStatus GoSystem_Stop(GoSystem system)
Stops all connected sensors.
GoSystem::GoSystem_ClearData
kStatus GoSystem_ClearData(GoSystem system)
Clears any buffered data messages.
GoSystem::GoSystem_ReceiveHealth
kStatus GoSystem_ReceiveHealth(GoSystem system, GoDataSet *data, k64u timeout)
Receives a set of sensor health messages.
GoSystem::GoSystem_ReceiveData
kStatus GoSystem_ReceiveData(GoSystem system, GoDataSet *data, k64u timeout)
Receives a set of sensor data messages.
kPointer
GoSystem::GoSystem_Reset
kStatus GoSystem_Reset(GoSystem system, kBool wait)
Reboots all connected sensors.
GoSystem::GoSystem_ClearHealth
kStatus GoSystem_ClearHealth(GoSystem system)
Clears any buffered health messages.
GoSystem::GoSystem_StartAlignment
kStatus GoSystem_StartAlignment(GoSystem system)
Performs alignment for sensors in the ready state.
kSize
kAlloc
GoSystem::GoSystem_SensorAt
GoSensor GoSystem_SensorAt(GoSystem system, kSize index)
Gets the sensor object at the specified index.
GoSensor.h
Declares the GoSensor class.
kIpAddress
GoSystem::GoSystem_ConstructEx
kStatus GoSystem_ConstructEx(GoSystem *system, kAlloc allocator)
Constructs a GoSystem object.
GoSystem::GoSystem_SdkVersion
kVersion GoSystem_SdkVersion()
Reports the Gocator firmware version that was built alongside this library.
GoSdkDef.h
Essential SDK declarations.
GoSystem::GoSystem_Cancel
kStatus GoSystem_Cancel(GoSystem system)
Aborts ongoing sensor communication.
GoSystem::GoSystem_HasChanges
kBool GoSystem_HasChanges(GoSystem system)
Reports whether the system has changes that require a refresh.
GoDataSet
Represents a collection of data channel or health channel messages.
GoSensor::GoSystem_GetExtendedDiscoveryInfo
kStatus GoSystem_GetExtendedDiscoveryInfo(GoSystem system, k32u deviceId, GoDiscoveryExtInfo *info, kAlloc allocator)
Gets the Discovery channel information for the given device ID (if the device is present and the comm...
GoSystem::GoSystem_ScheduledStart
kStatus GoSystem_ScheduledStart(GoSystem system, k64s value)
Starts all sensors that are currently in the ready state at a scheduled value.
GoSystem::GoSystem_SensorCount
kSize GoSystem_SensorCount(GoSystem system)
Gets the number of sensors in the system.
GoSystem::GoSystem_ProtocolVersion
kVersion GoSystem_ProtocolVersion()
Reports the Gocator Protocol version implemented by this library.
GoSystem::GoSystem_SetHealthHandler
kStatus GoSystem_SetHealthHandler(GoSystem system, GoDataFx function, kPointer receiver)
Sets a callback function that can be used to receive sensor health messages asynchronously.
k64s
GoDataFx
kStatus(kCall * GoDataFx)(kPointer context, GoSensor system, GoDataSet data)
Defines the signature for a GoSystem data/health handler.
Definition: GoSystem.h:64
GoSystem::GoSystem_SetDataCapacity
kStatus GoSystem_SetDataCapacity(GoSystem system, kSize capacity)
Sets the maximum amount of memory that can be used to buffer received data messages.
GoSystem::GoSystem_Construct
kStatus GoSystem_Construct(GoSystem *system, kAlloc allocator)
Constructs a GoSystem object.
GoSystem::GoSystem_FindSensorById
kStatus GoSystem_FindSensorById(GoSystem system, k32u id, GoSensor *sensor)
Gets the sensor object with the specified device id (serial number).
GoSystem::GoSystem_DataCapacity
kSize GoSystem_DataCapacity(GoSystem system)
Reports that maximum amount of memory that can be used to buffer received data messages.
kObject
kVersion
kStatus
GoSystem::GoSystem_FindSensorByIpAddress
kStatus GoSystem_FindSensorByIpAddress(GoSystem system, const kIpAddress *address, GoSensor *sensor)
Gets the sensor object with the specified IP address.
GoSystem::GoSystem_Encoder
kStatus GoSystem_Encoder(GoSystem system, k64s *encoder)
Gets the current encoder value from the sensor network.
GoDiscoveryExtInfo
Represents an extended Discovery Information object.
k64f
GoSystem::GoSystem_Timestamp
kStatus GoSystem_Timestamp(GoSystem system, k64u *time)
Gets the current time stamp from the sensor network.
kBool
GoSensor
Represents a Gocator sensor.
GoSystem::GoSystem_Refresh
kStatus GoSystem_Refresh(GoSystem system)
Updates client state to reflect any changes that have occurred in the sensor network.
GoSystem::GoSystem_SetDataHandler
kStatus GoSystem_SetDataHandler(GoSystem system, GoDataFx function, kPointer receiver)
Sets a callback function that can be used to receive sensor data messages asynchronously.
GoAddressInfo
Sensor network address settings.
Definition: GoSdkDef.h:750
GoSystem::GoSystem_Connect
kStatus GoSystem_Connect(GoSystem system)
Establishes control connections to all sensors.