Gocator API

- Home
- Categories
- Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
Public Member Functions
GoSystem Class Reference
GoSdk

## Description

Represents a system of Gocator devices.

During construction, a GoSystem object uses Gocator Discovery Protocol to locate devices. Subsequently, the list of detected devices can be accessed using GoSystem_SensorCount and GoSystem_SensorAt.

Immediately after construction, all sensor objects are in the online state. This state indicates that a sensor has been detected, but that the client has not yet established a control connection to the sensor. The only sensor functions than can be used in this state are GoSensor_State, GoSensor_Address, and GoSensor_SetAddress.

Because Gocator Discovery Protocol works across subnets, but Gocator Control Protocol does not, it is possible for a sensor to be successfully detected but for subsequent connection attempts to fail. In this case, the GoSensor_SetAddress function can be used to reconfigure the sensor to operate on the same subnet as the client.

If the client and device are configured to operate on the same subnet, the GoSystem_Connect or GoSensor_Connect functions can be used to establish control connections.

See also
  GoSystem_Construct, GoSystem_Connect, GoSensor_State, GoSensor_Address, GoSensor_SetAddress.

Inherits kObject.

## Public Member Functions
kStatus | GoSystem_AddMultiplexBank (GoSystem system, GoMultiplexBank *bank)
| Adds a multiplex bank with a unique ID to the system. More...
kStatus | GoSystem_Cancel (GoSystem system)
| Aborts ongoing sensor communication. More...
kStatus | GoSystem_ClearData (GoSystem system)
| Clears any buffered data messages. More...
kStatus | GoSystem_ClearHealth (GoSystem system)
| Clears any buffered health messages. More...
kStatus | GoSystem_ClearMultiplexBanks (GoSystem system)
| Removes all multiplex banks. More...
kStatus | GoSystem_Connect (GoSystem system)
| Establishes control connections to all sensors. More...
kStatus | GoSystem_Construct (GoSystem *system, kAlloc allocator)
| Constructs a GoSystem object. More...
kSize | GoSystem_DataCapacity (GoSystem system)
| Reports that maximum amount of memory that can be used to buffer received data messages. More...
kStatus | GoSystem_Disconnect (GoSystem system)
| Terminates control connections to all sensors. More...
kStatus | GoSystem_EnableData (GoSystem system, kBool enable)
| Establishes data connections to all connected sensors currently in the ready or running states. More...
kStatus | GoSystem_Encoder (GoSystem system, k64s *encoder)
| Gets the current encoder value from the sensor network. More...
kStatus | GoSystem_FindSensorById (GoSystem system, k32u id, GoSensor *sensor)
| Gets the sensor object with the specified device id (serial number). More...
kStatus | GoSystem_FindSensorByIpAddress (GoSystem system, const kIpAddress *address, GoSensor *sensor)
| Gets the sensor object with the specified IP address. More...
kBool | GoSystem_HasChanges (GoSystem system)
| Reports whether the system has changes that require a refresh. More...
k64f | GoSystem_MaxBankExposureDuration (GoSystem system, GoMultiplexBank bank)
| Gets the maximum sensor exposure duration in the given multiplex bank. More...
k64f | GoSystem_MaxMinimumMultiplexPeriod (GoSystem system)
| Returns the maximum value of all multiplexed sensor's minimum multiplexing periods. More...
GoMultiplexBank | GoSystem_MultiplexBankAt (GoSystem system, kSize index)
| Gets a multiplex bank corresponding to the given index. More...
kSize | GoSystem_MultiplexBankCount (GoSystem system)
| Gets the current multiplex bank count. More...
kVersion | GoSystem_ProtocolVersion ()
| Reports the Gocator Protocol version implemented by this library. More...
kStatus | GoSystem_ReceiveData (GoSystem system, GoDataSet *data, k64u timeout)
| Receives a set of sensor data messages. More...
kStatus | GoSystem_ReceiveHealth (GoSystem system, GoDataSet *data, k64u timeout)
| Receives a set of sensor health messages. More...
kStatus | GoSystem_Refresh (GoSystem system)
| Updates client state to reflect any changes that have occurred in the sensor network. More...
kStatus | GoSystem_RemoveMultiplexBank (GoSystem system, kSize index)
| Removes a multiplex bank at the given index. More...
kStatus | GoSystem_Reset (GoSystem system, kBool wait)
| Reboots all connected sensors. More...
kVersion | GoSystem_SdkVersion ()
| Reports the Gocator firmware version that was built alongside this library. More...
GoSensor | GoSystem_SensorAt (GoSystem system, kSize index)
| Gets the sensor object at the specified index. More...
kSize | GoSystem_SensorCount (GoSystem system)
| Gets the number of sensors in the system. More...
kStatus | GoSystem_SetDataCapacity (GoSystem system, kSize capacity)
| Sets the maximum amount of memory that can be used to buffer received data messages. More...
kStatus | GoSystem_SetDataHandler (GoSystem system, GoDataFx function, kPointer receiver)
| Sets a callback function that can be used to receive sensor data messages asynchronously. More...
kStatus | GoSystem_SetHealthHandler (GoSystem system, GoDataFx function, kPointer receiver)
| Sets a callback function that can be used to receive sensor health messages asynchronously. More...
kStatus | GoSystem_Start (GoSystem system)
| Starts all sensors that are currently in the ready state. More...
kStatus | GoSystem_StartAlignment (GoSystem system)
| Performs alignment for sensors in the ready state. More...
kStatus | GoSystem_StartExposureAutoSet (GoSystem system)
| Performs exposure auto set for sensors in the ready state. More...
kStatus | GoSystem_Stop (GoSystem system)
| Stops all connected sensors. More...
kStatus | GoSystem_Timestamp (GoSystem system, k64u *time)
| Gets the current time stamp from the sensor network. More...
kStatus | GoSystem_UpdateAllMultiplexParameters (GoSystem system, k64f period)
| Automatically update the single multiplexing delay and period configuration for all sensors contained in all defined multiplex banks. More...
kStatus | GoSystem_UpdateMultiplexDelay (GoSystem system)
| Automatically update the multiplexing single delay configuration for all sensors contained in all defined multiplex banks. More...
kStatus | GoSystem_UpdateMultiplexPeriod (GoSystem system, k64f period)
| Automatically update the multiplexing single period configuration for all sensors contained in all defined multiplex banks. More...

## Member Function Documentation

kStatus GoSystem_AddMultiplexBank | ( | GoSystem | system,
|  | GoMultiplexBank * | bank
| ) |  |

Adds a multiplex bank with a unique ID to the system.

Parameters

  system | GoSystem object.
  bank | A pointer to the newly created GoMultiplexBank object.

Returns
  Operation status.

kStatus GoSystem_Cancel | ( | GoSystem | system | ) |

Aborts ongoing sensor communication.

This method asynchronously aborts ongoing communication; the next time that any I/O operation blocks for an extended period of time, it will be terminated. This method is thread-safe.

In order to resume communication, call GoSystem_Refresh or GoSystem_Connect.

Parameters

  system | GoSystem object.

Returns
  Operation status.

kStatus GoSystem_ClearData | ( | GoSystem | system | ) |

Clears any buffered data messages.

When stopping and then restarting a system, it may be desirable to ensure that no messages from the previous session remain in any buffers. The GoSystem_ClearData function closes any open data channels, destroys any received messages, and then reopens data channels.

Parameters

  system | GoSystem object.

Returns
  Operation status.

kStatus GoSystem_ClearHealth | ( | GoSystem | system | ) |

Clears any buffered health messages.

Parameters

  system | GoSystem object.

Returns
  Operation status.

kStatus GoSystem_ClearMultiplexBanks | ( | GoSystem | system | ) |

Removes all multiplex banks.

Parameters

  system | GoSystem object.

Returns
  Operation status.

kStatus GoSystem_Connect | ( | GoSystem | system | ) |

Establishes control connections to all sensors.

A control connection is required before calling any sensor function except GoSensor_State, GoSensor_Address, or GoSensor_SetAddress.

Parameters

  system | GoSystem object.

Returns
  Operation status.

kStatus GoSystem_Construct | ( | GoSystem * | system,
|  | kAlloc | allocator
| ) |  |

Constructs a GoSystem object.

During construction, a GoSystem object uses Gocator Discovery Protocol to locate sensors. The list of detected sensors can be accessed using the GoSystem_SensorCount and GoSystem_SensorAt functions.

Parameters

  system | Receives constructed system object.
  allocator | Memory allocator (or kNULL for default)

Returns
  Operation status.

kSize GoSystem_DataCapacity | ( | GoSystem | system | ) |

Reports that maximum amount of memory that can be used to buffer received data messages.

Parameters

  system | GoSystem object.

Returns
  Data queue capacity, in bytes.

See also
  GoSystem_SetDataCapacity

kStatus GoSystem_Disconnect | ( | GoSystem | system | ) |

Terminates control connections to all sensors.

Parameters

  system | GoSystem object.

Returns
  Operation status.

kStatus GoSystem_EnableData | ( | GoSystem | system,
|  | kBool | enable
| ) |  |

Establishes data connections to all connected sensors currently in the ready or running states.

Data connections are not automatically established when sensor control connection are established. Use this function (or GoSensor_EnableData) to enable/disable data connections.

Parameters

  system | GoSystem object.
  enable | kTRUE to enable data connections; kFALSE to disable.

Returns
  Operation status.

See also
  GoSystem_ReceiveData, GoSensor_EnableData

kStatus GoSystem_Encoder | ( | GoSystem | system,
|  | k64s * | encoder
| ) |  |

Gets the current encoder value from the sensor network.

Parameters

  system | GoSystem object.
  encoder | Receives current encoder value (ticks).

Returns
  Operation status (kERROR_NOT_FOUND if no sensors available).

See also
  GoSystem_GetTime

kStatus GoSystem_FindSensorById | ( | GoSystem | system,
|  | k32u | id,
|  | GoSensor * | sensor
| ) |  |

Gets the sensor object with the specified device id (serial number).

Parameters

  system | GoSystem object.
  id | Device identifier.
  sensor | Receives sensor object.

Returns
  Operation status (kERROR_NOT_FOUND if sensor not found).

See also
  GoSystem_SensorCount, GoSystem_SensorAt

kStatus GoSystem_FindSensorByIpAddress | ( | GoSystem | system,
|  | const kIpAddress * | address,
|  | GoSensor * | sensor
| ) |  |

Gets the sensor object with the specified IP address.

Parameters

  system | GoSystem object.
  address | Pointer to sensor IP address.
  sensor | Receives sensor object.

Returns
  Operation status (kERROR_NOT_FOUND if sensor not found).

See also
  GoSystem_SensorCount, GoSystem_SensorAt

kBool GoSystem_HasChanges | ( | GoSystem | system | ) |

Reports whether the system has changes that require a refresh.

Sensors can undergo autonomous state changes that require client state to be refreshed (e.g. sensor goes offline). The GoSystem_HasChanges function can be used to determine if such changes have occurred.

The GoSystem_HasChanges function does not perform communication, and consequently, will not require the caller to block for a long duration. If changes are detected, the GoSystem_Refresh function can be called to resolve the changes.

This method is thread-safe.

Parameters

  system | GoSystem object.

Returns
  kTRUE if the system has changes.

k64f GoSystem_MaxBankExposureDuration | ( | GoSystem | system,
|  | GoMultiplexBank | bank
| ) |  |

Gets the maximum sensor exposure duration in the given multiplex bank.

Parameters

  system | GoSystem object.
  bank | The multiplex bank to check.

Returns
  The maximum sensor exposure duration contained in the multiplexing bank.

k64f GoSystem_MaxMinimumMultiplexPeriod | ( | GoSystem | system | ) |

Returns the maximum value of all multiplexed sensor's minimum multiplexing periods.

Parameters

  system | GoSystem object.

Returns
  Operation status.

GoMultiplexBank GoSystem_MultiplexBankAt | ( | GoSystem | system,
|  | kSize | index
| ) |  |

Gets a multiplex bank corresponding to the given index.

Parameters

  system | GoSystem object.
  index | The index of the multiplex bank to retrieve.

Returns
  The multiplex bank at the given index or kNULL if an invalid index is given.

kSize GoSystem_MultiplexBankCount | ( | GoSystem | system | ) |

Gets the current multiplex bank count.

Parameters

  system | GoSystem object.

Returns
  The current number of defined multiplex banks.

kVersion GoSystem_ProtocolVersion | ( |  | ) |

Reports the Gocator Protocol version implemented by this library.

A Gocator Protocol version number has a major component and a minor component. If the major version implemented by this library is the same as the major version implemented by a sensor device, then communication can proceed. Otherwise, the sensor should be upgraded or a newer version of this library should be obtained. Sensors with incompatible major versions will be reported as being in the incompatible state upon connection.

If major versions match, but the minor version implemented by this library is lower than the minor version implemented by the sensor, then some sensor features will not be accessible through this library.

If major versions match, but the minor version implemented by this library is higher than the minor version implemented by the sensor, then some features exposed by this library may be unimplemented by the sensor.

This method is thread-safe.

Returns
  Protocol version implemented by this library.

See also
  GoSensor_ProtocolVersion, GoSensor_State

kStatus GoSystem_ReceiveData | ( | GoSystem | system,
|  | GoDataSet * | data,
|  | k64u | timeout
| ) |  |

Receives a set of sensor data messages.

Sensor data messages can be received synchronously using this function or asynchronously by registering a callback with the GoSystem_SetDataHandler function.

NOTE: Data received with this function must be destroyed after use, otherwise a memory leak will result.

Parameters

  system | GoSystem object.
  data | Set of sensor data messages.
  timeout | Duration to wait for messages, in microseconds.

Returns
  Operation status.

See also
  GoDestroy, GoSystem_SetDataHandler, GoSystem_SetDataCapacity, GoSystem_EnableData

kStatus GoSystem_ReceiveHealth | ( | GoSystem | system,
|  | GoDataSet * | data,
|  | k64u | timeout
| ) |  |

Receives a set of sensor health messages.

Sensor health messages can be received synchronously using this function or asynchronously by registering a callback with the GoSystem_SetHealthHandler function.

Parameters

  system | GoSystem object.
  data | Set of sensor health messages.
  timeout | Duration to wait for messages, in microseconds.

Returns
  Operation status.

See also
  GoSystem_SetHealthHandler

kStatus GoSystem_Refresh | ( | GoSystem | system | ) |

Updates client state to reflect any changes that have occurred in the sensor network.

Sensors can undergo autonomous state changes that require client state to be refreshed (e.g. sensor goes offline). The GoSystem_Refresh function resynchronizes client state with the current state of the sensor network.

Calling this function may destroy or modify local sensor objects. The GoSystem_HasChanges function can be used prior to calling GoSystem_Refresh, to determine whether a refresh is needed.

Parameters

  system | GoSystem object.

Returns
  Operation status.

kStatus GoSystem_RemoveMultiplexBank | ( | GoSystem | system,
|  | kSize | index
| ) |  |

Removes a multiplex bank at the given index.

Parameters

  system | GoSystem object.
  index | The index of the multiplex bank to remove.

Returns
  Operation status.

kStatus GoSystem_Reset | ( | GoSystem | system,
|  | kBool | wait
| ) |  |

Reboots all connected sensors.

Parameters

  system | GoSystem object.
  wait | kTRUE to wait for reboot complete; kFALSE to return immediately.

Returns
  Operation status.

kVersion GoSystem_SdkVersion | ( |  | ) |

Reports the Gocator firmware version that was built alongside this library.

A Gocator SDK version number has a major component and a minor component. If the major version implemented by this library is the same as the major version implemented by a sensor device, then communication can proceed. Otherwise, the sensor should be upgraded or a version of this library matching the sensor should be obtained.

When it comes to the matter of mismatched SDK and firmware versions, so long as the protocol versions match up, they should be compatible.

Returns
  Firmware version that was built alongside this library.

See also
  GoSensor_FirmwareVersion, GoSystem_ProtocolVersion

GoSensor GoSystem_SensorAt | ( | GoSystem | system,
|  | kSize | index
| ) |  |

Gets the sensor object at the specified index.

Parameters

  system | GoSystem object.
  index | Sensor index.

Returns
  Sensor object.

See also
  GoSystem_SensorCount

kSize GoSystem_SensorCount | ( | GoSystem | system | ) |

Gets the number of sensors in the system.

Parameters

  system | GoSystem object.

Returns
  Count of sensors in the system.

See also
  GoSystem_SensorAt

kStatus GoSystem_SetDataCapacity | ( | GoSystem | system,
|  | kSize | capacity
| ) |  |

Sets the maximum amount of memory that can be used to buffer received data messages.

Received data messages are enqueued until they are accepted by the caller. This function determines the maximum size, in bytes, of enqueued messages. The default maximum size is 50 MB.

Parameters

  system | GoSystem object.
  capacity | Data queue capacity, in bytes.

Returns
  Operation status.

See also
  GoSystem_DataCapacity

kStatus GoSystem_SetDataHandler | ( | GoSystem | system,
|  | GoDataFx | function,
|  | kPointer | receiver
| ) |  |

Sets a callback function that can be used to receive sensor data messages asynchronously.

Sensor data messages can be received synchronously using the GoSystem_ReceiveData function or asynchronously by registering a callback function. If a callback function is registered, a background thread will be created to perform notifications.

To unregister a previously-registered data handler, call this function using kNULL in place of the callback function argument.

Parameters

  system | GoSystem object.
  function | Data callback function (or kNULL to unregister).
  receiver | Receiver argument for callback.

Returns
  Operation status.

See also
  GoDataFx, GoSystem_ReceiveData, GoSystem_SetDataCapacity, GoSystem_EnableData

kStatus GoSystem_SetHealthHandler | ( | GoSystem | system,
|  | GoDataFx | function,
|  | kPointer | receiver
| ) |  |

Sets a callback function that can be used to receive sensor health messages asynchronously.

Sensor health messages can be received synchronously using the GoSystem_ReceiveHealth function or asynchronously by registering a callback function. If a callback function is registered, a background thread will be created to perform notifications.

To unregister a previously-registered health handler, call this function using kNULL in place of the callback function argument.

Parameters

  system | GoSystem object.
  function | Health callback function (or kNULL to unregister).
  receiver | Receiver argument, passed to callback.

Returns
  Operation status.

See also
  GoDataFx, GoSystem_ReceiveHealth, GoSystem_SetDataCapacity, GoSystem_EnableData

kStatus GoSystem_Start | ( | GoSystem | system | ) |

Starts all sensors that are currently in the ready state.

Parameters

  system | GoSystem object.

Returns
  Operation status.

See also
  GoSystem_Stop, GoSensor_Start, GoSensor_Stop

kStatus GoSystem_StartAlignment | ( | GoSystem | system | ) |

Performs alignment for sensors in the ready state.

NOTE: This operation will result in sensor starts for the duration of the alignment. It can be canceled via GoSystem_Stop. This function's operation status does not correspond to the actual alignment result. In order to retrieve the alignment result, you must enable the data channel before calling this function, receive an alignment data message and then check its status.

Parameters

  system | GoSystem object.

Returns
  Operation status.

See also
  GoSystem_EnableData, GoSystem_ReceiveData, GoSystem_Stop

kStatus GoSystem_StartExposureAutoSet | ( | GoSystem | system | ) |

Performs exposure auto set for sensors in the ready state.

NOTE: This operation will result in sensor starts for the duration of the exposure AutoSet. A successful operation status does NOT modify the configuration. You must retrieve the resulting exposure values and set it for the appropriate exposure setting. This involves enabling the data connection prior to running exposure auto set and then receiving an exposure auto set message, which you can then use to query the status and access the resulting value.

Parameters

  system | GoSystem object.

Returns
  Operation status.

See also
  GoSystem_EnableData, GoSystem_ReceiveData

kStatus GoSystem_Stop | ( | GoSystem | system | ) |

Stops all connected sensors.

Parameters

  system | GoSystem object.

Returns
  Operation status.

See also
  GoSystem_Start, GoSensor_Start, GoSensor_Stop

kStatus GoSystem_Timestamp | ( | GoSystem | system,
|  | k64u * | time
| ) |  |

Gets the current time stamp from the sensor network.

Parameters

  system | GoSystem object.
  time | Receives current time stamp(microseconds).

Returns
  Operation status (kERROR_NOT_FOUND if no sensors available).

See also
  GoSystem_GetEncoder

kStatus GoSystem_UpdateAllMultiplexParameters | ( | GoSystem | system,
|  | k64f | period
| ) |  |

Automatically update the single multiplexing delay and period configuration for all sensors contained in all defined multiplex banks.

Parameters

  system | GoSystem object.
  period | The exposure period to set among all multiplexed sensors. A value of 0.0 will result in automatic period determination.

Returns
  Operation status.

kStatus GoSystem_UpdateMultiplexDelay | ( | GoSystem | system | ) |

Automatically update the multiplexing single delay configuration for all sensors contained in all defined multiplex banks.

Parameters

  system | GoSystem object.

Returns
  Operation status.

kStatus GoSystem_UpdateMultiplexPeriod | ( | GoSystem | system,
|  | k64f | period
| ) |  |

Automatically update the multiplexing single period configuration for all sensors contained in all defined multiplex banks.

Parameters

  system | GoSystem object.
  period | The exposure period to set among all multiplexed sensors. A value of 0.0 will result in automatic period determination.

Returns
  Operation status.

The documentation for this class was generated from the following file:

- GoSystem.h