|
Gocator API
|
The SDK provides several ways to detect that a sensor has been disconnected, ranging from sub-second event-driven notification to multi-second cached state queries. The right choice depends on how quickly your application needs to react and how much overhead it can tolerate. This page explains the available methods, how to choose between them, and the trade-offs involved.
Note: All detection times below assume a healthy network. Network delay - for example in accelerated or multisensor systems - may increase detection time.
| If your application needs to… | Method | Detection time [s] | Detection time when PC-accelerated [s] |
|---|---|---|---|
| React to disconnection within ~100 ms (e.g. halt a motion system before the next part reaches the sensor) | GoSensor_SetHeartbeatDisconnectHandler() (new in 6.6.x.x) | ~0.1 | ~0.1 |
| Periodically poll for sensor responsiveness with low overhead | GoSensor_IsResponsive() | >6 | >10 |
| Distinguish between connection states (online, offline, unresponsive, etc.) - not just detect disconnection | GoSensor_State() | >6 | >10 |
Several other methods can indirectly detect disconnection but are not recommended; see Methods to avoid below.
Heartbeat callback - fastest detection (~100 ms, new in 6.6.x.x)
Heartbeat monitoring is an opt-in UDP-based mechanism that fires a callback within approximately 100 ms of a sensor disconnection. It is suitable for time-critical reactions where the multi-second timing of the polled methods is too slow.
Enable heartbeat monitoring per sensor with GoSensor_EnableHeartbeat(), register a callback with GoSensor_SetHeartbeatDisconnectHandler(), and optionally adjust the timeout with GoSensor_SetHeartbeatTimeout() (default 100 ms). A reconnect callback is also available via GoSensor_SetHeartbeatReconnectHandler(). See Heartbeat usage notes below for important caveats before using this mechanism.
GoSensor_IsResponsive() - the recommended polled method
Returns kFALSE 6+ seconds after disconnection. This is the most reliable and lowest-overhead polled method, and is recommended for periodic application-level health checks. It relies directly on the GO_STATE_UNRESPONSIVE status (see Connection state machine below).
GoSensor_State() - full state, including disconnection
Use this if your application needs to distinguish between several sensor states rather than just connected vs. disconnected. To detect disconnection specifically, compare the result against GO_STATE_UNRESPONSIVE. Timing is similar to GoSensor_IsResponsive(), though it may be slightly slower because it can update the cache when invalid.
GO_STATE_OFFLINE status, which can take an indefinite amount of time to be set. After three GoSensor_Refresh() calls it will return false in 6+ seconds.A sensor enters the GO_STATE_UNRESPONSIVE state after missing three consecutive 2-second discovery cycles (a 6-second window). Calling GoSensor_Refresh() three or more times forcibly triggers discovery cycles, accelerating the transition. When GoSensor_Refresh() is called on an already-unresponsive sensor, it is formally disconnected: its state moves to GO_STATE_OFFLINE and it is removed from monitoring.
This state machine is the basis for the timing characteristics of the polled methods above and for GoSensor_IsConnected().
Heartbeat state is independent of SDK state. When the disconnect callback fires, the sensor's state as reported by GoSensor_IsResponsive(), GoSensor_State(), and related functions will not yet reflect the disconnection. Those functions still rely on the discovery and health message timeouts, which need their full time to elapse (6+ seconds). The heartbeat callback fires earlier as an advance signal - ideal for time-critical reactions such as stopping motion - but SDK state queries made immediately after the callback will still report the sensor as connected.
Enable heartbeat only after the sensor is in its intended connection state. Heartbeat registration is path-specific: enabling it on a directly-connected sensor registers with the sensor's heartbeat server, while enabling it on an accelerated sensor registers with the accelerator relay. If heartbeat is enabled on a direct connection and the sensor is subsequently accelerated, the registration becomes stale and the SDK will automatically disable heartbeat on the next discovery cycle. Heartbeat must be re-enabled after the sensor is fully in its new state.
Acceleration state changes require re-enabling heartbeat. If an accelerated sensor loses acceleration while heartbeat is active, the accelerator relay stops sending packets and the disconnect callback will fire due to timeout. Heartbeat is not automatically re-registered for the new direct connection; call GoSensor_EnableHeartbeat(kFALSE) followed by GoSensor_EnableHeartbeat(kTRUE) once the sensor is in its new stable state.
Each sensor's heartbeat receiver binds to an OS-assigned ephemeral port, so multiple sensors can be monitored simultaneously from a single SDK process without port conflicts.
Heartbeat API (6.6.x.x+):
Heartbeat example code is provided in GoSdk/GoHeartbeatExample/GoHeartbeatExample.c (single sensor) and GoSdk/GoHeartbeatExample/GoHeartbeatExampleMultipleSensor.c (multiple sensors).