Documentation for Driver() discovery parameter

[garyhooper]

I see use of a discovery parameter passed to Driver() in many sample pieces of code, but no complete documentation for it in the reference manual. Can someone point to the detailed docs for this?

Driver( name, { discovery=, ...} )

[nayelyz (SmartThings Developer Support)]

Hi, @garyhooper!

Can you share the link of the code where you’re seeing the reference to “discovery” to have a better reference, please?

[garyhooper]

@nayelyz, the issue is that I do not see it in the reference docs, but it is in sample code. I would expect it here, but it’s missing.

[orangebucket (Graham)]

@nayelyz

Can you share the link of the code where you’re seeing the reference to “discovery” to have a better reference, please?

Nayely, if I may attempt to butt in and not derail the thread, the discovery handler is basically not documented anywhere at all. The existence of a default discovery handler is acknowledged in the Driver reference but there is no mention of the discovery template option at all. It does, of course, appear in sample pieces of code for LAN drivers.

Worse still if you look to the SampleDrivers repo for inspiration you will find they are somewhat inconsistent and I suspect at best misleading, if not downright wrong.

The hello-world example has a discovery handler defined with …

function discovery.handle_discovery(driver, _should_continue)

That suggests two parameters. In Lua _ is usually used by itself to indicate an ignored value so something instantly looks a bit odd. As it stands it could be seen to imply that had the should_continue function been required it would be the second parameter. I am sure I am not the only person who has blindly copied that. However …

The lightbulb-lan-esp8266 uses …

function disco.start(driver, opts, cons)

And then there were three. Hmm. Perhaps we need to look to live drivers for more inspiration …

The three stock drivers using LAN handlers (bose, samsung-audio and wemo) use …

local function discovery_handler(driver, _, should_continue)

Again three parameters with the second one clearly ignored and the should_continue function passed as the third. I’d have to put my money on that being right.

Could that perhaps be what the ‘hello-world’ example should be using? It seems odd to have the most basic example implying the ‘should_continue’ function is passed as the second argument when it doesn’t seem to be correct.

[nayelyz (SmartThings Developer Support)]

Hi,
Sorry for the delay. The team is already checking the documentation update but they mentioned these are some of the key points:

A driver that has the discovery: {} permission in its config.yml has the option to register a handler for local discovery events. Local discovery is triggered when a user selects “Scan Nearby” from the Mobile App.
Typically, this permission is only used for LAN devices that need to do local network discovery such as by mDNS or UPnP.

The discovery handler is registered in the driver template in the init.lua for the driver by setting the discovery property, for example:
​

local driver = Driver("my_driver",
  {
    discovery = my_discovery_handler, -- <-- right here
    lifecycle_handlers = { ... },
    capability_handlers = { ... },
  }
)

The discovery handler callback is a function with 3 arguments:

local function my_discovery_handler(driver, args, should_continue)
-- your handler goes here
end

1. driver: The instantiated driver as defined by the driver template table in the driver’s init.lua (i.e. the table that gets passed as the 2nd argument to the Driver(..., ...) constructor)
2. args: A table containing the arguments for the discovery command that was sent to the hub. This is handled internally
3. should_continue: A callable function that takes no arguments. It will return a truthy value while scanning is active, and a falsy value when the hub has terminated the discovery scan session. The typical usage of this parameter is for implementing a discovery loop that scans repeatedly for the duration of the discovery request, which would be common for situations such as UDP-based discovery like SSDP/UPnP or mDNS where results aren’t always reliable or may take more than one query attempt to resolve.

For example:
​

local function my_discovery_handler(driver, args, should_continue)
  while should_continue()
      -- repeated discovery logic
  end
end