Documentation for Driver() discovery parameter

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=, ...} )

Hi, @garyhooper!

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

@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.

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.

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

1 Like