Feature/snaps callbacks

[aljazdu]

Purpose

This PR solves multiple minor issues with Snaps such as: missing callbacks for snap uploads, exposed device serial numbers when sending snaps, minor update of certain errors messages.

Specification

Added CallBacks to SendSnap(), which returns SendSnapCallbackResult which contains snap payload, name, timestamp, id, as well as SendSnapCallbackStatus which describes the status of snap upload.

Dependencies & Potential Impact

None / not applicable

Deployment Plan

None / not applicable

Testing & Validation

This was tested using the updated examples. both in python and C++.

[lnotspotl]

Left a few comments, there is a couple of edge cases that need to be handled (mainly null pointer related stuff), otherwise looks good!

[lnotspotl]

.

[lnotspotl]

I tried running the events.py example by creating a new Hub team and generating a hub API key, however, upon pressing s, I don't see any prints (no callback seems to be called).

I might be doing something wrong? Also, in the examples, can we print out some basic info, something like

print("Press `s` to send a dummy snap to the hub")
print("Press `q` to exit")

Otherwise the application starts running and the user does not know what to do unless they explicitly read the code beforehand (which they don't, usually)

Also, when I run events.py and spam "s", then the program closes seemingly randomly (the same goes for the C++ example)

[14442C1041CDB5D600] [1.4] [5.918] [system] [info] Temperatures - Average: 38.18C, CSS: 38.88C, MSS 38.65C, UPA: 38.41C, DSS: 36.77C
[14442C1041CDB5D600] [1.4] [5.918] [system] [info] Cpu Usage - LeonOS 16.74%, LeonRT: 15.69%
Sending snap
Sending snap
Sending snap
Sending snap
Sending snap
Sending snap
Sending snap
Sending snap
Sending snap
Sending snap
Sending snap
Sending snap
[14442C1041CDB5D600] [1.4] [1769000620.894] [host] [debug] Device about to be closed...
[14442C1041CDB5D600] [1.4] [1769000620.903] [host] [debug] Shutdown OK
[2026-01-21 14:03:41.047] [depthai] [info] XLinkInHost node stopped - exception: Couldn't read data from stream: '__x_2_passthrough' (X_LINK_ERROR)
[2026-01-21 14:03:41.047] [depthai] [info] XLinkInHost node stopped - exception: Couldn't read data from stream: '__x_3_out' (X_LINK_ERROR)
[14442C1041CDB5D600] [1.4] [1769000621.047] [host] [debug] Timesync thread exception caught: Couldn't read data from stream: '__timesync' (X_LINK_ERROR)
[14442C1041CDB5D600] [1.4] [1769000621.047] [host] [debug] Log thread exception caught: Couldn't read data from stream: '__log' (X_LINK_ERROR)
[14442C1041CDB5D600] [1.4] [1769000621.345] [host] [debug] Watchdog thread exception caught: Couldn't write data to stream: '__watchdog' (X_LINK_ERROR)
[2026-01-21 14:03:42.061] [depthai] [debug] XLinkResetRemote of linkId: (0)
[2026-01-21 14:03:42.061] [depthai] [info] Environment variable DEPTHAI_CRASHDUMP_TIMEOUT is not set. Using default value: '10500'
[14442C1041CDB5D600] [1.4] [1769000622.061] [host] [debug] Device closed, 1166

[lnotspotl]

Kazam_screencast_00008.mp4

[lnotspotl]

.

[aljazdu]

I tried running the events.py example by creating a new Hub team and generating a hub API key, however, upon pressing s, I don't see any prints (no callback seems to be called).

I might be doing something wrong? Also, in the examples, can we print out some basic info, something like

print("Press `s` to send a dummy snap to the hub")
print("Press `q` to exit")

Otherwise the application starts running and the user does not know what to do unless they explicitly read the code beforehand (which they don't, usually)

Also, when I run events.py and spam "s", then the program closes seemingly randomly (the same goes for the C++ example)

[14442C1041CDB5D600] [1.4] [5.918] [system] [info] Temperatures - Average: 38.18C, CSS: 38.88C, MSS 38.65C, UPA: 38.41C, DSS: 36.77C
[14442C1041CDB5D600] [1.4] [5.918] [system] [info] Cpu Usage - LeonOS 16.74%, LeonRT: 15.69%
Sending snap
Sending snap
Sending snap
Sending snap
Sending snap
Sending snap
Sending snap
Sending snap
Sending snap
Sending snap
Sending snap
Sending snap
[14442C1041CDB5D600] [1.4] [1769000620.894] [host] [debug] Device about to be closed...
[14442C1041CDB5D600] [1.4] [1769000620.903] [host] [debug] Shutdown OK
[2026-01-21 14:03:41.047] [depthai] [info] XLinkInHost node stopped - exception: Couldn't read data from stream: '__x_2_passthrough' (X_LINK_ERROR)
[2026-01-21 14:03:41.047] [depthai] [info] XLinkInHost node stopped - exception: Couldn't read data from stream: '__x_3_out' (X_LINK_ERROR)
[14442C1041CDB5D600] [1.4] [1769000621.047] [host] [debug] Timesync thread exception caught: Couldn't read data from stream: '__timesync' (X_LINK_ERROR)
[14442C1041CDB5D600] [1.4] [1769000621.047] [host] [debug] Log thread exception caught: Couldn't read data from stream: '__log' (X_LINK_ERROR)
[14442C1041CDB5D600] [1.4] [1769000621.345] [host] [debug] Watchdog thread exception caught: Couldn't write data to stream: '__watchdog' (X_LINK_ERROR)
[2026-01-21 14:03:42.061] [depthai] [debug] XLinkResetRemote of linkId: (0)
[2026-01-21 14:03:42.061] [depthai] [info] Environment variable DEPTHAI_CRASHDUMP_TIMEOUT is not set. Using default value: '10500'
[14442C1041CDB5D600] [1.4] [1769000622.061] [host] [debug] Device closed, 1166

Looking at the comment and the video recording you have sent, I have 2 comments.

Firstly, is your code up to date? Comparing the current events.py example with the screen recording I see that you are missing the functionality of printing local ids of the snaps when sending them.

Secondly, the functionality of snaps works in the following way: when you call sendSnap() a snap is added into a snap buffer inside of DAI. These snaps are then uploaded in a batch, with a predefined publish interval. Since this interval is set to 30s, followed by group preparation, upload, etc. follows, you might have to wait for up to 30s or even more before seeing a successful upload callback.
This delay was the cause of the callback implementation.

I have tried using the example.py in the current version and it worked.

[lnotspotl]

Thanks, @aljazdu, indeed, I had not pulled the latest changes and I can see the uploaded snaps after a while on the hub 👍

However, the issue with me uploading snaps super quickly persists, if I spam s, the app just crashes, any idea why that could be?

[aljazdu]

However, the issue with me uploading snaps super quickly persists, if I spam s, the app just crashes, any idea why that could be?

I will look into it and let you know. In the mean time, you can use the file_group example if you want to automate sending the snaps (it sends a snap when a detection confidence is within a certain threshold). It can be used to easily send a large number of snaps.

[aljazdu]

Thanks, @aljazdu, indeed, I had not pulled the latest changes and I can see the uploaded snaps after a while on the hub 👍

However, the issue with me uploading snaps super quickly persists, if I spam s, the app just crashes, any idea why that could be?

Fixed the app crashing, as well as added usage print statement for the user explaining what to press.

[lnotspotl]

Thanks @aljazdu, works nicely now 💯 Would you mind explaining what the issue was, the key checking before and after your change seems equivalent.

[aljazdu]

Thanks @aljazdu, works nicely now 💯 Would you mind explaining what the issue was, the key checking before and after your change seems equivalent.

Perfect, great to hear! The problem was erroneous duplicated waitKey() calls - which resulted in potentially keys not being registered - as well as a mistaken checking for -1, which checks for any key.