Gocator API
|
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 subequent 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.
Inherits kObject.
Public Member Functions | |
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_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 sensors currently in the ready or running states. More... | |
kStatus | GoSystem_FindSensor (GoSystem system, k32u id, GoSensor *sensor) |
Gets the sensor object with the specified device id (serial number). More... | |
kStatus | GoSystem_GetEncoder (GoSystem system, k64s *encoder) |
Gets the current encoder value from the sensor network. More... | |
kStatus | GoSystem_GetTimeStamp (GoSystem system, k64u *time) |
Gets the current time stamp from the sensor network. More... | |
kBool | GoSystem_HasChanges (GoSystem system) |
Reports whether the system has changes that require a refresh. 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_Reset (GoSystem system, kBool wait) |
Reboots all connected sensors. 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 asychronously. More... | |
kStatus | GoSystem_SetHealthHandler (GoSystem system, GoDataFx function, kPointer receiver) |
Sets a callback function that can be used to receive sensor health messages asychronously. More... | |
kStatus | GoSystem_Start (GoSystem system) |
Starts all sensors that are currently in the ready state. More... | |
kStatus | GoSystem_StartAlignment (GoSystem system) |
Starts alignment for sensor in the ready state. More... | |
kStatus | GoSystem_StartExposureAutoSet (GoSystem system) |
Starts exposure auto set for sensor(s) in the ready state. More... | |
kStatus | GoSystem_Stop (GoSystem system) |
Stops all connected sensors. More... | |
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.
system | GoSystem object. |
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.
system | GoSystem object. |
kStatus GoSystem_ClearHealth | ( | GoSystem | system | ) |
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.
system | GoSystem object. |
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.
system | Receives constructed system object. |
allocator | Memory allocator (or kNULL for default) |
kSize GoSystem_DataCapacity | ( | GoSystem | system | ) |
Reports that maximum amount of memory that can be used to buffer received data messages.
system | GoSystem object. |
kStatus GoSystem_Disconnect | ( | GoSystem | system | ) |
Terminates control connections to all sensors.
system | GoSystem object. |
kStatus GoSystem_EnableData | ( | GoSystem | system, |
kBool | enable | ||
) |
Establishes data connections to all 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.
system | GoSystem object. |
enable | kTRUE to enable data connections; kFALSE to disable. |
Gets the sensor object with the specified device id (serial number).
system | GoSystem object. |
id | Device identifier. |
sensor | Recieves sensor object. |
kStatus GoSystem_GetEncoder | ( | GoSystem | system, |
k64s * | encoder | ||
) |
Gets the current encoder value from the sensor network.
system | GoSystem object. |
encoder | Receives current encoder value (ticks). |
kStatus GoSystem_GetTimeStamp | ( | GoSystem | system, |
k64u * | time | ||
) |
Gets the current time stamp from the sensor network.
system | GoSystem object. |
time | Receives current time stamp(microseconds). |
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 communcation, 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.
system | GoSystem object. |
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 communcation 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.
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.
system | GoSystem object. |
data | Set of sensor data messages. |
timeout | Duration to wait for messages, in microseconds. |
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.
system | GoSystem object. |
data | Set of sensor health messages. |
timeout | Duration to wait for messages, in microseconds. |
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.
system | GoSystem object. |
kStatus GoSystem_Reset | ( | GoSystem | system, |
kBool | wait | ||
) |
Reboots all connected sensors.
system | GoSystem object. |
wait | kTRUE to wait for reboot complete; kFALSE to return immediately. |
Gets the sensor object at the specified index.
system | GoSystem object. |
index | Sensor index. |
kSize GoSystem_SensorCount | ( | GoSystem | system | ) |
Gets the number of sensors in the system.
system | GoSystem object. |
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.
system | GoSystem object. |
capacity | Data queue capacity, in bytes. |
Sets a callback function that can be used to receive sensor data messages asychronously.
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.
system | GoSystem object. |
function | Data callback function (or kNULL to unregister). |
receiver | Receiver argument for callback. |
Sets a callback function that can be used to receive sensor health messages asychronously.
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.
system | GoSystem object. |
function | Health callback function (or kNULL to unregister). |
receiver | Receiver argument, passed to callback. |
kStatus GoSystem_Start | ( | GoSystem | system | ) |
Starts all sensors that are currently in the ready state.
system | GoSystem object. |
kStatus GoSystem_StartAlignment | ( | GoSystem | system | ) |
Starts alignment for sensor in the ready state.
system | GoSystem object. |
kStatus GoSystem_StartExposureAutoSet | ( | GoSystem | system | ) |
Starts exposure auto set for sensor(s) in the ready state.
system | GoSystem object. |
kStatus GoSystem_Stop | ( | GoSystem | system | ) |
Stops all connected sensors.
system | GoSystem object. |