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

Description

Public Member Functions

Member Function Documentation