Gocator API
GoHeartbeat.h
Go to the documentation of this file.
1 /**
2  * @file GoHeartbeat.h
3  * @brief Declares the GoHeartbeat class for fast sensor disconnection detection.
4  *
5  * The GoHeartbeat class provides UDP-based heartbeat monitoring that can detect
6  * sensor disconnection within approximately 100ms, significantly faster than
7  * the standard health-based detection (~6 seconds).
8  *
9  * @internal
10  * Copyright (C) 2026 by LMI Technologies Inc.
11  * Licensed under the MIT License.
12  * Redistributed files must retain the above copyright notice.
13  */
14 #ifndef GO_SDK_HEARTBEAT_H
15 #define GO_SDK_HEARTBEAT_H
16 
17 #include <GoSdk/GoSdkDef.h>
18 #include <kApi/Io/kNetwork.h>
19 
20 /**
21  * Default UDP port for heartbeat communication.
22  *
23  * ============================================================================
24  * SHARED PROTOCOL CONSTANT - DUPLICATED ACROSS THREE LAYERS
25  * ============================================================================
26  * GoSdk, GoSensor (firmware), and GoSensorApp (accelerator) each define their
27  * own copy of the heartbeat wire format because they are independently
28  * compiled modules with no shared header. The three layers ship as a single
29  * version-locked release package; this is the enforcement mechanism for
30  * keeping these values in sync, NOT a build-time check.
31  *
32  * If you change ANY of the constants or the packet struct below, you MUST
33  * update ALL THREE matching definitions, or heartbeat will silently break:
34  *
35  * Port: GO_HEARTBEAT_DEFAULT_PORT (this file, SDK)
36  * GS_HEARTBEAT_SERVER_DEFAULT_PORT (GsHeartbeatServer.h, firmware)
37  * GS_REMOTEAPP_HEARTBEAT_DEFAULT_PORT(GsRemoteApp.z.h, accelerator)
38  *
39  * Magic: GO_HEARTBEAT_MAGIC (this file, SDK)
40  * GS_HEARTBEAT_MAGIC (GsHeartbeatServer.h, firmware)
41  * GS_REMOTEAPP_HEARTBEAT_MAGIC (GsRemoteApp.z.h, accelerator)
42  *
43  * Packet: GoHeartbeatPacket (this file, SDK)
44  * GsHeartbeatPacket (GsHeartbeatServer.h, firmware)
45  * GsRemoteAppHeartbeatPacket (GsRemoteApp.z.h, accelerator)
46  *
47  * The three packet structs MUST have identical layout AND identical packed
48  * size (currently 16 bytes). Any field addition, reorder, or width change
49  * must be applied symmetrically to all three.
50  * ============================================================================
51  */
52 #define GO_HEARTBEAT_DEFAULT_PORT (3195)
53 
54 /**
55  * Default heartbeat timeout in microseconds (100ms).
56  */
57 #define GO_HEARTBEAT_DEFAULT_TIMEOUT_US (100000)
58 
59 /**
60  * Default heartbeat interval in microseconds (25ms).
61  */
62 #define GO_HEARTBEAT_DEFAULT_INTERVAL_US (25000)
63 
64 /**
65  * Byte-order conversion macros for network packets.
66  * Network byte order is big-endian.
67  */
68 #if defined(K_ENDIAN_LITTLE)
69  #define GO_HEARTBEAT_HTON16(x) ((k16u)(((x) >> 8) | ((x) << 8)))
70  #define GO_HEARTBEAT_HTON32(x) ((k32u)(((x) >> 24) | (((x) >> 8) & 0xFF00) | (((x) << 8) & 0xFF0000) | ((x) << 24)))
71  #define GO_HEARTBEAT_HTON64(x) ((k64u)(((k64u)GO_HEARTBEAT_HTON32((k32u)(x)) << 32) | GO_HEARTBEAT_HTON32((k32u)((x) >> 32))))
72 #else
73  #define GO_HEARTBEAT_HTON16(x) (x)
74  #define GO_HEARTBEAT_HTON32(x) (x)
75  #define GO_HEARTBEAT_HTON64(x) (x)
76 #endif
77 
78 #define GO_HEARTBEAT_NTOH16(x) GO_HEARTBEAT_HTON16(x)
79 #define GO_HEARTBEAT_NTOH32(x) GO_HEARTBEAT_HTON32(x)
80 #define GO_HEARTBEAT_NTOH64(x) GO_HEARTBEAT_HTON64(x)
81 
82 /**
83  * @struct GoHeartbeatPacket
84  * @extends kValue
85  * @ingroup GoSdk
86  * @brief Represents a heartbeat UDP packet (wire format).
87  *
88  * This structure is packed to ensure consistent wire format across platforms.
89  * All multi-byte fields are stored in network byte order (big-endian).
90  */
91 #pragma pack(push, 1)
92 typedef struct GoHeartbeatPacket
93 {
94  k16u magic; ///< Magic identifier (0x474F = "GO") - network byte order
95  k32u sensorId; ///< Sensor ID that sent this heartbeat - network byte order
96  k16u sequence; ///< Rolling sequence number (0-65535) - network byte order
97  k64u timestamp; ///< Timestamp when packet was sent (microseconds) - network byte order
99 #pragma pack(pop)
100 
101 /**
102  * Magic number for heartbeat packets ("GO" in ASCII).
103  */
104 #define GO_HEARTBEAT_MAGIC (0x474F)
105 
106 /**
107  * @struct GoHeartbeatInfo
108  * @extends kValue
109  * @ingroup GoSdk
110  * @brief Represents heartbeat status information.
111  */
112 typedef struct GoHeartbeatInfo
113 {
114  k32u sensorId; ///< Sensor ID being monitored
115  kBool connected; ///< Current connection status
116  k64u lastReceivedTime; ///< Timestamp of last received heartbeat (microseconds)
117  k16u lastSequence; ///< Last received sequence number (wraps every 65536 packets)
118  k64u packetsReceived; ///< Total packets received
119  k64u packetsMissed; ///< Total packets missed (sequence gaps)
121 
122 /**
123  * @class GoHeartbeat
124  * @extends kObject
125  * @ingroup GoSdk
126  * @brief Provides fast UDP-based heartbeat monitoring for sensor disconnection detection.
127  *
128  * The GoHeartbeat class monitors UDP heartbeat packets from a sensor or accelerator
129  * and can detect disconnection within approximately 100ms (configurable).
130  *
131  * Example usage:
132  * @code
133  * GoHeartbeat heartbeat = kNULL;
134  *
135  * // Construct heartbeat monitor
136  * GoHeartbeat_Construct(&heartbeat, kNULL);
137  *
138  * // Set disconnect callback
139  * GoHeartbeat_SetDisconnectHandler(heartbeat, OnDisconnect, context);
140  *
141  * // Start monitoring sensor
142  * GoHeartbeat_Start(heartbeat, sensorId, sensorAddress, GO_HEARTBEAT_DEFAULT_PORT);
143  *
144  * // ... application runs ...
145  *
146  * // Stop and destroy
147  * GoHeartbeat_Stop(heartbeat);
148  * GoHeartbeat_Destroy(heartbeat);
149  * @endcode
150  */
151 typedef kObject GoHeartbeat;
152 
153 /**
154  * Defines the signature for a heartbeat disconnect callback function.
155  *
156  * This callback is invoked when a sensor is detected as disconnected
157  * (no heartbeat received within the configured timeout).
158  *
159  * @param context User-provided context pointer.
160  * @param heartbeat GoHeartbeat object that detected the disconnection.
161  * @param sensorId ID of the sensor that disconnected.
162  */
163 typedef void (kCall* GoHeartbeatDisconnectFx)(kPointer context, GoHeartbeat heartbeat, k32u sensorId);
164 
165 /**
166  * Defines the signature for a heartbeat reconnect callback function.
167  *
168  * This callback is invoked when a previously disconnected sensor
169  * starts sending heartbeats again.
170  *
171  * @param context User-provided context pointer.
172  * @param heartbeat GoHeartbeat object that detected the reconnection.
173  * @param sensorId ID of the sensor that reconnected.
174  */
175 typedef void (kCall* GoHeartbeatReconnectFx)(kPointer context, GoHeartbeat heartbeat, k32u sensorId);
176 
177 /**
178  * Constructs a GoHeartbeat object.
179  *
180  * @public @memberof GoHeartbeat
181  * @version Introduced in firmware 6.6.x.x
182  * @param heartbeat Receives the constructed heartbeat object.
183  * @param allocator Memory allocator (or kNULL for default).
184  * @return Operation status.
185  */
186 GoFx(kStatus) GoHeartbeat_Construct(GoHeartbeat* heartbeat, kAlloc allocator);
187 
188 /**
189  * Destroys a GoHeartbeat object.
190  *
191  * @public @memberof GoHeartbeat
192  * @version Introduced in firmware 6.6.x.x
193  * @param heartbeat Heartbeat object to destroy.
194  * @return Operation status.
195  */
196 GoFx(kStatus) GoHeartbeat_Destroy(GoHeartbeat heartbeat);
197 
198 /**
199  * Sets the timeout duration for disconnection detection.
200  *
201  * If no heartbeat is received within this timeout, the sensor is
202  * considered disconnected. Default is 100ms (100000 microseconds).
203  *
204  * @public @memberof GoHeartbeat
205  * @version Introduced in firmware 6.6.x.x
206  * @param heartbeat Heartbeat object.
207  * @param timeoutUs Timeout in microseconds.
208  * @return Operation status.
209  */
210 GoFx(kStatus) GoHeartbeat_SetTimeout(GoHeartbeat heartbeat, k64u timeoutUs);
211 
212 /**
213  * Gets the current timeout duration.
214  *
215  * @public @memberof GoHeartbeat
216  * @version Introduced in firmware 6.6.x.x
217  * @param heartbeat Heartbeat object.
218  * @return Timeout in microseconds.
219  */
220 GoFx(k64u) GoHeartbeat_Timeout(GoHeartbeat heartbeat);
221 
222 /**
223  * Sets the disconnect callback handler.
224  *
225  * This callback is invoked when a sensor is detected as disconnected.
226  * The callback is invoked from a background thread.
227  *
228  * @public @memberof GoHeartbeat
229  * @version Introduced in firmware 6.6.x.x
230  * @param heartbeat Heartbeat object.
231  * @param function Disconnect callback function (or kNULL to unregister).
232  * @param context Context argument for callback.
233  * @return Operation status.
234  */
236 
237 /**
238  * Sets the reconnect callback handler.
239  *
240  * This callback is invoked when a previously disconnected sensor
241  * starts sending heartbeats again.
242  *
243  * @public @memberof GoHeartbeat
244  * @version Introduced in firmware 6.6.x.x
245  * @param heartbeat Heartbeat object.
246  * @param function Reconnect callback function (or kNULL to unregister).
247  * @param context Context argument for callback.
248  * @return Operation status.
249  */
251 
252 /**
253  * Starts heartbeat monitoring for a sensor.
254  *
255  * This function begins listening for UDP heartbeat packets from the
256  * specified sensor. If heartbeats stop arriving within the configured
257  * timeout, the disconnect callback will be invoked.
258  *
259  * @public @memberof GoHeartbeat
260  * @version Introduced in firmware 6.6.x.x
261  * @param heartbeat Heartbeat object.
262  * @param sensorId Sensor ID to monitor.
263  * @param address IP address to listen on (use kIpAddress_AnyV4() to listen on all interfaces).
264  * @param port UDP port to listen on. Pass 0 to let the OS assign an
265  * ephemeral free port; this is the recommended setting
266  * because it allows a single process to monitor multiple
267  * sensors without port collisions. Use GoHeartbeat_LocalPort()
268  * after this call to retrieve the actually-bound port.
269  * @return Operation status.
270  */
271 GoFx(kStatus) GoHeartbeat_Start(GoHeartbeat heartbeat, k32u sensorId, kIpAddress address, k32u port);
272 
273 /**
274  * Returns the UDP port the heartbeat receiver is bound to.
275  *
276  * After GoHeartbeat_Start succeeds, this returns the actual port in use -
277  * either the explicit port the caller requested, or the ephemeral port the
278  * OS assigned (when the caller passed 0). The returned value is what must
279  * be sent to the sensor in the GO_CONTROL_REGISTER_HEARTBEAT_CLIENT command.
280  *
281  * @public @memberof GoHeartbeat
282  * @version Introduced in firmware 6.6.x.x
283  * @param heartbeat Heartbeat object.
284  * @return Bound UDP port, or 0 if Start has not been called yet.
285  */
286 GoFx(k32u) GoHeartbeat_LocalPort(GoHeartbeat heartbeat);
287 
288 /**
289  * Stops heartbeat monitoring.
290  *
291  * @public @memberof GoHeartbeat
292  * @version Introduced in firmware 6.6.x.x
293  * @param heartbeat Heartbeat object.
294  * @return Operation status.
295  */
296 GoFx(kStatus) GoHeartbeat_Stop(GoHeartbeat heartbeat);
297 
298 /**
299  * Reports whether heartbeat monitoring is currently active.
300  *
301  * @public @memberof GoHeartbeat
302  * @version Introduced in firmware 6.6.x.x
303  * @param heartbeat Heartbeat object.
304  * @return kTRUE if monitoring is active; kFALSE otherwise.
305  */
306 GoFx(kBool) GoHeartbeat_IsRunning(GoHeartbeat heartbeat);
307 
308 /**
309  * Reports whether the monitored sensor is currently connected.
310  *
311  * A sensor is considered connected if heartbeats have been received
312  * within the configured timeout period.
313  *
314  * @public @memberof GoHeartbeat
315  * @version Introduced in firmware 6.6.x.x
316  * @param heartbeat Heartbeat object.
317  * @return kTRUE if connected; kFALSE otherwise.
318  */
319 GoFx(kBool) GoHeartbeat_IsConnected(GoHeartbeat heartbeat);
320 
321 /**
322  * Gets the timestamp of the last received heartbeat.
323  *
324  * @public @memberof GoHeartbeat
325  * @version Introduced in firmware 6.6.x.x
326  * @param heartbeat Heartbeat object.
327  * @return Timestamp in microseconds, or 0 if no heartbeat received.
328  */
330 
331 /**
332  * Gets detailed heartbeat status information.
333  *
334  * @public @memberof GoHeartbeat
335  * @version Introduced in firmware 6.6.x.x
336  * @param heartbeat Heartbeat object.
337  * @param info Receives heartbeat status information.
338  * @return Operation status.
339  */
341 
342 #include <GoSdk/GoHeartbeat.x.h>
343 
344 #endif
k16u magic
Magic identifier (0x474F = "GO") - network byte order.
Definition: GoHeartbeat.h:94
void(kCall * GoHeartbeatReconnectFx)(kPointer context, GoHeartbeat heartbeat, k32u sensorId)
Defines the signature for a heartbeat reconnect callback function.
Definition: GoHeartbeat.h:175
Represents a heartbeat UDP packet (wire format).
Definition: GoHeartbeat.h:92
kStatus GoHeartbeat_Destroy(GoHeartbeat heartbeat)
Destroys a GoHeartbeat object.
k16u lastSequence
Last received sequence number (wraps every 65536 packets)
Definition: GoHeartbeat.h:117
k32u sensorId
Sensor ID that sent this heartbeat - network byte order.
Definition: GoHeartbeat.h:95
kStatus GoHeartbeat_Stop(GoHeartbeat heartbeat)
Stops heartbeat monitoring.
k64u packetsReceived
Total packets received.
Definition: GoHeartbeat.h:118
Provides fast UDP-based heartbeat monitoring for sensor disconnection detection.
k64u GoHeartbeat_Timeout(GoHeartbeat heartbeat)
Gets the current timeout duration.
kStatus GoHeartbeat_SetDisconnectHandler(GoHeartbeat heartbeat, GoHeartbeatDisconnectFx function, kPointer context)
Sets the disconnect callback handler.
k32u GoHeartbeat_LocalPort(GoHeartbeat heartbeat)
Returns the UDP port the heartbeat receiver is bound to.
kBool GoHeartbeat_IsRunning(GoHeartbeat heartbeat)
Reports whether heartbeat monitoring is currently active.
Essential SDK declarations.
kStatus GoHeartbeat_Construct(GoHeartbeat *heartbeat, kAlloc allocator)
Constructs a GoHeartbeat object.
k32u sensorId
Sensor ID being monitored.
Definition: GoHeartbeat.h:114
Represents heartbeat status information.
Definition: GoHeartbeat.h:112
k64u packetsMissed
Total packets missed (sequence gaps)
Definition: GoHeartbeat.h:119
kStatus GoHeartbeat_SetTimeout(GoHeartbeat heartbeat, k64u timeoutUs)
Sets the timeout duration for disconnection detection.
kStatus GoHeartbeat_Start(GoHeartbeat heartbeat, k32u sensorId, kIpAddress address, k32u port)
Starts heartbeat monitoring for a sensor.
k64u lastReceivedTime
Timestamp of last received heartbeat (microseconds)
Definition: GoHeartbeat.h:116
kStatus GoHeartbeat_SetReconnectHandler(GoHeartbeat heartbeat, GoHeartbeatReconnectFx function, kPointer context)
Sets the reconnect callback handler.
kStatus GoHeartbeat_GetInfo(GoHeartbeat heartbeat, GoHeartbeatInfo *info)
Gets detailed heartbeat status information.
kBool connected
Current connection status.
Definition: GoHeartbeat.h:115
void(kCall * GoHeartbeatDisconnectFx)(kPointer context, GoHeartbeat heartbeat, k32u sensorId)
Defines the signature for a heartbeat disconnect callback function.
Definition: GoHeartbeat.h:163
k16u sequence
Rolling sequence number (0-65535) - network byte order.
Definition: GoHeartbeat.h:96
k64u GoHeartbeat_LastReceivedTime(GoHeartbeat heartbeat)
Gets the timestamp of the last received heartbeat.
kBool GoHeartbeat_IsConnected(GoHeartbeat heartbeat)
Reports whether the monitored sensor is currently connected.
k64u timestamp
Timestamp when packet was sent (microseconds) - network byte order.
Definition: GoHeartbeat.h:97